> Cinder 0.1.0 documentation: ADR-0001: Build-versus-reuse decisions for the dependency stack
> Canonical page: https://cinder.ash10.dev/docs/adr/0001-dependency-stack/ · Source: `docs/adr/0001-dependency-stack.md` in the engine repository (engine commit 47c9352, imported 2026-11-09)
> Index of every page for agents: https://cinder.ash10.dev/llms.txt

# ADR-0001: Build-versus-reuse decisions for the dependency stack

Status: Accepted, 2026-11-08

## Context

The mission (section 2) lists a default library for every solved problem and allows replacement only
with evidence. Each row below records the decision, the pinned version, and the alternatives considered.
All libraries are vendored as git submodules under `third_party/` and built from source by `native/`.

## Decisions

| Concern | Decision | Pin | Alternatives considered and why rejected |
|---|---|---|---|
| Graphics | **Reuse wgpu-native** (webgpu.h), WGSL shaders | `v29.0.1.1` | Raw Vulkan + Metal: two backends to write and validate, months of work, no gain for this scope. SDL3 GPU API: no compute shader stage guarantees on all backends at the pinned release and a smaller validation layer than wgpu's. |
| Window/input | **Reuse SDL3** | `release-3.4.20` | GLFW: no gamepad rumble/haptics API parity, no file dialogs, weaker Wayland story. |
| Physics | **Reuse Jolt via joltc** | joltc `2bbcf73` (vendors Jolt 5.x; see THIRD_PARTY_NOTICES) | Bullet: C++ only, no maintained C API, weaker character controller. PhysX: C++ only, large. Writing our own: not the engine's job. |
| glTF | **Reuse cgltf** | `v1.15` | tinygltf: C++ and heavier; fastgltf: C++17 only. |
| Images | **Reuse stb_image** (source formats) and **KTX-Software** (KTX2 runtime, BasisU/UASTC encode) | stb `4e9b368`, KTX `v4.4.2` | Writing a PNG/JPEG decoder: solved problem. |
| Mesh processing | **Reuse meshoptimizer** and **MikkTSpace** | `v1.3`, `3e895b4` | Own vertex-cache optimiser or tangent generator: solved problems; MikkTSpace is the glTF-normative tangent basis. |
| Audio | **Reuse miniaudio** | `0.11.26` | OpenAL Soft: LGPL, needs a separate mixer design; SDL3 audio: no spatialiser or streaming decoders. |
| Debug UI | **Reuse Dear ImGui (docking) via Dear Bindings** with official SDL3 and WebGPU backends | imgui `v1.93.0-docking`, dear_bindings `v0.27` | cimgui: unofficial generator, lags releases; writing a UI: not the engine's job. |
| Profiling | **Reuse Tracy** | `v0.15.0` | Own profiler: not the engine's job. |
| ECS benchmark baseline | **Reuse flecs** (benchmark only, iterator API) | `v4.2.0` | Required by section 6 as the comparison target. |
| Bindings | **mojo-bindgen**, with the caveat recorded in ADR-0005 | see ADR-0005 | |
| Tests | Mojo `std.testing` + CTest for C | toolchain | |
| Env | **pixi** + **CMake/Ninja** | see docs/TOOLCHAIN.md | |

Written in Mojo, because they are the engine's own job or because Mojo's SIMD and `comptime` parameters
are the better tool: math, allocators, containers, job system, ECS, render graph and renderer front end,
culling, animation evaluation, asset database and cooker logic, scene serialization, gameplay framework,
sample game.

## Consequences

- Every pinned library's licence is permissive (MIT, zlib, BSD, Apache-2.0); recorded in
  `THIRD_PARTY_NOTICES.md`. No copyleft code is linked.
- wgpu-native is Rust. CMake drives `cargo` for it; see ADR-0004.
- The imgui `docking` branch is a release-tagged branch (`v1.93.0-docking`), pinned by tag like the rest.