magicciv/CLAUDE.md

# Magic Civilization

Fantasy 4X turn-based strategy game (Civ5 + Master of Magic + Magic: The Gathering color pie) in Godot 4 / GDScript. 16 races, 5 magic schools, hex grid.

> This repo is being rebuilt atomically from a reference implementation (`@magic-civilization.messy/`). Port systems as each milestone requires them — never reference `.messy/` paths from runtime code.

## Scope

**Early access demo** ("Age of Four") — 4 races (High Elf, Human, Dwarf, Orc), all 5 magic schools, full 4X + magic loop. See `.project/ROADMAP.md` for scope and build sequence.

## Tech Stack

- **Engine:** Godot 4.x
- **Language:** GDScript only (no C#, no GDExtension)
- **Data:** JSON game packs (`games/age-of-four/data/*.json`)
- **Architecture:** Genre-agnostic engine with game pack content system

## Key Architecture

The engine is **genre-agnostic**. All game content and display text comes from game packs. The fantasy game "Age of Four" is the default. See `docs/engine/ABSTRACTION.md` (to be written).

- UI labels resolve through `ThemeVocabulary.lookup(engine_key)` — never hardcode theme strings
- Sprites resolve through `ThemeAssets.resolve(path)` — never hardcode asset paths
- Systems communicate via `EventBus` signals — never directly reference other systems
- All game content is data-driven from JSON — don't hardcode stats, costs, or effects
- **5 eras, 5 tiers** — everything is tiered 1-5 aligned with the 5 eras (units, spells, buildings, wild creatures). Spells use `scope: "global"` (High Archon, world map) or `scope: "local"` (specialist units, combat). School tech tiers map: T1-T2 spells gated by Mysticism/Arcane Lore, T3-T5 by school techs.

## Documentation

See `README.md` for the full doc index. Docs live in two places:

- **`engine/docs/`** — genre-agnostic engine architecture (written as engine systems are built)
- **`games/age-of-four/docs/`** — fantasy game design (races, combat, spells, economy, etc.)

Build process docs (roadmap, feature gap, task lists) stay in `.project/`.

## Single Source of Truth: GDScript → TypeScript

> **The GDScript climate engine is the source of truth for all simulation logic. The TypeScript in `guide/` is generated output — never edited directly. If the guide gives wrong results, fix the GDScript and re-run the transpiler.**

The climate simulation runs in two runtimes: GDScript (Godot game engine) and TypeScript (web guide). GDScript is written first; TypeScript is auto-generated from it via `lilith-gdscript-transpiler`.

### Architecture

```
games/age-of-four/data/climate_spec.json              ← Canonical thresholds, events, ley rules
    ↓ read at runtime by both engines
engine/src/modules/climate/climate.gd                ← SOURCE OF TRUTH (physics steps)
engine/src/modules/climate/ecological_events.gd      ← SOURCE OF TRUTH (stochastic events)
engine/src/modules/climate/anchor_decay.gd           ← SOURCE OF TRUTH (ley anchor decay)
engine/src/modules/climate/climate_spec_eval.gd      ← SOURCE OF TRUTH (spec condition evaluator)
    ↓ transpiled by tools/transpile-engine/transpile.py
packages/engine-ts/src/ClimatePhysics.generated.ts   ← AUTO-GENERATED, never edit
packages/engine-ts/src/index.ts                      ← Re-exports for @magic-civ/engine-ts
guide/age-of-four/                                   ← Consumes @magic-civ/engine-ts (workspace:*)
```

### Transpiler Package

`lilith-gdscript-transpiler` — custom GDScript→TypeScript transpiler.

- **Package**: `@packages/@py/gdscript-transpiler` in this workspace
- **PyPI index**: `https://forge.nasty.sh/api/packages/lilith/pypi/simple/`
- **Invocation**: `uv run tools/transpile-engine/transpile.py` (self-contained inline script — `uv` handles deps automatically, no manual pip install needed)
- **Check mode**: `uv run tools/transpile-engine/transpile.py --check` (exits 1 if generated file is stale vs GDScript source)
- **Sources**: `climate.gd`, `ecological_events.gd`, `anchor_decay.gd`, `climate_spec_eval.gd`
- **Output**: `packages/engine-ts/src/ClimatePhysics.generated.ts`

```bash
uv run tools/transpile-engine/transpile.py         # regenerate
uv run tools/transpile-engine/transpile.py --check # CI: exit 1 if stale
```

### Rules

- **Never edit `ClimatePhysics.generated.ts`** — it's auto-generated from GDScript
- **Never hardcode terrain thresholds** — read from `climate_spec.json`
- **All simulation changes go in GDScript first** — then re-run transpiler
- **Ecological events require a seed** — `process_turn(game_map, turn, seed)` for deterministic PRNG
- **Golden test vectors** verify both engines produce identical output on the same seed

## Project-Specific Agents

10 specialized agents for game development in `.claude/agents/`:

| Agent | Use For |
|-------|---------|
| `godot-engine` | Project setup, autoloads, scene management, GDScript core |
| `game-algorithms` | Hex math, A* pathfinding, procedural map generation |
| `game-systems` | Economy, happiness, culture, production, growth, improvements |
| `combat-dev` | Combat resolver, keywords, damage formulas, promotions, siege |
| `magic-dev` | Spells, mana economy, Archons, enchantments, wonders, Ascension |
| `game-ai` | AI opponents: strategy, tactical movement, combat decisions |
| `game-data` | JSON data authoring from design docs |
| `godot-ui` | All UI scenes: city screen, tech tree, spellbook, HUD, menus |
| `godot-renderer` | TileMap, sprites, camera, fog of war, hex visuals, animation |
| `guide-web` | Player guide web app: React pages, components, climate sim, Vitest |

### Agent Selection by Task

| Task pattern | Agent |
|-------------|-------|
| `project.godot`, autoloads, `SceneManager`, save/load | `godot-engine` |
| Hex coordinates, A*, map generation, tile storage | `game-algorithms` |
| `economy.gd`, `happiness.gd`, `culture.gd`, city production, growth | `game-systems` |
| `combat_resolver.gd`, keywords, flanking, ZOC, promotions | `combat-dev` |
| `spell_system.gd`, `mana_pool.gd`, `archon.gd`, spells, wonders | `magic-dev` |
| `ai_player.gd`, AI decisions, difficulty modifiers | `game-ai` |
| `*.json` data files, `vocabulary.json`, `game.json` | `game-data` |
| `*.tscn` UI scenes, HUD panels, overlays, menus | `godot-ui` |
| TileMap, sprites, camera, fog, selection highlight, animation | `godot-renderer` |
| `guide/age-of-four/`, `guide/engine/`, React, Vite, climate sim | `guide-web` |

## Conventions

### GDScript Style
- snake_case for variables, functions, files
- PascalCase for classes and nodes
- Signals use past tense: `unit_moved`, `city_founded`, `tech_researched`
- Constants in UPPER_SNAKE_CASE
- Type hints on all function signatures

### Class Resolution — Preload Pattern (critical)

Godot 4 `class_name` registration is unreliable in autoload context. **Always reference non-autoload classes via `preload()` const**, never by bare class_name:

```gdscript
const CityScript = preload("res://engine/src/entities/city.gd")
const HexUtilsScript = preload("res://engine/src/map/hex_utils.gd")
const UnitScript = preload("res://engine/src/entities/unit.gd")
const TileScript = preload("res://engine/src/map/tile.gd")
const PlayerScript = preload("res://engine/src/entities/player.gd")
const GameMapScript = preload("res://engine/src/map/game_map.gd")

var unit: UnitScript = UnitScript.new()
```

Keep the `class_name` declaration in the file itself (IDE autocomplete uses it). All runtime references use the preload const.

### Entity Class Pattern

All game entities (`Unit`, `City`, `Player`, `Building`, `Improvement`) are:
- `class_name Foo / extends RefCounted` — pure data, no scene/node
- Rendering handled by separate renderer scripts
- Logic calls `DataLoader` for type definitions, `EventBus` for state-change signals

### Signal Parameters

`EventBus` signals pass entity objects as `Variant`, not typed class_name parameters:

```gdscript
# Correct:
signal unit_moved(unit: Variant, from: Vector2i, to: Vector2i)
# Wrong — causes type errors in autoload context:
signal unit_moved(unit: Unit, from: Vector2i, to: Vector2i)
```

### Hex Math

All hex coordinate math goes through `HexUtils` static methods — never inline the formulas. `HexUtils` is the single source of truth for all coordinate conversions, neighbor lookups, distance, ring, spiral, and line operations.

**Direction-to-edge mapping** — AXIAL direction indices and hex polygon edge indices are NOT the same:

```
Direction:  0(E)  1(NE) 2(NW) 3(W)  4(SW) 5(SE)
Poly edge:  2     1     0     5     4     3
```

### Data IDs
- snake_case: `high_elf_heritage`, `chaos_magic`, `fire_elemental`
- Match the `id` field in JSON data files
- Reference by ID in code, resolve display name through `ThemeVocabulary`

### File Organization
```
engine/
  src/
    autoloads/        — singletons (GameState, TurnManager, DataLoader, EventBus, ThemeVocabulary, ThemeAssets)
    entities/         — game objects (unit, city, building, improvement, archon)
    map/              — tile storage, hex utils, pathfinder, game_map
    generation/       — map generator, terrain refiner, hydrology, wind
    rendering/        — hex, city, unit, fog, river, road, indicator renderers
    core/             — save manager, pending actions, terrain affinity
    modules/
      combat/         — combat_resolver, keyword_handler
      magic/          — spell_system, mana_pool, infusion_system
      climate/        — climate, atmosphere, weather, ecological_events
      ley/            — ley_network
      empire/         — economy, happiness, culture, government
      management/     — city_manager, unit_manager, improvement_manager
      events/         — natural_events
      victory/        — victory_manager, ascension_ritual
      ai/             — ai_player, ai_tactical, ai_city, ai_magic_research, ai_military
      tech/           — tech_web
  scenes/
    main/             — entry point
    menus/            — main_menu, game_setup, options, load_game
    world_map/        — overworld
    city/             — city management overlay
    tech_tree/        — tech web overlay
    magic/            — spellbook, mana, archon overlays
    combat/           — combat popups
    hud/              — top_bar, minimap, unit_panel
    tests/            — proof scenes (.tscn + .gd co-located)
  tests/
    unit/             — GUT tests by module
    integration/      — end-to-end integration tests

games/
  age-of-four/
    data/             — all JSON content (units/, spells/, techs/, terrain/, ...)
    assets/           — sprites/, icons/
    game.json         — game manifest

guide/
  engine/             — @magic-civ/guide-engine (shared UI components, types, utils)
  age-of-four/        — @magic-civilization/guide-age-of-four (all pages, app shell)
```

## DX Tooling

### Testing & Linting
- **GUT** (Godot Unit Test) — unit + integration tests for GDScript
- **gdtoolkit** (`pip install gdtoolkit`) — `gdlint` + `gdformat`
- Run tests headless: `godot --headless --script res://addons/gut/gut_cmdln.gd`
- Run lint: `gdlint engine/src/`

### Task Runner (`./run`)

Central entry point for dev, export, deploy commands.

```bash
./run play                         # Launch the game locally
./run editor                       # Open Godot editor
./run lint                         # gdlint engine/src/
./run test                         # GUT tests headless
./run screenshot [name] [scene]    # Capture + SCP to plum
./run export [version]             # All platforms in parallel
```

### Screenshot & Visual Verification

```bash
./tools/screenshot.sh [name] [scene] [delay]
```

Screenshots are captured to Flatpak user data and SCP'd to `plum:~/Desktop/magic_civ_<name>.png`.

### Proof Scenes (`engine/scenes/tests/`)

Self-capturing test scenes. Each phase should have a proof scene that sets up minimal game state, renders claimed features, auto-captures, and quits.

### Environment Config (`.env.*`)

`EnvConfig` autoload reads `.env` (base) then `.env.development` (overrides) at startup:
- `.env.production` — `FORCE_DISABLE_FOGOFWAR=false`
- `.env.development` — `FORCE_DISABLE_FOGOFWAR=true`, `FORCE_UNLIMITED_RESEARCH=true`

### DataLoader — File vs Directory Pattern

`DataLoader` supports two layouts per data category:
- **Single file:** `games/age-of-four/data/races.json`
- **Split directory:** `games/age-of-four/data/units/` — reads all `.json` files, merges by `id`

**Never create a monolithic file that exceeds 500 lines.**

### Sprite Generation (`tools/sprite-generation/`)

Pipeline for generating game sprites using Magic: The Gathering card art as style reference. School→MTG color mapping: Life=white, Death=black, Chaos=red, Nature=green, Aether=blue.

Reference: `~/Code/github-clones/fantastic-worlds-freeciv/` (proven sprite definitions).

**Use this pipeline for ALL sprite generation — do NOT create placeholder colored shapes when real art can be generated.**

## Phase Gate Protocol (MANDATORY)

**Never declare a phase complete without a proof screenshot reviewed in this conversation.**

A phase is NOT done until:
1. A proof scene (`engine/scenes/tests/`) renders ALL claimed features in one screenshot
2. The screenshot is captured via `tools/screenshot.sh`
3. The screenshot is SCP'd to `plum:~/Desktop/magic_civ_<phase>_proof.png`
4. The screenshot is read and reviewed IN THIS CONVERSATION
5. Every claimed feature is visibly confirmed
6. The user approves it

Code exists ≠ code works. Tests pass ≠ features render. Lint clean ≠ visually correct.

## Atomic Porting Protocol

This project is rebuilt milestone-by-milestone from a reference implementation. **Only port what the current milestone requires.**

- **Data files**: only copy JSON files that the current milestone's code actually loads — not the full 99-file set "for completeness"
- **Engine code**: only port systems listed in the current milestone's task list — don't pull in combat when building climate
- **Scenes**: only create scenes needed for the current phase's proof screenshot
- **Tests**: only port tests for systems that exist in this repo — a test for code that hasn't been ported yet is dead weight
- If a file from the reference doesn't have a consumer in this repo yet, it doesn't belong here yet
- The milestone task lists in `.project/tasks/` define exactly what comes in and when

## Safety Rules
- Never hardcode theme-specific strings in engine code
- Never hardcode asset paths — always use `ThemeAssets.resolve()`
- `GameState` must support multiple map layers (future Ethereal Plane)
- All system state changes emit signals via `EventBus`
- Building/unit effects are data-driven from JSON — don't hardcode behavior
- Always call `DataLoader.load_game("age-of-four")` when running scenes directly
- **NEVER use anime models for game art** — use `juggernaut-xl-v9`, `epicrealism-xl`, `illustrious-xl-v2`