Three Kingdoms: Warlord's Fate — complete playable game

- Stylized 3D ink-painting map of China (12 provinces, 32 cities, 17 factions)
- Custom warlord creation (8 origins, banner, starting city) or historical factions
- City management: 7 buildings, 5 dev tiers, recruitment from levies
- Character system: stats, traits, loyalty, relationships, wounds, capture, death, succession
- Turn-based tactical battles with formations, stances, hero skills, cinematic 3D replay
- Sieges: assault, starvation, bribery, infiltration
- Diplomacy with trust memory, alliances, NAPs, trade, marriage, espionage, betrayal
- Scripted diverging history (Dong Zhuo, Guandu, Red Cliffs...) + world crises + court events
- AI factions with distinct personalities; prisoners (execute/release/recruit/ransom)
- Procedural guqin/taiko WebAudio score; save/load; victory + dynasty chronicle screens
- View-relative camera controls; headless test suites (smoke, stress, map validator)

README.md

@@ -0,0 +1,69 @@
+# 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
+```