Cinder architecture

Module map #

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.

sample/                 third-person sample game (Mojo), a `Game` run by cinder/app
  └── cinder/app        App runtime: owns every subsystem, fixed-step loop, headless mode, CLI
        └── cinder/tools      ImGui debug overlay (inspector, asset browser, render graph, log)
        └── cinder/{render,physics,anim,audio,input,assets,scene}
              └── cinder/ecs            archetype ECS, queries, command buffers, hierarchy, scheduler
              └── cinder/gfx            safe typed wgpu layer, shader manager, hot reload, debug draw
              └── cinder/platform       SDL3 window/input/gamepad, surfaces, ImGui event forwarding
                    └── cinder/core     log, assert, arena, handles, ring, math, jobs, time, fs, profile, boxed
                          └── cinder/ffi    generated bindings + layout tests (never hand-edited)
                                └── native/   libcinder_native (C11 shim) + vendored C/C++ libs

The C boundary #

• One shim, one shared library, flat C ABI (cinder_native.h, C11).
• Pull model. C callbacks (wgpu async requests, device lost, uncaptured errors, Jolt contacts, miniaudio data, SDL log) write fixed-size events into fixed-capacity SPSC/MPSC lock-free rings inside the shim. Mojo drains them once per frame on the main thread. Mojo code never executes on a C thread unless spike 4 proves it safe and an ADR records that (ADR-0003).
• Generated raw bindings live in cinder/ffi and are never edited by hand. A C program emits sizeof/alignof/offsetof for every bound struct and every enum value; a generated Mojo test asserts identical values. Mismatch fails CI.
• Safe wrappers: one distinct handle struct per resource type, ownership through __deinit__, explicit lifetimes for borrowed C strings and views, each shared library loaded exactly once, every unsafe_ call annotated with # SAFETY:.

Threading model #

• Main thread: SDL event pump, window, presentation (wgpuSurfacePresent), ImGui.
• Job system (cinder/core/jobs): one worker per physical core minus one, work-stealing deques, a per-frame dependency graph. Everything else (culling, animation, ECS systems, asset decode, physics step through Jolt's own job system adapter) runs there.
• Shared state crosses threads only through jobs, atomics or documented locks named in docs/THREADING.md.
• Audio: miniaudio's device thread runs in C only; it reads a lock-free command ring and never calls Mojo.

Frame loop #

Fixed 60 Hz simulation with accumulator (App.run_frame: poll events, fixed steps with physics and Game.fixed_update, Game.update, animation jobs, transform propagation, audio sync, render-scene bridge, render, ImGui, present or offscreen readback). Per-frame memory lives in persistent scratch fields that are cleared, never freed, between frames; steady state performs zero heap allocations from Mojo code (asserted by tests/perf/test_zero_alloc.mojo, ADR-0014).

Conventions (fixed) #

Right-handed, Y up, −Z forward, metres, column-major matrices, reverse-Z with infinite far plane, linear lighting, sRGB render targets, RGBA16F intermediates. Recoverable failures raise typed errors; broken invariants abort with a message.