Cairn

    Command line

    Editor

    Cairn-Editor [project file] [options]

    With no project file the editor opens the project hub.

    OptionMeaning
    --headlessNo window and no need for a display: the project, the scene and the command interface only
    --commands FILERun a file of agent commands, print one line of JSON per answer, then exit
    --server [PORT]Serve agent commands on a local port (47800 unless given) for as long as the editor runs
    --playEnter play mode at startup
    --select NAMESelect the entity with this name at startup
    --user-data DIRKeep a played game's saves and player settings in DIR
    --editor-data DIRKeep the window layout and the list of recent projects in DIR
    --templates DIRWhere project templates are, in place of the folder beside the program
    --statsOpen the Performance window at startup
    --validationTurn on Vulkan and nvrhi validation

    For automated runs:

    OptionMeaning
    --hiddenDo not show the window
    --frames NExit after N frames
    --screenshot FILESave the editor window as a PNG on exit
    --hub-page PAGEWith no project, start the hub on new or open
    --ui-script STEPSScripted mouse and keyboard, such as "10:click 366,290; 15:type Name"
    --expect-selected NAMEFail unless this entity is selected when the editor exits

    A hidden or headless editor ignores the saved layout and the recent projects list, opens no sound device and starts no other program, so automated runs are repeatable and leave nothing behind.

    Runtime

    Cairn-Runtime [project file] [options]

    With no project file the runtime looks for its own pack: Game.cairnpak beside the program, or in the Resources of a macOS bundle. That is what an exported game is.

    OptionMeaning
    --user-data DIRKeep saved games and the player's settings in DIR
    --no-vsyncPresent as fast as the GPU allows
    --statsStart with the stats overlay shown. F3 shows and hides it. Only with a project file: an exported game has none
    --stats-log FILEWrite every stats sample, twice a second, to a CSV file. See Performance
    --validationTurn on Vulkan and nvrhi validation
    --hiddenDo not show the window
    --frames NExit after N frames
    --screenshot FILESave the last frame as a PNG on exit

    The runtime exits with a non-zero code if any error was logged. With --validation, a Vulkan validation error counts.

    CLI

    Cairn-CLI [--port N] [command ...]

    Each argument is one JSON command. With none, commands are read from standard input, one per line. Each answer is printed as one line of JSON.

    Exit codeMeaning
    0Every command was answered with "ok": true
    1One was not
    2The editor could not be reached

    Environment variables

    VariableMeaning
    CAIRN_UPDATE_DOCS=1With the unit tests: rewrite the generated reference pages
    CAIRN_UPDATE_GOLDEN=1With the render tests: rewrite the reference images