canary/docs/development.md

Development Guide

Introduction

This document describes the development workflow used by Canary and serves as a reference for contributors who want to:

• Build the server locally
• Develop new features
• Fix bugs
• Create Lua systems
• Write tests
• Submit pull requests

Canary is an MMORPG server emulator written primarily in:

• C++20 (server core)
• Lua (gameplay systems)
• SQL (database schema)
• CMake (build system)

---

Development Philosophy

Canary follows a few important principles:

1. Keep the core engine stable.
2. Prefer gameplay customization through Lua.
3. Maintain compatibility with existing datapacks whenever possible.
4. Favor readability over clever implementations.
5. Keep systems modular and testable.
6. Avoid introducing unnecessary dependencies.

---

Development Environment

Recommended Tools

IDEs

Supported:

• Visual Studio 2026
• CLion
• VSCode

Useful Extensions

VSCode:

• C/C++
• CMake Tools

---

Repository Structure

canary/
│
├── src/
├── data/
├── data-canary/
├── data-otservbr-global/
├── docs/
├── tests/
├── docker/
├── metrics/
│
├── schema.sql
├── config.lua.dist
├── CMakeLists.txt
├── CMakePresets.json
├── vcpkg.json
└── package.json

---

Development Setup

Option 1: Docker (Recommended for Beginners)

The fastest way to start local testing is using the Docker quickstart.

Services provided:

• Canary
• MariaDB
• MyAAC
• Login Server

Start the stack:

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

This pulls the published Canary runtime image and builds the MyAAC quickstart image. It does not compile Canary locally.

Default endpoints:

Website:                 http://localhost:8080
Client login API:        http://localhost:8088/login
Canary login protocol:   7171
Canary game protocol:    7172
Canary status protocol:  7173
Login-server gRPC:       9090

Docker is ideal when:

• Testing scripts
• Developing datapacks
• Learning the project structure
• Avoiding local dependency installation
• Running local or LAN demos with trusted defaults

Do not expose the quickstart directly to the public Internet with default accounts, passwords or rolling image tags. See docker/DOCKER.md for the full Docker quickstart contract.

---

Option 2: Native Development

Recommended for engine contributors.

Required Software

Install Git, a supported C++ compiler, and mise. The repository's .mise.toml installs the pinned CMake, Ninja, Python, and sccache versions used by the native development workflow and relevant CI jobs.

Linux requires GCC or Clang. Windows requires Visual Studio with Desktop Development with C++.

---

Cloning the Repository

git clone https://github.com/opentibiabr/canary.git
cd canary

Canary does not require Git submodules. Install the pinned tools and vcpkg checkout from the repository root:

mise install
mise run bootstrap

---

Configuration

Create your local configuration:

cp config.lua.dist config.lua

Important settings:

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

Never commit personal configuration changes.

---

Build System

Use the tasks in .mise.toml so local builds use the same tool versions as CI:

mise run configure linux-debug
mise run build linux-debug
mise run test linux-debug

Replace linux-debug with another preset from CMakePresets.json as needed. The underlying CMake commands remain available for IDE integration and advanced use.

---

Building Canary

mise run configure linux-release
mise run build linux-release

Windows

Open the repository in Visual Studio.

Visual Studio can automatically:

• Detect CMake
• Resolve dependencies through vcpkg
• Generate the build cache

Make sure VCPKG_ROOT is configured before opening the folder or configuring the CMake preset.

Then:

Build → Build All

---

Dependency Management

Canary uses:

vcpkg.json

to declare dependencies.

Examples:

• asio
• curl
• libmariadb
• LuaJIT
• mbedtls
• protobuf
• pugixml
• spdlog

If dependencies fail:

cd "$VCPKG_ROOT"
git pull
./bootstrap-vcpkg.sh

or on Windows:

Set-Location $env:VCPKG_ROOT
git pull
.\bootstrap-vcpkg.bat

---

Running the Server

After compilation:

./canary

Expected startup sequence:

Loading config
Loading map
Loading monsters
Loading NPCs
Loading scripts
Starting game server

---

Database Development

Database schema:

schema.sql

Import:

mysql -u root -p database_name < schema.sql

Main tables:

accounts
players
guilds
houses
market
player_storage

Schema modifications should:

• Be backward compatible when possible
• Include migration documentation
• Avoid destructive changes

---

Lua Development

Most gameplay features belong in Lua.

Examples:

• Quests
• NPCs
• Actions
• Talkactions
• Spells
• Events

Typical locations:

data/scripts/
data/actions/
data/spells/
data/npc/

---

Lua API

The server exposes C++ functionality through Lua bindings.

Examples:

player:addExperience(1000)

player:addItem(2160)

Game.getPlayers()

Generated API documentation is available in:

docs/lua-api/

Enable generation:

generateLuaApiDocs = true

---

Adding New Features

Prefer Lua First

Before modifying C++:

Ask:

Can this be implemented entirely in Lua?

If yes:

Use Lua.

If no:

Extend the C++ engine.

---

Adding a New Lua Event

Example:

local event = CreatureEvent("Example")

function event.onLogin(player)
    player:sendTextMessage(MESSAGE_STATUS, "Welcome!")
    return true
end

event:register()

---

C++ Development

Source Layout

src/
├── game/
├── creatures/
├── map/
├── items/
├── io/
├── lua/
├── server/
├── utils/
└── lib/

Before creating new modules:

• Check existing systems.
• Extend existing classes when appropriate.
• Avoid duplicate functionality.

---

Coding Standards

Naming

Classes:

Player
Monster
ProtocolGame

Methods:

addExperience()
getHealth()
sendTextMessage()

Variables:

playerLevel
damageAmount
targetPosition

Constants:

MAX_PLAYERS
MAX_CONTAINER_ITEMS

---

General Guidelines

Prefer:

const auto&

instead of unnecessary copies.

Prefer:

std::vector
std::unordered_map
std::shared_ptr

when they match the ownership model of the surrounding code.

Avoid:

new
delete

when smart pointers are possible.

For Lua bindings that expose shared C++ objects, read docs/systems/lua-shared-userdata.md before changing ownership or userdata registration code.

---

Logging

Use existing logging systems.

Good:

g_logger().info("Player {} logged in", playerName);

Bad:

std::cout << "debug" << std::endl;

Never commit debugging output.

---

Debugging

Linux

Run with GDB:

gdb ./canary

Helper script:

./start_gdb.sh

---

Common Debug Targets

Investigate:

• Crashes
• Memory corruption
• Infinite loops
• Scheduler deadlocks

Useful commands:

bt
frame
print
continue

---

Testing

Canary includes automated tests.

Build tests:

cmake --preset linux-debug

cmake --build --preset linux-debug

Run tests:

ctest --preset linux-debug

Tests should be added for:

• New systems
• Bug fixes
• Edge cases
• Regression prevention

---

Pull Request Workflow

Create a Branch

git checkout -b feature/new-system

Examples:

feature/
fix/
refactor/
docs/

---

Commit Messages

Good:

fix(player): prevent logout race condition

feat(wheel): add progression API

refactor(combat): simplify condition processing

Avoid:

fix stuff

update

changes

---

Before Opening a Pull Request

Checklist:

• Builds successfully
• Tests pass
• No debug code
• No merge conflicts
• Documentation updated
• Lua scripts validated

---

Reviewing Changes

When reviewing code:

Focus on:

• Correctness
• Performance
• Security
• Maintainability
• Backward compatibility

Do not approve changes solely because they work locally.

---

Performance Considerations

Critical systems:

• Pathfinding
• Combat
• Scheduler
• Dispatcher
• Networking

Before introducing changes:

Consider:

How does this behave with 1000 players?

Small inefficiencies become large server costs.

---

Common Development Tasks

Add a Spell

data/spells/

Add a Monster

data/monster/

Add an NPC

data/npc/

Add a Quest

data/scripts/

Add Engine Functionality

src/

and expose it through:

src/lua/

if Lua access is required.

---

Troubleshooting

Dependency Errors

Rebuild vcpkg:

cd "$VCPKG_ROOT"
git pull
./bootstrap-vcpkg.sh

---

CMake Cache Issues

Remove only the affected preset directory, then reconfigure the same preset:

rm -rf build/<preset-name>
cmake --preset <preset-name>

For example, if linux-release is the broken cache, remove build/linux-release, not the entire build/ directory.

---

Lua Errors

Enable verbose logging.

Check:

data/logs/

and console output.

---

Development Workflow Summary

Create Branch
      ↓
Implement Feature
      ↓
Build
      ↓
Run Tests
      ↓
Manual Validation
      ↓
Update Documentation
      ↓
Open Pull Request
      ↓
Code Review
      ↓
Merge

---

Conclusion

Canary development is centered around:

• C++20 for engine performance
• Lua for gameplay flexibility
• CMake for reproducible builds
• vcpkg for dependency management
• Automated testing and code review

Contributors are encouraged to keep changes modular, documented, tested, and aligned with the project's goal of providing a modern and extensible MMORPG server platform.