### Server Directory Listing Example

Source: https://github.com/skyrim-multiplayer/skymp/blob/main/docs/docs_deploy.md

An example of the expected file structure and sizes within the server deployment directory.

```bash
$ ls -lhR skymp-server-<branch>/
skymp-server-<branch>/: 
total 8.0K
drwxrwxr-x 3 ubuntu ubuntu 4.0K Dec  5 12:04 server
-rw-rw-r-- 1 ubuntu ubuntu  239 Dec  5 12:02 server-settings.json

skymp-server-<branch>/server:
total 4.0K
drwxrwxr-x 2 ubuntu ubuntu 4.0K Dec  5 12:01 data

skymp-server-<branch>/server/data:
total 346M
-rw-rw-r-- 1 ubuntu ubuntu  25M Dec  5 12:01 Dawnguard.esm
-rw-rw-r-- 1 ubuntu ubuntu  62M Dec  5 12:01 Dragonborn.esm
-rw-rw-r-- 1 ubuntu ubuntu 3.8M Dec  5 12:01 HearthFires.esm
-rw-rw-r-- 1 ubuntu ubuntu 239M Dec  5 12:01 Skyrim.esm
-rw-rw-r-- 1 ubuntu ubuntu  18M Dec  5 12:01 Update.esm
```

--------------------------------

### Start Development Server

Source: https://github.com/skyrim-multiplayer/skymp/blob/main/docs/contributing/en/How to work with skyrim-platform.md

Navigate to the skyrim-platform/tools/dev_service directory in your command prompt and run this command to start the development server.

```bash
npm run dev
```

--------------------------------

### Full Plugin Initialization Example

Source: https://github.com/skyrim-multiplayer/skymp/blob/main/docs/skyrim_platform/cookbook.md

A comprehensive example demonstrating plugin initialization using event hooks, persistent storage, and JDB for data management. This includes setting up initialization flags and handling variable persistence.

```typescript
import * as JDB from "JContainers/JDB"
import { on, once } from "skyrimPlatform"

const initK = ".my-plugin.init";

const MarkInitialized = () => JDB.solveBoolSetter(initK, true, true);
const WasInitialized = () => JDB.solveBool(initK, false);

export function main() {
  let allowInit = storage["my-plugin-init"] as boolean | false;

  on("loadGame", () => {
    // Initialize when installed mid game and when loading a game
    // because this is always needed anyway.
    InitPlugin();
    allowInit = true;
    storage["my-plugin-init"] = true
  });

  // IMPORTANT: we are using ONCE instead of on.
  once("update", () => {
    // Has this plugin ever been initialized?
    // OnInit facsimile.
    if (allowInit || !WasInitialized()) {
      InitPlugin();
    }
  });

  // Initialize with the value it had before hot reloading or default 0
  let pluginVar1 = storage["my-plugin-var1"] as number | 0;

  function InitPlugin() {
    const key = ".my-plugin.var1";

    // Initialize with the value it had before reloading the game or default 0
    pluginVar1 = JDB.solveFlt(key, 0);

    // Save values inmediately to both disk and storage, so they don't get lost.
    JDB.solveFltSetter(key, pluginVar1, true);
    storage["my-plugin-var1"] = pluginVar1;

    // Let's suppose this was OnInit.
    MarkInitialized();
  }
}
```

--------------------------------

### Define Start Points

Source: https://github.com/skyrim-multiplayer/skymp/blob/main/docs/docs_server_configuration_reference.md

Configure a list of spawn points for players. The server will randomly select one of these points when starting.

```json
{
  // ...
  "startPoints": [
    {
      "pos": [22659, -8697, -3594],
      "worldOrCell": "0x1a26f",
      "angleZ": 268
    }
  ]
  // ...
}
```

--------------------------------

### Install Node-API Import Library

Source: https://github.com/skyrim-multiplayer/skymp/blob/main/overlay_ports/node-api-headers/CMakeLists.txt

Installs the generated 'node.lib' file to the 'lib' directory within the build's binary directory.

```cmake
install(FILES ${CMAKE_BINARY_DIR}/node.lib DESTINATION lib)
```

--------------------------------

### Set VCPKG Installation Options

Source: https://github.com/skyrim-multiplayer/skymp/blob/main/CMakeLists.txt

Configures options for vcpkg installation. It includes '--no-print-usage' and conditionally adds '--clean-after-build' based on CI environment or the NO_CLEAN_AFTER_BUILD option.

```cmake
if("$ENV{CI}" STREQUAL "true" OR NO_CLEAN_AFTER_BUILD)
  set(VCPKG_INSTALL_OPTIONS --no-print-usage)
else()
  set(VCPKG_INSTALL_OPTIONS --no-print-usage --clean-after-build)
endif()
```

--------------------------------

### Project Setup and Dependencies

Source: https://github.com/skyrim-multiplayer/skymp/blob/main/skymp5-server/CMakeLists.txt

Initializes the CMake project, enables testing, sets source directory, and includes common CMake modules.

```cmake
project(skymp5-server)
enable_testing()

set(SKYMP5_SERVER_SOURCE_DIR ${CMAKE_CURRENT_LIST_DIR})

include(${CMAKE_SOURCE_DIR}/cmake/apply_default_settings.cmake)
include(${CMAKE_SOURCE_DIR}/cmake/yarn.cmake)

find_package(CMakeRC CONFIG REQUIRED)
```

--------------------------------

### Conventional Commits Examples

Source: https://github.com/skyrim-multiplayer/skymp/blob/main/docs/docs_maintainer_rules.md

Examples demonstrating the Conventional Commits Specification format, including commit types, scopes, and breaking change indicators.

```git
feat(skymp5-server): add feature to choose default spawn points
```

```git
internal: make server's node addon buildable via top-level CMakeLists
```

```git
fix: server startup
```

```git
release(skyrim-platform): version 2.1
```

--------------------------------

### Yarn Command Execution on Windows

Source: https://github.com/skyrim-multiplayer/skymp/blob/main/skymp5-server/CMakeLists.txt

Executes the 'install' command using yarn, specifically for Windows environments.

```cmake
if(WIN32)
  yarn_execute_command(
    COMMAND install
    WORKING_DIRECTORY ${SKYMP5_SERVER_SOURCE_DIR}
  )
endif()
```

--------------------------------

### Ping-Pong Communication Example

Source: https://github.com/skyrim-multiplayer/skymp/blob/main/docs/skyrim_platform/browser.md

An example demonstrating two-way communication: Skyrim Platform sends a message to the browser using `executeJavaScript`, and the browser responds using `window.skyrimPlatform.sendMessage`. This cycle can be repeated.

```ts
once("tick", () => {
    browser.executeJavaScript("window.skyrimPlatform.sendMessage('yay')");
});

on("browserMessage", (event) => {
    printConsole(JSON.stringify(event.arguments));
    browser.executeJavaScript("window.skyrimPlatform.sendMessage('yay')");
});
```

--------------------------------

### Ping-Pong Example (Game <-> Browser Communication)

Source: https://github.com/skyrim-multiplayer/skymp/blob/main/docs/skyrim_platform/browser.md

Demonstrates a full communication loop between the game script and the browser context using `executeJavaScript` and `window.skyrimPlatform.sendMessage`.

```APIDOC
## Ping-Pong Example (Game <-> Browser Communication)

### Description
This example illustrates a bidirectional communication pattern between the game script (SP context) and the browser context. The game uses `browser.executeJavaScript` to send commands to the browser, and the browser uses `window.skyrimPlatform.sendMessage` to send data back to the game, which is then handled via the `browserMessage` event.

### Game Script Logic

- **Initiate communication:** Use `browser.executeJavaScript` to call `window.skyrimPlatform.sendMessage` from the browser.
- **Receive messages:** Use `on("browserMessage", ...)` to handle data sent from the browser.

### Example Implementation

```typescript
import { on, once, browser, printConsole } from "skyrimPlatform";

// Send a message to the browser on the first tick
once("tick", () => {
    browser.executeJavaScript("window.skyrimPlatform.sendMessage('Hello from game on tick!')");
});

// Handle messages from the browser and respond
on("browserMessage", (event) => {
    const receivedMessage = JSON.stringify(event.arguments);
    printConsole(`Received from browser: ${receivedMessage}`);

    // Respond back to the browser
    browser.executeJavaScript("window.skyrimPlatform.sendMessage('Acknowledged: ' + 
```

--------------------------------

### Server Configuration Example

Source: https://github.com/skyrim-multiplayer/skymp/blob/main/docs/docs_running_a_server.md

Modify the 'ip' field to your public IP address to allow players from the internet to connect. Ensure ports are open with your internet provider.

```json
{
  "dataDir": "data",
  "loadOrder": [
    "Skyrim.esm",
    "Update.esm",
    "Dawnguard.esm",
    "HearthFires.esm",
    "Dragonborn.esm"
  ],
  "ip": "127.0.0.1", // <=
  "name": "My Server"
}
```

--------------------------------

### Install Yarn Globally

Source: https://github.com/skyrim-multiplayer/skymp/blob/main/CONTRIBUTING.md

Installs Yarn, a package manager for JavaScript, globally on your system. This is a prerequisite for managing project dependencies.

```bash
npm install --global yarn
```

--------------------------------

### Perform GET Request with HttpClient

Source: https://github.com/skyrim-multiplayer/skymp/blob/main/docs/skyrim_platform/http.md

Initializes an HttpClient with a base URL and performs a GET request. The response body is printed to the console if the request is successful. Ensure the URL is correctly formatted, and be aware that `response.body` will be empty on failure.

```typescript
import { HttpClient } from "skyrimPlatform";
let url = "https://canhazip.com:443"; // URL may contain port or not
let http = new HttpClient(url);
http.get("/").then((response) => printConsole(response.body));
```

--------------------------------

### Configure and Run Tests with Coverage (Windows)

Source: https://github.com/skyrim-multiplayer/skymp/blob/main/CONTRIBUTING.md

Generate project files with coverage enabled and run tests on Windows. Requires OpenCppCoverage to be installed. The coverage report will be in the `build/__coverage` directory.

```bash
cmake .. -DCPPCOV_PATH="C:\ Program Files\OpenCppCoverage"
ctest -C Debug --verbose
```

--------------------------------

### Build Client with Yarn

Source: https://github.com/skyrim-multiplayer/skymp/blob/main/skymp5-client/CMakeLists.txt

Includes the yarn.cmake script, installs dependencies, and executes the build command for the client if BUILD_CLIENT is enabled.

```cmake
if(BUILD_CLIENT)
  include(${CMAKE_SOURCE_DIR}/cmake/yarn.cmake)

  yarn_execute_command(
    WORKING_DIRECTORY ${CMAKE_CURRENT_LIST_DIR}
    COMMAND install
  )

  set(out
    ${CMAKE_BINARY_DIR}/dist/client/Data/Platform/Plugins/skymp5-client.js
  )
  add_custom_command(
    OUTPUT ${out}
    COMMAND yarn --cwd "${CMAKE_CURRENT_LIST_DIR}" build
    DEPENDS ${sources}
  )
  add_custom_target(skymp5-client ALL
    DEPENDS ${out}
    SOURCES ${sources}
  )

  add_custom_command(
    TARGET skymp5-client POST_BUILD
    COMMAND ${CMAKE_COMMAND} -DCLIENT_SETTINGS_JSON_PATH=${CMAKE_BINARY_DIR}/dist/client/Data/Platform/Plugins/skymp5-client-settings.txt -DOFFLINE_MODE=${OFFLINE_MODE} -P ${CMAKE_SOURCE_DIR}/cmake/scripts/generate_client_settings.cmake
  )
else()
  add_custom_target(skymp5-client ALL
    SOURCES ${source}
    COMMAND ${CMAKE_COMMAND} -E echo "Building skymp5-client is disabled. To enable it, set BUILD_CLIENT to ON."
  )
endif()
```

--------------------------------

### CMake Configuration for CEF Prebuilt

Source: https://github.com/skyrim-multiplayer/skymp/blob/main/overlay_ports/cef-prebuilt/CMakeLists.txt

Configures the CMake build system to find and use a prebuilt CEF installation. It sets the module path, defines the CEF root directory, finds the CEF package, and includes the libcef_dll_wrapper. Finally, it installs the wrapper target.

```cmake
cmake_minimum_required(VERSION 3.18.2)
project(cef-prebuilt)

set(CMAKE_MODULE_PATH ${CMAKE_MODULE_PATH} "${CMAKE_SOURCE_DIR}/cmake")
set(CEF_ROOT "${CMAKE_SOURCE_DIR}")
find_package(CEF REQUIRED)
add_subdirectory(${CEF_LIBCEF_DLL_WRAPPER_PATH} libcef_dll_wrapper)

install(TARGETS libcef_dll_wrapper)
```

--------------------------------

### Generate Project Files with CMake (Windows)

Source: https://github.com/skyrim-multiplayer/skymp/blob/main/CONTRIBUTING.md

Generates project files using CMake. Specify the Skyrim SE directory if installed, otherwise, some tests will be skipped and server files may require manual installation.

```bash
mkdir build
cd build
cmake .. -DSKYRIM_DIR="C:/Program Files (x86)/Steam/steamapps/common/Skyrim Special Edition"
```

```bash
cd build
cmake ..
# Some tests would be skipped
# The server would require manual installation of Skyrim.esm and other master files
# Papyrus scripts that require Bethesda's compiler would not be compiled, prebuilts would be used
```

--------------------------------

### Create and Handle Custom Events

Source: https://github.com/skyrim-multiplayer/skymp/blob/main/docs/docs_events_system.md

Demonstrates how to create a custom event source and add a handler for it. Custom event names must start with an underscore.

```typescript
// 1) Making an event
// Custom event names have to start with underscore
mp.makeEventSource("_onSomeEvent", `
    ctx.sp.once("update", () => {
      ctx.sendEvent();
    });
  `);
);

// 2) Adding a handler for the event
mp._onSomeEvent = (pcFormId) => console.log("handled for", pcFormId); ;
```

--------------------------------

### Handle the 'effectStart' Event

Source: https://github.com/skyrim-multiplayer/skymp/blob/main/docs/skyrim_platform/new_events.md

The `effectStart` event is called when any Magic Effect begins. This example shows how to check for a specific effect from a mod.

```typescript
import { on } from "skyrimPlatform";

on("effectStart", (event) => {
  const fx = Game.getFormFromFile(0x800, "my-mod.esp");
  if (fx?.getFormID() !== event.effect.getFormID()) return;

  DoSomething(event.target);
})
```

--------------------------------

### CMake Configuration Error Example

Source: https://github.com/skyrim-multiplayer/skymp/blob/main/docs/docs_cmake_workflow.md

This is an example of a common CMake error encountered during project generation, specifically when a package configuration file cannot be found or is incompatible. It often indicates an issue with the build environment or selected kit.

```cmake
CMake Error at vcpkg/scripts/buildsystems/vcpkg.cmake:857 (_find_package):
  Could not find a configuration file for package "directxtk" that is
  compatible with requested version "".
```

--------------------------------

### Text Creation and Visibility

Source: https://github.com/skyrim-multiplayer/skymp/blob/main/docs/skyrim_platform/texts.md

Example of creating a text element and making the browser visible, which controls text visibility.

```APIDOC
## Example Usage

```typescript
// Create a text element at position (0,0) with white color and 'Tavern' font.
skyrimPlatform.createText(0, 0, "Hello World!", [1, 1, 1, 1], "Tavern");

// Make the browser visible to display the text.
skyrimPlatform.browser.setVisible(true);
```
```

--------------------------------

### Configure Project with CMake (No Skyrim Dir)

Source: https://github.com/skyrim-multiplayer/skymp/blob/main/CONTRIBUTING.md

Configure the project for users who do not have Skyrim SE installed. This command assumes the Skyrim directory is not needed for configuration.

```bash
./build.sh --configure -DCMAKE_BUILD_TYPE=Debug
```

--------------------------------

### Configure Project with CMake (Debug)

Source: https://github.com/skyrim-multiplayer/skymp/blob/main/CONTRIBUTING.md

Configure the project using the CMake wrapper for a Debug build. Replace the Skyrim directory path with your actual installation path.

```bash
./build.sh --configure -DCMAKE_BUILD_TYPE=Debug \
   -DSKYRIM_DIR="$HOME/.steam/debian-installation/steamapps/common/Skyrim Special Edition"
```

--------------------------------

### Load URL in Browser using Win32

Source: https://github.com/skyrim-multiplayer/skymp/blob/main/docs/skyrim_platform/win32.md

Use this function to open a given URL in the default web browser. Ensure the URL starts with 'https://'.

```typescript
import { win32 } from "skyrimPlatform";
let url = "https://google.com"; // URL should start with prefix https://
win32.loadUrl(url);
```

--------------------------------

### Configure Output Path

Source: https://github.com/skyrim-multiplayer/skymp/blob/main/skymp5-front/README.md

Create a `config.js` file to specify the output folder for the build. This is useful for directing compiled assets to the correct location within your Skyrim Multiplayer server setup.

```javascript
module.exports = {
    /* TIP: Change to '<your_server_path>/data/ui' */
    outputPath: "./dist",
};
```

--------------------------------

### Basic Plugin Initialization

Source: https://github.com/skyrim-multiplayer/skymp/blob/main/skymp5-client/README.md

This snippet shows how to initialize a Skyrim Platform plugin. It uses `once('tick', ...)` to print a message to the console when the game runs and `once('update', ...)` to display a message box when a game is started or loaded.

```typescript
import { Debug, once, printConsole } from 'skyrimPlatform'

once('tick', () => {
    printConsole('Hello! You can view this in the Skyrim ~ console on the Main Menu when the game runs')
})

once('update', () => {
    Debug.messageBox('Hello! This will appear when a new game is started or an existing game is loaded')
})
```

--------------------------------

### Conditional Plugin Initialization on Load Game and Update

Source: https://github.com/skyrim-multiplayer/skymp/blob/main/docs/skyrim_platform/cookbook.md

Implement logic to initialize a plugin only when appropriate. This example uses a boolean flag 'allowInit' and the 'once("update")' event to control initialization, preventing double initialization during save loads while allowing it on hot reloads.

```typescript
let allowInit = false;

on("loadGame", () => {
  allowInit = true;
});

once("update", () => {
  if (allowInit) {
    InitPlugin();
  }
});
```

--------------------------------

### Getting Browser Token

Source: https://github.com/skyrim-multiplayer/skymp/blob/main/docs/skyrim_platform/browser.md

Retrieve a unique token generated by Skyrim Platform at the start of each game session.

```APIDOC
## Getting Browser Token

### Description
Retrieves a unique token that Skyrim Platform generates at the beginning of each game session. This token is made available in the browser's JavaScript context as `window.spBrowserToken` after the page has loaded.

### Method

- **getToken(): string**
  Returns the unique Skyrim Platform token for the current game session.

### Usage in Browser
```javascript
// Access the token in the browser's JavaScript environment
const token = window.spBrowserToken;
console.log("SP Browser Token:", token);
```

### Example in Game Script
```typescript
import { browser } from "skyrimPlatform";

const token = browser.getToken();
console.log("Skyrim Platform Token:", token);
```
```

--------------------------------

### Initialize and Modify Text using Texts API

Source: https://github.com/skyrim-multiplayer/skymp/blob/main/docs/release/sp-2.8.md

Example demonstrating text creation and subsequent modification using various Texts API methods, including new functionalities for size, rotation, font, depth, effects, and origin.

```javascript
sp = skyrimPlatform;

let textId = sp.createText(0, 0, "Hello World!", [1, 1, 1, 1], "Tavern");

sp.on("activate", () => {
  sp.setTextPos(textId, 200, 200);

  sp.setTextString(textId, "Hello World!");

  sp.setTextColor(textId, [1,1,1,1]);

  // new methods usage
  sp.setTextSize(textId, 3);

  sp.setTextRotation(textId, 45);

  sp.setTextFont(textId, "Tavern");

  sp.setTextDepth(textId, 1);

  sp.setTextEffect(textId, sp.SpriteEffects.FlipHorizontally);

  sp.setTextOrigin(textId, [0,0]);
});
```

--------------------------------

### Get Character Code Point

Source: https://github.com/skyrim-multiplayer/skymp/blob/main/docs/skyrim_platform/texts.md

Python code to get the Unicode code point for a given character.

```python
ord('Ё')
```

--------------------------------

### Configure core dump pattern

Source: https://github.com/skyrim-multiplayer/skymp/blob/main/docs/docs_deploy.md

Set the kernel's core dump pattern to specify where and how core dump files should be saved. This example sets a detailed naming convention in /var/crash.

```bash
sudo sysctl kernel.core_pattern=/var/crash/core-%P-%u-%g-%s-%t-%c-%h
```

--------------------------------

### Get Character from Code Point

Source: https://github.com/skyrim-multiplayer/skymp/blob/main/docs/skyrim_platform/texts.md

Python code to get the character corresponding to a given Unicode code point.

```python
chr(1105)
```

--------------------------------

### Dynamically Add and Remove Hooks

Source: https://github.com/skyrim-multiplayer/skymp/blob/main/docs/release/sp-2.3.md

Example of using `on('effectStart')` and `on('effectFinish')` to add and remove animation event hooks. Ensure to check if the ID exists before removing.

```typescript
let id;

export let main = () => {
  on('effectStart', () => {
    id = hooks.sendAnimationEvent.add({...});
  });
  
  on('effectFinish', () => {
    if (id) {
      hooks.sendAnimationEvent.remove(id);
    }
  });
};
```

--------------------------------

### Build Project with CMake Wrapper

Source: https://github.com/skyrim-multiplayer/skymp/blob/main/CONTRIBUTING.md

Build the project after configuration. Navigate to the build directory and execute the build script. Additional arguments are passed to CMake.

```bash
cd build
../build.sh --build
```

--------------------------------

### Compile the Project

Source: https://github.com/skyrim-multiplayer/skymp/blob/main/CLAUDE.md

Use this command to compile the entire project. Ensure you are in the build directory.

```bash
cmake --build .

```

--------------------------------

### Configure VCPKG Manifest Features

Source: https://github.com/skyrim-multiplayer/skymp/blob/main/CMakeLists.txt

Appends features to VCPKG_MANIFEST_FEATURES based on the SKYRIM_VR and BUILD_NODEJS options. This allows vcpkg to install the correct dependencies for the selected build configuration.

```cmake
if(SKYRIM_VR)
  list(APPEND VCPKG_MANIFEST_FEATURES "skyrim-vr")
else()
  list(APPEND VCPKG_MANIFEST_FEATURES "skyrim-flatrim")
endif()

if(BUILD_NODEJS)
  list(APPEND VCPKG_MANIFEST_FEATURES "build-nodejs")
else()
  list(APPEND VCPKG_MANIFEST_FEATURES "prebuilt-nodejs")
endif()
```

--------------------------------

### Create Server Directory Structure

Source: https://github.com/skyrim-multiplayer/skymp/blob/main/docs/docs_deploy.md

Set up the necessary directory structure on the server for a specific branch, including a place for server data.

```bash
mkdir -p ~/skymp-server-<branch>/server/data
```

--------------------------------

### Get and set weapon type

Source: https://github.com/skyrim-multiplayer/skymp/blob/main/docs/skyrim_platform/new_types.md

Uses the WeaponType enum to get or set the type of a weapon. Note that Battleaxes and Warhammers share the same value.

```typescript
weapon.getWeaponType() === WeaponType.WarAxe;
```

```typescript
weapon.setWeaponType(WeaponType.Greatsword);
```

--------------------------------

### Define Project and Source Files

Source: https://github.com/skyrim-multiplayer/skymp/blob/main/skymp5-client/CMakeLists.txt

Initializes the CMake project and finds all source files in the src directory.

```cmake
project(skymp5-client)

file(GLOB_RECURSE sources ${CMAKE_CURRENT_LIST_DIR}/src/*)
```

--------------------------------

### Generate Project with CMake

Source: https://github.com/skyrim-multiplayer/skymp/blob/main/docs/contributing/en/How to work with skyrim-platform.md

Use this command in the build folder to generate the project files. Turning off SweetPie is recommended for easier server entry.

```bash
cmake .. -DSWEETPIE=OFF
```

--------------------------------

### Configure Additional Server Settings

Source: https://github.com/skyrim-multiplayer/skymp/blob/main/docs/docs_server_configuration_reference.md

Automate fetching server settings from GitHub. Specify the repository, branch/tag/commit, path regex, and optionally a personal access token.

```json
{
  // ...
  "additionalServerSettings": [
    {
      "type": "github",
      "repo": "your-org/server-settings-repo",
      "ref": "main", // Specify the branch, tag, or commit hash here
      "pathRegex": "^(common|indev)/.*", // No need to check for .json extension
      "token": "YOUR_GITHUB_PERSONAL_ACCESS_TOKEN"
    }
  ]
  // ...
}
```

--------------------------------

### Build Project with CMake

Source: https://github.com/skyrim-multiplayer/skymp/blob/main/docs/contributing/en/How to work with skyrim-platform.md

Execute this command in the build folder to compile the entire project in Release configuration.

```bash
cmake --build . --config Release
```

--------------------------------

### Get Text Color

Source: https://github.com/skyrim-multiplayer/skymp/blob/main/skyrim-platform/src/platform_se/codegen/convert-files/Definitions.txt

Retrieves the current color of a text element.

```typescript
export declare function getTextColor(textId: number): number[];
```

--------------------------------

### Run Podman Container for Development

Source: https://github.com/skyrim-multiplayer/skymp/blob/main/CONTRIBUTING.md

Use this command to run a Podman container for development, mounting the current directory and setting up the VCPKG cache. The `--security-opt label=disable` flag is for SELinux users.

```bash
. misc/github_env_linux; podman run -it --rm -v "$PWD:$PWD" --security-opt label=disable -w "$PWD" \
    -e VCPKG_DEFAULT_BINARY_CACHE=/home/skymp/.cache/vcpkg/archives \
    $SKYMP_VCPKG_DEPS_IMAGE bash
```

--------------------------------

### Get Text Position

Source: https://github.com/skyrim-multiplayer/skymp/blob/main/skyrim-platform/src/platform_se/codegen/convert-files/Definitions.txt

Retrieves the current position of a text element.

```typescript
export declare function getTextPos(textId: number): number[];
```

--------------------------------

### Library Creation and Include Directories

Source: https://github.com/skyrim-multiplayer/skymp/blob/main/savefile/CMakeLists.txt

Creates a static library named 'savefile' using the discovered source files. It then sets up public include directories for the library.

```cmake
add_library(savefile STATIC ${savefile_src})
target_include_directories(savefile PUBLIC ${CMAKE_CURRENT_LIST_DIR}/src)
target_include_directories(savefile PUBLIC ${CMAKE_CURRENT_LIST_DIR}/include)
```

--------------------------------

### Text Properties

Source: https://github.com/skyrim-multiplayer/skymp/blob/main/skyrim-platform/src/platform_se/codegen/convert-files/Definitions.txt

Functions to set and get various properties of text elements.

```APIDOC
export declare function setTextPos(textId: number, xPos: number, yPos: number): void;
export declare function getTextPos(textId: number): number[];

export declare function setTextString(textId: number, text: string): void;
export declare function getTextString(textId: number): string;

export declare function setTextColor(textId: number, color: number[]): void;
export declare function getTextColor(textId: number): number[];

export declare function setTextSize(textId: number, size: number): void;
export declare function getTextSize(textId: number): number;

export declare function setTextRotation(textId: number, rotation: number): void;
export declare function getTextRotation(textId: number): number;

export declare function setTextFont(textId: number, name: string): void;
export declare function getTextFont(textId: number): string;

export declare function setTextDepth(textId: number, depth: number): void;
export declare function getTextDepth(textId: number): number;

export declare function setTextEffect(textId: number, effect: number): void;
export declare function getTextEffect(textId: number): number;

export declare function setTextOrigin(textId: number, origin: number[]): void;
export declare function getTextOrigin(textId: number): number[];

export declare function setTextRefr(textId: number, refrFormId: number): void; // pass 0 to detach
export declare function setTextRefrNode(textId: number, nodeName: string): void;
export declare function setTextRefrOffset(textId: number, offset: number[]): void;
export declare function setTextRefrScreenOffset(textId: number, offset: number[]): void;
```

--------------------------------

### Project Initialization

Source: https://github.com/skyrim-multiplayer/skymp/blob/main/CMakeLists.txt

Sets the minimum required CMake version and defines the project name. It also enables testing support.

```cmake
cmake_minimum_required(VERSION 3.19)
project(skymp)
enable_testing()
```

--------------------------------

### Get Text Effect

Source: https://github.com/skyrim-multiplayer/skymp/blob/main/skyrim-platform/src/platform_se/codegen/convert-files/Definitions.txt

Retrieves the visual effect applied to a text element.

```typescript
export declare function getTextEffect(textId: number): number;
```

--------------------------------

### Configure Migration Database Driver

Source: https://github.com/skyrim-multiplayer/skymp/blob/main/docs/docs_database_drivers.md

Use the 'migration' driver for on-the-fly database type transitions. Ensure you back up your data before using this driver. Specify 'databaseOld' and 'databaseNew' configurations.

```json5
{
  // ...
  "databaseDriver": "migration",
  "databaseOld": {
    "databaseDriver": "file",
    "databaseName": "world"
  },
  "databaseNew": {
    "databaseDriver": "mongodb"
    // ...
  }
  // ...
}
```

--------------------------------

### Get Text Depth

Source: https://github.com/skyrim-multiplayer/skymp/blob/main/skyrim-platform/src/platform_se/codegen/convert-files/Definitions.txt

Retrieves the current depth (layering) of a text element.

```typescript
export declare function getTextDepth(textId: number): number;
```

--------------------------------

### Configure Skyrim Platform Library (CMake)

Source: https://github.com/skyrim-multiplayer/skymp/blob/main/skyrim-platform/src/platform_lib/CMakeLists.txt

Sets up the build for the platform_lib static library on MSVC. It includes default settings, finds all source files, defines the library, and links external dependencies.

```cmake
if(MSVC)
    include(${CMAKE_SOURCE_DIR}/cmake/apply_default_settings.cmake)

    file(GLOB_RECURSE sources "${CMAKE_CURRENT_SOURCE_DIR}/*.h" "${CMAKE_CURRENT_SOURCE_DIR}/*.cpp")
    add_library(platform_lib STATIC ${sources})
    target_link_libraries(platform_lib PUBLIC viet)
    target_include_directories(platform_lib PUBLIC ${CMAKE_CURRENT_SOURCE_DIR})
    target_include_directories(platform_lib PUBLIC "${CMAKE_SOURCE_DIR}/1js")
    target_include_directories(platform_lib PUBLIC "${SKYRIM_PLATFORM_SOURCE_DIR}/src/third_party")

    find_package(unofficial-node-addon-api REQUIRED)
    target_link_libraries(platform_lib PUBLIC unofficial::node-addon-api::node-addon-api)

    apply_default_settings(TARGETS platform_lib)
endif()
```

--------------------------------

### Get Text Font

Source: https://github.com/skyrim-multiplayer/skymp/blob/main/skyrim-platform/src/platform_se/codegen/convert-files/Definitions.txt

Retrieves the current font face of a text element.

```typescript
export declare function getTextFont(textId: number): string;
```

--------------------------------

### Get Text Rotation

Source: https://github.com/skyrim-multiplayer/skymp/blob/main/skyrim-platform/src/platform_se/codegen/convert-files/Definitions.txt

Retrieves the current rotation angle of a text element.

```typescript
export declare function getTextRotation(textId: number): number;
```

--------------------------------

### Glob and Add Resource Library for Standard Scripts

Source: https://github.com/skyrim-multiplayer/skymp/blob/main/skymp5-server/CMakeLists.txt

Finds all files in the standard_scripts directory and creates a resource library named server_standard_scripts. It then applies default settings to this library.

```cmake
file(GLOB_RECURSE standard_scripts
  ${CMAKE_CURRENT_SOURCE_DIR}/standard_scripts/*
)
cmrc_add_resource_library(server_standard_scripts ${standard_scripts}
  NAMESPACE server_standard_scripts
)
apply_default_settings(TARGETS server_standard_scripts)
```

--------------------------------

### Get Text Size

Source: https://github.com/skyrim-multiplayer/skymp/blob/main/skyrim-platform/src/platform_se/codegen/convert-files/Definitions.txt

Retrieves the current font size of a text element.

```typescript
export declare function getTextSize(textId: number): number;
```

--------------------------------

### Include MakeID and spdlog dependencies

Source: https://github.com/skyrim-multiplayer/skymp/blob/main/viet/CMakeLists.txt

Finds the MakeID header directory and links the 'viet' library with the spdlog logging library. Ensure spdlog is configured correctly for the project.

```cmake
find_path(MAKEID_INCLUDE_DIR NAMES MakeID.h)
target_include_directories(viet PUBLIC ${MAKEID_INCLUDE_DIR})

find_package(spdlog CONFIG REQUIRED)
target_link_libraries(viet PUBLIC spdlog::spdlog)
```

--------------------------------

### Get Text String

Source: https://github.com/skyrim-multiplayer/skymp/blob/main/skyrim-platform/src/platform_se/codegen/convert-files/Definitions.txt

Retrieves the current text content of a text element.

```typescript
export declare function getTextString(textId: number): string;
```

--------------------------------

### Get Text Visibility

Source: https://github.com/skyrim-multiplayer/skymp/blob/main/skyrim-platform/src/platform_se/codegen/convert-files/Definitions.txt

Retrieves the current visibility setting for all text elements.

```typescript
export declare function getTextsVisibility(): 'inheritBrowser' | 'off' | 'on';
```

--------------------------------

### Configure Project with CMake (Release)

Source: https://github.com/skyrim-multiplayer/skymp/blob/main/CONTRIBUTING.md

Configure the project for a production environment using a Release build type. This optimizes the build for performance.

```bash
./build.sh --configure -DCMAKE_BUILD_TYPE=Release
```

--------------------------------

### Handle Non-Native Papyrus Function Calls in JavaScript

Source: https://github.com/skyrim-multiplayer/skymp/blob/main/docs/release/sp-2.7.md

Demonstrates how Skyrim Platform now throws JavaScript exceptions for non-native function calls instead of crashing. This example shows a typical update loop logging player health and an example of a non-native function call that would previously crash but now throws an exception.

```javascript
sp = skyrimPlatform;
sp.on("update", () => {
  sp.printConsole(sp.Game.getplayer().getActorValuePercentage("health")); 
  // ^ "1"

  sp.printConsole(sp.Game.getplayer().getAVPercentage("health")); 
  // ^ "[Exception] Function is not native 'Actor.getAVPercentage'"
  // No crash in the new version
});
```

--------------------------------

### Windows Launch Script Generation

Source: https://github.com/skyrim-multiplayer/skymp/blob/main/skymp5-server/CMakeLists.txt

Generates batch files for launching the server on Windows, for both release and development.

```cmake
if(WIN32)
  # On Windows create launch_server.bat in ./build/dist/server
  # This .bat file is for launching the server
  set(bat "node dist_back/skymp5-server.js\n")
  set(bat "${bat}pause\n")
  file(WRITE ${PROJECT_BINARY_DIR}/launch_server.bat.tmp "${bat}")

  # Same but for dev (no pause, placed into ./build dir)
  set(bat "@echo off\n") # Turn off command echoing
  set(bat "${bat}setlocal\n") # setlocal/endlocal is for temporary cd
  set(bat "${bat}cd dist/server\n")
  set(bat "${bat}node dist_back/skymp5-server.js\n")
  set(bat "${bat}set EXIT_CODE=%ERRORLEVEL%\n")
  set(bat "${bat}endlocal & exit /B %EXIT_CODE%\n")
  file(WRITE ${CMAKE_BINARY_DIR}/launch_server.bat "${bat}")

  add_custom_command(
    TARGET ${PROJECT_NAME} POST_BUILD
    COMMAND ${CMAKE_COMMAND} -E copy ${PROJECT_BINARY_DIR}/launch_server.bat.tmp ${CMAKE_BINARY_DIR}/dist/server/launch_server.bat
  )
endif()
```

--------------------------------

### Get Text Origin

Source: https://github.com/skyrim-multiplayer/skymp/blob/main/skyrim-platform/src/platform_se/codegen/convert-files/Definitions.txt

Retrieves the origin point used for rendering a text element.

```typescript
export declare function getTextOrigin(textId: number): number[];
```

--------------------------------

### Quest Events

Source: https://github.com/skyrim-multiplayer/skymp/blob/main/skyrim-platform/src/platform_se/codegen/convert-files/Definitions.txt

Subscribe to events related to quest status changes, such as starting, stopping, or stage progression.

```APIDOC
## onQuestStart

### Description
Registers a callback function to be executed when a quest starts.

### Signature
`on(eventName: 'questStart', callback: (event: QuestStartStopEvent) => void): EventHandle`

## onceQuestStart

### Description
Registers a callback function to be executed once when a quest starts.

### Signature
`once(eventName: 'questStart', callback: (event: QuestStartStopEvent) => void): EventHandle`

## onQuestStop

### Description
Registers a callback function to be executed when a quest stops.

### Signature
`on(eventName: 'questStop', callback: (event: QuestStartStopEvent) => void): EventHandle`

## onceQuestStop

### Description
Registers a callback function to be executed once when a quest stops.

### Signature
`once(eventName: 'questStop', callback: (event: QuestStartStopEvent) => void): EventHandle`

## onQuestStage

### Description
Registers a callback function to be executed when a quest stage changes.

### Signature
`on(eventName: 'questStage', callback: (event: QuestStageEvent) => void): EventHandle`

## onceQuestStage

### Description
Registers a callback function to be executed once when a quest stage changes.

### Signature
`once(eventName: 'questStage', callback: (event: QuestStageEvent) => void): EventHandle`
```

--------------------------------

### Get Server Public Key

Source: https://github.com/skyrim-multiplayer/skymp/blob/main/docs/docs_deploy.md

Obtain the server's public SSH key for known hosts configuration.

```bash
ssh-keyscan <server ip>
<...>
# <server ip>:22 SSH-2.0-OpenSSH_8.2p1 Ubuntu-4ubuntu0.2
<server ip> ecdsa-sha2-nistp256 AAAAE<...>
<...>
```

--------------------------------

### Configure File Database Driver

Source: https://github.com/skyrim-multiplayer/skymp/blob/main/docs/docs_database_drivers.md

Use the 'file' driver for default local storage. Set 'databaseName' to specify the subdirectory within the server folder. Only relative paths are supported.

```json5
{
  // ...
  "databaseDriver": "file",
  "databaseName": "world"
  // ...
}
```

--------------------------------

### AI Package Events

Source: https://github.com/skyrim-multiplayer/skymp/blob/main/skyrim-platform/src/platform_se/codegen/convert-files/Definitions.txt

Handle events related to AI package execution, including starting, changing, and ending.

```APIDOC
## onPackageStart

### Description
Registers a callback function to be executed when an AI package starts.

### Signature
`on(eventName: 'packageStart', callback: (event: PackageEvent) => void): EventHandle`

## oncePackageStart

### Description
Registers a callback function to be executed once when an AI package starts.

### Signature
`once(eventName: 'packageStart', callback: (event: PackageEvent) => void): EventHandle`

## onPackageChange

### Description
Registers a callback function to be executed when an AI package changes.

### Signature
`on(eventName: 'packageChange', callback: (event: PackageEvent) => void): EventHandle`

## oncePackageChange

### Description
Registers a callback function to be executed once when an AI package changes.

### Signature
`once(eventName: 'packageChange', callback: (event: PackageEvent) => void): EventHandle`

## onPackageEnd

### Description
Registers a callback function to be executed when an AI package ends.

### Signature
`on(eventName: 'packageEnd', callback: (event: PackageEvent) => void): EventHandle`

## oncePackageEnd

### Description
Registers a callback function to be executed once when an AI package ends.

### Signature
`once(eventName: 'packageEnd', callback: (event: PackageEvent) => void): EventHandle`
```

--------------------------------

### Get Custom Property Value

Source: https://github.com/skyrim-multiplayer/skymp/blob/main/docs/docs_clientside_scripting_reference.md

Retrieve the value of a custom property using `ctx.get()`. Built-in properties are not reliably supported.

```typescript
const v = ctx.get("myAwesomeProperty");
```

--------------------------------

### Project and Source File Configuration

Source: https://github.com/skyrim-multiplayer/skymp/blob/main/savefile/CMakeLists.txt

Defines the project name and recursively finds all C++ and header files in the src and include directories. It also appends a .clang-format file to the source list.

```cmake
project(savefile)
include(${CMAKE_SOURCE_DIR}/cmake/apply_default_settings.cmake)

file(GLOB_RECURSE savefile_src "${CMAKE_CURRENT_LIST_DIR}/src/*.cpp" "${CMAKE_CURRENT_LIST_DIR}/src/*.h" "${CMAKE_CURRENT_LIST_DIR}/include/*.h")

list(APPEND savefile_src ${CMAKE_SOURCE_DIR}/.clang-format)
```

--------------------------------

### Handle the 'unequip' Event

Source: https://github.com/skyrim-multiplayer/skymp/blob/main/docs/skyrim_platform/new_events.md

The `unequip` event is triggered when an Actor unequips an item. This example specifically checks if the player unequips a weapon.

```typescript
import { on } from "skyrimPlatform";

on("unequip", (event) => {
  if (event.actor.getFormID() !== Game.getPlayer()?.getFormID()) return;

  const w = Weapon.from(event.baseObj);

  if (w) {
    printConsole("Player unequipped a weapon");
  }
})
```

--------------------------------

### Get equipped item type

Source: https://github.com/skyrim-multiplayer/skymp/blob/main/docs/skyrim_platform/new_types.md

Uses the EquippedItemType enum to determine the type of an equipped item. Note that Battleaxes and Warhammers share the same value.

```typescript
player.getEquippedItemType(0) === EquippedItemType.Sword;
```

```typescript
player.getEquippedItemType(0) === EquippedItemType.Torch;
```

--------------------------------

### Run Docker Container for Linux Build Dependencies

Source: https://github.com/skyrim-multiplayer/skymp/blob/main/CONTRIBUTING.md

Uses a Docker image with pre-installed dependencies to build the server on Linux, useful for unsupported distributions or to avoid manual dependency management.

```bash
. misc/github_env_linux; docker run -it --rm -v "$PWD:$PWD" -w "$PWD" -u "`id -u`:`id -g`" \
    $SKYMP_VCPKG_DEPS_IMAGE bash
```

--------------------------------

### Define Build Options

Source: https://github.com/skyrim-multiplayer/skymp/blob/main/CMakeLists.txt

Defines boolean options for the build, such as SKYRIM_VR, BUILD_NODEJS, PREPARE_NEXUS_ARCHIVES, BUILD_UNIT_TESTS, INSTALL_CLIENT_DIST, BUILD_GAMEMODE, BUILD_CLIENT, BUILD_FRONT, BUILD_SKYRIM_PLATFORM, BUILD_SCRIPTS, and OFFLINE_MODE. These options control which features are included in the build.

```cmake
option(SKYRIM_VR "Skyrim VR (1.4) build" OFF)
option(BUILD_NODEJS "Build NodeJS port if ON, use a pre-built otherwise" OFF)
```

```cmake
option(PREPARE_NEXUS_ARCHIVES "Prepare SP and other archives during build or not" OFF)
option(BUILD_UNIT_TESTS "Build unit tests (excluded from build when off - workaround for #1182)" ON)
option(INSTALL_CLIENT_DIST "Install the client into SKYRIM_DIR after build" OFF)
option(BUILD_GAMEMODE "Build gamemode" OFF)
option(BUILD_CLIENT "Build client" ON)
option(BUILD_FRONT "Build front" OFF)
option(BUILD_SKYRIM_PLATFORM "Build Skyrim Platform" ON)
option(BUILD_SCRIPTS "Build skymp5-scripts and Papyrus scripts in skyrim-platform" ON)
option(OFFLINE_MODE "Enable offline mode in generated server settings and client settings" ON)
```

--------------------------------

### Get Reference Position

Source: https://github.com/skyrim-multiplayer/skymp/blob/main/docs/docs_clientside_scripting_reference.md

In `updateOwner` and `updateNeighbor` contexts, `ctx.refr` refers to the current object reference. This snippet shows how to retrieve its 3D coordinates.

```typescript
const pos = [
  ctx.refr.getPositionX(),
  ctx.refr.getPositionY(),
  ctx.refr.getPositionZ()
];
```

--------------------------------

### ctx.respawn()

Source: https://github.com/skyrim-multiplayer/skymp/blob/main/docs/docs_clientside_scripting_reference.md

Respawns the `ctx.refr` immediately.

```APIDOC
## ctx.respawn()

### Description
Respawns `ctx.refr` immediately.

### Usage
```typescript
ctx.respawn();
```
```

--------------------------------

### Utility Wait Example

Source: https://github.com/skyrim-multiplayer/skymp/blob/main/docs/skyrim_platform/native.md

The Utility.wait() function returns a Promise that resolves after a specified duration. It's useful for introducing delays in script execution.

```typescript
Utility.wait(1).then(() => printConsole("1 second passed"));
```

--------------------------------

### Check Browser Visibility and Focus

Source: https://github.com/skyrim-multiplayer/skymp/blob/main/docs/release/sp-2.4.md

Use these methods to get the current state of the browser window's visibility and focus. No specific imports are required.

```typescript
printConsole("isVisible:", browser.isVisible());
printConsole("isFocused:", browser.isFocused());
```

--------------------------------

### Get property value

Source: https://github.com/skyrim-multiplayer/skymp/blob/main/docs/docs_serverside_scripting_reference.md

Use `mp.get` to retrieve the current value of a specified property for a given form ID. Returns `undefined` if the property does not exist.

```typescript
interface Mp {
  get(formId: number, propertyName: string): void;
}

mp.get(0xff000000, "type");
mp.get(0xff000000, "pos");
mp.get(0xff000000, "myAwesomeProperty");
```

--------------------------------

### Handle the 'tick' Event

Source: https://github.com/skyrim-multiplayer/skymp/blob/main/docs/skyrim_platform/new_events.md

The `tick` event is called every frame immediately after the game starts. Note that this event does not have access to game methods and objects.

```typescript
import { on } from "skyrimPlatform";

on("tick", () => {
  // No access to game methods here.
});
```

--------------------------------

### Build with Parallel Processing

Source: https://github.com/skyrim-multiplayer/skymp/blob/main/CONTRIBUTING.md

Utilize all available CPU threads for the build process by adding the `--parallel $(nproc)` argument. This can significantly speed up build times.

```bash
cd build
../build.sh --build --parallel $(nproc)
```

--------------------------------

### Define Unique Mod Key

Source: https://github.com/skyrim-multiplayer/skymp/blob/main/docs/skyrim_platform/cookbook.md

Create a unique key name for your mod to avoid conflicts with other mods. The key must start with a '.' and should not contain spaces.

```typescript
const key = ".my-unique-mod-name";
```

--------------------------------

### Set Output Directories

Source: https://github.com/skyrim-multiplayer/skymp/blob/main/skyrim-platform/src/platform_se/CMakeLists.txt

Sets the runtime and PDB output directories for specific targets.

```cmake
set_target_properties(skyrim_platform SkyrimPlatformCEF skyrim_platform_entry PROPERTIES
  RUNTIME_OUTPUT_DIRECTORY "bin"
  PDB_OUTPUT_DIRECTORY "bin"
)
```

--------------------------------

### Link Server Guest Library

Source: https://github.com/skyrim-multiplayer/skymp/blob/main/skymp5-server/CMakeLists.txt

Links the server_guest_lib target with the server_standard_scripts resource library.

```cmake
target_link_libraries(server_guest_lib PUBLIC server_standard_scripts)
```

--------------------------------

### on/once

Source: https://github.com/skyrim-multiplayer/skymp/blob/main/docs/skyrim_platform/new_methods.md

Subscribes to game events. `on` subscribes to an event and will trigger the callback every time the event occurs, while `once` subscribes to an event and will trigger the callback only the first time the event occurs.

```APIDOC
## on/once

### Description
Subscribes to game events. `on` subscribes to an event and will trigger the callback every time the event occurs, while `once` subscribes to an event and will trigger the callback only the first time the event occurs.

### Method Signatures
`on (eventName: string, callback: any): void`
`once (eventName: string, callback: any): void`
```

--------------------------------

### Dynamically Add and Remove Hooks

Source: https://github.com/skyrim-multiplayer/skymp/blob/main/docs/skyrim_platform/events.md

Example of dynamically adding and removing animation event hooks based on game events like `effectStart` and `effectFinish`.

```typescript
var id;

export let main = () => {
  on('effectStart', () => {
    id = hooks.sendAnimationEvent.add({...});
  });
  
  on('effectFinish', () => {
    if (id) {
      hooks.sendAnimationEvent.remove(id);
    }
  });
};


```

--------------------------------

### Configure TSConverter JSON Dependency

Source: https://github.com/skyrim-multiplayer/skymp/blob/main/skyrim-platform/src/platform_se/CMakeLists.txt

This snippet finds the JSON header files and adds them to the include directories for the TSConverter target. It assumes nlohmann/json is installed.

```cmake
if(TARGET TSConverter)
  find_path(JSON_INCLUDE_DIR NAMES json.hpp PATH_SUFFIXES nlohmann)
  get_filename_component(JSON_INCLUDE_DIR ${JSON_INCLUDE_DIR} DIRECTORY)
  target_include_directories(TSConverter PUBLIC ${JSON_INCLUDE_DIR})
endif()
```

--------------------------------

### Clone Repository and Initialize Submodules

Source: https://github.com/skyrim-multiplayer/skymp/blob/main/CONTRIBUTING.md

Clones the Skyrim Multiplayer repository and initializes/updates its submodules. This ensures all necessary dependencies and components are downloaded.

```bash
git clone https://github.com/skyrim-multiplayer/skymp.git
cd skymp
git submodule init
git submodule update
```

--------------------------------

### Get cell reference count by form type

Source: https://github.com/skyrim-multiplayer/skymp/blob/main/docs/skyrim_platform/new_types.md

Uses the FormType enum to specify the type of form when counting references in a cell. Ensure FormType is imported.

```typescript
cell.getNumRefs(FormType.NPC);
```

```typescript
myBook.getType() === FormType.Book;
```

--------------------------------

### Browser Interface

Source: https://github.com/skyrim-multiplayer/skymp/blob/main/skyrim-platform/src/platform_se/codegen/convert-files/Definitions.txt

Controls the in-game browser.

```APIDOC
## Browser Interface (`browser`)

### Description
Provides control over the in-game browser.

### Methods
#### setVisible(visible: boolean): void
Sets the visibility of the browser.

#### isVisible(): boolean
Checks if the browser is currently visible.

#### setFocused(focused: boolean): void
Sets the focus state of the browser.

#### isFocused(): boolean
Checks if the browser is currently focused.

#### loadUrl(url: string): void
Loads the specified URL in the browser.

#### executeJavaScript(src: string): void
Executes the provided JavaScript code within the browser.
```

--------------------------------

### Global Storage and Settings

Source: https://github.com/skyrim-multiplayer/skymp/blob/main/skyrim-platform/src/platform_se/codegen/convert-files/Definitions.txt

Access to global storage and settings objects.

```APIDOC
## Global Storage and Settings

### Description
Provides access to global key-value storage and configuration settings.

### Variables
#### storage: Record<string, unknown>
A global object for storing arbitrary data.

#### settings: Record<string, Record<string, unknown>>
A global object for storing nested settings.
```

--------------------------------

### Get Integer INI Setting

Source: https://github.com/skyrim-multiplayer/skymp/blob/main/docs/skyrim_platform/ini_settings.md

Use this to retrieve an integer value from the INI settings. Specify the section, key, and a default value to return if the key is not found.

```c++
settings->GetInteger("Debug", "LogLevel", spdlog::level::level_enum::info);
```

--------------------------------

### Load Plugins with WebPack using Plain JavaScript

Source: https://github.com/skyrim-multiplayer/skymp/blob/main/docs/release/sp-2.1.md

Demonstrates loading plugins using plain JavaScript, supported alongside WebPack. Ensure the `sp` variable is assigned to `skyrimPlatform`.

```javascript
// Data/Platform/Plugins/test.js
sp = skyrimPlatform;

sp.printConsole("Hello JS");
```

--------------------------------

### Open URL in System Browser

Source: https://github.com/skyrim-multiplayer/skymp/blob/main/docs/release/sp-2.4.md

Open a given URL in the user's default system browser. Currently, only URLs starting with 'https://' are supported.

```typescript
win32.loadUrl("https://github.com/skyrim-multiplayer/skymp");
```

--------------------------------

### Run Specific Unit Test by Tag

Source: https://github.com/skyrim-multiplayer/skymp/blob/main/CLAUDE.md

This command allows you to run a particular unit test, filtered by tags. Navigate to the build directory first. Replace '[Respawn]' with the desired test tag.

```bash
cd build
./unit/unit [Respawn]

```

--------------------------------

### Verify Plugin Output in Skyrim Console

Source: https://github.com/skyrim-multiplayer/skymp/blob/main/skymp5-client/README.md

After successful compilation and copying, run Skyrim and open the console (~). If the plugin is running correctly, you should see '[Script] Hello! You can view this in the Skyrim ~ console on the Main Menu when the game runs'.

```plaintext
[Script] Hello! You can view this in the Skyrim ~ console on the Main Menu when the game runs
```