3.8 KiB
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 withcargo 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>.mdnote. - 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/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).
Further subsystem notes are added here as systems are implemented and locked.