Status: foundation
EXISTSon Linux/Wayland; Milestone 2 (First 3D and Free Camera) Phases 0–6EXISTSon Linux/Wayland + Vulkan 1.3 with Phase 6 / Gate G3SIGNED OFF BY OWNER (2026-11-18); wider engine architecturePLANNED.spawn-core,spawn-math,spawn-platform(Wayland),spawn-input,spawn-render(Vulkan 1.3),spawn-cli(offline Slang shader cook), and the rootspawn-enginecomposition binary implement the foundation and first-3d Phases 0–5 slices; all other crates (spawn-ecs,spawn-world,spawn-scene,spawn-assets,spawn-physics, etc.) and X11/Windows backends remainSCAFFOLDorPLANNED. The repository's root AGENTS.md and crate-levelAGENTS.mdfiles remain the authoritative ownership and agent-behavior rules.
| Document | What it answers |
|---|---|
| Engine invariants | What must never be violated anywhere in the engine? |
| Engine design | How do all subsystems fit together? |
| Quality gates | What must pass before a commit, merge, milestone or release? |
| Decision register | What has been decided, what is pending, and when to revisit? |
| Foundation overview | What was built in Milestone 1 (EXISTS on Linux/Wayland), and what was excluded? |
| Foundation specification | What must the first native runtime slice do? |
| Foundation design | How do the foundation subsystems cooperate without coupling? |
| Foundation invariants | What milestone rules govern the foundation slice? |
| Foundation verification | How were the foundation requirements proven? |
| Foundation delivery plan | In what order did the foundation increments land? |
| First 3D overview | What is in Milestone 2 (Phases 0–6 EXISTS on Linux/Wayland + Vulkan 1.3; Gate G3 SIGNED OFF BY OWNER (2026-11-18)), and what stays out of scope? |
| First 3D specification | What must the initial 3D rendering, shader cook, math, and free-camera slice do? |
| First 3D design | How do spawn-math, spawn-cli, spawn-render, and spawn-engine deliver 3D without coupling? |
| First 3D invariants | What spatial, shader, GPU, and simulation/presentation rules govern Milestone 2? |
| First 3D verification | How are math precision, offline shader cooking, reversed-Z occlusion, and camera determinism proven, and what remains for Gate G3? |
| First 3D delivery plan | In what order (Phases 0–6) is Milestone 2 progressing? |
| Architecture decisions | Which choices are proposed or accepted? |
| Approved dependencies | Which third-party crates may be added, where, and which are rejected? |
- AGENTS.md: enduring rules for coding agents, boundaries, and ownership.
- docs/architecture: engine-wide invariants (binding), technical design, quality gates and the decision register.
- docs/DEPENDENCIES.md: approved, rejected and deferred third-party crates.
- docs/foundation: specification and verification record of Spawn's first running slice (
EXISTSon Linux/Wayland). - docs/first-3d: specification, design, invariants, and verification record of Milestone 2 (Phases 0–6
EXISTSon Linux/Wayland + Vulkan 1.3; Phase 6 / Gate G3SIGNED OFF BY OWNER (2026-11-18)). - docs/adr: rationale and status of engineering decisions; proposed ADRs do not authorize implementation.
- Rust code and Cargo manifests: the actual implemented state. If documentation disagrees with code, flag and resolve the conflict, do not assume the document was implemented.
When a milestone requirement changes, update its requirement ID, related invariants, verification cases, and affected ADRs in the same change. Do not silently promote Proposed decisions to Accepted. Do not invent API types or record speculative features as delivered.
Scope at this stage:
- Implemented (foundation/,
EXISTSon Linux/Wayland): native application lifecycle, window, raw input events (including relative pointer motion and cursor constraints), semantic input sampling, a Vulkan 1.3 clear frame, graceful recovery, and headless timing/input/composition tests. - Implemented (first-3d/, Phases 0–6
EXISTSon Linux/Wayland + Vulkan 1.3; Phase 6 / Gate G3SIGNED OFF BY OWNER (2026-11-18)):spawn-math(f32primitives,f64world positions, reversed-Z, single-site Vulkan Y-flip,libmdeterministic subset), offline Slang → SPIR-V shader cooking inspawn-cli(ADR-0014), in-house Vulkan 1.3 block allocator, buffers,D32_SFLOATreversed-Z depth, and dynamic-rendering mesh pipeline inspawn-render, plus a genre-free 60 Hzf64free-fly camera withalphapresentation interpolation, procedural 3D scene, and camera-relativef32submission inspawn-engine. No genre-specific behavior; X11, Windows, and wider engine subsystems remainPLANNED/SCAFFOLD.