58 lines
5.3 KiB
Markdown
58 lines
5.3 KiB
Markdown
# 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`](../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/`](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/`](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/`](adr/): Architecture Decision Records.
|
|
- [`adr/0001-record-architecture-decisions.md`](adr/0001-record-architecture-decisions.md): Establishes the ADR practice.
|
|
- [`adr/0002-half-scale-voxel-grid.md`](adr/0002-half-scale-voxel-grid.md): The half-scale voxel grid.
|
|
- [`adr/0003-seed-deterministic-worldgen.md`](adr/0003-seed-deterministic-worldgen.md): Seed-deterministic worldgen.
|
|
- [`adr/0004-server-authoritative-simulation.md`](adr/0004-server-authoritative-simulation.md): Server-authoritative simulation.
|
|
- [`adr/0005-namespaced-content-ids.md`](adr/0005-namespaced-content-ids.md): Namespaced content IDs.
|
|
- [`adr/0006-base-game-on-modding-api.md`](adr/0006-base-game-on-modding-api.md): Base game built directly on the modding API.
|
|
- [`adr/0007-declarative-content-via-modding-api.md`](adr/0007-declarative-content-via-modding-api.md): Declarative content loads through the modding API.
|
|
- [`adr/0008-split-coordinate-entity-positions.md`](adr/0008-split-coordinate-entity-positions.md): Split-coordinate entity positions.
|
|
- [`adr/0009-baseline-relative-sparse-chunk-persistence.md`](adr/0009-baseline-relative-sparse-chunk-persistence.md): Baseline-relative sparse chunk persistence.
|
|
- [`adr/0010-net-crate-async-runtime.md`](adr/0010-net-crate-async-runtime.md): Dedicated `net` crate with a confined async runtime.
|
|
- [`adr/0011-authority-stream-for-server-pushed-state.md`](adr/0011-authority-stream-for-server-pushed-state.md): A dedicated authority stream for server-pushed state.
|
|
- [`adr/template.md`](adr/template.md): The template for logging new decisions.
|
|
|
|
Subsystem notes:
|
|
|
|
- [`packs.md`](packs.md): Data packs and resource packs (load order, layout, resolution).
|
|
- [`rendering.md`](rendering.md): Rendering and coordinate gotchas (Vulkan clip space, Blender/glTF import).
|
|
- [`chunk_streaming.md`](chunk_streaming.md): Chunk streaming and the async worker pipeline.
|
|
- [`meshing.md`](meshing.md): Greedy meshing, the mesh worker pool, and frustum culling.
|
|
- [`diagnostics.md`](diagnostics.md): Runtime statistics collection and the debug panel.
|
|
- [`save_format.md`](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.
|