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
cargofor it; see ADR-0004. - The imgui
dockingbranch is a release-tagged branch (v1.93.0-docking), pinned by tag like the rest.