### Docker Quickstart Setup

Source: https://github.com/opentibiabr/canary/blob/main/README.md

Copies the environment file and starts the Docker Compose stack for a local test server.

```bash
cp .env.dist .env
docker compose up -d --build
```

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

### Docker Quickstart Start Script (PowerShell)

Source: https://github.com/opentibiabr/canary/blob/main/README.md

Starts the Docker stack using a PowerShell script, cleaning up leftovers without removing database volumes.

```powershell
.\up.ps1
```

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

### Project and Protobuf Setup

Source: https://github.com/opentibiabr/canary/blob/main/src/protobuf/CMakeLists.txt

Initializes the project and finds the required Protobuf library. Ensure Protobuf is installed and discoverable by CMake.

```cmake
project(protobuf)

find_package(Protobuf REQUIRED)
find_package(Threads)
```

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

### Docker Quickstart

Source: https://github.com/opentibiabr/canary/blob/main/docs/operations.md

Use this command to start the server in detached mode using Docker Compose. Ensure you are in the 'docker' directory.

```bash
cd docker
docker compose up -d
```

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

### Docker Quickstart Start Script (Bash)

Source: https://github.com/opentibiabr/canary/blob/main/README.md

Starts the Docker stack using a Bash script, cleaning up leftovers without removing database volumes.

```bash
sh ./up.sh
```

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

### Local Quickstart Environment Variables

Source: https://github.com/opentibiabr/canary/blob/main/docker/DOCKER.md

Set these variables for local quickstart to define the server IP and game port that the client login server advertises.

```env
CANARY_SERVER_IP=127.0.0.1
CANARY_GAME_PORT=7172
```

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

### Start Docker Stack

Source: https://github.com/opentibiabr/canary/blob/main/docs/development.md

Use this command to start the development environment using Docker Compose. Ensure you are in the 'docker' directory and have copied the .env file.

```bash
cd docker
cp .env.dist .env
docker compose up -d --build
```

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

### Install Build Dependencies on Ubuntu

Source: https://github.com/opentibiabr/canary/blob/main/docs/building/wsl-ubuntu-24.04.md

Installs Git, CMake, build tools, and necessary libraries for compiling Canary. Use this command to set up your build environment.

```bash
sudo apt update
sudo apt install git cmake build-essential autoconf libtool ca-certificates curl zip unzip tar pkg-config ninja-build ccache linux-headers-generic -y
```

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

### Start Docker Compose (Shell)

Source: https://github.com/opentibiabr/canary/blob/main/docker/DOCKER.md

Use the shell script to start Docker Compose, with an option for LAN configuration.

```bash
sh ./up.sh
```

```bash
LAN=true sh ./up.sh
```

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

### Start Canary Server for LAN (Linux/macOS)

Source: https://github.com/opentibiabr/canary/blob/main/docs/docker/quickstart-for-beginners.md

Execute this command to start the Docker stack and enable access from other devices on your local network. It configures the server IP for LAN communication.

```bash
LAN=true sh ./up.sh
```

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

### Player:sendTutorial

Source: https://github.com/opentibiabr/canary/blob/main/docs/lua-api/lua_api.md

Sends a tutorial message or guide to the player.

```APIDOC
## Player:sendTutorial(tutorialId: number)

### Description
Sends a tutorial guide or message to the player, identified by a tutorial ID.

### Method
`Player:sendTutorial`

### Parameters
- **tutorialId** (number) - Required - The ID of the tutorial to send.

### Returns
- `boolean|nil` - Indicates if the tutorial was sent successfully.
```

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

### Start Docker Compose (PowerShell)

Source: https://github.com/opentibiabr/canary/blob/main/docker/DOCKER.md

Use the PowerShell script to start Docker Compose, with an option for LAN configuration.

```powershell
.
up.ps1
```

```powershell
.
up.ps1 -Lan
```

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

### Start Canary Server for LAN (Windows)

Source: https://github.com/opentibiabr/canary/blob/main/docs/docker/quickstart-for-beginners.md

Use this PowerShell command to start the Docker stack and configure it for access from other devices on your local network. It sets the server IP for LAN use.

```powershell
.\up.ps1 -Lan
```

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

### Start Docker Compose

Source: https://github.com/opentibiabr/canary/blob/main/docker/DOCKER.md

Start the Docker Compose services in detached mode with a build.

```bash
docker compose up -d --build
```

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

### Basic GoogleTest Unit Test Example

Source: https://github.com/opentibiabr/canary/blob/main/tests/README.md

A simple GoogleTest example demonstrating a basic assertion. New unit test files should be placed under 'tests/unit' and registered in the nearest CMakeLists.txt.

```cpp
TEST(FooTest, DoesBar) {
	EXPECT_TRUE(true);
}
```

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

### Small Community Infrastructure

Source: https://github.com/opentibiabr/canary/blob/main/docs/operations.md

Recommended starting points for CPU, RAM, and storage for a small community server.

```text
2 CPU Cores
4 GB RAM
50 GB SSD
```

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

### Lua Binding Registration Examples

Source: https://github.com/opentibiabr/canary/blob/main/docs/systems/lua-api-docgen.md

Examples of new Lua binding registrations that are inspected by `check_lua_api_binding_docs.py`. These include methods, global methods, and class registrations.

```text
Lua::registerMethod
Lua::registerGlobalMethod
Lua::registerSharedClass
Lua::registerClass
```

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

### Lua API Examples

Source: https://github.com/opentibiabr/canary/blob/main/docs/development.md

Examples of using the Lua API to interact with game elements. These functions are exposed from C++ to Lua.

```lua
player:addExperience(1000)
```

```lua
player:addItem(2160)
```

```lua
Game.getPlayers()
```

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

### Documenting NetworkMessage Constructor

Source: https://github.com/opentibiabr/canary/blob/main/docs/systems/lua-api-docgen.md

Example of documenting the constructor signature for a callable class.

```APIDOC
## NetworkMessage()

### Description
Creates a new NetworkMessage object.

### Method
NetworkMessage()

### Returns
- **NetworkMessage** - A new instance of NetworkMessage.
```

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

### Add New Event Example

Source: https://github.com/opentibiabr/canary/blob/main/data/json/eventscheduler/README.md

An example of a new event object to be added to the events.json file, demonstrating custom settings for name, dates, script, rates, and appearance.

```json
{
	"name": "Double XP Weekend",
	"startdate": "01/01/2026",
	"enddate": "01/03/2026",
	"script": "double_xp.lua",
	"ingame": {
		"exprate": 200,
		"lootrate": 100,
		"bosslootrate": 150,
		"spawnrate": 120,
		"skillrate": 150
	},
	"description": "Enjoy a double XP weekend with increased boss loot and spawn rates!",
	"colors": {
		"colordark": "#1a2b3c",
		"colorlight": "#3c4d5e"
	},
	"details": {
		"displaypriority": 5,
		"isseasonal": 0,
		"specialevent": 1
	}
}
```

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

### Game.startRaid

Source: https://github.com/opentibiabr/canary/blob/main/docs/lua-api/lua_api.md

Starts a raid in the game.

```APIDOC
## Game.startRaid

### Description
Starts a raid in the game.

### Method
`Game.startRaid(raidName: string)`

### Parameters
#### Path Parameters
- **raidName** (string) - Required - The name of the raid to start.

### Returns
`number`
```

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

### Medium Community Infrastructure

Source: https://github.com/opentibiabr/canary/blob/main/docs/operations.md

Recommended starting points for CPU, RAM, and storage for a medium community server.

```text
4 CPU Cores
8 GB RAM
100 GB SSD
```

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

### Large Community Infrastructure

Source: https://github.com/opentibiabr/canary/blob/main/docs/operations.md

Recommended starting points for CPU, RAM, and storage for a large community server.

```text
8+ CPU Cores
16+ GB RAM
NVMe Storage
```

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

### Install Build Dependencies on Debian

Source: https://github.com/opentibiabr/canary/blob/main/docs/building/wsl-debian.md

Installs essential build tools and libraries required for compiling Canary, including Git, CMake, a C++ compiler, and other development utilities.

```bash
sudo apt update
sudo apt install git cmake build-essential autoconf libtool ca-certificates curl zip unzip tar pkg-config ninja-build ccache linux-headers-amd64 -y
```

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

### Update GCC to Version 14

Source: https://github.com/opentibiabr/canary/blob/main/docs/building/ubuntu-24.04.md

Installs GCC and G++ version 14 and configures system alternatives to use them as the default. Verifies the installation by printing the versions.

```bash
sudo apt update
sudo apt install gcc-14 g++-14 -y
sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-14 100 --slave /usr/bin/g++ g++ /usr/bin/g++-14 --slave /usr/bin/gcov gcov /usr/bin/gcov-14
sudo update-alternatives --set gcc /usr/bin/gcc-14
gcc-14 --version
g++-14 --version
```

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

### Register Creature Callback

Source: https://github.com/opentibiabr/canary/wiki/Revscriptsys-(EventCallback)

Example of registering a creatureOnAreaCombat callback to handle combat logic.

```lua
local callback = EventCallback()

function callback.creatureOnAreaCombat(creature, tile, isAggressive)
	-- custom behavior when a creature enters combat area
	return true
end

callback:register()
```

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

### Install Required Software for Canary Build

Source: https://github.com/opentibiabr/canary/blob/main/docs/building/debian.md

Installs Git, CMake, build tools, and essential libraries for compiling Canary on Debian. This command ensures all dependencies are met before proceeding with the build.

```bash
sudo apt update
sudo apt install git cmake build-essential autoconf libtool ca-certificates curl zip unzip tar pkg-config ninja-build ccache linux-headers-$(uname -r) -y
```

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

### Register Party Callback

Source: https://github.com/opentibiabr/canary/wiki/Revscriptsys-(EventCallback)

Example of registering a partyOnJoin callback to handle party membership events.

```lua
local callback = EventCallback()

function callback.partyOnJoin(party, player)
	-- custom behavior when a player joins a party
end

callback:register()
```

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

### Register Player Callback

Source: https://github.com/opentibiabr/canary/wiki/Revscriptsys-(EventCallback)

Example of registering a playerOnLook callback to handle player interaction events.

```lua
local callback = EventCallback()

function callback.playerOnLook(player, position, thing, stackpos, lookDistance)
	-- custom behavior when a player looks at something
end

callback:register()
```

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

### Run VSCode Lua API Setup Script

Source: https://github.com/opentibiabr/canary/blob/main/docs/systems/lua-api-docgen.md

Execute the PowerShell script to set up VSCode for Lua API documentation.

```powershell
powershell -ExecutionPolicy Bypass -File tools/setup_vscode_lua_api.ps1
```

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

### Register NPC Callback

Source: https://github.com/opentibiabr/canary/wiki/Revscriptsys-(EventCallback)

Example of registering an npcOnSpawn callback to handle NPC spawning events.

```lua
local callback = EventCallback()

function callback.npcOnSpawn(npc, position)
	-- custom behavior when a npc spawns
end

callback:register()
```

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

### Documenting Player:addItem Binding

Source: https://github.com/opentibiabr/canary/blob/main/docs/systems/lua-api-docgen.md

Example of documenting a specific Lua function binding for the Player class using a docblock.

```APIDOC
## Player:addItem

### Description
Adds an item to the player's inventory.

### Method
Player:addItem

### Parameters
#### Path Parameters
- **itemId** (number|string) - Required - The ID of the item to add.
- **count** (number) - Optional - The number of items to add.
- **canDropOnMap** (boolean) - Optional - Whether the item can be dropped on the map.

### Returns
- **Item|Item[]|nil|false** - The added item(s), nil if not added, or false on failure.
```

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

### Register Monster Callback

Source: https://github.com/opentibiabr/canary/wiki/Revscriptsys-(EventCallback)

Example of registering a monsterOnSpawn callback to handle monster spawning events.

```lua
local callback = EventCallback()

function callback.monsterOnSpawn(monster, position)
	-- custom behavior when a monster spawns
end

callback:register()
```

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

### Player:getGuid()

Source: https://github.com/opentibiabr/canary/blob/main/docs/lua-api/lua_api.md

Gets the player's unique identifier (GUID). Returns a number or nil.

```APIDOC
## Player:getGuid()

### Description
Gets the player's unique identifier (GUID).

### Returns
- `number|nil`: The player's GUID.
```

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

### Skip Docker Cleanup

Source: https://github.com/opentibiabr/canary/blob/main/docker/DOCKER.md

Use these commands to start the project without performing any Docker cleanup operations.

```powershell
.\up.ps1 -SkipCleanup
```

```bash
SKIP_CLEANUP=true sh ./up.sh
```

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

### Optimize Players Table

Source: https://github.com/opentibiabr/canary/blob/main/docs/operations.md

An example SQL command to optimize the 'players' table, often used during maintenance.

```sql
OPTIMIZE TABLE players;
```

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

### Sensitive Values Examples

Source: https://github.com/opentibiabr/canary/blob/main/docs/operations.md

Lists examples of sensitive information that should be managed securely.

```text
Database Passwords
API Keys
Webhook Tokens
SMTP Credentials
Admin Accounts
```

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

### Startup Loading Time Summary

Source: https://github.com/opentibiabr/canary/blob/main/docs/maps/startup-loading-performance.md

Provides a high-level overview of the time taken for modules and scripts to load after optimizations. This is a key indicator of overall startup performance.

```text
Loaded modules and scripts in 1-2 seconds.
```

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

### Initialize KV Library in C++

Source: https://github.com/opentibiabr/canary/blob/main/src/kv/README.md

Shows how to include the header and initialize the KV instance via constructor injection or the global singleton.

```cpp
#include <kv/kv.h>

// In your class constructor
MyClass(KV &kv) : kv(kv) {}

// Or use the global singleton
KV &kv = g_kv();
```

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

### Set up vcpkg Dependency Manager

Source: https://github.com/opentibiabr/canary/blob/main/docs/building/debian.md

Clones the vcpkg repository and runs its bootstrap script. This prepares the environment for managing project dependencies.

```bash
git clone https://github.com/microsoft/vcpkg
cd vcpkg
./bootstrap-vcpkg.sh
cd ..
```

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

### Setting Up and Using a Test Container

Source: https://github.com/opentibiabr/canary/blob/main/src/lib/di/README.md

Demonstrates setting a test container with a custom logger implementation and retrieving instances through DI::create, inject, and g_logger. Ensures that instances are retrieved from the test container when it's active.

```cpp
{
    di::extension::injector<> injector{};
    DI::setTestContainer(&InMemoryLogger::install(injector));

    auto &logger = dynamic_cast<InMemoryLogger &>(injector.create<Logger &>());
    auto &logger2 = dynamic_cast<InMemoryLogger &>(inject<Logger>());
    auto &logger3 = g_logger();
}
```

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

### Player Event Callbacks

Source: https://github.com/opentibiabr/canary/wiki/Revscriptsys-(EventCallback)

This section details the available event callbacks for Players and provides an example of how to implement a player-related callback.

```APIDOC
## Player Event Callbacks

### Available Functions
- `(bool) playerOnBrowseField`
- `(void) playerOnLook`
- `(void) playerOnLookInBattleList`
- `(void) playerOnLookInTrade`
- `(bool) playerOnLookInShop`
- `(bool) playerOnMoveItem`
- `(void) playerOnItemMoved`
- `(void) playerOnChangeZone`
- `(void) playerOnChangeHazard`
- `(bool) playerOnMoveCreature`
- `(void) playerOnReportRuleViolation`
- `(void) playerOnReportBug`
- `(bool) playerOnTurn`
- `(bool) playerOnTradeRequest`
- `(bool) playerOnTradeAccept`
- `(void) playerOnGainExperience`
- `(void) playerOnLoseExperience`
- `(void) playerOnGainSkillTries`
- `(void) playerOnRemoveCount`
- `(void) playerOnRequestQuestLog`
- `(void) playerOnRequestQuestLine`
- `(void) playerOnStorageUpdate`
- `(void) playerOnCombat`
- `(void) playerOnInventoryUpdate`

### Example Usage (Lua)
```lua
local callback = EventCallback()

function callback.playerOnLook(player, position, thing, stackpos, lookDistance)
	-- Custom behavior when a player looks at something
	print('Player looked at something!')
end

callback:register()
```
```

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

### Run the Canary Server

Source: https://github.com/opentibiabr/canary/blob/main/docs/development.md

Execute the compiled Canary server binary. The server will then proceed through its startup sequence.

```bash
./canary
```

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

### Set and Get Player Storage Value

Source: https://github.com/opentibiabr/canary/blob/main/src/creatures/players/components/README.md

Use this to assign a value to a storage key and retrieve it later. The get operation returns -1 if the key does not exist.

```cpp
// Assign a value to a storage
player.storage().add(1000, 1);

// Read the value
int value = player.storage().get(1000);
if (value != -1) {
	g_logger().info("Storage 1000 = {}", value);
}
```

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

### Create Local Configuration

Source: https://github.com/opentibiabr/canary/blob/main/docs/development.md

Copy the default configuration file to create a local configuration. Modify settings like server name, IP, and database credentials as needed. Avoid committing personal configuration changes.

```bash
cp config.lua.dist config.lua
```

```lua
serverName = "Development Server"
ip = "127.0.0.1"
mysqlHost = "localhost"
mysqlUser = "root"
mysqlPass = "password"
```

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

### Perform Basic KV Operations in C++

Source: https://github.com/opentibiabr/canary/blob/main/src/kv/README.md

Demonstrates setting and retrieving integer values using the KV store.

```cpp
// Set an integer value
kv.set("age", 30);

// Get an integer value
int age = kv.get<int>("age");
```

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

### Build Current Backend (Windows Release)

Source: https://github.com/opentibiabr/canary/blob/main/docs/crypto-backend-evaluation.md

Commands to build the current backend in release mode on Windows. Run from the repository root.

```powershell
cmake --preset windows-release
cmake --build --preset windows-release
```

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

### Manual Project Setup (luarc.json)

Source: https://github.com/opentibiabr/canary/blob/main/docs/systems/lua-api-docgen.md

Configure LuaLS project settings in .luarc.json to include the Lua API documentation. This is an alternative to VSCode's settings.json for project-wide configuration.

```json
{
  "workspace.library": ["docs/lua-api"],
  "workspace.preloadFileSize": 1000,
  "workspace.checkThirdParty": false
}
```

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

### VSCode Manual Workspace Setup (settings.json)

Source: https://github.com/opentibiabr/canary/blob/main/docs/systems/lua-api-docgen.md

Configure VSCode's Lua extension to include the generated Lua API documentation in its workspace library. This ensures editor autocomplete and other features work correctly with the API.

```json
{
  "Lua.workspace.library": [
    "${workspaceFolder}/docs/lua-api"
  ],
  "Lua.workspace.checkThirdParty": false
}
```

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

### Game.getReturnMessage

Source: https://github.com/opentibiabr/canary/blob/main/docs/lua-api/lua_api.md

Gets a return message for a given value.

```APIDOC
## Game.getReturnMessage

### Description
Gets a return message for a given value.

### Method
`Game.getReturnMessage(value: any)`

### Parameters
#### Path Parameters
- **value** (any) - Required - The value to get a return message for.

### Returns
`string`
```

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

### Copy Environment File

Source: https://github.com/opentibiabr/canary/blob/main/docker/DOCKER.md

Copy the distribution environment file to .env before configuring.

```bash
cp .env.dist .env
```

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

### Build and Run Tests (Windows Release)

Source: https://github.com/opentibiabr/canary/blob/main/docs/crypto-backend-evaluation.md

Commands to build the release version with tests enabled and then execute unit and integration tests on Windows. Run from the repository root.

```powershell
cmake --preset windows-release-enabled-tests
cmake --build --preset windows-release-enabled-tests
.uild\windows-release-enabled-tests\tests\unit\canary_ut.exe
.uild\windows-release-enabled-tests\tests\integration\canary_it.exe
```

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

### MonsterType Properties and Methods

Source: https://github.com/opentibiabr/canary/blob/main/docs/lua-api/lua_api.md

Functions to get or set properties of a monster type.

```APIDOC
## MonsterType:outfit

### Description
Gets or sets the outfit of the monster type.

### Parameters
- `outfit` (any, optional) - The outfit to set for the monster type.

### Returns
- `boolean|nil` - Returns true if the outfit was set successfully, nil otherwise. If no argument is provided, it returns the current outfit status.
```

```APIDOC
## MonsterType:race

### Description
Gets or sets the race of the monster type.

### Parameters
- `race` (string, optional) - The race to set for the monster type.

### Returns
- `boolean|number|nil` - Returns true if the race was set successfully, nil otherwise. If no argument is provided, it returns the current race status.
```

```APIDOC
## MonsterType:raceId

### Description
Gets or sets the race ID of the monster type.

### Parameters
- `arg2` (number, optional) - The race ID to set for the monster type.

### Returns
- `boolean|number|nil` - Returns true if the race ID was set successfully, nil otherwise. If no argument is provided, it returns the current race ID status.
```

```APIDOC
## MonsterType:registerEvent

### Description
Registers a specific event for the monster type.

### Parameters
- `name` (string) - The name of the event to register.

### Returns
- `boolean|nil` - Returns true if the event was registered successfully, nil otherwise.
```

```APIDOC
## MonsterType:respawnTypeIsUnderground

### Description
Gets or sets whether the monster type's respawn is underground.

### Parameters
- `arg2` (any, optional) - A value to set the underground respawn status.

### Returns
- `boolean|number|nil` - Returns a boolean or number indicating the status. If an argument is provided, it attempts to set the status.
```

```APIDOC
## MonsterType:runHealth

### Description
Gets or sets a value related to the monster's health behavior during running.

### Parameters
- `arg2` (number, optional) - A numerical value to set.

### Returns
- `boolean|number|nil` - Returns a boolean or number indicating the status. If an argument is provided, it attempts to set the value.
```

```APIDOC
## MonsterType:soundChance

### Description
Gets or sets the chance for the monster to make a sound.

### Parameters
- `arg2` (number, optional) - The chance value to set.

### Returns
- `boolean|number` - Returns a boolean or number indicating the status. If an argument is provided, it attempts to set the value.
```

```APIDOC
## MonsterType:soundSpeedTicks

### Description
Gets or sets the tick duration for monster sounds.

### Parameters
- `arg2` (number, optional) - The tick duration to set.

### Returns
- `boolean|number` - Returns a boolean or number indicating the status. If an argument is provided, it attempts to set the value.
```

```APIDOC
## MonsterType:staticAttackChance

### Description
Gets or sets the chance for a monster to perform a static attack.

### Parameters
- `arg2` (number, optional) - The chance value to set.

### Returns
- `boolean|number|nil` - Returns a boolean or number indicating the status. If an argument is provided, it attempts to set the value.
```

```APIDOC
## MonsterType:strategiesTargetDamage

### Description
Gets or sets a strategy related to targeting based on damage.

### Parameters
- `arg2` (number, optional) - A numerical value to set.

### Returns
- `boolean|number|nil` - Returns a boolean or number indicating the status. If an argument is provided, it attempts to set the value.
```

```APIDOC
## MonsterType:strategiesTargetHealth

### Description
Gets or sets a strategy related to targeting based on health.

### Parameters
- `arg2` (number, optional) - A numerical value to set.

### Returns
- `boolean|number|nil` - Returns a boolean or number indicating the status. If an argument is provided, it attempts to set the value.
```

```APIDOC
## MonsterType:strategiesTargetNearest

### Description
Gets or sets a strategy related to targeting the nearest entity.

### Parameters
- `arg2` (number, optional) - A numerical value to set.

### Returns
- `boolean|number|nil` - Returns a boolean or number indicating the status. If an argument is provided, it attempts to set the value.
```

```APIDOC
## MonsterType:strategiesTargetRandom

### Description
Gets or sets a strategy related to targeting randomly.

### Parameters
- `arg2` (number, optional) - A numerical value to set.

### Returns
- `boolean|number|nil` - Returns a boolean or number indicating the status. If an argument is provided, it attempts to set the value.
```

```APIDOC
## MonsterType:targetDistance

### Description
Gets or sets the target distance for the monster.

### Parameters
- `arg2` (number, optional) - The target distance to set.

### Returns
- `boolean|number|nil` - Returns a boolean or number indicating the status. If an argument is provided, it attempts to set the value.
```

```APIDOC
## MonsterType:targetPreferMaster

### Description
Gets or sets whether the monster prefers its master as a target.

### Parameters
- `arg2` (boolean, optional) - A boolean value to set.

### Returns
- `boolean|number|nil` - Returns a boolean or number indicating the status. If an argument is provided, it attempts to set the value.
```

```APIDOC
## MonsterType:targetPreferPlayer

### Description
Gets or sets whether the monster prefers players as targets.

### Parameters
- `arg2` (boolean, optional) - A boolean value to set.

### Returns
- `boolean|nil` - Returns a boolean indicating the status. If an argument is provided, it attempts to set the value.
```

```APIDOC
## MonsterType:variant

### Description
Gets or sets the variant of the monster type.

### Parameters
- `arg2` (string, optional) - The variant string to set.

### Returns
- `boolean|string` - Returns a boolean or string indicating the status. If an argument is provided, it attempts to set the value.
```

```APIDOC
## MonsterType:yellChance

### Description
Gets or sets the chance for the monster to yell.

### Parameters
- `arg2` (number, optional) - The chance value to set.

### Returns
- `boolean|number|nil` - Returns a boolean or number indicating the status. If an argument is provided, it attempts to set the value.
```

```APIDOC
## MonsterType:yellSpeedTicks

### Description
Gets or sets the tick duration for monster yells.

### Parameters
- `arg2` (number, optional) - The tick duration to set.

### Returns
- `boolean|number|nil` - Returns a boolean or number indicating the status. If an argument is provided, it attempts to set the value.
```

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

### MonsterType:faction

Source: https://github.com/opentibiabr/canary/blob/main/docs/lua-api/lua_api.md

Gets or sets the faction for the monster. Accepts an optional argument.

```APIDOC
## MonsterType:faction

### Description
Gets or sets the faction for the monster.

### Method
`MonsterType:faction(arg2?: any)`

### Parameters
- **arg2** (any) - Optional - The faction value to set.

### Returns
- `boolean|number|nil` - Returns a boolean indicating success, the current faction value if no argument is provided, or nil on failure.
```

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

### Clone and Bootstrap vcpkg

Source: https://github.com/opentibiabr/canary/blob/main/docs/building/windows-(cmake).md

Clone the vcpkg repository, navigate into it, and run the bootstrap script to prepare it for use. This is a prerequisite for managing project dependencies.

```powershell
git clone https://github.com/microsoft/vcpkg
cd vcpkg
.ootstrap-vcpkg.bat
.\
```

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

### Documenting TalkAction:onSay Binding

Source: https://github.com/opentibiabr/canary/blob/main/docs/systems/lua-api-docgen.md

Example of documenting multiple Lua names sharing a single C++ handler using a registration-level docblock.

```APIDOC
## TalkAction:onSay

### Description
Handles the 'onSay' event for TalkActions.

### Method
TalkAction:onSay

### Parameters
#### Path Parameters
- **callback** (fun(player: Player, words: string, param: string, type: integer): boolean) - Required - The callback function to execute.

### Returns
- **boolean** - Indicates if the action was successful.
```

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

### Add Offer to Category

Source: https://github.com/opentibiabr/canary/blob/main/data/modules/scripts/gamestore/readme.md

Example of adding a new offer to a category file. Ensure all required fields like 'icons', 'name', and 'price' are provided. Optional fields can be omitted.

```lua
offers = {
    {
        icons = { "item.png" },
        name = "Example Offer",
        price = 100
    }
}
```

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

### Player:getManaSpent()

Source: https://github.com/opentibiabr/canary/blob/main/docs/lua-api/lua_api.md

Gets the total mana the player has spent. Returns a number or nil.

```APIDOC
## Player:getManaSpent()

### Description
Gets the total mana the player has spent.

### Returns
- `number|nil`: The total mana spent by the player.
```

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

### Verify vcpkg Environment Setup

Source: https://github.com/opentibiabr/canary/blob/main/docs/building/debian.md

Checks if the VCPKG_ROOT environment variable is set correctly and if the vcpkg toolchain file exists. This is a crucial step to confirm vcpkg is ready for use.

```bash
echo $VCPKG_ROOT
# Expected output:
# /home/<user>/vcpkg
```

```bash
test -f "$VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake" && echo "vcpkg OK" || echo "vcpkg not found"
```

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

### Player:getLoyaltyTitle()

Source: https://github.com/opentibiabr/canary/blob/main/docs/lua-api/lua_api.md

Gets the player's loyalty title. Returns a string or nil.

```APIDOC
## Player:getLoyaltyTitle()

### Description
Gets the player's loyalty title.

### Returns
- `string|nil`: The player's loyalty title.
```

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

### Player:getLoyaltyBonus()

Source: https://github.com/opentibiabr/canary/blob/main/docs/lua-api/lua_api.md

Gets the player's loyalty bonus. Returns a number or nil.

```APIDOC
## Player:getLoyaltyBonus()

### Description
Gets the player's loyalty bonus.

### Returns
- `number|nil`: The player's loyalty bonus.
```

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

### Player:getHarmony()

Source: https://github.com/opentibiabr/canary/blob/main/docs/lua-api/lua_api.md

Gets the player's current harmony value. Returns a number.

```APIDOC
## Player:getHarmony()

### Description
Gets the player's current harmony value.

### Returns
- `number`: The player's harmony value.
```

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

### Execute Debugger Script

Source: https://github.com/opentibiabr/canary/blob/main/docs/development.md

Use the provided helper script to launch the application within GDB. This simplifies the debugging setup process.

```bash
./start_gdb.sh
```

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

### Player:getGuildLevel()

Source: https://github.com/opentibiabr/canary/blob/main/docs/lua-api/lua_api.md

Gets the player's guild level. Returns a number or nil.

```APIDOC
## Player:getGuildLevel()

### Description
Gets the player's guild level.

### Returns
- `number|nil`: The player's guild level.
```

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

### MonsterType:name

Source: https://github.com/opentibiabr/canary/blob/main/docs/lua-api/lua_api.md

Gets or sets the name of a monster. Accepts an optional string argument.

```APIDOC
## MonsterType:name

### Description
Gets or sets the name of a monster. Accepts an optional string argument.

### Method
`MonsterType:name(arg2?: string)`

### Returns
`boolean|string|nil`
```

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

### Build Canary on Windows with Visual Studio

Source: https://github.com/opentibiabr/canary/blob/main/docs/development.md

On Windows, open the repository in Visual Studio. Ensure VCPKG_ROOT is configured before opening or configuring the CMake preset. Visual Studio can automatically detect CMake, resolve dependencies via vcpkg, and generate the build cache.

```text
Build → Build All
```

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

### Default Lua Startup Configuration

Source: https://github.com/opentibiabr/canary/blob/main/docs/maps/startup-loading-performance.md

These are the default configuration values for Lua startup optimizations. Enable luaStartupLoadTelemetry only when measuring startup performance.

```lua
luaStartupLoadTelemetry = false
luaScriptBytecodeCache = true
luaScriptBytecodeCachePath = "cache/lua-bytecode"
luaScriptDebugHook = false
luaScriptDebugHookInterval = 30000
```

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

### MonsterType:health

Source: https://github.com/opentibiabr/canary/blob/main/docs/lua-api/lua_api.md

Gets or sets the health of a monster. Accepts an optional number argument.

```APIDOC
## MonsterType:health

### Description
Gets or sets the health of a monster. Accepts an optional number argument.

### Method
`MonsterType:health(arg2?: number)`

### Returns
`boolean|number|nil`
```

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

### MonsterType:deathSound

Source: https://github.com/opentibiabr/canary/blob/main/docs/lua-api/lua_api.md

Gets or sets the death sound for the monster. Accepts an optional argument.

```APIDOC
## MonsterType:deathSound

### Description
Gets or sets the death sound for the monster.

### Method
`MonsterType:deathSound(arg2?: any)`

### Parameters
- **arg2** (any) - Optional - The death sound to set.

### Returns
- `boolean|number` - Returns a boolean indicating success or the current death sound value.
```

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

### Dump Database to SQL File

Source: https://github.com/opentibiabr/canary/blob/main/docs/operations.md

Use this command to create a full SQL dump of your database. Ensure you have the necessary permissions for the specified user.

```bash
mysqldump \
  -u root \
  -p \
  canary > backup.sql
```

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

### Player:sendOutfitWindow

Source: https://github.com/opentibiabr/canary/blob/main/docs/lua-api/lua_api.md

Opens the outfit selection window for the player.

```APIDOC
## Player:sendOutfitWindow()

### Description
Opens the outfit selection window, allowing the player to change their appearance.

### Method
`Player:sendOutfitWindow`

### Returns
- `boolean|nil` - Indicates if the outfit window was opened successfully.
```

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

### AI Version Prompt for Release Tagging

Source: https://github.com/opentibiabr/canary/blob/main/docs/release.md

Use this prompt with AI to help choose the next release tag. Paste command outputs from the tagging tutorial into the placeholders. It analyzes commit logs and changed files based on SemVer policy to recommend a tag, bump type, justification, risks, and exact commands.

```markdown
You are helping choose the next Canary release version.

Previous release tag: <previous tag>
Candidate release target: origin/main
Commit range: <previous tag>..origin/main

Use this SemVer policy:
- PATCH for bug fixes, crash fixes, non-breaking CI/build/release fixes,
  documentation updates, world-data fixes, or compatibility corrections that do
  not require config, schema, client, deployment, or operator changes.
- MINOR for backwards-compatible gameplay features, new systems, optional
  config, new supported protocol/client functionality, compatible migrations,
  Docker/operator convenience, or meaningful content additions.
- MAJOR for breaking config/deployment changes, required manual migrations,
  incompatible database/storage changes, removed APIs, removed supported
  behavior, or protocol/client incompatibility.

Analyze these inputs:

Commit log:
<paste git log --oneline --decorate --first-parent output>

Changed files:
<paste git diff --name-only output>

Return:
1. Recommended next tag.
2. Whether the bump is patch, minor, or major.
3. The concrete commits or file areas that justify the bump.
4. Any release risks or manual notes maintainers should check.
5. The exact tag commands to run.
```

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

### Player:getMaxSoul()

Source: https://github.com/opentibiabr/canary/blob/main/docs/lua-api/lua_api.md

Gets the player's maximum soul capacity. Returns a number or nil.

```APIDOC
## Player:getMaxSoul()

### Description
Gets the player's maximum soul capacity.

### Returns
- `number|nil`: The player's maximum soul capacity.
```

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

### Player:getMaxMana()

Source: https://github.com/opentibiabr/canary/blob/main/docs/lua-api/lua_api.md

Gets the player's maximum mana capacity. Returns a number or nil.

```APIDOC
## Player:getMaxMana()

### Description
Gets the player's maximum mana capacity.

### Returns
- `number|nil`: The player's maximum mana capacity.
```

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

### Build Project with CMake

Source: https://github.com/opentibiabr/canary/blob/main/docs/development.md

Use CMake presets to configure and build the project for debugging on Linux. Ensure CMake is installed and the project is cloned.

```bash
cmake --preset linux-debug

cmake --build --preset linux-debug
```

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

### Player:getLivestreamViewersCount()

Source: https://github.com/opentibiabr/canary/blob/main/docs/lua-api/lua_api.md

Gets the count of the player's livestream viewers. Returns a number or nil.

```APIDOC
## Player:getLivestreamViewersCount()

### Description
Gets the count of the player's livestream viewers.

### Returns
- `number|nil`: The count of livestream viewers.
```

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

### Player:getLivestreamViewers()

Source: https://github.com/opentibiabr/canary/blob/main/docs/lua-api/lua_api.md

Gets the player's livestream viewers. Returns a string, table, or nil.

```APIDOC
## Player:getLivestreamViewers()

### Description
Gets the player's livestream viewers.

### Returns
- `string|table|nil`: The player's livestream viewers.
```

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

### Player:getLastLogout()

Source: https://github.com/opentibiabr/canary/blob/main/docs/lua-api/lua_api.md

Gets the timestamp of the player's last logout. Returns a number or nil.

```APIDOC
## Player:getLastLogout()

### Description
Gets the timestamp of the player's last logout.

### Returns
- `number|nil`: The timestamp of the last logout.
```

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

### Player:getInstantSpells()

Source: https://github.com/opentibiabr/canary/blob/main/docs/lua-api/lua_api.md

Gets a table of the player's instant spells. Returns a table or nil.

```APIDOC
## Player:getInstantSpells()

### Description
Gets a table of the player's instant spells.

### Returns
- `table|nil`: A table containing the player's instant spells.
```

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

### Configure vcpkg Environment (systemd)

Source: https://github.com/opentibiabr/canary/blob/main/docs/building/wsl-ubuntu-24.04.md

Sets the VCPKG_ROOT environment variable globally for the user by creating a configuration file in systemd's environment directory. This method requires systemd to be enabled.

```bash
mkdir -p ~/.config/environment.d
echo 'VCPKG_ROOT=$HOME/vcpkg' > ~/.config/environment.d/10-vcpkg.conf
```

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

### Player:getIdleTime()

Source: https://github.com/opentibiabr/canary/blob/main/docs/lua-api/lua_api.md

Gets the player's idle time in seconds. Returns a number or nil.

```APIDOC
## Player:getIdleTime()

### Description
Gets the player's idle time in seconds.

### Returns
- `number|nil`: The player's idle time.
```

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

### Publish a New Release Tag

Source: https://github.com/opentibiabr/canary/blob/main/docs/release.md

Create and push a new SemVer tag from the main branch to initiate the release process. Ensure your local main branch is up-to-date before tagging.

```bash
git switch main
git pull --ff-only origin main
git fetch --force --tags origin
git tag -a v3.6.0 -m v3.6.0
git push origin v3.6.0
```

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

### MonsterType:nameDescription

Source: https://github.com/opentibiabr/canary/blob/main/docs/lua-api/lua_api.md

Gets or sets the name description of a monster. Accepts an optional string argument.

```APIDOC
## MonsterType:nameDescription

### Description
Gets or sets the name description of a monster. Accepts an optional string argument.

### Method
`MonsterType:nameDescription(arg2?: string)`

### Returns
`boolean|string|nil`
```

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

### MonsterType:mitigation

Source: https://github.com/opentibiabr/canary/blob/main/docs/lua-api/lua_api.md

Gets or sets the mitigation value of a monster. Accepts an optional number argument.

```APIDOC
## MonsterType:mitigation

### Description
Gets or sets the mitigation value of a monster. Accepts an optional number argument.

### Method
`MonsterType:mitigation(arg2?: number)`

### Returns
`boolean|number`
```

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

### Configure vcpkg Environment (fallback)

Source: https://github.com/opentibiabr/canary/blob/main/docs/building/wsl-ubuntu-24.04.md

Sets the VCPKG_ROOT environment variable by appending it to the user's bashrc file. Use this as a fallback if systemd is not enabled or available.

```bash
echo 'export VCPKG_ROOT=$HOME/vcpkg' >> ~/.bashrc
source ~/.bashrc
```

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

### MonsterType:maxHealth

Source: https://github.com/opentibiabr/canary/blob/main/docs/lua-api/lua_api.md

Gets or sets the maximum health of a monster. Accepts an optional number argument.

```APIDOC
## MonsterType:maxHealth

### Description
Gets or sets the maximum health of a monster. Accepts an optional number argument.

### Method
`MonsterType:maxHealth(arg2?: number)`

### Returns
`boolean|number|nil`
```

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

### Player:getExperience()

Source: https://github.com/opentibiabr/canary/blob/main/docs/lua-api/lua_api.md

Retrieves the player's current experience points. Returns the experience as a number, or nil if not available.

```APIDOC
## Player:getExperience()

### Description
Retrieves the player's current experience points.

### Returns
- `number|nil`: The player's experience points, or nil if they cannot be retrieved.
```

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

### MonsterType:manaCost

Source: https://github.com/opentibiabr/canary/blob/main/docs/lua-api/lua_api.md

Gets or sets the mana cost of a monster. Accepts an optional number argument.

```APIDOC
## MonsterType:manaCost

### Description
Gets or sets the mana cost of a monster. Accepts an optional number argument.

### Method
`MonsterType:manaCost(arg2?: number)`

### Returns
`boolean|number|nil`
```

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

### MonsterType:light

Source: https://github.com/opentibiabr/canary/blob/main/docs/lua-api/lua_api.md

Gets or sets the light properties of a monster. Accepts optional number arguments.

```APIDOC
## MonsterType:light

### Description
Gets or sets the light properties of a monster. Accepts optional number arguments.

### Method
`MonsterType:light(arg2?: number, arg3?: number)`

### Returns
`boolean|number|nil`
```

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

### Verify vcpkg Toolchain File

Source: https://github.com/opentibiabr/canary/blob/main/docs/building/ubuntu-24.04.md

Checks if the vcpkg toolchain file exists at the expected location, indicating a successful vcpkg setup.

```bash
test -f "$VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake" && echo "vcpkg OK" || echo "vcpkg not found"
```

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

### MonsterType:experience

Source: https://github.com/opentibiabr/canary/blob/main/docs/lua-api/lua_api.md

Gets or sets the experience value for the monster. Accepts an optional number argument.

```APIDOC
## MonsterType:experience

### Description
Gets or sets the experience value for the monster.

### Method
`MonsterType:experience(arg2?: number)`

### Parameters
- **arg2** (number) - Optional - The experience value to set.

### Returns
- `boolean|number|nil` - Returns a boolean indicating success, the current experience value if no argument is provided, or nil on failure.
```

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

### Configure and Build Canary Project

Source: https://github.com/opentibiabr/canary/blob/main/docs/building/debian.md

Configures the build using CMake with a specific preset and then builds the project. The -j4 flag utilizes 4 parallel jobs for faster compilation.

```bash
cmake --preset linux-release -DTOGGLE_BIN_FOLDER=ON
cmake --build --preset linux-release -j4
```

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

### MonsterType:enemyFactions

Source: https://github.com/opentibiabr/canary/blob/main/docs/lua-api/lua_api.md

Gets or sets enemy factions for the monster. Accepts an optional faction argument.

```APIDOC
## MonsterType:enemyFactions

### Description
Gets or sets enemy factions for the monster.

### Method
`MonsterType:enemyFactions(faction?: any)`

### Parameters
- **faction** (any) - Optional - The enemy faction to set.

### Returns
- `boolean|table|nil` - Returns a boolean indicating success, a table of current enemy factions if no argument is provided, or nil on failure.
```

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

### Configure, Build, and Run Tests with CMake Presets

Source: https://github.com/opentibiabr/canary/blob/main/tests/README.md

Use these commands to configure, build, and run tests via CMake presets. Replace 'linux-debug' with 'macos-debug' or 'windows-debug' for different platforms.

```bash
# Configure and build tests
cmake --preset linux-debug && cmake --build --preset linux-debug

# Run all tests
ctest --preset linux-debug

# Run only unit tests
ctest --preset linux-debug -R unit

# Run only integration tests
ctest --preset linux-debug -R integration

# Use -VV for verbose output showing individual test cases
ctest --preset linux-debug -VV
```

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

### MonsterType:defense

Source: https://github.com/opentibiabr/canary/blob/main/docs/lua-api/lua_api.md

Gets or sets the defense value of the monster. Accepts an optional number argument.

```APIDOC
## MonsterType:defense

### Description
Gets or sets the defense value of the monster.

### Method
`MonsterType:defense(arg2?: number)`

### Parameters
- **arg2** (number) - Optional - The defense value to set.

### Returns
- `boolean|number|nil` - Returns a boolean indicating success, the current defense value if no argument is provided, or nil on failure.
```