---
name: living-world
description: Build a top-down 2D world that feels alive and looks rich, in the spirit of Breath of the Wild. Use it when making or improving a 2D explore/glide game with height you can read (many small ledges, diagonal cliffs, ramps, a baked sun-lit height map), a textured ground with groves and zone-specific decoration, zones mixed side by side, a screen full of small things that react to the world (swaying grass, wind socks, tethered balloons, drifting seeds, smoke, puddles, sparrows, cloud shadows), a glider with a shadow and an honest landing marker, rising and sinking air (thermals, cliff lift, cold air), wind, day and night, weather already under way from the start, creatures in groups that show the air, fire and ice that combine by rules, sea and islands, and temperature zones that look and feel different. Also use it to keep a busy screen ordered (full but ordered, no landmarks) and to test it cheaply (node self-tests, a quick GPU Chromium test with a richness check). Plain JS modules plus a playable Phaser 3 starter. Not about combat.
---

# Living world

A top-down world whose ground has height you can read, whose air you can see and ride, and whose fire, ice,
weather and creatures follow a few rules that meet each other. Distilled from a finished top-down glider game in the
spirit of Breath of the Wild, built and playtested over many sessions. Its player said the world was the best part,
and that height and the glider were its heart. Every number here felt right in play; start from them.

## What the world is made of

| part | what it is | code |
|---|---|---|
| ground | a tile height map in whole levels (24 px); `shapeLand` builds it from a few knobs (many small ledges, massifs, sea); `bevel` turns staircases into diagonal cliffs; ramps (`placeRamp`, ramp runs) and `escapeRamps`; `printMap`; baked once into a sun-lit picture; cliff faces drawn every frame | `scripts/terrain.js` |
| hero and glider | walk, fall, glide; one glide step for the hero, the landing prediction and the reach search; `autoRamps` | `scripts/glider.js` |
| air | ONE field: columns (warm rocks, vents, fires, steam), cliff lift, sun-warmed walls, cold air, wind | `scripts/air.js` |
| zones | palettes, faces, ramps per zone; `mixZones` lays them side by side; `zoneCold` makes their cold real air; frost, particles, mist, chill and scorch | `scripts/temperature-zones.js` |
| rules | fire, carried flames, embers, lightning, rain, ponds that fill and freeze, ice that melts and slides | `scripts/interactions.js` |
| sky | one clock: the time of day (it changes the air) and seeded weather every day, light most of the time and loud rarely, already under way at the start (`opening`); `drawWeather` for the light kinds | `scripts/clock.js` |
| life | hawk kettles, gull colonies, swift flocks (bats at night), a skein of geese, herds of hares and goats, a great bird: each reads the same air as the hero; `findGullSites` | `scripts/creatures.js` |
| look | texture baked into the ground per zone, lush and dry patches, worn trails (`makeTrails`), groves of trees, bushes, boulders, reeds, palms, cacti; lit sprites | `scripts/decor.js` |
| alive | the small things that react, placed by themselves from the map and the air: swaying tufts and flowers with gusts running over them, dandelions, wind socks, pennants, tethered balloons (lift) and kites (wind), drifting seeds/leaves/ash/sand, smoke and steam, cloud shadows moving with the wind, puddles that fill in rain, frost glints, heat shimmer, sparrows that flush, midges in lift, butterflies, fireflies; `richness` | `scripts/ambient.js` |
| starter | a small playable Phaser world (about 2 x 2 screens, with a sea) wiring all of it, debug starts, tests | `templates/starter/` |

Everything is plain ES modules with no engine inside (Phaser only appears in thin adapters that take the scene).
The rules run in node, so they test in under a second.

## Start a game from the starter

1. Copy it, with the modules beside it (`S` = this skill's folder, run in the game's folder):
   `cp -R $S/templates/starter/* . && mkdir -p js/living-world && cp $S/scripts/*.js js/living-world/`, then in
   `js/lw.js` change `../../../scripts/` to `./living-world/`. `test/lib.mjs` finds what to serve by itself.
2. **Rewrite `js/world.js`**: set the map's knobs from the request (`LAND`: relief, ledges, massifs, sea, keep; and
   `ZONE_RULES`), then the air, fires, ponds, life, and `SPOTS` (the debug starts: functions of the world). The
   starter's `buildTerrain` is the pipeline: `shapeLand` -> `mixZones` -> `bevel` -> `autoRamps` -> `escapeRamps` ->
   `makeTrails` -> `scatterProps` -> bake. Do not hand-type rectangles of levels (they come out as big blocks).
   Keep the fields `view.js` reads (`decor`, `sock`, `mistSpots`, `cumulus`) and the look (`scatterProps` with a
   `keepOut`, `chainPaint(groundPaint(t, ZONE_IDS), yours)`). **Use the helpers, don't rewrite them** (ramp routers
   and map printers are already there). Pick built-in zones before inventing one. `main.js` needs no edit.
3. **Adapt `js/view.js`** only for new things to draw (lava, geysers). The camera, terrain, decor, marker, clouds,
   waves, weather and HUD already follow the rules below. Its reactive layer (`createPhaserAmbient`) fills every
   screen and places itself from your map, air and fires: keep it. For a new zone add a line to `AMBIENT_ZONES`.
4. **Fill the world.** Every zone gets its marks, props and reactive things; groups of creatures in their air;
   weather going from the start. **No landmarks**: no beacons, towers, shrines, labels or pointers to places.
5. **Before you stop**, run `node test/quick.mjs` (Playwright in the game's `node_modules`) and `node test/shots.mjs`.
   Rewrite quick.mjs's node checks for your map (one per rule your world depends on), keep its browser part: it
   fails any debug start or **any zone's screen** under the richness target (fix a sparse zone with its
   `AMBIENT_ZONES` rates, never the target). Then look at each still shot for two seconds; if nothing moves, fill it.
6. Read the reference for the part you are changing. They hold the numbers and the mistakes behind them.

## One set of names and units (every file uses these)

- **px and seconds.** 16 px = 1 tile (`TERRAIN.TILE`), 1 level = 24 px (`TERRAIN.LEVEL`), levels 0 to 6. Heights
  are absolute px (`z`, `top`); `g` is the ground height at a thing's foot.
- **Wind in breeze units:** 1 = 60 px/s of drift (`AIR.WIND_TO_PX`). **Lift 1 = 105 px/s up** (`AIR.LIFT`). Breezes
  are `{ x0, y0, x1, y1, day: [wx, wy], night: [wx, wy], steady }`.
- **`ahead`** = seconds into the future. Every air function takes it, so a prediction can see a moving storm, and
  (with `air.skyAt = (a) => clock.fAt(a)`) the wind turning at dusk.
- **13:00 with no weather is the reference hour:** every time factor is 1 or 0 and the world plays as built.
- Factories: `createTerrain`, `createAir`, `createInteractions`, `createClock`, `createLife`, `createHero`,
  `createCamera`, `createBody`, `createAmbient`. Tables: `TERRAIN`, `GLIDER`, `AIR`, `ZONES`, `PALETTES`, `RULES`,
  `FIRE`, `WEATHER`, `DAY_TABLE`, `BODY`, `AMBIENT`. Each number has one owner (`LIFT` lives in air.js).

## Build order

Build and test each step before the next; each is playable on its own.
1. **Height first** ([height-and-glider.md](references/height-and-glider.md)): the map from knobs (`shapeLand`,
   `mixZones`, `bevel`, `autoRamps` + `escapeRamps`, both counts 0), the bake, cliff faces, the camera, stillness.
2. **The glider and the air** (+ [air-and-temperature.md](references/air-and-temperature.md)): one warm-rock column
   by the start, breezes and cliff lift, the shadow, the marker. Tune until riding up feels calm.
3. **Time and weather** ([time-weather-life.md](references/time-weather-life.md)): `air.setSky(clock.f)`,
   `air.skyAt`, day and night winds, light, storms with look-ahead; light weather from the first second.
4. **Interactions and zones** ([interactions.md](references/interactions.md)): fires as columns, flames, embers,
   ponds, ice; cold zones as real air (`zoneCold`), palettes, frost, mist, the body.
5. **Creatures, in groups**: hawk kettles (`addHawks`), gull colonies at `findGullSites`, a skein, herds.
6. **Fill the world, then order it** ([looks.md](references/looks.md), [calm-screen.md](references/calm-screen.md)):
   marks, props and the reactive layer in every zone; the hero and the air in use stay loudest; no landmarks. **Rules
   passing is not done: the richness check on every start and zone, and two seconds on each still screen.**

## The 17 rules that matter most

1. **No climbing, no stamina, no glide timer.** You go up on rising air or by walking ramps (2 tiles per level,
   you step up 7 px at most). Pushing into a wall is a soft bump. A long fall is a 0.9 s tumble, no damage.
2. **Height reads in a still frame, from every side, without turning the view.** Whole levels of 24 px; a baked
   ground lit by a fixed north-west sun (`SUN [-0.6, -0.8]`, `SUN_TAN 1.15`); a tint step per level
   (`0.88 + 0.045 * level`) on a palette **at least 4% brighter every level up** (`paletteSteps`); cliff faces drawn
   every frame, south faces hanging at least 0.3 px per px of height. Not isometric blocks. Diagonal edges are
   diagonal cliffs (`bevel`), not 1-tile stairs.
3. **The stillness rule.** When the hero stops, the terrain is pixel-identical. The camera follows the distance
   travelled (look-ahead 14 px over 48 px of travel), never time. Zoom depends on height only: 2.0 on the ground,
   never zoomed out more than 37%. Test it with screenshots.
4. **One glide step** for the hero, the landing prediction and the reach search. Walk 74 px/s (faster than
   gliding), glide 58 px/s, drift 26 px/s, sink 18 px/s, steering `1 - exp(-5.5 dt)`, vertical speed easing to
   `-sink + lift * 105` at 3/s.
5. **The landing marker never lies.** Same step, same air, looking ahead in time. Teal ring soft, orange ring hard,
   blue-grey ring water, red cross at a wall, chevrons only while still rising (lift over 0.3), an arrow pinned to
   the screen's edge when off screen (never on the HUD). Nothing ever covers it.
6. **One air field, one question.** Everything that flies asks `air.liftAt` and `air.windAt`: the glider, the
   marker, embers, seeds, birds, balloons. Rising air takes the strongest source (max, never the sum); sinking air
   is subtracted.
7. **Only columns are launch pads** (take-off needs column lift 0.3). Cliff lift (44 px in front of a face, up to
   46 px over its top) and sun-warmed walls catch a glider but never launch one. Wingtip air never does.
8. **Everything is soft.** Rising air fades over the last 36 px below its top (you hover ~7 px under it); wind and
   cold zones have 24 px edges; a storm's core fades over its last 30 px; the wind leans each column 0.4 px per px
   risen per breeze unit, capped at 0.9 r.
9. **Temperature is air.** A cold zone sinks (0.12 to 0.45) and pours downhill; a fire's warmth cancels it. If the
   ground looks cold, the glider must sink there. Never a zone that only looks different.
10. **The sky changes the air, never whether you can get somewhere.** At night warm rocks keep 45% strength and 36%
    height, fires rise 30% higher, cold sinks 35% harder; the day wind turns into a night wind with a calm between.
    Keep steady winds where a route depends on them. A day lasts 6 minutes.
11. **Weather is seeded, never-ending, and mostly light.** A journey opens with light weather under way over the
    spawn. Light kinds (drizzle 0.22 rain, a 0.24 breeze, fog, flurries, haze) fill ~70% of the day under every
    rule's threshold. Loud kinds (storm, squall, gusty front): at most 2 a day, 2 h apart, none before `calmUntil`,
    one event at a time; a `schedule` adds set pieces to the seeded days. A storm builds 1.5 h at the map edge.
12. **Write rules, not encounters.** A fire is a warm column and never spreads. Embers in wind of 0.22+ light an
    unlit fire in 2.2 s; lightning hits the tallest thing within 96 px (a tree, a fire, or bare high ground: a mesa top); ponds fill in rain and freeze at night;
    fires that burned from the start come back 6 s after being put out. Every rule goes through the shared air.
13. **No dead ends.** Every place you can reach can get back to the goal, on foot or by air, checked with the real
    glide step in every state: dawn, night, each storm, fires lit and unlit, ponds full and frozen.
14. **Creatures read the same air, in groups, so what they do is true.** Hawks kettle 2-3 to a column at 64-80% of
    its radius round its wind-leaned centre, 9-34 px under its top; with no lift at its spot a hawk circles tighter
    and lower until it finds it. Gulls hang in colonies of 3 along a windward face, 22 px under its top, only where
    `findGullSites` finds lift. Geese cross high on the wind; seeds ride 95% of the wind and 72% of the lift. Heavy
    rain (> 0.3) sends birds off, drizzle lowers the hawks; at night hawks roost, gulls sit, the swifts are bats.
15. **Full but ordered.** Many small quiet things, a few loud ones, one loudest (the hero and the air in use). The
    many (~100 tufts, seeds, sparrows, puddles, glints a screen) are small, in the ground's hues, in groups; the loud
    few (socks, pennants, balloons, kites, fires) are muted and 150+ px apart, at most ~2.5 a screen. Every one shows
    a system (wind, lift, temperature, wet, time). Circles mean only the landing marker. No permanent text; the
    weather warning has no words. Clouds are at most a fifth there within 150 px of the hero. A storm darkens at most
    28%. **No landmarks**: no beacons, towers, shrines, labels or pointers to places.
16. **Rich by default, quiet in detail, and alive.** No flat colour fields: texture in the ground, groves not
    sprinkles, different small things per zone, water that moves at the shore; nothing as bright or saturated as the
    hero, glider or marker. What moves (ambient.js) is drawn over the still ground and hidden in the terrain-only
    view, so stopping gives a pixel-identical ground while the grass keeps swaying.
17. **A full map, not big blocks.** Many small ledges of 1-2 levels and every length (`shapeLand`, `ledges`
    0.5-0.8), irregular massifs (lobes, spurs, a steep side, a way up), zones mixed side by side (`mixZones`, mix 0.5:
    two looks on most screens, soft edges), each zone's cold real air (`zoneCold`).

## Shaping a map from knobs (terrain.js)

Hand-made maps tend to be a few big blocks (stepped pyramids, wide terraces) with one zone per screen. `shapeLand(t,
knobs)` builds a smooth height field and cuts it into whole levels: slopes become narrow ledges, noise breaks them up,
a massif's contours never nest as rings. Set the knobs from the request, keep the rest:

| the request says | knobs |
|---|---|
| "gentle meadows", "rolling hills" | `relief: 0.3, ledges: 0.4, mounds: 0.6` |
| "many little ledges", "terraced" | `relief: 0.5, ledges: 0.7, grain: 8` |
| "rugged", "badlands", "canyon" | `relief: 0.8, ledges: 0.85, grain: 7`; mesas `kind: 'mesa'` (glide-only: `skip`) |
| "a big mountain", "snowy peaks" | `massifs: [{ c, r, rx: 16-20, ry: 12-14, top: 5-6, steep: [0, 1] }]` |
| "a volcano" | `massifs: [{ kind: 'volcano', rx: 10-14, top: 4-5 }]` (a crater one level down) |
| "by the sea", "sea cliffs" / "an island" | `sea: 'south'`, `beach: 3` (cliffs `beach: 0`) / `sea: 'around'` or `'islands'` |
| "rising inland" / flat places | `tilt: { to: [0, -1], levels: 2-3 }` / `keep: [[c, r, radius, level]]` (start, camps) |

Then: `mixZones(t, ids, rules, { mix: 0.5 })` (e.g. `[{ id: 'meadow' }, { id: 'forest', share: 0.3 }, { id: 'snow',
above: 4 }, { id: 'beach', shore: 3 }]`), `bevel(t)`, `autoRamps(t, starts, { skip })` and `escapeRamps(t, starts,
{ skip })` (a way up autoRamps missed, a way out of every hollow: `unreached === 0 && trapped === 0`). A ramp reads as
one worn slope and climbs 2-3 narrow terraces as one run. If a count is not 0: `printMap(t, mark)`, then raise
`shelves`, lower `ledges`, move the place, or `skip` it as glide-only; never loosen the check. Island coasts keep
walking traps (you glide off): judge them by `findDeadEnds`. Details and hand-shaping helpers: height-and-glider.md.

**Water** (`t.water`, 1 per tile) is a wall on foot and open air for the glider; a landing in it washes the hero up
where they last stood (`land-water`), the marker shows it blue-grey, it puts out a carried flame. The bake paints it;
glints go on their own layer. A sea wind onshore by day (`over: 100`) gives cliff lift on every windward shore.

## A rich, full look (decor.js, ambient.js)

Without these a world looks flat, or textured but empty; the starter has all of this by default: keep it.
- **Texture in the ground, baked once** (`groundPaint(t, ZONE_IDS)`): per zone (`DECOR`) grass tufts, flowers in
  patches, pebbles, cracks, sand ripples, snow streaks, leaf litter, ash, a wet band at the shore; lush and dry
  patches shift the hue at the same brightness; big marks within 22% of the ground's brightness (`PATCH_CAP`). Chain
  your hooks: `chainPaint(groundPaint(...), frost, trails.paint)`.
- **Worn trails** (`makeTrails` after the ramps; pass `trails.keepOut` to the scatter, chain `trails.paint`) and
  **groves** (`scatterProps(t, ZONE_IDS, { keepOut, faces })` before the bake: trees in groves, 4% strays, bushes at
  their edges, boulders, reeds, cacti; solids that cast the bake's shadows; drawn by `createPhaserDecor`).
- **Things that react, on every screen** (`ambient.js`; tested values: 100-152 a screen in 6-18 kinds, moving
  pixels 8-22%; at 2-3% a screen reads as empty). `createPhaserAmbient(scene, world, { ids,
  keepOut })` places ~100 swaying tufts a screen (tips up to 1.6x the ground's brightness), dandelions, socks and kites
  where it blows, balloons where it rises, pennants by camps, puddles, sparrows, midges, butterflies, fireflies, smoke,
  steam, cloud shadows. `richness(scene)` -> `{ count, kinds }`; quick.mjs needs `RICHNESS_TARGET` (80 and 8) on
  every start and every zone. Tufts are things, not texture: blades 4-6 px that stand (lean at most 0.45), 1.5+ px
  wide on screen. A new or sparse zone: `Object.assign(AMBIENT_ZONES.<id>, { tuft, birds, insects })` in view.js.
- **Judge it**: "would this spot make a nice wallpaper, is something small moving everywhere, and is the hero still
  the loudest thing?" A flat zone needs marks and reactive things; a busy one lower rates, never a quieter hero.

## Pitfalls (each one cost real time)

- Climbing on a stamina ring (not fun); isometric stacks (hid everything); a camera easing with time
  (the ground "kept moving"); summed air sources (rockets); a take-off test asking for the strongest air (every windy
  cliff foot an elevator); a marker that lied in storms and at dusk; calm dawn removing the only way up; 4-minute
  days; 40 circles on one screen; text toasts; clouds over the hero; a spreading grass fire burning routes away.
- `findDeadEnds` that saw one glide home only (507 false dead ends); hawks circled a column's
  foot while the wind leaned its air away; per-tile cliff lift split prediction and flight (20-42 px).
- Calm read as empty (the target is busy but ordered); loud props on a
  summit read as a destination (kept off the highest ground); a quiet first minute, no weather after day 0; single
  birds read as decoration; the tile graph stepped onto bevelled tiles; `placeRamp` left 1-tile pits.
- **Tufts read as ground texture**: 2-px dashes leaning almost flat in a breeze, at half the tested count (now
  taller, upright, wider, denser defaults); **sparse zones passed** because only five spots were sampled (now every
  zone's screen is checked);
  **hawks added circling started at (0, 0)** and crossed the map in their first second; **trails skipped places
  reached only by hopping off a ledge** (`makeTrails` may drop one level, reports `unlinked`); **an islet's beach under
  a low cliff was a trap** with no room for a ramp (`escapeRamps` raises such strips); **lightning ignored mesas**.

## Test cheaply

- **The rules, in node.** Run the one for the part you touched after every change (each under 5 s):
  `selftest-terrain-glider.mjs` (65: ramps, no climbing, shadows, stillness, the honest marker, no dead ends, water,
  bevel, shapeLand, the ramp pipeline with no trap, a raised beach, mixed zones, zone cold); `selftest-air.mjs` (76: the air, every
  interaction, every palette steps up, the body); `selftest-clock-life.mjs` (97: the day, storms, the opening at any
  hour, weather every day, light vs loud, drawWeather, kettles in real lift, colonies, night, bats, geese, herds);
  `selftest-decor.mjs` (44: texture, groves, trails, autoRamps + escapeRamps, gull sites); `selftest-ambient.mjs`
  (41: tufts per screen, nothing on water or ramps, the contrast cap, loud things spaced and off summits, socks lag
  the wind, balloons rise in lift, seeds ride the air, puddles fill and freeze, sparrows flush, the census).
- **The starter's quick test, "rich and alive"** (~40 s, must stay under 2 minutes): `node test/quick.mjs`
  (`--node` skips the browser). Node: your map's rules, colonies and kettles in real lift, no NaN flyers, the opening,
  weather every day. Chromium on the GPU (channel `chromium`, `--mute-audio --use-angle=metal --enable-gpu
  --ignore-gpu-blocklist`): weather at the hero within 10 s, birds in groups in their air, every debug start clean,
  **every debug start and every zone's screen meets `RICHNESS_TARGET`**, stillness with the weather running (and that it can fail), the
  texture, the storm. Keep its thresholds (when a check fails, move the world, not the check).
- **Screenshots:** `node test/shots.mjs [spot ...]` into `./living-world-shots/`. A spot for every promise: start,
  thermal, cliff lift, storm, night, dawn, each zone, fire, ice, sea. Ask of each: what is the loudest thing? Can I
  find the hero and the marker in a second? Does every level read? Does something small move everywhere?
- **Budget:** the reach check is the slow one (2 s on 96 x 64 tiles, 15-45 s on islands). Fail on any console
  error; prove each check can fail once; never loosen a rule to pass.

## The starter (`templates/starter/`)

A textured meadow by the sea rising in small ledges to a frosty upland (built by `shapeLand` from the knobs in
`LAND`, zones mixed by `ZONE_RULES`, diagonal cliffs, ramps by autoRamps + escapeRamps), with groves, worn trails and
warm rocks (a hawk kettle), a cliff that a steady north wind turns into cliff lift (a gull colony), a lit brazier
whose embers light a camp fire downwind, a frozen pond, a glide-only mesa, a sea with waves, and a reactive layer on
every screen (swaying grass, a wind sock, pennants by the camp, balloons over the warm rocks, a kite, sparrows,
midges, butterflies or fireflies, puddles, frost glints, smoke). A 3-minute demo day (`DAY_LEN` 180; make your game's
360) with one set-piece storm at 13:30 on top of seeded weather, and light weather already under way at every start.
Arrows/WASD walk, Space glides, E lets go. `js/world.js` builds and steps the world with no engine and holds `SPOTS`;
`js/view.js` draws it with Phaser 3; `js/main.js` reads `?spot=`, `&time=HH:MM`, `&day=N`, `&weather=0`, `&seed=N`,
`&test=1`, `&terrain=1`, `&hints=0`, `&opening=0|drizzle|breeze|fog|flurry|haze`; `js/lw.js` is the one place that
imports `scripts/`. Serve it (`python3 -m http.server`); Phaser loads from a CDN in `index.html`.

## References

- [height-and-glider.md](references/height-and-glider.md): height, a map from knobs, bevel, ramps, water, stillness,
  the camera, the glider, the marker, no dead ends. [air-and-temperature.md](references/air-and-temperature.md): the
  air field, mixed zones, zone cold, the body. [interactions.md](references/interactions.md): fire, flames, embers,
  lightning, rain, ponds, ice. [time-weather-life.md](references/time-weather-life.md): the day, weather, the opening,
  storms, creatures in groups. [calm-screen.md](references/calm-screen.md): full but ordered, no landmarks, HUD.
  [looks.md](references/looks.md): the rich look in detail (marks, props, trails, things that react, new zones).
