# THREE KINGDOMS: WARLORD'S FATE 三國：群雄命運

A complete strategy-RPG in the dying years of the Han dynasty. Raise a banner as a
nobody with one city — or command one of 16 historical factions — and write your
own chronicle across a stylized ink-painting 3D map of China.

Every campaign generates different history: Dong Zhuo may fall to his adopted son,
Yuan Shu may crown himself, the Yellow Turbans may rise again, and somewhere in a
quiet village the greatest mind of the age is waiting to be found.

## Run it

```bash
cd warlords-fate
python3 -m http.server 8901
# open http://127.0.0.1:8901/
```

No build step. Vanilla ES modules + Three.js (vendored at `js/vendor/three.module.js`).

## The loop

END TURN advances one month: taxes & harvests → salaries → AI factions scheme →
sieges grind on → events fire → officers drift loyal or restless.

- **Cities** — upgrade farms/markets/walls/academies, recruit from levies, march an
  idle general out with a drafted host.
- **War** — move armies between adjacent provinces. Attacking opens a cinematic
  battle: pick a formation, give a stance, watch hero skills trigger in slow motion.
  Sieges can also be starved out, bribed, or infiltrated.
- **Officers** — stats, traits, loyalty, sworn brothers, rivals, wounds, death, and
  capture. Execute, release, ransom, or persuade prisoners. Search cities for
  hidden talents.
- **Diplomacy** — alliances, non-aggression pacts, trade pacts, marriage, tribute
  demands, espionage. Trust is remembered; betrayal poisons every court.
- **Events** — scripted history that can diverge plus world crises and court drama,
  all with meaningful choices.
- **Victory** — hold 20 cities, destroy every rival, or claim the Mandate of Heaven.
  Then read the Chronicle of Your Dynasty.

## Tests

Headless logic suites (no browser needed):

```bash
node tools/smoke.mjs    # 60-turn run incl. save/load roundtrip
node tools/stress.mjs   # 4 scenarios: passive/aggressive/AI-campaign/challenge
node tools/check-map.mjs # map integrity validator
```

Browser journey was verified end-to-end with Puppeteer (screenshots in `shots/`).

## Layout

```
index.html          DOM shell: screens, HUD, panels, modals
css/style.css       ink/parchment/bronze theme
js/data.js          map ASCII, 32 cities, 17 factions, ~69 generals, units, buildings…
js/state.js         global state, RNG, save/load
js/world.js         hex grid geometry + province adjacency
js/sim.js           economy, battles, sieges, AI, turn engine
js/events.js        scripted history + crises + court events
js/map3d.js         stylized 3D China (instanced hexes, pagodas, rivers, banners)
js/battle3d.js      cinematic tactical battle scene
js/battle-sim…      pure battle simulation driving the replay
js/audio.js         procedural guqin/drums/gong WebAudio score
js/ui.js            panels, HUD, event modals, portraits
js/main.js          bootstrap, game loop, orchestration
```