Wildlife Kingdom — original browser zoo-management sim

- Procedural canvas art: 15 species × 4 poses, 15 buildings, modular terrain, UI icons
- Habitat enclosure detection, biome suitability, staff/guest AI pathfinding
- Economy: tickets, shops, wages, star rating, research tiers, 15 missions
- Day/night cycle, particles, WebAudio soundtrack & synth SFX
- Mouse + touch controls, responsive UI, localStorage autosave
- Verified: 31/31 logic tests (test/smoke.js) · 12/12 render audits (test/qa.html)

README.md

@@ -0,0 +1,77 @@
+# Wildlife Kingdom 🦁
+
+A cozy, original **zoo-management simulation** that runs entirely in your browser —
+no installation, no build step, no assets to download. Every animal, building, tree
+and sound is generated procedurally in code (Canvas 2D vector art + WebAudio), so the
+game is a single static folder you can open anywhere.
+
+> Original world & characters. Not affiliated with, and contains nothing from, any
+> existing game or franchise.
+
+## ▶ How to Play
+
+**Option A — just open it:** double-click `index.html` (any modern desktop/tablet/phone browser).
+
+**Option B — serve it** (nicer URLs):
+
+```bash
+python3 -m http.server 8313 --directory /root/zoo
+# → http://127.0.0.1:8313
+```
+
+Progress **autosaves** to your browser every 30 s and when the tab hides.
+
+## The Loop
+
+Build paths → fence a habitat → paint its biome → adopt animals → hire keepers →
+delight guests → earn TownCoins… spend them on rare species, restaurants and an
+aquarium → climb from 1★ to 5★ Wildlife Legend.
+
+- **Guests only walk on paths.** Connect everything to your entrance.
+- **Habitats must be fully enclosed** with fences; each species has favorite grounds,
+  space needs and enrichment wishes. A keeper gate lets staff in.
+- **Happy animals + happy guests + facilities + decor = stars**, and stars drive ticket
+  sales and footfall.
+- **Research points** unlock Tier II–IV: lions, penguins, elephants, pandas, polar
+  bears, the aquarium, reptile house and more.
+- **15 missions** teach everything and reward coins/RP along the way.
+
+## Controls
+
+| Action | Desktop | Touch |
+|---|---|---|
+| Pan | drag / WASD / arrows / right-drag | one-finger drag (empty hand) |
+| Zoom | wheel, `+`/`-` | pinch |
+| Paint / place | pick tool, click-drag | pick tool, tap-drag |
+| Inspect | click anything | tap |
+| Bulldoze | `X` | toolbar button |
+| Pause · speed | `Space`, `1·2·3` | HUD buttons |
+
+## Project Layout
+
+```
+index.html          app shell
+styles.css          original cream/rounded UI identity
+js/util.js          math, RNG, canvas helpers
+js/data.js          all content: species, buildings, terrain, research, missions
+js/audio.js         WebAudio soundtrack + SFX synth (no audio files)
+js/sprites.js       procedural art: terrain, nature, buildings, 15 animals × poses, icons
+js/world.js         tile grid, habitat enclosure detection, pathfinding
+js/entities.js      Animal / Guest / Keeper / Vet AI + particles
+js/sim.js           economy, rating, missions, research, spawning, save/load
+js/render.js        iso camera, cached layers, day/night lighting
+js/input.js         mouse/touch tools & camera
+js/ui.js            HUD, toolbar, panels, modals, toasts
+test/smoke.js       headless logic test-suite (node test/smoke.js)
+test/qa.html        in-browser render audit (pixel sampling)
+screenshots/        captured from headless Chrome
+ART_DIRECTION.md    the visual identity bible (palette, shapes, rules)
+```
+
+## Verified Quality
+
+- `node test/smoke.js` → **31/31 logic checks** (enclosures, pathfinding, economy,
+  research, save/load, demo zoo)
+- `test/qa.html` under headless Chrome → **10/10 render audits**
+  (all 15 species × 4 poses, all 15 buildings, every UI icon, water/day-night pixels)
+- Zero console errors on menu and gameplay loads.