> Cinder 0.1.0 documentation: Engine README
> Canonical page: https://cinder.ash10.dev/docs/readme/ · Source: `README.md` in the engine repository (engine commit 47c9352, imported 2026-11-09)
> Index of every page for agents: https://cinder.ash10.dev/llms.txt

# 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](https://cinder.ash10.dev/docs/status.md) for exactly what has been verified and [REPORT.md](https://cinder.ash10.dev/docs/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](https://pixi.sh) 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](https://cinder.ash10.dev/docs/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](https://cinder.ash10.dev/docs/toolchain.md): exact pinned versions.
- [docs/MOJO_NOTES.md](https://cinder.ash10.dev/docs/mojo-notes.md): Mojo 1.2.0 idioms used, lifetime rules learned the hard way, banned legacy forms.
- [docs/ARCHITECTURE.md](https://cinder.ash10.dev/docs/architecture.md): module map, C boundary, threading model.
- [docs/adr/](https://cinder.ash10.dev/docs/adr.md): architecture decision records.

## Licence

Apache-2.0. See LICENSE.