# Cinder

> Cinder 0.1.0 is a 3D game engine written in Mojo 1.2.0 over one C11 shim (libcinder_native) wrapping wgpu-native/WGSL, SDL3, Jolt, cgltf, KTX-Software, meshoptimizer, miniaudio, Dear ImGui and Tracy. Linux x86-64 is built and tested; macOS arm64 is declared but not yet built or run; benchmarks ran only on a software rasteriser (Mesa lavapipe).

Every link below is raw Markdown. Any HTML docs page is also available as Markdown at its path without the trailing slash plus `.md`. Machine-readable index of pages and 1306 API symbols: https://cinder.ash10.dev/docs/index.json. Full text of every page in one file: https://cinder.ash10.dev/llms-full.txt. Agent context file (AGENTS.md / CLAUDE.md): https://cinder.ash10.dev/agents/AGENTS.md. Read-only MCP endpoint (Streamable HTTP): https://cinder.ash10.dev/mcp. Documentation imported from engine commit 47c9352 on 2026-11-09.

## Start here

- [Cinder documentation](https://cinder.ash10.dev/docs.md): Cinder 0.1.0 is a 3D game engine written in Mojo 1.2.0 over one C11 native shim. These pages are imported verbatim from the engine repository; the status report is the source of truth for what has been verified. Every page is also available as raw Markdown at its path plus…
- [Build your first game](https://cinder.ash10.dev/docs/tutorial.md): This tutorial builds a small game on Cinder from nothing: a red ball you push around a lit ledge to knock six crates off the edge. It takes about an hour. The finished code is in examples/first_game/ and is compiled and run headless by tests/examples/test_first_game.mojo, so…
- [First game: complete source](https://cinder.ash10.dev/docs/examples/first-game.md): The finished code of the tutorial, copied verbatim from examples/first_game/ in the engine repository. The engine's test tests/examples/test_first_game.mojo compiles it and runs it headless, so it builds under the pinned toolchain (Mojo 1.2.0). Each # Step N comment marks…
- [Sample game entry point](https://cinder.ash10.dev/docs/examples/sample-game.md): sample/main.mojo from the engine repository, verbatim: the entry point of the third-person sample game (ADR-0014). The game itself lives in sample/game/ (components, levels, settings, gameplay) and is built only on public engine APIs.
- [Using Cinder with AI coding agents](https://cinder.ash10.dev/agents.md): A ready-to-use AGENTS.md / CLAUDE.md brief, the llms.txt and JSON indexes, raw Markdown URLs, the MCP endpoint and prompts that work.

## Subsystem guides

- [Subsystem guides](https://cinder.ash10.dev/docs/guides.md): One guide per engine module: key types and ownership, setup, per-frame use, threading rules and pitfalls. Each links to its generated API reference.
- [Animation guide (cinder/anim)](https://cinder.ash10.dev/docs/guides/anim.md): cinder/anim is skeletal animation written in Mojo: skeletons built from glTF skins or read from cooked .cskel files, clip sampling into local poses, blend trees evaluated on a shared phase, animators with states, crossfades, events and root motion, and an AnimationSystem that…
- [Application runtime (cinder/app)](https://cinder.ash10.dev/docs/guides/app.md): cinder/app is the top of the engine: App owns every subsystem, runs the fixed-step game loop and renders, either into an SDL window or, with --headless, into an offscreen texture that can be read back. Gameplay implements the Game trait and is called from App.run_frame. The…
- [Assets guide (cinder/assets)](https://cinder.ash10.dev/docs/guides/assets.md): cinder/assets gets content from disk into the renderer. It has two paths:
- [Audio (cinder/audio)](https://cinder.ash10.dev/docs/guides/audio.md): cinder/audio is the engine's sound layer over miniaudio. It provides mixing buses, decoded and streamed sounds, one-shots that clean up after themselves, 3D spatialisation with distance attenuation, a single listener, and an ECS bridge that moves sounds with entities and the…
- [cinder/core guide](https://cinder.ash10.dev/docs/guides/core.md): cinder/core is the lowest Mojo layer of the engine: logging, assertions, a bump arena, generational handles and pools, a bounded ring, byte packing and hashing, file helpers, a monotonic clock with a fixed-step accumulator, CPU images, the job system, Tracy zones, Boxed heap…
- [ECS guide (cinder/ecs)](https://cinder.ash10.dev/docs/guides/ecs.md): cinder/ecs is the archetype entity component system every gameplay-facing module builds on. It sits directly above cinder/core (it uses core/math for Mat4 and core/jobs for the scheduler) and below render, physics, anim, audio, assets and scene, which define their own…
- [cinder/gfx guide](https://cinder.ash10.dev/docs/guides/gfx.md): cinder/gfx is the safe, typed layer over wgpu-native. It owns the wgpu instance, adapter, device and queue (Gfx), keeps every GPU object the engine creates in generational pools behind typed handles (Resources), compiles WGSL with editor-friendly diagnostics and hot reload…
- [Input (cinder/input)](https://cinder.ash10.dev/docs/guides/input.md): cinder/input maps raw platform events to named gameplay controls. A game asks pressed("jump") or axis("move_x") instead of testing scancodes, players can rebind controls at runtime, and the whole map saves to a small text file. The package sits beside audio, physics, anim and…
- [Physics guide (cinder/physics)](https://cinder.ash10.dev/docs/guides/physics.md): cinder/physics is the safe Mojo layer over Jolt. Jolt is reached through joltc inside libcinder_native; the parts of the shim that need C callbacks live in native/src/physics_shim.c (query filters, closest-hit collectors, CharacterVirtual extended update defaults) and…
- [cinder/platform guide](https://cinder.ash10.dev/docs/guides/platform.md): cinder/platform is the thin Mojo layer over SDL3 and the native shim's surface helpers. It loads libcinder_native exactly once, initialises SDL, creates windows, drains SDL's event queue into engine-level Events, opens and closes gamepads as they appear, creates the wgpu…
- [cinder/render: the renderer](https://cinder.ash10.dev/docs/guides/render.md): cinder/render turns a RenderScene (camera, lights, instances, joint palettes, environment) into one submitted command buffer per frame. It is a clustered forward+ renderer with cascaded and atlas shadow maps, GPU-baked image-based lighting, GTAO, physically based bloom, AgX…
- [Scene guide (cinder/scene)](https://cinder.ash10.dev/docs/guides/scene.md): cinder/scene is the layer between the ECS and the rest of the engine's content pipeline. It has three independent parts:
- [Tools: debug overlay, Tracy profiling, headless mode](https://cinder.ash10.dev/docs/guides/tools.md): Cinder's developer tooling is three things: the Dear ImGui debug overlay in cinder/tools, the Tracy client wrapper in cinder/core/profile.mojo, and the --headless mode of cinder/app that lets the same executables run without a display for tests, benchmarks and captures.

## Engine design

- [Cinder architecture](https://cinder.ash10.dev/docs/architecture.md): Dependencies point downward only. A module may import from the layers below it, never from the same layer except where noted, and never from above.
- [Threading model](https://cinder.ash10.dev/docs/threading.md): Fixed by section 4 of the brief; this page records how it is realised and which shared state exists.
- [Mojo 1.2.0 notes for Cinder](https://cinder.ash10.dev/docs/mojo-notes.md): Source of truth: https://mojolang.org/docs (manual and std reference for 1.2.0) and the release notes for 1.0.0, 1.1.0 and 1.2.0. Everything below was read from those pages on 2026-11-08 and confirmed by compiling spikes/hello/ under the pinned toolchain. When the compiler…
- [Toolchain](https://cinder.ash10.dev/docs/toolchain.md): Every version below is pinned. Changing one requires an ADR and a green CI run.
- [Render validation](https://cinder.ash10.dev/docs/render-validation.md): Golden-image tests (tests/golden/test_golden_gltf.mojo) render Khronos glTF-Sample-Assets models headless and compare them with committed references per platform. This file records how the references were produced and reviewed, and the tolerances.
- [Benchmarks](https://cinder.ash10.dev/docs/benchmarks.md): How Cinder measures performance, what the numbers mean, and how regressions are caught. The measured results for each run live in REPORT.md (section 4); this page is the method.

## Architecture decision records

- [Architecture decision records](https://cinder.ash10.dev/docs/adr.md): Every significant build-versus-reuse, layering and deviation decision, with context and consequences. Deviations from the original brief each point to one of these.
- [ADR-0001: Build-versus-reuse decisions for the dependency stack](https://cinder.ash10.dev/docs/adr/0001-dependency-stack.md): Status: Accepted, 2026-11-08
- [ADR-0002: No MAX / max.gpu for rendering; GPU compute is WGSL](https://cinder.ash10.dev/docs/adr/0002-no-max-gpu.md): Status: Accepted, 2026-11-08
- [ADR-0003: One C11 shim owning every callback; Mojo pulls events](https://cinder.ash10.dev/docs/adr/0003-native-shim-pull-model.md): Status: Accepted, 2026-11-08 (callback-in-Mojo question deferred to spike 4)
- [ADR-0004: Building wgpu-native from source through CMake](https://cinder.ash10.dev/docs/adr/0004-wgpu-native-build.md): Status: Accepted, 2026-11-08
- [ADR-0005: Generating the Mojo bindings](https://cinder.ash10.dev/docs/adr/0005-bindings-generation.md): Status: Accepted, 2026-11-08 (decided by spike 9; supersedes the "Proposed" version of the same day)
- [ADR-0006: Start from scratch rather than fork stargine](https://cinder.ash10.dev/docs/adr/0006-no-fork-of-stargine.md): Status: Accepted, 2026-11-08
- [ADR-0007: Development host is a Linux container; Windows host is a file server](https://cinder.ash10.dev/docs/adr/0007-dev-environment-container.md): Status: Accepted, 2026-11-08
- [ADR-0008: Job system scheduling in Mojo, threads and parking from the shim](https://cinder.ash10.dev/docs/adr/0008-job-system-threads.md): Status: Accepted, 2026-11-08
- [ADR-0009: Graphics layer shape (typed handles, error scopes for shader diagnostics)](https://cinder.ash10.dev/docs/adr/0009-gfx-layer.md): Status: accepted, 2026-11-08.
- [ADR-0010: Renderer architecture (forward+, frame graph, shader assembly)](https://cinder.ash10.dev/docs/adr/0010-renderer.md): Status: accepted, 2026-11-08.
- [ADR-0011: Keep the Mojo archetype ECS (benchmarked against flecs)](https://cinder.ash10.dev/docs/adr/0011-ecs-mojo-vs-flecs.md): Status: accepted, 2026-11-08.
- [ADR-0012: Phase 6 subsystems: physics, animation, audio and input](https://cinder.ash10.dev/docs/adr/0012-physics-animation-audio-input.md): Status: accepted, 2026-11-09.
- [ADR-0013: Tools and the application runtime (Phase 7)](https://cinder.ash10.dev/docs/adr/0013-tools-and-app-runtime.md): Status: accepted, 2026-11-09.
- [ADR-0014: Sample game, benchmarks and the zero-allocation frame (Phase 8)](https://cinder.ash10.dev/docs/adr/0014-sample-game-and-performance.md): Status: accepted, 2026-11-09.

## API reference (generated from docstrings)

- [API reference](https://cinder.ash10.dev/docs/api.md): Generated by tools/gen_api_docs.py from the docstrings in cinder/; do not edit by hand.
- [cinder.anim API](https://cinder.ash10.dev/docs/api/anim.md): Source: cinder/anim/__init__.mojo
- [cinder.app API](https://cinder.ash10.dev/docs/api/app.md): Source: cinder/app/__init__.mojo
- [cinder.assets API](https://cinder.ash10.dev/docs/api/assets.md): Source: cinder/assets/__init__.mojo
- [cinder.audio API](https://cinder.ash10.dev/docs/api/audio.md): Source: cinder/audio/__init__.mojo
- [cinder.core API](https://cinder.ash10.dev/docs/api/core.md): Source: cinder/core/__init__.mojo
- [cinder.ecs API](https://cinder.ash10.dev/docs/api/ecs.md): Source: cinder/ecs/__init__.mojo
- [cinder.gfx API](https://cinder.ash10.dev/docs/api/gfx.md): Source: cinder/gfx/__init__.mojo
- [cinder.input API](https://cinder.ash10.dev/docs/api/input.md): Source: cinder/input/__init__.mojo
- [cinder.physics API](https://cinder.ash10.dev/docs/api/physics.md): Source: cinder/physics/__init__.mojo
- [cinder.platform API](https://cinder.ash10.dev/docs/api/platform.md): Source: cinder/platform/__init__.mojo
- [cinder.render API](https://cinder.ash10.dev/docs/api/render.md): Source: cinder/render/__init__.mojo
- [cinder.scene API](https://cinder.ash10.dev/docs/api/scene.md): Source: cinder/scene/__init__.mojo
- [cinder.tools API](https://cinder.ash10.dev/docs/api/tools.md): Source: cinder/tools/__init__.mojo

## Project status and records

- [Deliverable report](https://cinder.ash10.dev/docs/report.md): Living document. Every claim below was verified in this repository under the pinned toolchain on the date given; nothing is reported from memory or intention. Phases are those of the mission brief.
- [Status](https://cinder.ash10.dev/docs/status.md): Last updated: 2026-11-09. One row per phase; "verified" means executed in this repository under the pinned toolchain, with the command named. Nothing here is claimed from memory.
- [Changelog](https://cinder.ash10.dev/docs/changelog.md): All notable changes to Cinder. The format follows Keep a Changelog; versions follow semantic versioning. Dates are the day the phase gate passed on Linux x86-64 (REPORT.md has the runs).
- [Engine README](https://cinder.ash10.dev/docs/readme.md): 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).
- [Third-party notices](https://cinder.ash10.dev/docs/third-party-notices.md): Every dependency is vendored as a git submodule under third_party/ at the exact ref below and built from source by native/. Licence texts are in each submodule at the path given. All licences are permissive; no copyleft code is linked into Cinder.

## For AI agents

- [AGENTS.md](https://cinder.ash10.dev/agents/AGENTS.md): build commands, container workflow, layering rules, the zero-allocation rule and Mojo 1.2.0 pitfalls in one brief.
- [Using Cinder with AI coding agents](https://cinder.ash10.dev/agents.md): how to give an agent Cinder context, prompts, MCP setup.
- [JSON index](https://cinder.ash10.dev/docs/index.json): pages, headings and API symbols.

## Optional

- [Full text](https://cinder.ash10.dev/llms-full.txt): every page above concatenated.