Code style

Consistency across the codebase makes reviews faster and diffs cleaner. All C++ code is enforced by clang-format and checked by clang-tidy. Lua and SQL conventions are followed by convention.

C++ Style

The project targets C++20 and uses a style based on WebKit with Allman braces. The canonical configuration lives in .clang-format at the repository root and is compatible with clang-format-20.

Key rules

Rule	Value
Brace style	Allman (braces on their own line)
Indent width	4 spaces
Tabs	Never — spaces only
Column limit	0 (use your best judgement)
Pointer alignment	Left (`int* ptr`)
Standard	Latest (C++20)
Short blocks/ifs/loops on one line	Never
Template declarations	Always break before `<`
Include sorting	Enabled
Consecutive alignment	Assignments, declarations, and macros are aligned

Allman brace example

if (condition)
{
    doSomething();
}
else
{
    doSomethingElse();
}

Access modifiers

Access modifiers (public:, private:, protected:) use an offset of -4 so they sit flush with the class body rather than indented.

class MyClass
{
public:
    void publicMethod();

private:
    int m_value;
};

Running clang-format

# From the repository root
python tools/run_clang_format.py

clang-tidy checks

The .clang-tidy configuration enables a focused set of checks:

Checks: >-
  -*,
  cppcoreguidelines-avoid-goto,
  cppcoreguidelines-init-variables,
  cppcoreguidelines-no-malloc,
  cppcoreguidelines-pro-type-const-cast,
  cppcoreguidelines-pro-type-member-init,
  cppcoreguidelines-slicing,
  cppcoreguidelines-special-member-functions,
  cppcoreguidelines-virtual-class-destructor,
  misc-definitions-in-headers,
  modernize-pass-by-value,
  modernize-use-emplace,
  modernize-use-nullptr,
  modernize-use-override,
  performance-*

clang-tidy is run in CI automatically. You can run it locally via the dev Docker Compose setup (see Development workflow).

Lua Style

Lua scripts live under scripts/ and use the following conventions observed throughout the codebase.

Indentation

4 spaces — no tabs.

Naming conventions

Construct	Convention	Example
Local variables	`camelCase`	`local playerJob`
Global tables/namespaces	`camelCase` under `xi.`	`xi.zone.WEST_RONFAURE`
Constants / enum values	`UPPER_SNAKE_CASE`	`xi.job.WHM`
Functions	`camelCase`	`function onMobDeath(mob, killer)`
Type annotations	`---@type TypeName`	`---@type CClientEntityPair`

Script structure

Zone and NPC scripts expose callback functions that the C++ engine calls via luautils:

-- scripts/zones/West_Ronfaure/Zone.lua
local zone = {}

zone.onInitialize = function(zone)
    -- Called when the zone is initialized
end

zone.onGameDay = function(zone)
    -- Called each Vana'diel day
end

return zone

Test scripts

Tests use a describe/it BDD-style framework:

describe('Smoke Tests', function()
    it('New Character Flow', function()
        ---@type CClientEntityPair
        local player = xi.test.world:spawnPlayer({
            zone = xi.zone.PORT_SAN_DORIA,
            new  = true,
        })

        player.assert:inZone(xi.zone.PORT_SAN_DORIA)
        player.assert:hasItem(xi.item.ONION_SWORD)
    end)
end)

SQL Style

SQL files live under sql/ and use MariaDB/MySQL syntax with the following conventions.

File structure

Each table has a corresponding .sql file at sql/<table_name>.sql. Files use INSERT INTO statements with explicit value lists.

Formatting

-- Use backtick-quoted identifiers
INSERT INTO `mob_spawn_points` VALUES (17305056, 379.803, -0.187, 490.047, 0, 0);

-- Multi-row inserts keep one row per line
INSERT INTO `zone_settings` VALUES
(  1, 'South_Gustaberg',     0, 0, ..., 54230),
(  2, 'North_Gustaberg',     0, 0, ..., 54230),
(  3, 'Zeruhn_Mines',        0, 0, ..., 54230);

Character set

All databases and tables use utf8mb4 with utf8mb4_general_ci collation:

CREATE DATABASE xidb CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;

Protected tables

The following tables contain live player data and are never overwritten by dbtool update:

chars, char_* tables (inventory, jobs, skills, stats, etc.)
accounts, accounts_banned, accounts_totp
auction_house, auction_house_items
linkshells, server_variables, conquest_system

See tools/dbtool.py for the full list.

Contributing

Architecture

Tools

C++ Style

Key rules

Allman brace example

Access modifiers

Running clang-format

clang-tidy checks

Lua Style

Indentation

Naming conventions

Script structure

Test scripts

SQL Style

File structure

Formatting

Character set

Protected tables

Build docs developers (and LLMs) love

Contributing

Architecture

Tools

​C++ Style

​Key rules

​Allman brace example

​Access modifiers

​Running clang-format

​clang-tidy checks

​Lua Style

​Indentation

​Naming conventions

​Script structure

​Test scripts

​SQL Style

​File structure

​Formatting

​Character set

​Protected tables

Build docs developers (and LLMs) love

C++ Style

Key rules

Allman brace example

Access modifiers

Running clang-format

clang-tidy checks

Lua Style

Indentation

Naming conventions

Script structure

Test scripts

SQL Style

File structure

Formatting

Character set

Protected tables