Magic Civilization

Fantasy 4X turn-based strategy game in Godot 4 + Rust, hex grid.

Game 1 — "Age of Dwarves" (current Early Access): single race (Dwarves), 5 AI-only clan personalities the player can face as opponents (Ironhold, Goldvein, Blackhammer, Deepforge, Runesmith), no magic mechanics, mundane tech only. Full 4X loop (cities, tech tree, wonders T1-T10, combat, wild creatures, domination victory). High-tier items and late-game wonders carry ancient/inexplicable flavor as Game 2 teasers — effects remain strictly mundane numeric bonuses.

Game 2 — "Age of Kzzykt" (future): adds magic, ley lines, Archons, spells, Ascension victory, more races. Eventual vision includes 16 races and 5 magic schools (Civ5 + Master of Magic + Magic: The Gathering color pie).

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 (combat, economy — spells/races are Game 2 scope)

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	4 demo races, gendering, fusions, release schedule
ECONOMIC_SYSTEMS.md	Economy, civic axis, capitalism cascade
GOVERNMENTS.md	Government types and mechanics
GLOSSARY.md	Term definitions
COMBAT_SYSTEM.md	Combat mechanics (written when M8 is built)
military/COMMUNICATIONS.md	Comms tiers, first-contact, courier envelopes, perceived state, war-dec semantics
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	Demo scope + 12-phase build sequence
FEATURE_GAP.md	New systems beyond the reference implementation
tasks/m0-m4/	Milestone task lists with porting checklists

Quick Start

./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