Caffeine

Building

Stable Engine Doppio Last verified:

Manual CMake configuration for the engine and C ABI, the Rust workspace that builds Doppio, and the test commands used by CI and agents.

Engine (C++20 + CMake)#

bash
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build -j

For editor work, build only the C ABI after a source change:

bash
cmake --build build --target caffeine-capi -j

Artifacts#

TargetOutputPurpose
caffeine-corebuild/libcaffeine-core.aEngine library without ImGui or editor code.
caffeine-capibuild/libcaffeine-capi.so / .dylib / .dllStable C ABI loaded by Doppio and external frontends.
caffeine-runtimebuild/caffeine-runtimeStandalone ImGui runtime host for scenes.
caffeine-combinedbuild/caffeine-combinedCombined runtime build with the editor-support shim.
caffeine-render-snapshotbuild/caffeine-render-snapshotReference-scene renderer for visual regression images.
caf-encodebuild/caf-encodeLegacy CAF encoder; prefer the caf-pack CLI.
Doppio pluginsbuild/plugins/*.soEvery plugin from the doppio-plugins submodule, loaded on demand.

Doppio (Rust 2021 + Iced 0.14)#

Build the C ABI first, then the workspace:

bash
cd doppio
cargo build -p doppio-ui
cargo run -p doppio-ui

The binaries are written to doppio/target/<profile>/doppio and doppio/target/<profile>/doppio-headless (the latter requires the headless feature). The release profile is the one used by the launcher:

bash
cd doppio
cargo build --release -p doppio-ui

Common CMake options#

OptionDefaultEffect
CAFFEINE_BUILD_HEADLESSOFFBuilds caffeine-core without SDL3 or RHI for servers and CI.
CAFFEINE_ENABLE_SCRIPTINGONLua 5.4 + sol2 bindings and the script system.
CAFFEINE_ENABLE_BULLET3ONBullet3 rigid-body physics.
CAFFEINE_BUILD_DOPPIO_PLUGINSONBuilds every plugin from doppio-plugins into build/plugins; set OFF for minimal or headless builds.
CMAKE_BUILD_TYPEDebugUse Release for editor and benchmark work.

Note. If the doppio-plugins submodule is missing, configure fails with an explicit message. Run ./scripts/submodules.sh or pass -DCAFFEINE_BUILD_DOPPIO_PLUGINS=OFF.

Tests#

C++ engine#

bash
cd build
ctest --output-on-failure

The Catch2 binary is build/tests/CaffeineTest; run a single tag or test directly:

bash
./build/tests/CaffeineTest "[ecs]"

Rust editor#

bash
cd doppio
cargo test -p doppio-ui
cargo test -p doppio-ui --features headless

The headless feature runs the committed UI flows in doppio/tests/ui-flows/. The combined check used by CI is:

bash
./scripts/check-rust-ui.sh

Headless driver#

bash
./scripts/doppio-headless.sh widgets
./scripts/doppio-headless.sh run doppio/tests/ui-flows --format text

See the headless guide for the full action reference, screenshots, baselines and GIF/MP4 recording.

Platform helpers#

Command Platform What it does
./scripts/build.sh debug Linux/macOS Configure and build Debug
./scripts/build.sh release Linux/macOS Configure and build Release
./scripts/build.sh test Linux/macOS Debug build followed by ctest
./scripts/build.sh rebuild Linux/macOS Remove build/, configure and build
./scripts/build.sh clean Linux/macOS Remove build/
scripts\build.bat Windows Windows build helper
./scripts/build.fish Fish shell Fish variant
./scripts/build-launcher.sh Linux/macOS Builds the Rust launcher

Cleaning#

bash
rm -rf build doppio/target

Reconfigure after deleting build/. Cargo caches are safe to delete but make the next Rust build slower.