Cinder

A 3D game engine written in Mojo 1.2 over a single C11 native shim (wgpu-native, SDL3, Jolt, miniaudio, cgltf, Dear ImGui). Targets Linux x86-64 (Vulkan) and macOS Apple Silicon (Metal).

Project state: Phase 0 (reconnaissance, pins, architecture) and Phase 1 (nine risk spikes) are complete and verified on Linux. The macOS half of every gate has not been run: no Apple hardware or runner was available. Phases 2 to 9 (engine proper) have not started. See docs/STATUS.md for exactly what has been verified and REPORT.md for the deliverable report.

Quick start (Linux, or any host with Docker) #

bash

git clone --recursive <this repository> cinder && cd cinder
docker build -t cinder-toolchain:1 -f docker/Dockerfile.toolchain docker
tools/in_container.sh pixi install
tools/in_container.sh pixi run -e bindgen bindgen   # regenerate cinder/ffi from the C headers
tools/in_container.sh pixi run native              # build the native shim, run its CTest suite
tools/in_container.sh pixi run test                # lint, layout test, every spike (incl. X11 + Wayland)

On a native Linux or macOS host with pixi installed, drop the tools/in_container.sh prefix (the windowed spikes then need a display, or Xvfb/Weston as the script starts them). The Windows host used for development runs everything through the container (ADR-0007); on Windows set CINDER_HOST_ROOT to the repository's real path if it is reached through a substituted drive.

The sample game #

bash

tools/in_container.sh pixi run sample                    # windowed: arena level, WASD/Space, Esc for the menu
tools/in_container.sh pixi run sample -- --level sponza  # the Khronos atrium with a mesh collider
tools/in_container.sh pixi run sample-headless           # offscreen autopilot run (tests, CI, benchmarks)

sample/main.mojo accepts --headless, --level arena|sponza, --autopilot, --frames N, --screenshot PATH, --verbose and the engine options from cinder.app.parse_app_args. Assets are CC0 and fetched by tools/fetch_game_assets.py (attribution in assets/game/ATTRIBUTION.md). Settings, key bindings and saves land in .cache/sample/.

Benchmarks #

bash

tools/in_container.sh pixi run bench-all   # stress scene + sample game headless, JSON in .cache/bench, baseline check
tools/in_container.sh pixi run test-zero-alloc   # asserts zero Mojo allocations per steady-state frame

tools/bench_check.py --update records new baselines in bench/baselines/. Numbers are only comparable on the same adapter; see REPORT.md for the measured results and the budgets.

Layout #

Path	Contents
`cinder/ffi/`	Generated raw bindings (one module, one library struct). Never edited by hand.
`native/`	`libcinder_native` C11 shim, the ImGui C++ shim, CMake build of all vendored libraries, layout printer.
`third_party/`	Vendored dependencies as pinned git submodules. Licences in THIRD_PARTY_NOTICES.md.
`spikes/`	Phase 1 risk spikes, each a TestSuite program; `spikes/common` holds their shared helpers.
`tests/`	Every test suite (core, gfx, render, golden images, ECS, scene, assets, physics, anim, audio, input, app, tools, sample, perf).
`tools/`	Container runner, vendoring, bindings generator, lint, test drivers, asset fetchers, benchmark checker.
`sample/`	The sample game (a `Game` over `cinder.app.App`).
`bench/`	Benchmarks (stress scene, sample game, ECS vs flecs) and recorded baselines.
`bugs/`	Minimal reproducers for toolchain defects met, with the workaround used.
`docs/`	Toolchain, Mojo notes, architecture, ADRs, status.
`docker/`	Toolchain image.

Documentation #

docs/TOOLCHAIN.md: exact pinned versions.
docs/MOJO_NOTES.md: Mojo 1.2.0 idioms used, lifetime rules learned the hard way, banned legacy forms.
docs/ARCHITECTURE.md: module map, C boundary, threading model.
docs/adr/: architecture decision records.

Licence #

Apache-2.0. See LICENSE.