Synvael/docs

Documentation

This is the technical, implementation-facing documentation for Synvael. You can think of this directory as the code-side counterpart to the game-design specification. It describes exactly how subsystems are built under the hood, not what the game should feel like to play.

How documentation is layered

Our documentation lives at three different altitudes. Each layer answers a distinct type of question, and we keep content strictly at the layer it belongs to. This ensures no single file turns into an unreadable monolith.

Layer	Location	Answers	Churn
Project conventions	DEVELOPMENT.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

We use a strict rule to keep DEVELOPMENT.md lean: if a piece of documentation is specific to only one subsystem, it does not go in DEVELOPMENT.md. It belongs in that subsystem's module docs or a docs/<subsystem>.md note, and DEVELOPMENT.md only links to it. DEVELOPMENT.md is an index and a rulebook, not a dumping ground for feature specs.

Where to put a new piece of documentation

Not every subsystem gets a dedicated document. You should default to using module documentation unless the technical design spans across multiple modules.

• A rule that is true across the whole project (like a convention or an invariant) goes in DEVELOPMENT.md.
• How a specific subsystem is implemented belongs in Rust module docs right next to the code (//! at the top of the module). These docs can't drift far from the code and they render cleanly with cargo doc.
• Cross-file technical designs that are just too large for a doc comment (like the rendering frame graph, the network protocol, or the worldgen pipeline) get a dedicated docs/<subsystem>.md note.
• The reasoning behind a specific, hard-to-reverse choice becomes an ADR in docs/adr/.

Relationship to the design specification

The canonical design specification (which covers intent, world rules, gameplay-system behavior, and unresolved questions) is maintained entirely separately and is not part of this repository. This docs/ tree exists strictly to record how the engine implements those designs.

To maintain the link between intent and implementation, each subsystem note should explicitly name the design topic it implements (by title, like "Design source: Worldgen"). This lets us trace the path from design to code without tightly coupling the repository to an external location. If the implementation and the design ever diverge, make sure to document that discrepancy clearly in the relevant subsystem note or ADR, rather than just 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 directly 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: The template for logging new decisions.

Subsystem notes:

• packs.md: Data packs and resource packs (load order, layout, resolution).
• rendering.md: Rendering and coordinate gotchas (Vulkan clip space, Blender/glTF import).
• chunk_streaming.md: Chunk streaming and the 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.

We will add further subsystem notes here as those systems are implemented and locked down.