magicciv/.project/designs

Engineering Designs

Visual references for system architecture and screens. These designs document what is rendered, how data flows, and the geometric primitives the simulation runs on. They are not user-facing tutorials; they exist so someone modifying the relevant code can see the whole shape at once.

Surfaces

This directory has three surfaces, listed in the order to add new work:

1. React app at app/ — Vite + React 19 + styled-components + react-router-dom. The active surface for interactive mockups. Run with pnpm dev from app/. New interactive sketches go here as app/src/pages/<Name>.tsx plus a route in app/src/App.tsx and a NavLink in app/src/pages/Index.tsx.
2. Markdown design docs (*.md here) — annotated anatomies, source-map tables, and architecture diagrams. The active surface for static documentation.
3. Legacy HTML sketches (*-sketch.html here) — pre-React static mockups. Kept as side-by-side references; new sketches should be added to the React app (#1), not as standalone HTML.

Hex grid

The hex tile geometry — 1 centre slot + 6 shared-edge slots — the differentiator from every other 4X's hex grid.

File	Surface	What it shows
app/src/pages/HexFormation.tsx (route /hex)	React	Interactive mockup; click slots to highlight; toggle centre / edges / both
hex-formation-duality.md	Markdown	Annotated hex with central area + 6 edge slots; direction → edge lookup; what the geometry buys
hex-formation-sketch.html	Legacy HTML	Self-contained static reference; mirrors the React mockup
formation-slot-anatomy.md	Markdown	A centre slot record + an edge slot record — both annotated with field maps and damage exposure

Source of truth. public/games/age-of-dwarves/docs/HEX_GEOMETRY.md is the canonical specification. The engineering designs in this section illustrate it; if they conflict, the canonical doc wins.

Tech / Culture trees

Visual reference for the research-tree UX. Both trees share the same screen (KnowledgeTree base scene); only the data source, vocabulary, and signal names change.

File	What it shows
overview.md	Full screen layout, both trees side-by-side, the shared scene structure
card-anatomy.md	Annotated tech / tradition card — every visual element labelled
detail-panel.md	Annotated right-side detail panel — sections + data-source map
indicator-legend.md	The 7 unlock-type letter badges and their accent colours
tech-tree-full.md	Full tech tree — 8 pillars × 10 tiers with example nodes
culture-tree-full.md	Full culture tree — 6 pillars × 10 tiers with all 30 traditions
data-flow.md	JSON → Rust → GDExtension → GDScript → UI pipeline
unlock-categorization.md	How each typed bucket renders (units / buildings / wonders / lenses / resources / mechanics)

Source of truth. The actual visual rendering lives in src/game/engine/scenes/knowledge_tree/knowledge_tree.gd. If a design disagrees with the code, the code wins — open a PR to update the design.

Statistics, end-of-game & replays

Civ-style stats surfaces during a live game, the post-game summary, and the persistent past-games archive. All three read from one shared GameHistory artefact owned by the mc-replay crate — no parallel bookkeeping.

File	What it shows
stats-screens.md	Five live-game tabs (Demographics, Graphs, Rankings, Replay, Histories); TurnSnapshot schema; visibility rules per contact-state; composite score formula
end-game-summary.md	Outcome banner; final standings; full-game score graph with event markers; awards (JSON-driven); footer actions (View Map / Watch Replay / Save / Export / Main Menu); GameOver triggers
past-games-replays.md	Past Games index card grid; rehydrated end-game summary; replay viewer (scrubber + ticker + stats overlay, projection not re-simulation); compare view; archive layout on disk; GameHistory schema; per-pack versioning across the three-game series

Source of truth. src/simulator/crates/mc-replay/ (to be created) owns GameHistory, TurnSnapshot, TurnEvent, and the archive I/O. Score weights, awards, and victory conditions live as JSON under public/games/age-of-dwarves/data/. If a design here disagrees with the crate or the JSON, the code wins.

Audio system

Visual reference for the sound stack — engine architecture, manifest schema, categorical fallback ladder, OSS sourcing pipeline, per-pack swappability across the three games in the series.

File	Surface	What it shows
audio-system.md	Markdown	One-engine-many-packs diagram; sfx + music.tracks schema; the 4-step play_for_entity resolution ladder; per-entry _silent fallback chain; signal-flow from EventBus to AudioStreamPlayer pool; bus topology + volume sliders; OSS sourcing pipeline with the licence gate; pack layout on disk; file-by-file ownership

Source of truth. src/game/engine/src/autoloads/audio_manager.gd for runtime behaviour; public/games/age-of-dwarves/data/audio.json for the live manifest; tools/audio-validate.py and tools/audio-licenses-render.py for the gates. If a design here disagrees with one of those, the code wins.

Other sketches (ported to React)

Each static HTML mockup has a React port in app/; the HTML files remain as side-by-side references.

• combat-preview-sketch.html → CombatPreview page (route /combat)
• hud-sketch.html → Hud page (route /hud)
• main-menu-sketch.html → MainMenu page (route /menu)
• tech-tree-sketch.html → TechTree page (route /tech)
• promotion-picker-sketch.html → PromotionPicker page (route /promotion)
• city-screen-sketch.html → CityScreen page (route /city)
• design-gallery.html → DesignGallery page (route /gallery)

Procedural terrain

Canonical specifications for the Wave 0–E worldgen pipeline. Each doc is the contract that the corresponding Rust crate mechanically implements.

Canonical doc	Companion lab page	Objective
WORLDGEN_PIPELINE.md	/world-gen (WorldGen.tsx)	p1-51
TECTONICS.md	/world-gen/tectonics (Tectonics.tsx)	p1-50
HYDROLOGY.md	/world-gen/hydrology (Hydrology.tsx)	p1-47
CLIMATE.md	/world-gen/climate (Climate.tsx)	p2-49
ECOLOGY_BINDING.md	/world-gen/ecology (Ecology.tsx) + /world-gen/lab (Lab.tsx, integration)	p1-48, p1-49
WORLDGEN_RNG.md	/world-gen/rng (Rng.tsx)	p2-50
WORLDGEN_PRESETS.md	/world-gen/presets (Presets.tsx) + new-game screen (Wave E)	p2-51

Source of truth. These docs are the canonical spec; if the Rust implementation or the design lab disagree, the canonical doc wins — open a PR to resolve the conflict explicitly.

Worldsim runtime & terraforming cascade

Engineering designs for the runtime (per-turn) worldsim — the living-world USP. These are build-plan / architecture designs (not lab pages); they document how the existing worldgen engines are driven inside the playable turn via WorldSim::step and how the terraforming cascade hooks into that seam.

Design doc	What it shows	Objective(s)
p2-80-bullet2-port-sizing.md	Feasibility + sizing + phased-bridgehead plan for routing the playable discrete turn through a single Rust WorldSim::step (the whole-game Rail-1 port question)	p2-80
p2-76-79-terraforming-cascade-design.md	Build-ready engineering design for the terraforming → environmental cascade: bunker → deposit destruction + contamination → runtime localized hydrology re-solve → flood/parch → flora dieback → fauna migration. Data model, WorldSim::step integration seam, increment ordering, risks, open questions	p2-76, p2-77, p2-78, p2-79

Substrate. Both ride the WorldSim::step seam from p2-80 (src/simulator/crates/mc-worldsim/). The cascade reuses the worldgen hydrology solver (HYDROLOGY.md / mc-mapgen/src/hydrology.rs) windowed for the runtime re-solve.

Game-start scripts

Engine for the opening sequence — the hardcoded freepeople tribe-founding prologue (p0-34) becomes a declarative JSON script run by a generic Rust runner, with the dwarf prologue as the bundled default and a modder-facing op vocabulary.

Design doc	What it shows	Objective(s)
p3-14-game-start-script-design.md	Declarative start-script model + bounded op vocabulary, StartScriptRunner architecture (replaces PrologueTurn::advance), default-script-as-data completeness proof, determinism contract, modder validation/error story, selection/layering, increments	p3-14

See also

• UI_DESIGN_SYSTEM.md (this directory) — top-level art direction brief covering mood, palette, and typography for the whole game. The per-screen designs above inherit those rules; they don't override them.
• app/src/theme.ts — design-token export used by every React page (t.bg.*, t.text.*, t.accent.*, t.border.*, t.font.*, t.radius.*).