# Part III — Pipelines & Workflows

#### The data pipeline

The path every piece of battlefield information takes:

```
map files (facts)  ──►  rules layer (judgments)  ──►  consumers (pathfinding, combat, AI, rendering)

```

1. **Maps are facts.** A `.vmap` file (or a generator) holds voxels: material, shape, rotation, height.
2. **The registry names the materials** (append-only). The codec checks catalog versions so old maps can't silently load wrong.
3. **The rules layer interprets.** Consumers never read "walkable" from the map — they read facts and ask the rules.
4. **Consumers decide.** Pathfinding, and later combat and AI, produce verdicts (reachable, cost, damage) that are *reported*, never written back into the map.

#### The build & test pipeline

The guardrail that keeps the game trustworthy:

1. **`./run_tests.sh`** imports the project (so new classes register), then runs the whole headless test suite.
2. The suite covers the codec round-trips (byte-exact), the append-only catalog contract, and every subsystem's core behavior — including all of the pathfinding pipeline.
3. A **pre-commit hook** runs the suite; a commit that turns the suite red is rejected.
4. Tests are small, focused files under `tests/`, auto-discovered by name.

**Rule:** no red commits, ever. When behavior changes, the tests change with it.

#### The content & asset pipeline

How maps and content get made:

- **Builders** (`tools/*.gd`, run from Godot) construct demo maps, the test "museum" map, and the voxel demos programmatically, then pack them through the same codec any game would use.
- **The test map** is the scenario museum — every hazard, elevation shape, layered structure, and wall the model can express — and its tests assert the map's shape so builders can't drift.
- Future **procedural generation** and the **in-game editor** are just other producers of the same map data, flowing through the same codec and renderer.

#### The docs & wiki pipeline

The documentation is versioned in the repo and mirrored to the wiki:

1. **Canonical docs live in the repo:** this bible, `MAP_RULES.md`, `CONTEXT.md`.
2. **`tools/sync_wiki.py`** reads a manifest (`tools/wiki_manifest.json`) and pushes each doc (and each bible part) to a BookStack book as chapters and pages — creating or updating in place.
3. The wiki is a **rendered view**; the repo is the source of truth. When the game changes, the docs change first (rule below) and the sync re-mirrors them.

#### The ship workflow

- Branch `main`; commits are concise, lowercase, imperative, focused on "why"; push frequently to the Forgejo remote.
- Repo uses the **SHA-256 object format** — never recreate it as sha1, never rely on push-to-create.
- When the game is ready to distribute on Arch Linux, a PKGBUILD makes it installable with `paru` (see `CONTEXT.md`).

---