Skip to content
brasga-aPublic

About

A modular, general-purpose game engine built in Rust, focused on performance, extensibility, and scalable multiplayer, with optional Luau scripting.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Spawn Engineering Documentation

Status: foundation EXISTS on Linux/Wayland; Milestone 2 (First 3D and Free Camera) Phases 0–6 EXISTS on Linux/Wayland + Vulkan 1.3 with Phase 6 / Gate G3 SIGNED OFF BY OWNER (2026-11-18); wider engine architecture PLANNED. spawn-core, spawn-math, spawn-platform (Wayland), spawn-input, spawn-render (Vulkan 1.3), spawn-cli (offline Slang shader cook), and the root spawn-engine composition 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 remain SCAFFOLD or PLANNED. The repository's root AGENTS.md and crate-level AGENTS.md files remain the authoritative ownership and agent-behavior rules.

Start here

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?

Documentation hierarchy

  • 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 (EXISTS on Linux/Wayland).
  • docs/first-3d: specification, design, invariants, and verification record of Milestone 2 (Phases 0–6 EXISTS on Linux/Wayland + Vulkan 1.3; Phase 6 / Gate G3 SIGNED 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.

Change policy

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/, EXISTS on 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 EXISTS on Linux/Wayland + Vulkan 1.3; Phase 6 / Gate G3 SIGNED OFF BY OWNER (2026-11-18)): spawn-math (f32 primitives, f64 world positions, reversed-Z, single-site Vulkan Y-flip, libm deterministic subset), offline Slang → SPIR-V shader cooking in spawn-cli (ADR-0014), in-house Vulkan 1.3 block allocator, buffers, D32_SFLOAT reversed-Z depth, and dynamic-rendering mesh pipeline in spawn-render, plus a genre-free 60 Hz f64 free-fly camera with alpha presentation interpolation, procedural 3D scene, and camera-relative f32 submission in spawn-engine. No genre-specific behavior; X11, Windows, and wider engine subsystems remain PLANNED / SCAFFOLD.

About

A modular, general-purpose game engine built in Rust, focused on performance, extensibility, and scalable multiplayer, with optional Luau scripting.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages