diff --git a/.project/designs/stats-screens.md b/.project/designs/stats-screens.md new file mode 100644 index 00000000..d64e3874 --- /dev/null +++ b/.project/designs/stats-screens.md @@ -0,0 +1,67 @@ +# In-game Statistics Screens + +Civ-style statistics surfaced during a live game. Player can open at any turn to compare their civilization against rivals across multiple axes. Read-only views over per-turn snapshots the simulator already records for the AI's strategic evaluation. + +## Surfaces + +Five tabs in a single `Statistics` modal scene, opened from the HUD info button (or `F9`). Each tab is one full-bleed view, so opening the modal lands on the most-recently-viewed tab. + +| Tab | What it shows | Primary widget | +|---|---|---| +| **Demographics** | Single-turn snapshot of every clan: population, cities, army strength, gold, culture, tech count, score. Player's row highlighted; columns sortable. | Sortable table | +| **Graphs** | Per-turn line graph; one line per known clan. Y-axis selector: score / population / cities / army / gold-per-turn / culture-per-turn / tech-count / land-area. X-axis is turn number. | Multi-line chart | +| **Rankings** | Top-N leaderboard for the currently-selected metric. Reuses the Graphs Y-axis selector. Shows trend arrow vs. previous turn. | Ranked list | +| **Replay** | Time-scrubber over the current game's turn history. Map preview + key-events ticker (city founded, war declared, wonder built, leader killed). Live-game version of the post-game replay (see [past-games-replays.md](past-games-replays.md)). | Map + scrubber + event log | +| **Histories** | Per-clan chronicle: founding turn, wars fought (with outcomes), wonders built, eras entered, leaders. Tab through clans. | Timeline | + +## Visibility rules + +- A rival clan only appears in Demographics / Graphs / Rankings once the player has met them. Pre-contact rivals are absent (not greyed) — discovering them mid-game retroactively backfills their line on the graph from the contact turn forward only. +- Espionage / scrying upgrades (post-Game-1) widen what's visible per rival; in Game 1 every met rival shows the full column. + +## Data source + +Each turn-end the simulator appends one `ClanStatSnapshot` row per clan to `GameHistory.snapshots: Vec`. Snapshots are the same data the strategic AI already reads for threat assessment — no new bookkeeping, just a UI projection. + +| Field | Type | Source crate | +|---|---|---| +| `turn` | `u32` | `mc-turn` | +| `clan_id` | `ClanId` | `mc-core` | +| `population` | `u32` | `mc-economy` | +| `cities` | `u32` | `mc-economy` | +| `army_strength` | `f32` | `mc-combat` (sum of unit power) | +| `gold` | `i64`, `gold_per_turn` | `mc-economy` | +| `culture_per_turn` | `f32` | `mc-economy` | +| `tech_count` | `u32` | `mc-tech` | +| `land_area` | `u32` (hexes owned) | `mc-economy` | +| `score` | `f32` | `mc-score` (composite) | + +`GameHistory` is owned by `mc-replay` (new crate, see [past-games-replays.md](past-games-replays.md)) and is the same artefact serialized at game-end for the past-games archive. + +## Score formula + +Score is one composite number used for the Rankings default and for end-game ordering. Weights live in `public/games/age-of-dwarves/data/score.json` (Rail-2: no hardcoded weights). First pass: + +``` +score = w_pop * population + + w_cities * cities + + w_tech * tech_count + + w_culture * culture_total + + w_land * land_area + + w_wonders * wonder_count * 10 + + w_military * army_strength +``` + +The exact weights are tuning data, not design — the design commitment is "one composite score, JSON-driven weights, recomputed every turn-end". + +## Source-of-truth pointers + +- Snapshot type + history container: `src/simulator/crates/mc-replay/src/snapshot.rs` (to be created) +- Score formula data: `public/games/age-of-dwarves/data/score.json` (to be created) +- Modal scene: `src/game/engine/scenes/statistics/statistics.gd` (to be created) +- React mockup target: `app/src/pages/Statistics.tsx` (route `/stats`) + +## See also + +- [end-game-summary.md](end-game-summary.md) — terminal version of these stats +- [past-games-replays.md](past-games-replays.md) — archive surface that consumes the same `GameHistory`