48 lines
3.7 KiB
Markdown
48 lines
3.7 KiB
Markdown
# 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`](../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/`](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/`](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/`](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 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/template.md`](adr/template.md): template for new decisions.
|
|
|
|
Subsystem notes:
|
|
|
|
- [`packs.md`](packs.md): data packs & resource packs (load order, layout, resolution).
|
|
- [`rendering.md`](rendering.md): rendering & coordinate gotchas (Vulkan clip space, Blender/glTF import).
|
|
|
|
Further subsystem notes are added here as systems are implemented and locked.
|