Cairn

    Contributing

    AGENTS.md at the top of the repository is the full guide for changing the engine, for people and for agents. This page is the short version.

    Ground rules

    • Tests come first. A feature is not done until it has unit tests and the test scene uses it.
    • Permissive licences only: MIT, zlib, BSD, Apache 2.0, public domain.
    • No shortcut that leaves a known bug behind. If something is deliberately simple, say so in a comment and name the limit.
    • Review the diff before every commit.

    Tests

    ./build/Tests/Cairn-Tests            # unit tests, no GPU needed
ctest --test-dir build --output-on-failure # everything
    KindWhereWhat it checks
    Unit testsTests/srcLogic with no GPU. They run on every build
    Render testsTests/renderImages against references in Tests/Golden
    Command testsTests/commandsGames and templates played through agent commands
    Editor testsCairn-Editor/CMakeLists.txtThe editor's window, with a scripted mouse and keyboard

    Test names are full sentences that state the behaviour: "A click picks the nearest mesh under it".

    When a render test fails, open the image it wrote to build/Tests/RenderOutput and compare it with the reference. Never update a reference without looking at it.

    Code style

    • PascalCase for types, functions and file names. camelCase for locals and parameters.
    • Member variables are m_ plus PascalCase. Statics are s_ plus PascalCase.
    • Tabs. Braces on their own line.
    • Everything lives in the Cairn namespace.
    • Comments say why, or state a rule the caller must follow. They do not narrate the code.

    Generated pages

    Two pages of this site are generated from the code:

    After changing a binding or a command, run:

    CAIRN_UPDATE_DOCS=1 ./build/Tests/Cairn-Tests

    A unit test fails while either is out of date, so they cannot drift from the code.

    Adding things

    To addDo this
    A componentThe struct, an entry in OptionalComponents, reading and writing in the serializer, an inspector section, a Lua binding, an entity in the test scene and a serializer test
    A Lua functionBind it through TypeBinder or TableBinder with its usage and description, and add a test
    An agent commandAdd(name, parameters, description, handler) in CommandProcessor.cpp, with a test that undo gives back the same scene
    A shaderThe GLSL file, and a row in EmbeddedShaders.cpp
    A templateA folder in Templates/, and a play test in Tests/commands

    This site

    The site is Rspress, in Docs/.

    cd Docs
bun install
bun run dev      # preview while writing
bun run build    # the static site, in doc_build