Documentation

Technical, implementation-facing documentation for the Synvael engine. This directory is the code-side counterpart to the game-design specification; it describes how subsystems are built, not what the game should feel like.

How documentation is layered

Documentation lives at three altitudes. Each layer answers a different question, and content is kept at the layer it belongs to so that no single file accretes everything.

Layer	Location	Answers	Churn
Project conventions	AGENTS.md	"What rules apply no matter which feature I touch?"	Slow, a finite set of cross-cutting invariants
Subsystem technical docs	this docs/ tree + Rust module docs (//!, ///)	"How does this subsystem work?"	Grows with features, distributed across files
Architecture decisions	docs/adr/	"Why was this chosen over the alternatives?"	Append-only, one file per decision

The rule that keeps AGENTS.md lean: if a piece of documentation is specific to one subsystem, it does not go in AGENTS.md. It goes in that subsystem's module docs or a docs/<subsystem>.md note, and AGENTS.md only links to it. AGENTS.md is an index and a rulebook, not a container for feature specs.

Where to put a new piece of documentation

• A rule true across the whole project (a convention, an invariant) → AGENTS.md.
• How one subsystem is implemented → prefer Rust module docs next to the code (//! at the top of the module). They cannot drift far from the code and render with cargo doc.
• Cross-file technical design too large for a doc comment (e.g. the rendering frame graph, the network protocol, the worldgen pipeline) → a docs/<subsystem>.md note.
• The reasoning behind a specific, hard-to-reverse choice → an ADR in docs/adr/.

Relationship to the design specification

The canonical design specification (intent, world rules, gameplay-system behaviour, and unresolved questions) is maintained separately and is not part of this repository. This docs/ tree records how the engine implements those designs.

Each subsystem note should name the design topic it implements (by title, e.g. "Design source: Worldgen"), so the trail from intent to implementation exists without coupling the repository to an external location. When the implementation and the design disagree, surface the disagreement rather than silently resolving it in code.

Index

• adr/: Architecture Decision Records.
  • adr/0001-record-architecture-decisions.md: establishes the ADR practice.
  • adr/0002-half-scale-voxel-grid.md: the half-scale voxel grid.
  • adr/0003-seed-deterministic-worldgen.md: seed-deterministic worldgen.
  • adr/0004-server-authoritative-simulation.md: server-authoritative simulation.
  • adr/0005-namespaced-content-ids.md: namespaced content IDs.
  • adr/0006-base-game-on-modding-api.md: base game built on the modding API.
  • adr/0007-declarative-content-via-modding-api.md: declarative content loads through the modding API.
  • adr/0008-split-coordinate-entity-positions.md: split-coordinate entity positions.
  • adr/0009-baseline-relative-sparse-chunk-persistence.md: baseline-relative sparse chunk persistence.
  • adr/0010-net-crate-async-runtime.md: dedicated net crate with a confined async runtime.
  • adr/0011-authority-stream-for-server-pushed-state.md: a dedicated authority stream for server-pushed state.
  • adr/template.md: template for new decisions.

Subsystem notes:

• packs.md: data packs & resource packs (load order, layout, resolution).
• rendering.md: rendering & coordinate gotchas (Vulkan clip space, Blender/glTF import).
• chunk_streaming.md: chunk streaming and async worker pipeline.
• meshing.md: greedy meshing, the mesh worker pool, and frustum culling.
• diagnostics.md: runtime statistics collection and the debug panel.
• save_format.md: chunk persistence, region-file layout, save actor, and load pipeline.

Further subsystem notes are added here as systems are implemented and locked.