IMPERIUM ARCANUM — web-based Caesar 3-like city builder with heroes, magic & monsters

- Full classic layer: roads/walkers, 11-tier housing evolution, food chain,
  industry chains, trade routes, taxes/wages, ratings, fires & collapse
- Fantasy layer: heroes (XP/levels/auras), mana & 7 spells, monsters/invasions,
  walls/towers/legions/golems, campaign of 5 scenarios + endless sandbox
- Canvas2D isometric engine with procedural sprites, zero runtime deps
- Save/load slots + autosave, WebAudio synth music/SFX, HUD/menus/minimap
- Tests: headless sim smoke test + Playwright E2E (build/combat/save)

README.md

@@ -0,0 +1,100 @@
+# IMPERIUM ARCANUM ⚔️🔮
+
+**A Caesar 3–style city builder with heroes, magic and monsters — running entirely in your browser.**
+
+Inspired by [Caesar 3](https://en.wikipedia.org/wiki/Caesar_III) and its open-source remaster
+[Augustus / Julius](https://github.com/keriew/augustus), rebuilt from scratch as a modern web game — then
+extended with a full **heroes & magic** fantasy layer.
+
+---
+
+## ▶ Play
+
+```bash
+pnpm install
+pnpm dev            # → http://localhost:5173
+```
+
+Production build:
+
+```bash
+pnpm build          # outputs dist/ (single-page, static hosting ready)
+pnpm preview        # serve the production bundle
+```
+
+No backend. No accounts. Saves live in your browser's local storage.
+
+---
+
+## 🏛️ Classic city-builder depth
+
+| System | Details |
+| --- | --- |
+| **Roads & walkers** | Buildings may be placed anywhere; connect them with roads to employ workers. Prefects, priests, actors, teachers, doctors and tax collectors patrol as animated walkers |
+| **Housing evolution** | 11 tiers from Small Tent to Estate — water → food variety → religion → entertainment → education → health + luxury goods + desirability |
+| **Food chain** | Farms/orchards/fisheries → carts → granary → market buyers → peddlers feed homes; famine starves citizens and stalls growth |
+| **Industry chains** | Clay→Pottery · Timber→Furniture · Olives→Oil · Grapes→Wine · Iron+Timber→Weapons — warehouses store, markets distribute |
+| **Trade** | Open routes with foreign cities, toggle per-good import/export lists, quarterly caravans, price factors per partner |
+| **Treasury** | Tax rates, wages, forums/senate collection coverage, unemployment and sentiment feedback |
+| **Ratings & victory** | Culture / Prosperity / Peace / Favor ratings drive scenario goals across the 5-mission campaign |
+| **Disasters** | Fire spreads tile-to-tile until prefects douse it; buildings collapse without engineers |
+
+## ⚔️ Heroes
+
+Build the **Hall of Heroes** and summon legends:
+
+- **Aurelius the Champion** — unbreakable melee tank
+- **Lyra the Huntress** — swift ranged killer
+- **Magnus the Stormcaller** — area devastation, +industry aura
+
+Heroes gain XP, level up (more HP/damage), passively boost nearby industry,
+fall in battle and return from the underworld after a few months.
+
+## 🔮 Magic
+
+Temples trickle mana; **Ley Pylons on crystal seams**, mage towers and the **Arcanum** make you rich in it.
+
+Spells (bottom bar): 🌿 Blessing of Ceres · 🔥 Firestorm · 💧 Healing Rain · 💨 Hermes' Haste ·
+🗿 Summon Golem · 🛡️ Aegis Ward · 🔮 Divine Insight.
+The Great Library and Arcanum research advanced spells.
+
+## 👹 Monsters
+
+Hydra, Minotaur, Harpy flocks and the Lich King (who raises skeletons) attack in scripted campaign waves
+and scaling sandbox raids. Answer with walls, towers, legions trained from weapons, golems, heroes and spells.
+
+## 🗺️ Content
+
+- **5 campaign scenarios** — farming village → breadbasket → ley-line awakening → iron frontier → eternal city of magic
+- **Endless sandbox** with prosperity-scaled monster waves
+- Procedural maps: rivers, forests, clay, iron, crystal ley lines, fertile meadows
+
+---
+
+## 🎮 Controls
+
+| Input | Action |
+| --- | --- |
+| Left click | Place / select · drag paints roads, walls, plazas, gardens |
+| Right-drag / WASD | Pan camera |
+| Mouse wheel | Zoom |
+| `Space` | Pause |
+| `1` – `4` | Game speed |
+| `Esc` | Cancel tool / close panel |
+
+Overlays: fire risk, water coverage, desirability, farm fertility.
+
+## 🛠️ Tech
+
+- TypeScript + Vite, zero runtime dependencies
+- Canvas2D isometric renderer with procedurally drawn sprites (no art assets)
+- Deterministic seeded maps, BFS/A* pathfinding, monthly-tick economy simulation
+- WebAudio synthesized music & SFX
+- Test suite: headless sim test (`scripts/simtest.ts`) + Playwright E2E (`scripts/e2e-test.mjs`, `scripts/combat-e2e.mjs`)
+
+```bash
+node scripts/build-simtest.mjs && node /tmp/simtest.mjs   # sim balance smoke test
+BASE=http://localhost:5173/ node scripts/e2e-test.mjs     # full browser E2E
+```
+
+*Made with ⚖️ by an open hand — have fun, Governor.*