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