Cinder v0.1.0
DocsStart

Cinder documentation

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 .md, and the whole set is indexed for AI agents in /llms.txt.

Start #

  • Build your first game: 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: 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: 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: 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.

Guides #

  • Subsystem guides: 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): 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): 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): cinder/assets gets content from disk into the renderer. It has two paths:
  • Audio (cinder/audio): 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: 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): 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: 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): 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): 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: 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: 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): 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: 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: 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: 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: 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: Every version below is pinned. Changing one requires an ADR and a green CI run.
  • Render validation: 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: 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.

Decisions #

API reference #

Project #

  • Deliverable report: 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: 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: 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: 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: 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.

Using Cinder with AI agents #

View as Markdown