Skip to content
CrossfireCrossfire

Build from source

You only need this to work on the engine or the editor themselves. To make games, install a release.

The two repositories are separate:

The editor expects the engine next to it, in a folder named odin_sdl_engine:

  • Directoryworkspace/
    • Directoryodin_sdl_engine/ the engine (crossfire-engine)
      • …
    • Directoryodin_sdl_editor/ the editor (crossfire-editor)
      • …

(Set ENGINE_DIR=/path/to/engine on any task command to use another place.)

What you need

Section titled “What you need”
Tool For
Odin dev-2026-10 Everything. Newer nightlies may work; older ones don’t. Homebrew’s odin usually lags behind
Task The editor’s build commands (Taskfile.yml)
Git Cloning, with submodules (Skald, SDL, Box2D, …)
A C compiler Box2D, built once from the engine’s submodule
CMake The engine’s static SDL (SDL3, SDL3_image, SDL3_ttf, SDL3_mixer, built from submodules and linked into the editor and every game)
A C++ compiler and Python 3 The shader tools (glslang, SDL_shadercross) that task run builds once, for projects’ own shaders
A Vulkan driver Running the editor (it draws with Vulkan)

Build the editor

Section titled “Build the editor”

  1. Install the tools. On Debian or Ubuntu (other distributions have the same packages under similar names):

    Terminal window
    sudo apt install build-essential clang cmake ninja-build pkg-config git \
      libx11-dev libxext-dev libxrandr-dev libxcursor-dev libxi-dev libxss-dev libxtst-dev libxfixes-dev \
      libxkbcommon-dev libwayland-dev wayland-protocols libdecor-0-dev libegl1-mesa-dev libgl1-mesa-dev \
      libdrm-dev libgbm-dev libpulse-dev libasound2-dev libpipewire-0.3-dev libudev-dev libdbus-1-dev \
      libvulkan1 mesa-vulkan-drivers

    The -dev packages are what SDL’s build looks for (windows, Wayland, sound, gamepads). Then install Odin dev-2026-10 and Task, and put both in your PATH.

  2. Clone both repositories side by side, with their submodules:

    Terminal window
    git clone --recursive https://github.com/bcrowe306/crossfire-editor odin_sdl_editor
    git clone --recursive https://github.com/bcrowe306/crossfire-engine odin_sdl_engine
    cd odin_sdl_editor

  3. One-time setup: the submodules, Odin’s STB libraries (Skald uses them) and the engine’s Box2D:

    Terminal window
    task setup

  4. Build and run the editor (optimized). The first run also builds the engine’s static SDL, the prebuilt player and the shader tools, which takes a while:

    Terminal window
    task run

The editor opens its demo project (examples/demo_project). task run -- path/to/MyGame opens another. Press F5 to play: the first time, the editor builds the engine’s game player (progress in the Output tab).

Useful editor tasks

Section titled “Useful editor tasks”

task alone lists them all.

Command What it does
task run Build optimized (build/release/) and run. Program arguments go after --
task run:debug Build with debug info (slower) and run
task build, task build:release Build without running
task check Type-check the editor, with vet
task test The unit tests
task verify check and test
task prebuilt Build this system’s prebuilt player, so projects without scripts play without compiling
task emsdk Install Emscripten for web exports (about 1 GB, needs Python 3)
task shadertools Build the shader compilers that projects’ own GLSL shaders need
task ols Build the Odin language server for the built-in code editor (not needed if ols is in your PATH)

Build only the engine

Section titled “Build only the engine”

The engine is a library. Its own repository builds and tests it without the editor:

Terminal window
git clone --recursive https://github.com/bcrowe306/crossfire-engine odin_sdl_engine
cd odin_sdl_engine
tools/build_box2d.sh                          # once: Box2D into box2d/lib
tools/build_sdl_static.sh                     # once: SDL linked statically (needs CMake)
odin check . -no-entry-point -vet-unused      # type-check the library
odin test . -vet-unused -define:ODIN_TEST_FAIL_ON_BAD_MEMORY=true   # the tests (a leak fails)
odin build player -out:player_bin             # the player: player_bin <project folder>

On Windows, run these in Git Bash. Without build_sdl_static.sh, games link the system’s SDL3 libraries instead (on Windows, the ones Odin ships).

A game uses the engine as a package: import e "engine:.", built with -collection:engine=<engine folder>.

Crossfire is MIT licensed. Found a mistake? Report it.