magicciv/README.md

# Magic Civilization

Fantasy 4X turn-based strategy game (Civ5 + Master of Magic + MTG color pie) in Godot 4 / GDScript.

## Structure

```
engine/          — genre-agnostic game engine (GDScript)
  src/           — autoloads, entities, map, generation, modules, rendering
  scenes/        — Godot scenes (.tscn + .gd)
  docs/          — engine architecture docs

games/
  age-of-dwarves/   — fantasy game pack (the default theme)
    data/        — all JSON game content
    assets/      — sprites, icons
    docs/        — game design docs (races, combat, spells, economy)

guide/           — player guide web app (React/TypeScript)
  engine/        — @magic-civ/guide-engine (shared components)
  age-of-dwarves/   — guide pages for Age of Dwarves

packages/
  engine-ts/     — @magic-civ/engine-ts (auto-generated climate simulation)

tools/           — sprite generation, transpiler, screenshot capture
```

## Docs

### Engine (`engine/docs/`)

| Doc | Covers |
|-----|--------|
| ARCHITECTURE.md | Project structure, autoloads, scene lifecycle |
| ABSTRACTION.md | Genre-agnostic vocabulary, theme pack system |
| DATA_FORMAT.md | JSON data schemas, DataLoader patterns |

### Game Design (`public/games/age-of-dwarves/docs/`)

| Doc | Covers |
|-----|--------|
| [RACES.md](public/games/age-of-dwarves/docs/RACES.md) | 4 demo races, gendering, fusions, release schedule |
| [ECONOMIC_SYSTEMS.md](public/games/age-of-dwarves/docs/ECONOMIC_SYSTEMS.md) | Economy, civic axis, capitalism cascade |
| [GOVERNMENTS.md](public/games/age-of-dwarves/docs/GOVERNMENTS.md) | Government types and mechanics |
| [GLOSSARY.md](public/games/age-of-dwarves/docs/GLOSSARY.md) | Term definitions |
| COMBAT_SYSTEM.md | Combat mechanics (written when M8 is built) |
| SPELL_SYSTEM.md | Spell/mana system (written when M9 is built) |
| ERA_SYSTEM.md | Era progression (written when needed) |

### Build Process (`.project/`)

| Doc | Covers |
|-----|--------|
| [ROADMAP.md](.project/ROADMAP.md) | Demo scope + 12-phase build sequence |
| [FEATURE_GAP.md](.project/FEATURE_GAP.md) | New systems beyond the reference implementation |
| `tasks/m0-m4/` | Milestone task lists with porting checklists |

## Quick Start

```bash
./run play          # Launch the game
./run editor        # Open Godot editor
./run lint          # gdlint engine/src/
./run test          # GUT tests headless
pnpm dev            # Serve the player guide
```