Initial commit: Theriapolis baseline at port/godot branch point

Captures the pre-Godot-port state of the codebase. This is the rollback anchor for the Godot port (M0 of theriapolis-rpg-implementation-plan-godot-port.md). All Phase 0 through Phase 6.5 work is included; Phase 7 is in flight. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-04-30 20:40:51 -07:00
commit b451f83174
525 changed files with 75786 additions and 0 deletions
@@ -0,0 +1,750 @@
+# Theriapolis — Godot Port — Design & Implementation Plan
+
+**Status:** Proposed (drafted 2026-04-30).
+Targets the codebase state **after Phase 7 ships**: SAVE_SCHEMA_VERSION ≥ 7,
+~700+ tests green, dungeons + PoI interiors + dialogue→combat handoff live,
+17–19 screens in `Theriapolis.Game`, CodexUI as the in-game UI framework.
+
+**Audience:** the agent who will land the Godot port. Read §3 (pre-flight audit)
+before writing code — the size and shape of the rewrite surface determines milestone
+ordering. Read §10 (risks) before committing to dates.
+
+**Governing docs:**
+- `theriapolis-rpg-implementation-plan.md` §12 (binding hard rules — all still
+  apply post-port)
+- `CharacterCreator.zip` (at repo root) — the **canonical visual + interaction
+  spec** for character creation and, by extension, the design language for
+  every other screen. See `README.md` inside the zip for the integration
+  contract; `index.html` `<style>` block for the full design system; `src/*.jsx`
+  for component structure. **This supersedes `theriapolis-codex-ui-implementation-plan.md`
+  and the existing CodexUI implementation as design authority for the port.**
+- `theriapolis-codex-ui-implementation-plan.md` — historical only. CodexUI is
+  the "pale imitation" of the React prototype that we're discarding.
+- `theriapolis-rpg-implementation-plan-phase7.md` §1.10 (Phase-7 carryover
+  items — verify each is in `Core` before port begins)
+- `CLAUDE.md` "Hard Rules" section — every rule remains in force; the port
+  changes the rendering host, not the rules.
+
+**All hard rules from the original plan §12 remain in force.** No engine code
+in `Theriapolis.Core`, all RNG via `SeededRng`, all magic numbers in
+`Constants.cs`, determinism + linear-feature exclusion contracts unchanged. The
+architecture test gets a one-line update (the forbidden namespace becomes
+`Godot` instead of `Microsoft.Xna`).
+
+---
+
+## 1. Goals & non-goals
+
+### Goals
+
+1. **Replace MonoGame + Myra + CodexUI with Godot 4 (C#).** Modern, composable
+   `Control`-node UI; no more hand-rolling NineSlice and layout primitives.
+2. **Preserve `Theriapolis.Core` byte-for-byte.** Zero changes to worldgen,
+   RNG, polylines, settlements, dungeons, save schema, or any deterministic
+   subsystem. The architecture test continues to enforce engine-free Core.
+3. **Adopt the React prototype's design language as the new in-game UI.**
+   `CharacterCreator.zip` is the spec: parchment / dark / blood themes via
+   CSS custom properties, illuminated-codex typography (Cormorant Garamond,
+   Crimson Pro, Cinzel, etc.), trait/skill hover popovers with viewport
+   clamping, floating Aside summary, codex-styled stepper, foil/seal/rule
+   visual vocabulary. Every screen — not just character creation — adopts
+   this design language.
+4. **Behavioural parity for every shipped screen.** Title, character
+   creation, world map, play (tactical), combat HUD, inventory, save/load,
+   level-up, shop, quest log, reputation, defeated, pause, interaction,
+   dungeon, plus the Phase-7 dialogue→combat overlay. *Visual* parity with
+   today's CodexUI is **not** a goal — the React prototype is the new
+   baseline. Behavioural parity (what each screen *does*) is the goal.
+5. **Ship all three themes.** Parchment (default), dark (leather &
+   candlelight), blood (warm crimson). The React prototype already designed
+   them; Godot's Theme + ThemeVariation system makes shipping all three
+   approximately free. Theme is a runtime player setting, not a dev tweak.
+6. **Tests still green.** All ~700 Core/worldgen/determinism/save tests pass
+   unchanged. Project builds and runs `dotnet test` and the headless
+   `Theriapolis.Tools` CLI exactly as before.
+7. **One Godot project replacing two C# projects** (`Theriapolis.Game` +
+   `Theriapolis.Desktop`). The Godot project references `Theriapolis.Core`
+   directly and ships as the new desktop entry point.
+
+### Non-goals
+
+- **No new gameplay features.** This is a port + UI rebuild, not a phase.
+  Defer all "while we're in there" gameplay temptations. The character-creation
+  surface gains a Subclass step (§5.6) only because Phase 6.5 already shipped
+  subclass selection and the existing CodexUI surfaces it; the React prototype
+  predates 6.5 and doesn't include it. This is a forced reconciliation, not new
+  scope.
+- **No mobile / web export** in this port. Godot supports them; we're not
+  exercising them yet. (The React prototype is web-native; if a future phase
+  wants a true web client, that's a separate effort.)
+- **No save-format change.** Saves written by the MonoGame build must load in
+  the Godot build and vice versa. SAVE_SCHEMA_VERSION does not bump.
+- **No Godot-side determinism.** Core is the deterministic boundary. Anything
+  Godot does with rendering/animation/UI state is presentation-only.
+- **No embedding the React prototype.** We are not shipping a webview, an
+  Electron sidecar, or any HTML rendering inside Godot. The zip is a *design
+  spec*, not a build artifact.
+- **No data-schema migration in this port.** If `CharacterCreator.zip`'s
+  `data/*.json` shape diverges from the live `Content/Data/*.json` (it almost
+  certainly does — the zip predates Phase 6.5), the live schema wins. The
+  React prototype's data files are reference material for *UI structure*, not
+  for *content*.
+
+---
+
+## 2a. The CharacterCreator.zip baseline
+
+The user has a React-via-Babel character-creation prototype (Claude Design
+output, ~345 KB) that they prefer over the in-game CodexUI implementation.
+CodexUI was a "pale imitation" of this prototype; rather than re-port the
+imitation, we go back to the source. The prototype is at the repo root as
+`CharacterCreator.zip` and contains:
+
+- `index.html` — host page with the **complete design system** in a single
+  `<style>` block: CSS custom properties for three themes (parchment / dark /
+  blood), density toggle (compact/normal), font pairings, page layout,
+  stepper, cards, chips, popovers, drag affordances. This is the visual
+  source of truth.
+- `src/main.jsx`, `src/app.jsx` — wizard shell, 7-step state machine,
+  per-step validation, forward-navigation gating, `Aside` summary
+  computation (sums clade + species ability mods).
+- `src/steps.jsx` — all 7 step components (`StepClade`, `StepSpecies`,
+  `StepClass`, `StepBackground`, `StepStats`, `StepSkills`, `StepReview`).
+- `src/data.jsx` — runtime constants (ABILITIES, SKILL_LABEL, SKILL_DESC,
+  SKILL_ABILITY, SIZE_LABEL, LANGUAGES, ITEM_NAME, STANDARD_ARRAY,
+  abilityMod, signed). The Godot port copies the *constants*, not the JS.
+- `src/trait-hint.jsx` — the hover-popover primitives (TraitName,
+  LanguageChip, SkillChip, BonusPill) with viewport clamping behaviour.
+  Reusable across every screen.
+- `src/portrait.jsx` — placeholder portrait component (silhouette /
+  heraldry / placeholder modes).
+- `data/{clades,species,classes,backgrounds}.json` — content data **as
+  shaped for the UI**. Field-level docs in the README §"File map".
+- `README.md` — explicit integration instructions written for downstream
+  developers; covers state shape, drag-drop payloads, popover clamping,
+  theme system. Read this once before starting M5.
+
+**What we use from the zip:**
+- The CSS design system → ported to a Godot `Theme` resource (M5).
+- The 7-step wizard structure, validation rules, Aside layout → ported to
+  Godot Control nodes (M6).
+- The hover-popover behaviour → reusable Godot widget (M5).
+- The drag-drop ability-assignment payload contract → Godot's drag-drop API.
+
+**What we don't use from the zip:**
+- The React/Babel runtime — irrelevant in Godot.
+- The HTML/JSX components — replaced by Godot scenes + C# scripts.
+- The `data/*.json` files — `Content/Data/*.json` (the live game data) is
+  authoritative for content. The zip's data files are reference material for
+  UI structure only.
+
+## 2b. Why now / why Godot
+
+The MonoGame UI ceiling — Myra is dead-upstream and CodexUI is hand-rolled —
+means every new screen costs disproportionate time. Phase 7 added two more
+screens (dungeon, dialogue→combat) on top of an already 17-screen surface; the
+trend is bad. Godot's `Control` node tree, theme system, and editor-driven
+scene composition are an order of magnitude cheaper for the kind of UI
+authoring this game needs.
+
+The port is *cheap relative to the alternatives* because `Theriapolis.Core`
+was designed engine-agnostic from day one (architecture test enforced). Every
+deterministic system — the part of this codebase that is *expensive* to
+rebuild — survives unchanged. We are replacing the rendering shell and the UI
+toolkit, not the game.
+
+Alternatives considered and rejected:
+
+- **Stay on MonoGame, replace Myra only** (e.g. ImGui.NET, FontStashSharp +
+  CodexUI). Cheaper short-term, but doubles down on a hand-rolled UI
+  framework with no editor tooling. Doesn't fix the actual ceiling.
+- **Avalonia + MonoGame.** Awkward windowing model; mixing two render loops
+  is fragile.
+- **Unity.** Heavier port (Mono → Unity's CLR, asset pipeline overhaul,
+  licensing), worse 2D pixel-art tooling.
+- **Stride.** Less mature 2D pipeline, smaller community.
+
+Godot 4 with C# wins on: native 2D pixel-art workflow, editor scene authoring,
+mature `Control`-node UI, MIT licence, `.NET 8` first-class support.
+
+---
+
+## 3. Pre-flight audit (what we're rewriting)
+
+Run before kickoff to confirm post-Phase-7 numbers; the table below is the
+**2026-04-30 snapshot** and is only the starting point.
+
+| Subsystem            | LOC    | Files | Notes                                             |
+|----------------------|-------:|------:|---------------------------------------------------|
+| `Theriapolis.Game/CodexUI`         | 4,492  | 28 | Hand-rolled UI framework — biggest rewrite        |
+| `Theriapolis.Game/Screens`         | 5,014  | 17 | Screen logic; ~50% UI wiring, ~50% game logic     |
+| `Theriapolis.Game/Rendering`       | 1,317  |  9 | World/tactical renderers, camera, atlases, sprites|
+| `Theriapolis.Game/Input,Platform,UI`|   548  |  6 | Input mapping, save paths, clipboard               |
+| `Theriapolis.Game/Game1.cs` + ScreenManager | 166 | 2 | App shell + screen stack                  |
+| `Theriapolis.Desktop`              |     37 |  1 | Will be deleted; Godot project replaces it        |
+| **Total rewrite**    | **~11,500** | **63** |                                            |
+
+**Untouched:**
+- `Theriapolis.Core` (all generation, simulation, save/load, polylines)
+- `Theriapolis.Tools` (CLI worldgen-dump, settlement-report, tile-inspect)
+- `Theriapolis.Tests` (xUnit)
+- `Content/Data/*.json` (biomes, factions, dungeon templates, etc.)
+- `Content/Gfx/*.png` (sprites, tiles, atlases)
+- `Content/Fonts/*.ttf`
+
+**Re-run before kickoff:**
+```bash
+# Confirm Core is still MonoGame-free (must return zero matches)
+grep -rn "Microsoft\.Xna\|MonoGame" Theriapolis.Core/
+
+# Confirm test count
+dotnet test --no-build --logger "console;verbosity=minimal" | tail
+```
+
+---
+
+## 4. Architecture
+
+### 4.1 New project layout
+
+```
+Core (no engine deps)              ← unchanged
+Tools (ImageSharp, headless)       ← unchanged
+Tests (xUnit)                      ← unchanged
+Theriapolis.Godot/                 ← NEW; replaces Game + Desktop
+    project.godot
+    Theriapolis.Godot.csproj       ← references Core
+    Scenes/                        ← .tscn scene files (one per screen)
+    UI/                            ← .tscn + .gd-style C# Control scripts
+    Theme/                         ← Godot Theme resource for CodexUI styling
+    Rendering/                     ← Camera2D, world/tactical Node2D scripts
+    Input/                         ← Godot InputMap + adapter to Core actions
+    Platform/                      ← SavePaths, Clipboard (Godot APIs)
+    Autoload/                      ← Game state singleton bridging to Core
+```
+
+### 4.2 The Core boundary
+
+Core's public surface is unchanged. The Godot side talks to Core through the
+same APIs `Theriapolis.Game` used:
+
+- `WorldGenerator.Generate(seed, dataDir)` → `WorldState`
+- `Save.Write(path, snapshot)` / `Save.Read(path)` (whatever the Phase-7 save
+  API ended up named — verify post-7)
+- Resolver, encounter lifecycle, dungeon stamping, quest engine — all
+  invoked exactly as before.
+
+### 4.3 The architecture test
+
+Update `Architecture/CoreNoDependencyTests.cs` to forbid the `Godot`
+namespace in `Theriapolis.Core` in addition to (or instead of) MonoGame.
+This is a one-line change. **Keep both bans for the duration of the port** so
+the in-flight branch can't accidentally regress.
+
+### 4.4 Render model
+
+The seamless-zoom contract (CLAUDE.md "Seamless Zoom Model") survives. The
+implementation moves:
+
+| Concept                  | MonoGame                    | Godot                                   |
+|--------------------------|-----------------------------|-----------------------------------------|
+| Camera                   | `Rendering/Camera2D.cs` (custom) | `Camera2D` node + zoom property    |
+| World tile rendering     | `WorldMapRenderer` + `SpriteBatch` | `TileMap` or `Node2D._Draw` over `WorldState` |
+| Tactical tile rendering  | `TacticalRenderer` + atlas  | `TileMap` with chunked `set_cell` updates |
+| Polyline rendering       | `LineFeatureRenderer` (SpriteBatch lines) | `Line2D` node per polyline      |
+| Sprite (player/NPC)      | `PlayerSprite`/`NpcSprite`  | `AnimatedSprite2D`                       |
+| Atlas loading            | `TileAtlas`/`TacticalAtlas`/`CodexAtlas` | `AtlasTexture` resources       |
+| Game loop                | `Game1.Update`/`Draw`       | `_Process` / `_Draw` on root node       |
+
+`Line2D` for polylines is a meaningful upgrade — anti-aliased, width-tapered,
+texture-able lines without the manual quad strip work `LineFeatureRenderer`
+does today.
+
+### 4.5 UI model
+
+The React prototype's design system maps onto Godot's `Theme` + `Control`
+system. The mapping below is from **the React prototype** (the new spec), not
+from CodexUI (which is being deleted). For CodexUI → React-prototype
+correspondences, see the existing CodexUI source as a behavioural reference
+only; do not preserve its visual choices.
+
+| React prototype (CharacterCreator.zip)              | Godot equivalent                                       |
+|-----------------------------------------------------|--------------------------------------------------------|
+| CSS custom properties (`--bg`, `--ink`, `--gild`, ...)  | `Theme` resource type variations (one per theme)   |
+| `[data-theme="dark"]` / `[data-theme="blood"]`      | `ThemeVariation` resources, switched via player setting|
+| `.codex-header`, `.codex-title`, `.codex-sub`       | `PanelContainer` + `Label` with display font theme     |
+| `.stepper` / `.step` / `.step.active/.complete/.locked` | Custom `HBoxContainer` script with state-driven theme |
+| `.page` (two-column main + aside)                   | `HSplitContainer` or `HBoxContainer` (fixed ratio)     |
+| `.card` (Calling/History/Species cards)             | `PanelContainer` + `StyleBoxTexture` (nine-slice)      |
+| `.chip` (skill/feature/language chips)              | `PanelContainer` + `Label`, themed                     |
+| `.btn.primary` / `.btn.ghost`                       | `Button` with theme variations                         |
+| `.aside` (right-rail summary)                       | `MarginContainer` + `VBoxContainer` (signal-bound)     |
+| `.popover` (TraitName/SkillChip/BonusPill hover)    | Custom `PopupPanel` widget — viewport-clamp logic      |
+| HTML5 `dataTransfer` drag-drop in StepStats         | `_GetDragData` / `_CanDropData` / `_DropData`          |
+| Cormorant Garamond / Crimson Pro / Cinzel / Uncial  | `FontFile` resources bundled in `res://`               |
+| `loadData()` (fetch JSON)                           | Existing `ContentLoader` (Core) → unchanged            |
+
+**Theme switching is a runtime player setting**, not a developer toggle. The
+React prototype's `tweaks-panel.jsx` is **not** ported — it was a dev
+affordance. Theme selection lives in the existing settings screen. The
+prototype's density toggle (compact vs. normal spacing) is **dropped from
+scope**: ship only the normal spacing values (`--gap: 24px`, `--pad: 28px`).
+
+The character-creation flow is the densest UI in the game and ships first
+(M6) as the pilot for the design language. Every other screen inherits the
+Theme + widget vocabulary established there.
+
+---
+
+## 5. Milestones
+
+Ten milestones, each independently demoable. Build them in this order; each
+unblocks the next.
+
+### M0. Pre-flight (½ day)
+
+- Create `port/godot` branch off `main` post-Phase-7.
+- Re-run the §3 audit; record actual LOC and screen count.
+- Install Godot 4.x (mono build) + `.NET 8` SDK; confirm `dotnet --version`
+  matches Core's target.
+- Create `Theriapolis.Godot.csproj` referencing `Theriapolis.Core`;
+  hello-world scene loads + builds.
+
+**Exit criteria:** `dotnet build` of the new csproj succeeds; Godot opens the
+empty project; CI (or local `dotnet test`) is unchanged from main.
+
+### M1. Headless parity (1 day)
+
+Goal: prove Core works untouched under Godot's csproj.
+
+- From a Godot autoload script, call `WorldGenerator.Generate(12345)` and
+  log the FNV hash of the resulting `WorldState`.
+- Confirm hash matches `Theriapolis.Tools worldgen-dump --seed 12345`.
+- Update `Architecture/CoreNoDependencyTests.cs` to forbid `Godot.*` in Core
+  (in addition to MonoGame).
+
+**Exit criteria:** identical worldgen hash from Tools CLI and Godot host. No
+test regressions.
+
+### M2. World map render (3 days)
+
+The lowest-risk visual milestone — pure data → pixels, no UI.
+
+- `Rendering/WorldMapNode.cs`: `Node2D` with `_Draw` rendering tile colours
+  from `WorldState.Tiles`. Mirror `WorldMapRenderer.cs` colour logic.
+- `Camera2D` node with mouse-wheel zoom; reproduce
+  `C.WORLD_TILE_PIXELS`-aware coordinate model.
+- `LineFeatureNode.cs`: instantiate one `Line2D` per polyline in
+  `WorldState.Rivers`/`Roads`/`Rails`. Width and colour from constants.
+- Manual visual diff vs `Theriapolis.Tools worldgen-dump --seed 12345
+  --out world.png`; pixel-diff utility optional.
+
+**Exit criteria:** generate world from seed 12345 in Godot, compare to tools
+PNG output side-by-side; rivers/roads/rails visually correct, including
+bridges and wye-junctions. No determinism drift.
+
+### M3. Asset pipeline (2 days)
+
+- Copy `Content/Data/*.json` and `Content/Gfx/*.png` into the Godot project's
+  `res://` filesystem; configure `.csproj` to keep them in sync (or symlink).
+- Convert each PNG atlas into Godot `AtlasTexture` resources. Tile atlas, NPC
+  atlas, CodexUI atlas — three separate themes.
+- Write a `ContentLoader` autoload that exposes the same `string
+  ContentDataDirectory` / `ContentGfxDirectory` contract Game1 had, so
+  Core's data loading code (`Loaders.cs` etc.) is unchanged.
+- Verify `biomes.json` / `factions.json` / dungeon room templates load.
+
+**Exit criteria:** Core can read all data files via the Godot path; PNG atlases
+render correctly in a test scene.
+
+### M4. Tactical render (3 days)
+
+- `Rendering/TacticalNode.cs`: `TileMap` showing the 3×3 world-tile window
+  around the player (`C.TACTICAL_WINDOW_WORLD_TILES`).
+- Streaming: re-implement the 64-tile chunk loader from `TacticalRenderer.cs`
+  using `TileMap.SetCell` calls bounded to the visible viewport.
+- `PlayerSprite` / `NpcSprite` → `AnimatedSprite2D` nodes. Walk-cycle frames
+  drive from the existing per-sprite frame-index logic (Core-side).
+- Camera follow + smooth zoom from world-map view → tactical view at the
+  zoom threshold.
+
+**Exit criteria:** walk around a generated world, tactical view streams
+chunks correctly, sprites animate, camera transitions are smooth.
+
+### M5. Codex design system in Godot (4 days)
+
+Port the React prototype's design system to a Godot Theme. This is the
+foundation every subsequent screen builds on.
+
+- Extract the `<style>` block from `CharacterCreator.zip/index.html` into a
+  written audit (one-time, ~½ day): every CSS custom property → Theme
+  constant; every selector → Theme type/variation; every nine-slice candidate
+  identified.
+- `Theme/codex.tres`: Godot Theme with the parchment palette as default —
+  `--bg` / `--ink` / `--gild` / `--seal` / `--rule` mapped to Theme constants;
+  display + body fonts as Theme default fonts; standard spacing/radius
+  constants.
+- `Theme/Variations/dark.tres` and `Theme/Variations/blood.tres`: ThemeVariations
+  for the other two themes. Player setting selects the active variation.
+- Fonts: copy Cormorant Garamond, Crimson Pro, Spectral, EB Garamond, Cinzel,
+  Uncial Antiqua, JetBrains Mono into `res://Fonts/`. Bundle as `FontFile`
+  resources at the sizes the prototype uses (verify by spot-rendering each).
+- `UI/Widgets/CodexPopover.cs`: reusable hover-popover Control implementing
+  the `TraitName` / `SkillChip` / `BonusPill` pattern from
+  `src/trait-hint.jsx`. Includes the viewport-clamp + flip-above-or-below
+  behaviour the React version has (README §"Hover popovers and viewport
+  clamping" — `documentElement.clientWidth/Height`, not `window.inner*`).
+- `UI/Widgets/CodexStepper.cs`: the `.stepper` / `.step` widget — Roman
+  numerals, locked/active/complete states, click-to-jump with gating.
+  Reused by character creation and any future multi-step flow.
+- "Kitchen sink" scene showing each primitive (button primary/ghost, card,
+  chip, popover, stepper, aside, page header, validation banner) under all
+  three themes. Side-by-side comparison against screenshots taken from the
+  React prototype (open `index.html` locally with `python3 -m http.server`).
+
+**Exit criteria:** kitchen-sink scene visually matches React-prototype
+screenshots across all three themes; the popover widget passes a manual
+viewport-edge test (trigger near each edge, popover stays in-bounds).
+
+### M6. Title + character creation (5 days)
+
+The character-creation flow is M5's first real customer. Direct port of the
+React prototype's structure.
+
+- `Scenes/TitleScreen.tscn`: vertical button stack on a parchment field with
+  the codex title (Cinzel / Uncial Antiqua treatment) and a version label.
+  Plain — exists mostly to validate the design system in a non-trivial
+  composition.
+- `Scenes/CharacterCreation.tscn`: top-level scene matching `app.jsx`:
+  - `codex-header` band: title + folio counter ("Folio III of VIII").
+  - `CodexStepper` (from M5) bound to the 8 steps (see below).
+  - `page` two-column body: per-step scene (left) + Aside (right).
+  - `nav-bar`: Back / validation banner / Next.
+- One scene per step under `Scenes/CharacterCreation/Steps/`. Direct
+  port of `src/steps.jsx`:
+  1. `StepClade` — clade picker grid; selecting a clade auto-defaults
+     species per `app.jsx` `useEffect([cladeId])`.
+  2. `StepSpecies` — species cards filtered by clade.
+  3. `StepClass` — calling cards; level-1 features filtered from
+     `level_table` per the prototype's contract.
+  4. `StepSubclass` — **NEW vs. React prototype**. The prototype is
+     pre-Phase-6.5 and has no subclass picker. **Confirmed scope: a
+     dedicated step**, not an inline picker on the Calling card.
+     Adopts the M5 design vocabulary (cards laid out the same way as
+     `StepClass`, one card per available subclass for the chosen
+     calling). Data shape from the live `Content/Data/classes.json`.
+  5. `StepBackground` — history cards.
+  6. `StepStats` — ability assignment, **drag-drop**. Reproduce the
+     payload contract from `steps.jsx` `handleDrop` /
+     `dropToPool` exactly:
+     - pool→slot, slot→slot (swap), slot→pool
+     - payload shape: `{from:"pool", value, idx}` or
+       `{from:"slot", value, ability}`
+     Use Godot's `_GetDragData` / `_CanDropData` / `_DropData`.
+     Roll-history list mirrors `statHistory` array.
+  7. `StepSkills` — class skill picks above background-locked skills.
+     Skill chips use the M5 `CodexPopover` (SkillChip + BonusPill).
+  8. `StepReview` — name entry + final summary. The "Confirm & Begin"
+     button does what `app.jsx` step's TODO told us to: hand the
+     final character object to Core (see README §4 "Wire the
+     'Confirm & Begin' handoff").
+- `UI/Aside.tscn` + script: ports `Aside` from `app.jsx` — clade/species
+  flavor, total ability scores including bonuses (sum of
+  `statAssign[ab] + clade.ability_mods[ab] + species.ability_mods[ab]`),
+  size + speed, skill list. Bound to a Core `CharacterDraft` model via
+  Godot signals.
+- Validation: per-step `Validate()` mirroring `validate(i)` in `app.jsx`
+  exactly (clade picked, species picked, ..., assigned 6/6 abilities, picked
+  N/N skills, name non-empty).
+- Forward-navigation gating: a step is locked iff some earlier step has
+  unmet validation, per the prototype's `firstIncomplete` rule. Backward
+  navigation always allowed.
+
+**Schema reconciliation sub-task (½ day, kicks off M6):** before writing UI,
+diff the React prototype's `data/*.json` against `Content/Data/*.json`.
+For each entity (clade / species / class / background), produce a one-page
+field map noting where the live schema is a superset (Phase 6.5 added
+fields), where it differs in shape, and where the prototype assumed a
+field the live schema lacks. Live schema wins on all conflicts. The map
+becomes the contract the step scripts read against.
+
+**Exit criteria:** create a character end-to-end across all 8 steps, hash
+the resulting `PlayerCharacter` blob, confirm it matches the same character
+created via the MonoGame build using the same inputs (modulo subclass step,
+which the React prototype lacks). Side-by-side screenshots of each step in
+parchment / dark / blood themes match the prototype's design language.
+
+### M7. Play loop screens (5 days)
+
+Port in dependency order; each is ~½–1 day.
+
+1. `WorldGenProgressScreen` — progress bar driven by Core stage callbacks.
+2. `WorldMapScreen` — wraps the M2 world map node + minimap + UI overlays.
+3. `PlayScreen` — wraps the M4 tactical node + HUD overlay (HP, stamina,
+   minimap).
+4. `PauseMenuScreen` — `PopupPanel` overlay; pauses Core sim tick.
+5. `SaveLoadScreen` — `ItemList` of saves; `Save.Read`/`Save.Write` calls
+   unchanged.
+6. `InteractionScreen` — dialogue tree UI; densest text rendering after
+   character creation.
+
+**Exit criteria:** load a save from the MonoGame build, walk around, save,
+reload — bytes identical.
+
+### M8. Combat + dungeon screens (4 days)
+
+The Phase-7-shipped surface.
+
+1. `CombatHUDScreen` — turn order, ability bar, target reticle, damage
+   numbers. Damage-number animations move from `SpriteBatch` to
+   `AnimatedSprite2D` or tween-driven `Label` nodes.
+2. `DungeonScreen` (Phase-7) — variant of `PlayScreen` for bounded
+   interiors; same tactical render path, different camera bounds + exit-tile
+   logic.
+3. `LevelUpScreen` — stat allocation grid; reuse character-creation widgets.
+4. `InventoryScreen` / `ShopScreen` — drag-drop between containers using
+   Godot's native drag-drop API (replaces `DragDropController.cs`).
+5. `QuestLogScreen` / `ReputationScreen` / `DefeatedScreen` — mostly
+   text-list views.
+6. **Dialogue → combat handoff** (Phase-7): the
+   `InteractionScreen` "settle this here" branch closes the popup and
+   instantiates `CombatHUDScreen.tscn` with the encounter pre-loaded. The
+   Phase-7 plumbing on the Core side is unchanged.
+
+**Exit criteria:** play through Old Howl mine end-to-end (Phase-7 showcase
+content): walk in, combat, loot, walk out, return to overworld.
+
+### M9. Input, save paths, clipboard (1 day)
+
+The platform layer.
+
+- `Input/InputMap.tres`: every binding from `InputManager.cs` + the new
+  Godot `InputMap` actions. Adapt to Core via an `InputAdapter` autoload
+  exposing the same enum-typed action API the screens use today.
+- `PlayerController` → `_PhysicsProcess`-driven node consuming the adapter.
+- `Platform/SavePaths.cs` → use `OS.GetUserDataDir()` (Godot's
+  cross-platform per-user dir); confirm the directory matches MonoGame's
+  `LocalApplicationData` path so saves remain interoperable, *or* migrate
+  on first run with an explicit migration helper.
+- `Platform/Clipboard.cs` → `DisplayServer.ClipboardSet`/`ClipboardGet`.
+- **Window mode: borderless fullscreen at native desktop resolution.**
+  In `project.godot`, set `display/window/size/mode = 3`
+  (`Fullscreen` — borderless, native resolution). Stretch settings:
+  `display/window/stretch/mode = "canvas_items"`,
+  `stretch/aspect = "expand"`. Design the Theme so type and spacing
+  remain legible across common resolutions (1920×1080, 2560×1440,
+  3840×2160). The React prototype's `width=1440` viewport meta is
+  *not* a constraint — the codex aesthetic should fill the screen.
+  Add a developer-only `--windowed` CLI flag (or F11 toggle) for
+  iteration.
+
+**Exit criteria:** every keybinding works; saves written by the MonoGame
+build load in the Godot build.
+
+### M10. Cleanup, packaging, decommission (2 days)
+
+- Delete `Theriapolis.Game/` and `Theriapolis.Desktop/`. Remove from the
+  solution.
+- Drop MonoGame + Myra packages from `Theriapolis.Core.csproj` (there should
+  be none, but verify) and the new Godot csproj's transitive graph.
+- Update `CLAUDE.md`:
+  - "Build & Run Commands": replace `dotnet run --project Theriapolis.Desktop`
+    with the Godot launch command.
+  - "Project Architecture": replace `Theriapolis.Game` paragraph with
+    `Theriapolis.Godot`.
+  - Architecture-test description: forbid `Godot.*` (not `Microsoft.Xna.*`)
+    in Core.
+- Configure Godot export presets for Windows / Linux / macOS desktop.
+- Smoke-test export builds on each target platform.
+
+**Exit criteria:** `Theriapolis.Game` / `Theriapolis.Desktop` are gone;
+`dotnet test` is green; an exported Windows build runs and plays through Old
+Howl mine.
+
+---
+
+## 6. Total estimate
+
+| Phase | Work                              | Days |
+|-------|-----------------------------------|-----:|
+| M0    | Pre-flight                        |  0.5 |
+| M1    | Headless parity                   |  1   |
+| M2    | World map render                  |  3   |
+| M3    | Asset pipeline                    |  2   |
+| M4    | Tactical render                   |  3   |
+| M5    | Codex design system in Godot      |  4   |
+| M6    | Title + character creation        |  5   |
+| M7    | Play loop screens                 |  5   |
+| M8    | Combat + dungeon screens          |  4   |
+| M9    | Input, save paths, clipboard      |  1   |
+| M10   | Cleanup, packaging, decommission  |  2   |
+| **Total** |                               | **30.5** |
+
+≈ **6–7 calendar weeks** assuming a single full-time engineer, no
+significant blockers, and the post-Phase-7 baseline is genuinely stable. Pad
+20% (~7–8 weeks) for the unknowns called out in §10. M5 grew by 1 day vs.
+the original plan to absorb the design-system audit and the reusable popover
+ stepper widgets, both of which pay back in M6–M8. M6 grew by 1 day to
+absorb the schema reconciliation and the Subclass step. If the agent doing
+the port can run M2/M3/M4 in parallel via worktrees, shave 3–4 days.
+
+---
+
+## 7. Determinism & save compatibility
+
+The bright line: **anything that touches `WorldState`, `PlayerCharacter`,
+`Save.*`, or the Phase-7 dungeon/encounter state is Core's job, not Godot's.**
+
+- All RNG is Core. No `randf()`, no `RandomNumberGenerator` Godot calls in
+  gameplay paths. Only presentation-layer randomness (e.g. animation jitter)
+  may use Godot RNG, and only in code paths that don't feed back into Core.
+- Save compatibility test: `Tests/SaveCompat/MonogameToGodotTests.cs` reads
+  a fixture save written by the MonoGame build (committed to the repo) and
+  asserts every Core-loadable field round-trips identically.
+- Per-stage hash tests (`WorldgenDeterminismTests`, `Phase23DeterminismTests`,
+  any Phase-7 additions) continue to run unchanged.
+
+---
+
+## 8. Testing strategy
+
+### What stays
+- All `Theriapolis.Tests/` xUnit tests run unchanged. They reference Core
+  only and don't care about the host.
+- All `Theriapolis.Tools/` CLI behaviour (`worldgen-dump`,
+  `settlement-report`, `tile-inspect`) is unchanged.
+
+### What's added
+- `Tests/SaveCompat/MonogameToGodotTests.cs` — one fixture save per major
+  schema event (post-Phase-3, post-Phase-6, post-Phase-7), each loaded and
+  hashed for equality.
+- `Tests/Architecture/NoGodotInCoreTests.cs` — twin of the existing MonoGame
+  ban; reflection check that `Theriapolis.Core.dll` has no `Godot.*`
+  references.
+- A small `Theriapolis.Godot/Tests/` Godot-side script set (one .tscn per
+  visual milestone) for manual visual-diff comparison vs MonoGame screenshots.
+  Not run in CI.
+
+### What's gone
+- Any tests that exercise `Theriapolis.Game/`-specific code (there should be
+  none — Game has no test coverage today by design — verify before deleting).
+
+---
+
+## 9. Migration & rollback
+
+- The port runs on a `port/godot` branch; `main` keeps shipping MonoGame
+  patches if needed during the 6–7 week window.
+- After M10 ships, MonoGame branch is tagged `monogame-final` and frozen.
+  No back-merges from `main` into `port/godot` after M5 (CodexUI parity
+  point) — too much surface diverges.
+- **Rollback plan:** if the port stalls past M6 with unsolvable Godot-side
+  blockers, abandon `port/godot` and reconsider §2's "ImGui.NET / replace
+  Myra only" alternative. M0–M5 work is salvageable for a future attempt.
+
+---
+
+## 10. Risks & open questions
+
+### Real risks
+
+1. **Data-schema reconciliation.** `CharacterCreator.zip/data/*.json`
+   predates Phase 6.5 (subclasses, levelling, hybrids, scent tags). The live
+   `Content/Data/*.json` has additional fields and possibly different shapes
+   per Phase-6.5 deviations. The React prototype's UI assumes the older
+   shape. *Mitigation:* the M6 schema-reconciliation sub-task produces a
+   field map before any UI code is written; the live schema wins on all
+   conflicts; the React component's data assumptions are adapted to
+   match. Do this audit in writing — do not let it leak into ad-hoc
+   step-by-step "oh we also need..." discoveries.
+2. **Phase-6.5 features absent from the React prototype.** Specifically: no
+   subclass picker (README §"Known caveats"), no levelling beyond level 1,
+   no hybrid-character clade pairing, no scent-mask UI. *Mitigation:* the
+   plan adds an explicit Subclass step (M6 step #4); levelling stays in
+   `LevelUpScreen` (M8) where it already lives; hybrids are a clade-picker
+   variant (M6 StepClade); scent UI lives elsewhere (likely InventoryScreen
+   or a future settings surface). All of these adopt the M5 design
+   language; none invent new visual idioms.
+3. **Codex-aesthetic completeness.** The React prototype only designed the
+   character-creation surface. Other screens (combat HUD, world map
+   overlays, dungeon UI) need design decisions extending the codex
+   vocabulary. *Mitigation:* M5's reusable widget set (popover, stepper,
+   panel/card/chip, button variants) covers ~80% of every screen; the
+   remaining ~20% (combat-specific overlays, minimap framing) gets one
+   design decision per screen made during M7/M8 with the M5 vocabulary
+   as the base. If a screen needs a brand-new visual idiom, flag it
+   instead of inventing one — defer to a polish pass.
+4. **Tactical chunk streaming performance.** `TileMap.SetCell` is well
+   optimised but the 64-tile chunk loader was tuned against `SpriteBatch`.
+   *Mitigation:* if M4 reveals a perf issue, fall back to `MultiMeshInstance2D`
+   for tile rendering.
+5. **Save path divergence.** `OS.GetUserDataDir()` defaults to
+   `%APPDATA%/Godot/app_userdata/<project>` on Windows; MonoGame writes
+   under `%LOCALAPPDATA%/Theriapolis`. *Mitigation:* override Godot's
+   user-data path explicitly to match the MonoGame path, or ship a one-shot
+   migration on first launch (preferred).
+6. **C# hot-reload ergonomics in Godot.** Godot 4's C# tooling is solid but
+   not as snappy as MonoGame's iteration loop. *Mitigation:* set up
+   editor-side debugging early (M0), accept slower iteration.
+7. **Drag-drop fidelity** (M6 stats step + M8 inventory). Godot's native
+   drag-drop is event-driven; the React prototype uses HTML5 `dataTransfer`
+   with a documented payload shape. *Mitigation:* port the payload contract
+   verbatim (`{from:"pool", value, idx}` / `{from:"slot", value, ability}`),
+   serialise as `Variant` dictionaries; if native API doesn't suffice for a
+   custom drag preview, write a thin `_GuiInput`-driven shim on `Control`
+   nodes.
+
+### Non-risks (called out so we don't worry about them)
+
+- **Core porting.** Core does not port. It is referenced.
+- **Determinism.** Determinism lives in Core and is not touched.
+- **Test breakage.** Tests reference Core only.
+- **Tools CLI.** Tools references Core only.
+
+### Resolved decisions (locked in 2026-04-30)
+
+1. **Subclass step UX.** Dedicated 8th step, not an inline picker on the
+   Calling card. Implementation in M6 step #4.
+2. **Density toggle.** Dropped from scope. Ship only the prototype's normal
+   spacing values (`--gap: 24px`, `--pad: 28px`). The React prototype's
+   compact mode was a dev-time experiment, not a player feature.
+3. **Window mode.** Borderless fullscreen at native desktop resolution by
+   default. The Theme must scale legibly across 1920×1080 / 2560×1440 /
+   3840×2160. F11 (or `--windowed`) toggles to a windowed mode for
+   iteration. Configured in M9.
+4. **Default theme.** Parchment. Dark and blood ship as player-selectable
+   variations in the existing settings screen.
+
+### Open questions for the user / project lead
+
+1. **Pixel-art shader stack.** CodexUI uses MonoGame `SpriteBatch` with
+   point filtering; do any tactical-render screens depend on
+   `SamplerState.PointClamp` behaviour that needs reproducing in Godot?
+   (Default Godot project import settings set `Filter: Nearest` for pixel
+   art — likely fine, confirm at M5.)
+2. **Audio.** Phase 7 may or may not have introduced audio. If so, M9 grows
+   to include `AudioStreamPlayer` integration.
+3. **Multi-monitor + DPI.** With borderless-fullscreen as the default, the
+   Godot build will pick the *primary* monitor's native resolution at
+   launch. Confirm that's the desired behaviour, or add a monitor-selection
+   setting. DPI scaling on high-density displays may need explicit handling;
+   defer to M9.
+
+---
+
+## 11. Done definition
+
+The port is complete when, simultaneously:
+
+1. `Theriapolis.Game/` and `Theriapolis.Desktop/` are deleted from the repo.
+2. `dotnet test` is green (≥ Phase-7 test count, none removed except
+   verified Game-only tests, plus the new save-compat + architecture tests).
+3. A save written by `monogame-final` loads in the Godot build, plays through
+   Old Howl mine, saves, reloads — all without errors.
+4. The Godot build exports cleanly to Windows desktop and runs the same
+   end-to-end smoke test.
+5. `CLAUDE.md` is updated to reflect the new project layout and build
+   commands; the architecture test forbids `Godot.*` in Core.
+6. `theriapolis-rpg-implementation-plan-godot-port.md` (this file) gets a
+   "Status: Shipped 20XX-XX-XX" header and a §12 deviation table for any
+   milestone that landed differently than planned.