@funpixel/tools 0.0.0-stage → 0.1.1

package/plugins/robin/claude/skills/world-and-story/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: world-and-story
+description: Use when a game should feel like a place with a story (a world to explore, an opening, characters who speak, a crowd that cheers), or its world reads empty, silent, static or aimless. Covers landmarks, kit dressing, a living world (people on task loops, creatures with gaits), atmosphere, story sized to the game and voice.
+---
+
+# World and story: a place worth being in
+
+A game can be correct and still feel like a box: a field of tiles, a goal in a sentence, nothing
+that says where you are or that anyone is watching. The acclaimed games put the story in the place.
+Pick what fits from this shelf; a tight arcade game may want none of it.
+
+## Tools
+
+- `generate_image` for key art, backdrops and vistas; `generate_sprite` and `generate_spritesheet`
+  for a kit of props and characters that move; `edit_image` for a variant (a lit and an unlit
+  lamp) so one kit tells a before and after.
+- `generate_skybox` for a 3D sky; `find_material` and `get_material` for free Poly Haven HDRIs,
+  textures and models; `generate_3d_model` for a hero prop or character; `build_level` when the
+  place is an interior or a set with a plan (skill `fp:3d`).
+- `generate_music` and `generate_sound` for the place's sound (skill `fp:audio`).
+- `capture_view` and `audit_screens` to see each beat at phone size; locally `capture`, `play`
+  (a blind player: ask it its goal), `profile`, `life` (ambient life) and `depth` (story beats
+  seen in play), all `npx @funpixel/tools`.
+
+## What the hits do
+
+- **Hollow Knight**: the world is the story. Ruins and inscriptions explain a fallen kingdom
+  without a cutscene; each area owns a colour, a sound and a silhouette. Landmarks you glimpse
+  early you reach late.
+- **Hades**: story rides the loop. Every death returns you home where characters remark on what
+  just happened, so losing is content. Text is short and voiced.
+- **Celeste**: each chapter is one place, one new mechanic and one feeling,
+  bracketed by a short scene. Postcards between chapters say what it is about.
+- **Silt & Signal** (Crayon, our web reference): a one-line promise on the title, a voiced beat
+  before control, then a chapter card and a goal with a waypoint; 7 chapters, 61 voiced lines in
+  12–15 minutes. Notes: [references/shelf.md](references/shelf.md).
+
+## Craft on the shelf
+
+1. **A place before a level.** Name the place in one line and give it one landmark the player can
+   see from most of the map (a tower, a tree, a lighthouse), two or three districts that differ in
+   colour and material, and a route the eye follows. Keep the play space readable: walkable ground
+   one value band, blocking things another, threats their own colour.
+2. **Dress from a kit, not a tile.** Six to twelve pieces in one style (rocks, bushes, flowers,
+   lamps, fences, crates) scattered by rule: dense at edges, clear on the route, a ring around
+   landmarks, jittered scale, flip and tint so repeats hide. Seeded, so it is the same place every
+   run. Code for Pixi and Three: [references/world-kit.md](references/world-kit.md).
+3. **Tell it with things.** Put two or three props per area that imply what happened (a cart on
+   its side by a broken bridge, dark lamps along a road with one lit). Change something the player
+   can see when they act: the lamp lights, the bridge mends, the music opens up.
+4. **Author the opening.** Title (name, one-line promise, one button) → a beat of a few seconds
+   that shows the world and the want (a pan, one or two lines, skippable) → the first control,
+   taught by the space → the first objective in words with a waypoint and a distance → a first
+   payoff inside a minute. Recipes: [references/opening-and-chapters.md](references/opening-and-chapters.md).
+5. **Chapters and objectives as data.** A chapter is a place plus one new idea; an objective has
+   words, a target and a done-test. The HUD shows the chapter and the current goal; the world
+   answers when one completes. Save progress with `@funpixel/sdk/save`. Many rooms:
+   `npx @funpixel/tools world forge --seed N` drafts them as data from `## Places` and the kit
+   (doors, a critical path, a light per room); `world check` proves each door and goal is reached:
+   [references/forged-world.md](references/forged-world.md).
+6. **Story at the game's size.** An opening beat, a goal said by a person, chapters whose lines
+   change as you go, an ending that changes the world; about 30–60 short lines for the 15 minutes a game plays at least,
+   or "declined" on purpose for an arcade round. One line at a time, clear of the controls.
+   Sizes, lines as data and the GDD's `## Story` table: [references/story-at-size.md](references/story-at-size.md).
+   Voice: the platform's `cast_voice` + `voice_line` (a story game's default offer, priced), a
+   voice in code, a murmur, or the creator's own text-to-speech: [references/voice.md](references/voice.md).
+7. **One set-piece.** Plant it early (a sealed door, a dark tower), pay it off with camera, light,
+   sound and a change the player keeps seeing. Lighting and effects: skill `fp:art`; music
+   that turns with it: skill `fp:audio`.
+8. **A living, made world.** Each person animates, walks a task loop, idles and answers the
+   player; a crowd is a few focused scenes along the path, never the hero's face; creatures have
+   gaits, flyers flap; a painted cut-out animates too, never a picture slid. What the camera
+   passes is built from the first look's kit, never a flat box, and stands on the ground:
+   [references/living-world.md](references/living-world.md). A world that notices:
+   [references/atmosphere.md](references/atmosphere.md). `npx @funpixel/tools check` (or `life`,
+   `walk`, `boxes`) shows what slides, clumps, floats or reads unfinished.
+9. **See it as a player would.** Capture title, beat and first goal at phone size; ask the blind
+   player its goal; profile the dressed view.
+
+## Worked example
+
+Brief: "a small valley at dusk, bring light back to it". Lantern Vale: a tower on the ridge, a
+road, lamps. In the lab a seeded `scatter` dressed a phone view with about 280 pieces, the road
+clear, a ring round the tower, in 3 draw calls. The opening: title
+"The Last Light / Every lamp in the valley went out but one", a pan under two lines from Ada, then
+`01 / THE LAST LIGHT` over "Reach the tower at the top of the valley" with an edge arrow reading 113 m.
+
+
+## Common mistakes
+
+- Scattering uniformly: repeats line up and the route disappears into clutter.
+- A goal only in text: players look for the thing on screen; give it a marker and a distance.
+- A cutscene before any control that runs long or cannot be skipped; keep the first beat short.
+- Story in a wall of text; one line at a time, and let the place say the rest.
+- A landmark that is never reached, or a world change the player never sees.
+- A strange number never explained. Voices placed by room and deed, cards that name what happened:
+  [references/opening-and-chapters.md](references/opening-and-chapters.md#a-radio-placed-rather-than-narrated).
+
+Where this comes from: the hits (research 18), Crayon's GDD (research 19), our own games, our lab.

package/plugins/robin/claude/skills/world-and-story/references/atmosphere.md

@@ -0,0 +1,208 @@
+# Atmosphere: a world that notices the player
+
+A place feels alive when things in it move on their own and answer what the player does. Our
+racer (29 Sep) played well and still read as "a game of shapes": no one in the stands, nothing
+at the trackside, no moment at the finish. The owner's words: "environment and crowd cheers were
+missing". This page is a shelf of patterns per genre and the cheap code under them. Pick what the
+brief wants; a puzzle in an empty white room may want none of it, on purpose.
+
+## Three layers
+
+| Layer | What it is | Cheap build |
+|---|---|---|
+| Ambient life | things that move without the player: flags, birds, passers-by, a crowd shuffling, weather | instanced cards or impostors on a slow sine; a few particles; two or three looping sprites |
+| A bed | one quiet loop that says where you are: a crowd murmur, rain, a city hum, a room tone | one `generate_sound` with `loop: true`, 20–30 s, played under the music |
+| Reactions | the place answering a moment: a roar, a gasp, lights, a camera flash, a line from someone | the bed swells or hushes, a sting plays, the cards jump, one line of text or voice |
+
+Reactions carry the most for the least. A crowd that stands still but roars when you overtake reads
+as alive; a crowd that waves forever and never notices you reads as wallpaper.
+
+## Per genre
+
+| Genre | Ambient life | Bed | Reactions to the player |
+|---|---|---|---|
+| Racing | grandstands at the start, the finish and one bend; flags and banners on the fences; marshals; a blimp or birds overhead | crowd murmur by the stands, wind at speed | the roar swells as you pass a stand (by distance); a hush at the countdown, then a cheer on GO; a gasp on a crash; a cheer on a boost or an overtake; an announcer line at the start and the last lap; confetti, flashbulbs and fireworks at the line; rivals with a name, a colour and a one-line taunt |
+| Arena, sports | the crowd around the whole field, stadium light, a scoreboard | the stadium's roar, a chant loop | the crowd as a scoreboard of feeling: rises with a rally, groans at a miss, erupts on a goal; a chant after a streak; a replay of the best moment |
+| Theatre, stage | an audience in rows, stage light, a curtain | murmur before, silence during | laughs, gasps and applause timed to the act; a curtain call with the house on its feet; coughs in a flat patch tell the player they are losing the room |
+| City, adventure | passers-by on the pavement, traffic, birds on wires, laundry in the wind, lights switching on at dusk | traffic, voices, gulls, rain | people turn to look at a stunt, a shopkeeper calls out, a crowd gathers at a set piece; a street lights up when you fix it |
+| Horror | almost nothing, and that is the point | a low room tone and long silences | absence as atmosphere: distant sounds with long, uneven gaps; the bed drops out a beat before a threat speaks; one sound close behind the player |
+| Nature, journey | grass and trees in wind, herds, fish, fireflies at night | wind, water, birdsong by time of day | animals scatter or follow; a herd runs beside the player; birds lift when you land |
+| Puzzle, cosy | one companion or small creature, a window with weather | a soft room or garden loop | the companion looks at the piece you hold, cheers a clear, sighs at an undo |
+
+## A crowd that reacts (Three)
+
+Spectators as camera-facing cards in one `InstancedMesh`: a few hundred people in one draw call.
+Four poses on one sheet (generated with `generate_spritesheet`, or flat colour silhouettes), a
+per-person phase so they never bob in step, and an `excite` level every event can raise.
+
+```ts
+import * as THREE from 'three';
+
+/** A stand of people: one instanced quad per person, facing the camera, bobbing by excitement. */
+export class Crowd {
+  mesh: THREE.InstancedMesh;
+  excitement = 0.1;            // 0 idle … 1 on their feet; decays back to `idle`
+  idle = 0.1;
+  private base: THREE.Vector3[] = [];
+  private phase: number[] = [];
+  private m = new THREE.Matrix4(); private q = new THREE.Quaternion(); private s = new THREE.Vector3(1, 1, 1); private v = new THREE.Vector3();
+  constructor(sheet: THREE.Texture, rows: number, perRow: number, origin: THREE.Vector3, rowStep = new THREE.Vector3(0, 0.6, -0.9), seatStep = new THREE.Vector3(0.7, 0, 0)) {
+    const geo = new THREE.PlaneGeometry(0.6, 1.1);
+    geo.translate(0, 0.55, 0);                              // feet on the seat
+    const mat = new THREE.MeshBasicMaterial({ map: sheet, transparent: true, alphaTest: 0.5 });
+    this.mesh = new THREE.InstancedMesh(geo, mat, rows * perRow);
+    this.mesh.name = 'crowd';
+    const colors = [0xe85d4a, 0x3d7bd9, 0xf2c94c, 0x5cb85c, 0xf5f0e6];
+    let i = 0;
+    for (let r = 0; r < rows; r++) for (let c = 0; c < perRow; c++, i++) {
+      this.base.push(origin.clone().addScaledVector(rowStep, r).addScaledVector(seatStep, c + (r % 2) * 0.35));
+      this.phase.push(Math.random() * Math.PI * 2);
+      this.mesh.setColorAt(i, new THREE.Color(colors[(i * 7) % colors.length]));
+    }
+  }
+  /** Raise the crowd (a pass, a goal, the finish). Takes the higher of now and `level`. */
+  excite(level: number) { this.excitement = Math.max(this.excitement, level); }
+  update(t: number, dt: number, camera: THREE.Camera) {
+    this.excitement += (this.idle - this.excitement) * Math.min(1, dt * 0.8);   // settles over ~2 s
+    const hop = 0.02 + this.excitement * 0.35, rate = 2 + this.excitement * 8;
+    for (let i = 0; i < this.base.length; i++) {
+      const p = this.base[i];
+      const y = Math.max(0, Math.sin(t * rate + this.phase[i])) * hop;
+      this.q.copy(camera.quaternion);                         // billboard: face the camera
+      this.m.compose(this.v.set(p.x, p.y + y, p.z), this.q, this.s);
+      this.mesh.setMatrixAt(i, this.m);
+    }
+    this.mesh.instanceMatrix.needsUpdate = true;
+  }
+}
+```
+
+With a sheet of poses, pick the frame per person by offsetting UVs in a small `onBeforeCompile`, or
+build two meshes (sitting, arms up) and swap visibility above an excitement of 0.6. Far stands can
+be a single textured strip with a vertex wobble; only the near ones need people.
+
+Flags and banners: a plane with 8×2 segments whose vertices move by `sin(x * 3 + t * 6) * x * 0.1`
+each frame, or a sprite sheet of four frames. One colour per team or rival reads at phone size.
+
+## A crowd that reacts (Pixi)
+
+```ts
+import { Container, Sprite, Texture } from 'pixi.js';
+
+/** A row of spectators behind the track: sprites with their own phase, hopping by excitement. */
+export function crowdRow(textures: Texture[], count: number, width: number, baseY: number) {
+  const row = new Container({ label: 'crowd' });
+  const people = Array.from({ length: count }, (_, i) => {
+    const s = new Sprite(textures[i % textures.length]);
+    s.anchor.set(0.5, 1); s.x = (i + 0.5) * (width / count); s.y = baseY;
+    s.tint = [0xffffff, 0xffd9c2, 0xc2d9ff, 0xfff0a0][(i * 5) % 4];
+    row.addChild(s);
+    return { s, phase: Math.random() * Math.PI * 2 };
+  });
+  let excitement = 0.1;
+  return {
+    row,
+    excite(level: number) { excitement = Math.max(excitement, level); },
+    update(t: number, dt: number) {
+      excitement += (0.1 - excitement) * Math.min(1, dt * 0.8);
+      for (const p of people) p.s.y = baseY - Math.max(0, Math.sin(t * (2 + excitement * 8) + p.phase)) * (1 + excitement * 14);
+    },
+  };
+}
+```
+
+## One bed, swelled and ducked (Web Audio)
+
+One looped crowd bed plus a handful of stings covers a whole race. The bed's gain is the crowd's
+mood: it follows the nearest stand by distance, drops for the countdown, and jumps on a moment.
+Stings duck the music a little so they are heard.
+
+```ts
+/** The crowd's sound: a looped bed whose level follows events, and stings over it. */
+export class CrowdSound {
+  private bed: GainNode; private src?: AudioBufferSourceNode;
+  private level = 0.25; private target = 0.25;
+  constructor(private ctx: AudioContext, private out: AudioNode, private music?: GainNode) {
+    this.bed = ctx.createGain(); this.bed.gain.value = 0; this.bed.connect(out);
+  }
+  start(bedBuffer: AudioBuffer) {
+    this.src = this.ctx.createBufferSource();
+    this.src.buffer = bedBuffer; this.src.loop = true; this.src.connect(this.bed); this.src.start();
+  }
+  /** 0 silent … 1 roaring. Eases there over `secs`. */
+  set(level: number, secs = 0.8) {
+    this.target = level;
+    this.bed.gain.setTargetAtTime(level, this.ctx.currentTime, secs / 3);
+  }
+  /** A burst above the current level that falls back (a pass, a boost, a goal). */
+  swell(peak = 0.9, holdSecs = 1.2) {
+    const t = this.ctx.currentTime, g = this.bed.gain;
+    g.cancelScheduledValues(t); g.setTargetAtTime(peak, t, 0.08); g.setTargetAtTime(this.target, t + holdSecs, 0.6);
+  }
+  /** The hush before a start: the bed nearly out, then back with a cheer on GO. */
+  hush(secs = 0.6) { this.set(0.05, secs); }
+  /** A one-shot over the bed; the music dips under it and comes back. */
+  sting(buffer: AudioBuffer, gain = 1) {
+    const s = this.ctx.createBufferSource(), g = this.ctx.createGain();
+    s.buffer = buffer; g.gain.value = gain; s.connect(g).connect(this.out); s.start();
+    if (this.music) {
+      const t = this.ctx.currentTime, m = this.music.gain, was = m.value;
+      m.cancelScheduledValues(t); m.setTargetAtTime(was * 0.5, t, 0.05); m.setTargetAtTime(was, t + buffer.duration * 0.8, 0.4);
+    }
+  }
+}
+
+// Wiring for a race (numbers are a start, tune by ear):
+// each frame:  crowdSound.set(0.2 + 0.6 * Math.max(0, 1 - distToNearestStand / 40), 0.4);
+// countdown:   crowdSound.hush(); on GO: crowdSound.swell(1, 1.5); crowd.excite(1);
+// overtake:    crowdSound.swell(0.85); crowd.excite(0.7); __FPX_MOMENT__?.('overtake', 2);
+// crash:       crowdSound.sting(gasp); crowd.excite(0.5);
+// finish:      crowdSound.swell(1, 3); crowdSound.sting(finishCheer); crowd.excite(1); confetti();
+```
+
+Sounds to make with `generate_sound` (2 credits each): "a large stadium crowd murmuring, distant,
+steady, no announcer" with `loop: true`; "a crowd cheer rising and falling, 2 seconds"; "a crowd
+gasp, short"; "a crowd roar with whistles and applause, 4 seconds"; for horror, "a distant metal
+door creak in a large empty building". Keep the prompts free of words the model reads as music.
+The audio skill (`fp:audio`) has the mastering, loudness and loop rules; its adaptive-music
+reference has the duck and the stinger on the bar line.
+
+## The finish, the goal, the curtain: a set piece
+
+The end of a race or a round is the moment players remember, so stage it like the title:
+
+1. Slow the world for a beat (time scale 0.3 for 0.4 s) as the line is crossed.
+2. The crowd at its loudest, a sting, the stand on its feet.
+3. Light: flashbulbs (small white sprites flickering at random in the stands for 1.5 s), a burst of
+   confetti in the team colours, fireworks at night (particles: skill `fp:art`).
+4. Someone says something: the announcer ("And it's the blue boat by a nose!"), a rival's line, the
+   coach. One line, on screen and voiced if you have voice (see [voice.md](voice.md)).
+5. Then the result card over the still-cheering world, not over a black screen.
+
+Record the moment for the looks: `window.__FPX_MOMENT__?.('finish', 3)` at the instant the crowd
+erupts, and declare the view `moment: true` so capture shoots it as a burst.
+
+## Horror: absence as atmosphere
+
+Horror inverts the pattern: the world reacts by going quiet. Keep the bed low and let it drop out
+entirely about a second before a threat appears, so the silence is the warning. Space distant
+sounds unevenly (8–25 s apart, never on a timer the player can learn), pan them, and put one
+sound close and behind at the worst moment. One horror game's hum rising under the last recorder line is
+the model: the world answers the story, not the player's score.
+
+## Budget and cost
+
+- A stand of 400 instanced cards: one draw call; the per-frame matrix loop is under 0.2 ms on a
+  phone for that count. Past a few thousand people, move the bob into the vertex shader.
+- Update far crowds at half rate, and hide them when the camera is past them.
+- One bed and four stings is about 10 credits of sound for a whole game.
+- Check it with `npx @funpixel/tools profile --views <race>` before and after the crowd.
+
+## Hooks so a mirror can see it
+
+- Name the nodes (`crowd`, `flag`, `bird`, `passerby`): `funtools life` counts what moves that is
+  not the player, whether a bed loops, and whether anything answered your moment marks. It warns
+  when a great moment passes with nothing reacting; it never blocks.
+- Expose the mood in `__FPX_STATE__` (`crowd: 0.85`) so a play log shows the swell.
+- Declare the set piece as a view with `moment: true`.
+- The blind player and the experience seats score "world"; ask them what the place felt like.

package/plugins/robin/claude/skills/world-and-story/references/forged-world.md

@@ -0,0 +1,79 @@
+# A world forged as data
+
+For a game with several rooms or areas: a dungeon, a valley of districts, a run of chapters. One
+arena needs none of this. `world forge` drafts the place as data the game loads; it is a first
+draft you reshape, never an engine that owns the game, and it only uses the prop kinds the game
+names (or plain roles), so two games forged from two briefs do not look alike.
+
+## 1. Declare what the place is made of
+
+The forger reads the design document (or `--from brief.json`):
+
+- `## Places`: one row per chapter. The first column names it; a `Landmark` column gives the
+  thing each chapter is seen by.
+- `**Kit:** pine (cover), boulder (cover), lamp (light), bell tower (landmark), fern` — the
+  game's own kinds, each with a role. `cover` blocks and shelters, `landmark` is seen from afar
+  and blocks, `light` is a light source, `dressing` never collides, `marker` points the way. A
+  kind with no role is dressing.
+- `**Palette:** #1b2a4a, #e8b04a` — the first colour sets the fog, the second the sky.
+
+A JSON brief says the same: `{ "kind": "3d", "rooms": 8, "chapters": [{ "name": "Low Road",
+"landmark": "the bell tower" }], "props": ["fern", { "kind": "lamp", "role": "light" }],
+"palette": ["#1b2a4a"], "shapes": ["basin"], "step": 0.5 }`.
+
+## 2. Forge, and compare seeds before you keep one
+
+```
+npx @funpixel/tools world forge --seed 7            # 2D or 3D from funpixel.json; --kind to choose
+npx @funpixel/tools world forge --variety 8 --seed 1 # eight seeds side by side, nothing written
+```
+
+The same seed and brief give the same file. Each seed draws its own grammar: which room shapes the
+world leans on (halls, pillars, caves, crosses, split rooms, rings; or rolling, terraced, basin,
+ridge, plateau, dune ground in 3D), how dense, how branchy, how many loops, how far the light turns
+between chapters. `--variety` scores how far apart the seeds are and names near-twins; pick the
+seed that fits the game, not the first one.
+
+## 3. Reshape it, then check it
+
+Edit tiles, move props, rename rooms. A file changed by hand is kept: forge refuses to write over
+it without `--force`. After every edit, `npx @funpixel/tools world check`: every door is a door on
+both sides, each room's doors, goal and places are reached from its arrival (3D: no rise between
+cells over `movement.step`, solid props closed), every room is reached through the doors, and the
+instance and draw-call budgets hold. Exit 1 names the room and the cell.
+
+The check proves the data. Only play proves the game reads it: build collisions from the same
+tiles and heights you draw, never a copy kept in sync by hand, then `verify` and `walk`.
+
+## 4. Load it
+
+The starter's `src/world.ts` reads it with no engine:
+
+```ts
+import { loadWorld, room, eachTile, heightAt, place, lightOf, through } from './world';
+const world = loadWorld(import.meta.glob('../design/world/**/*.json', { eager: true, import: 'default' }))!;
+let here = room(world, world.critical_path[0]);
+// Pixi: one sprite per wall tile, the arrival as the spawn
+eachTile(here, (x, y, kind) => { if (kind === 'solid') walls.addChild(wall(x * TILE, y * TILE)); });
+// Three: ground vertices from the heightfield, props from the game's own models
+const y = heightAt(here, px, pz, world.cell);
+for (const i of here.instances) spawn(i.kind, i.pos, i.rot, i.scale);
+const light = lightOf(world, here);   // fog, light, sky and ambient for this room
+// A door the player walks through
+here = through(world, here, doorId) ?? here;
+```
+
+A missing room or place warns with the names that exist and falls back (the first room, the
+arrival), so a typo never throws while loading and never drops the player at the origin.
+
+## 5. Use the places
+
+- `arrival`: where the player enters (the door they came through, or the start).
+- `goal`: the last room of the critical path.
+- `reward`: the payoff of a side or secret room; make it worth the detour.
+- `vista`: the highest spot the player can stand on in a 3D room; a camera beat or a lookout.
+- `landmark`: the chapter's landmark, for the waypoint arrow and the distance in the HUD.
+
+Each room's `atmosphere` holds only what differs from the world's: a later chapter turns the sky,
+a secret room is dimmer, the goal room warmer. The forger keeps an ambient floor; keep it when you
+tune by hand, because a black room is unreadable, not moody.

package/plugins/robin/claude/skills/world-and-story/references/living-world.md

@@ -0,0 +1,237 @@
+# A living world: people, creatures and a place that moves
+
+The owner's verdict after three rounds of one game built two ways (Oct 2026): "both
+did nice work, some in environment, some in dynamics... models static, NPCs static: it has to be a
+living environment." The build that lost on dynamics had 28 townsfolk animated in place (none
+walked anywhere), kites that slid, a still hound and one person standing inside a container. The
+build that won on dynamics had rigged townsfolk walking task routes, seven of eleven turning to the
+hero, creatures with gaits; and it lost points because every townsperson wore the hero's face.
+Round 4, by eye: "the crowd must be fewer and focused; placements and spacing", flat-colour
+container boxes beside one painted building, and the landed ship hovering over a cliff.
+
+This is the bar for any scale and engine, from a Pixi village to a Three harbour. Pick what fits;
+a one-screen arcade game may want only the last section.
+
+## The bar, per thing that lives
+
+| who | body | moves through space | idle | answers the player |
+|---|---|---|---|---|
+| a person | a rig, sheet frames or cut-out parts that animate | a task loop between places (haul, patrol, errand, sweep, chat) | breathing, weight shift, a look round | head turn, a wave, steps aside, stops to let them by |
+| a scene of people | one rig or sheet shared, looks varied per person | within the scene: haul, serve, mend | each a different idle phase | the nearest notice; a cheer or hush at big moments |
+| a walking creature | a gait (legs or frames, the `quadruped` preset in `src/motion.ts`) whose rate follows ground speed | wander, graze, patrol a home range | sniff, scratch, sit | flee, follow, or watch, with hysteresis |
+| a flyer | wings that flap, a body that banks into turns | loops, perches, flocks | a perch with a ruffle or preen | scatter when approached, circle what matters |
+| the place | cloth and plants in wind, dust, water, smoke | machines working (cranes, carts, wheels, mills) | lights that breathe, flicker or sweep | lamps that light, doors that open, birds that lift as the hero passes |
+
+The tests that matter: nothing slides like a stone (motion with nothing inside it changing), no
+crowd that only animates in place, no person wearing the hero's face, no flyer gliding without a
+flap, feet on the ground, and one scale (a person 1.55–1.90 m beside a 1.75 m hero).
+
+## A few scenes, not a crowd
+
+Fewer people, each one readable. Place a handful of scenes along the player's path, each with
+one purpose a player gets at a glance (two haulers at a crane, a vendor and a buyer at a stall, a
+mender at a net), spaced so each reads on its own and the next comes into view as the last one
+leaves. Inside a scene people stand close; between scenes, leave air. Density follows the budget and
+the genre, never "many people": a quiet walk 3 to 6 people, a town street 6 to 12 in 3 to 5 scenes,
+a festival more, still grouped. Plan the number in `funpixel.json` (`"walk": { "crowd": { "people":
+[6, 10] } }`) and mark each person's scene in the actors contract (`scene: "crane"`). `walk` warns
+on clumps (people within 1.5 m with no shared scene), empty stretches of the path (40 m with nobody
+in view) and a count beyond the plan.
+
+## Made, not boxes
+
+The camera's nearest geometry is the most detailed, never the plainest. Every structure the player
+passes reads as made: shape detail (bevels, ribs, doors, rails, roof clutter) and a texture or
+decals in the palette, matched to the best-painted asset in the scene. A flat-colour box beside a
+painted building reads as unfinished, and so do big flat facets filling the foreground; give them
+the same hand (bake the painted look into a texture, trim the silhouette, break the faces). Landed
+vehicles and big props rest on the ground under their whole footprint: read the terrain height at
+their legs or corners, keep them off an edge, and mark what flies `flying: true` and what is landed
+`landed: true` in the actors contract. `npx @funpixel/tools boxes` names what reads unfinished and
+what is off the ground in a view; `walk` checks both along its routes.
+
+## Placement and scale first
+
+Place every actor from the ground height at its feet, never a fixed `y`; test the spawn against the
+props' footprints and push it clear (a person inside a container reads as a bug before it reads as a
+person). Keep a scale sheet in metres in `funpixel.json` (`"scale": { "person": 1.75, "crate": 0.8 }`)
+and size every model from it. Paths for task loops run on walkable ground, around props, with the
+ends at places that explain the job (the stack and the cart, the stall and the well).
+
+## Technique 1: rig clones with clip sets (Three)
+
+One rigged body, cloned per person with `SkeletonUtils.clone` (bones are not shared, geometry is),
+an `AnimationMixer` each, every clip playing at weight 0 and blended by speed and job. The walk's
+rate follows ground speed so feet do not skate. The job is laid on top, bone by bone, after the
+mixer runs. Recolour per person; swap the face and hair: a crowd of the hero's clones is the
+mistake the winning build made.
+
+```ts
+import { clone } from 'three/examples/jsm/utils/SkeletonUtils.js';
+const WALK_SPEED = 1.45; // m/s the walk clip was authored at
+
+function makePerson(gltf, look, rng) {
+  const body = clone(gltf.scene);
+  body.traverse((o) => {
+    if (!o.isMesh) return;
+    o.frustumCulled = false; // a skinned mesh's box is its bind pose
+    o.material = o.material.clone();
+    if (o.name === 'Face') o.material.map = look.faceMap;   // a face pool, never the hero's
+    if (o.name === 'Hair') o.visible = look.hair === o.userData.style;
+    if (o.material.color) o.material.color.offsetHSL(look.hue, look.sat, look.light);
+  });
+  const root = new THREE.Group(); root.add(body);
+  root.scale.setScalar(look.height / 1.75);                  // 1.55–1.90 m
+  const mixer = new THREE.AnimationMixer(body);
+  const act = Object.fromEntries(gltf.animations.map((c) => {
+    const a = mixer.clipAction(c); a.play(); a.setEffectiveWeight(0);
+    a.time = rng() * c.duration;                              // no two in step
+    return [c.name, a];
+  }));
+  return { root, mixer, act, weights: {} };
+}
+
+function animate(p, speed, job, dt) {
+  const want = speed > 0.05 ? { walk: Math.min(1, speed / 0.5), idle: 1 - Math.min(1, speed / 0.5) } : { [job.idle]: 1 };
+  for (const [name, a] of Object.entries(p.act)) {
+    const w = (p.weights[name] ?? 0) + ((want[name] ?? 0) - (p.weights[name] ?? 0)) * Math.min(1, dt * 6);
+    p.weights[name] = w; a.setEffectiveWeight(w);
+  }
+  p.act.walk?.setEffectiveTimeScale(Math.max(0.3, speed / (WALK_SPEED * p.root.scale.y)));
+  p.mixer.update(dt);
+}
+```
+
+No rig? `generate_3d_model` with animation gives a rigged body with walk and idle; the character
+library (`npx @funpixel/tools character`) has animated masters to restyle. A 2D game gets the same
+from a sheet with idle and walk cycles per look (`generate_spritesheet`).
+
+## Technique 2: a task loop that moves them through space
+
+A small state machine per person: go to the next point, do the job there for a while, go on. The
+same loop drives a creature's home range. Yield to the player and turn the head toward them.
+
+```ts
+type Task = { kind: 'haul' | 'patrol' | 'errand' | 'chat'; path: [number, number][]; wait: [number, number] };
+
+function stepPerson(p, task, hero, world, dt) {
+  if (p.wait > 0) { p.wait -= dt; p.speed = 0; }
+  else {
+    const [gx, gz] = task.path[p.wp];
+    const dx = gx - p.x, dz = gz - p.z, d = Math.hypot(dx, dz);
+    if (d < 0.3) { p.wp = (p.wp + 1) % task.path.length; p.wait = lerp(task.wait[0], task.wait[1], p.rng()); p.carrying = !p.carrying; }
+    else {
+      p.yaw = turnToward(p.yaw, Math.atan2(dx, dz), dt * 5);
+      p.speed += ((task.kind === 'errand' ? 2.2 : 1.2) - p.speed) * Math.min(1, dt * 4);
+    }
+  }
+  const toHero = Math.hypot(hero.x - p.x, hero.z - p.z);
+  const ahead = (hero.x - p.x) * Math.sin(p.yaw) + (hero.z - p.z) * Math.cos(p.yaw);
+  if (toHero < 2.2 && ahead > 0) p.speed = 0;                 // let them by
+  p.look = toHero < 9 ? angleTo(p, hero) : 0;                 // the head follows the hero
+  if (toHero < 6 && !p.waved) { p.waved = true; p.reacting = 'wave'; }
+  const nx = p.x + Math.sin(p.yaw) * p.speed * dt, nz = p.z + Math.cos(p.yaw) * p.speed * dt;
+  [p.x, p.z] = world.pushOutOfSolids(nx, nz, 0.3);          // never through a crate or a wall
+  p.y = world.groundAt(p.x, p.z);
+}
+```
+
+Give the loop's end points a reason a player can read: a crate appears on the cart, the lamp
+lights, the stall's shutter goes up.
+
+## Technique 3: an instanced gait in the shader
+
+For dozens of creatures or far crowds, one `InstancedMesh` of cut-out cards (or low meshes) and a
+per-instance attribute: gait phase, gait amount (0 still to 1 full stride), breath offset, reaction.
+The vertex shader swings the lower part of the card as legs, bobs the body twice a cycle and
+breathes when still; flyers flap by distance from the body's centre line.
+
+```ts
+mesh.geometry.setAttribute('aAnim', new THREE.InstancedBufferAttribute(new Float32Array(count * 4), 4));
+material.onBeforeCompile = (sh) => {
+  sh.uniforms.uTime = shared.time;
+  sh.vertexShader = 'attribute vec4 aAnim; uniform float uTime;\n' + sh.vertexShader.replace('#include <begin_vertex>', `
+    vec3 transformed = position;
+    float h = uv.y, amt = aAnim.y, ph = aAnim.x;
+    float side = step(0.5, uv.x) * 2.0 - 1.0;
+    float leg = 1.0 - smoothstep(0.0, 0.45, h);                          // the bottom 45% swings
+    transformed.x += leg * 0.12 * amt * sin(ph + side * 3.14159);
+    transformed.y += 0.04 * amt * abs(sin(ph)) * h;                      // two bobs a stride
+    transformed.y += 0.012 * sin(uTime * 2.2 + aAnim.z) * (1.0 - amt) * h; // breath when still
+    #ifdef FLYER
+      transformed.y += 0.25 * abs(position.x) * sin(uTime * 14.0 + ph); // wings flap
+    #endif`);
+};
+// each frame, per instance: phase advances with distance walked, so the stride matches the ground
+anim[i * 4] += speed * dt / strideLength * Math.PI * 2;
+anim[i * 4 + 1] = Math.min(1, speed / 0.3);
+mesh.geometry.attributes.aAnim.needsUpdate = true;
+```
+
+## Technique 4: painted cut-outs that animate (Pixi, and billboards in Three)
+
+A picture moved is motion, not animation: a crab sprite slid along the ground, a goat card that bobs
+or flips, a kite that drifts and pulses its opacity all read as stones (a fresh build of that game, 3 Oct).
+A cut-out lives by one of four means. **Frames by distance:** a walker gets 6+ frames, the hero
+8–12 (contact, down, passing, up for each foot), and the frame advances by ground covered, one
+cycle per about 0.8 body heights (1.4 m at 1.75 m), so it never treadmills when standing or skates
+when fast. **A bent plane:** in the vertex shader, sway by height (top moves, feet pinned), squash
+2–4% on each footfall, breathing at rest; declare `deform: true` in the actors contract, since the
+scene cannot show a shader. **Hinged parts:** head, torso, arms and legs in a container, each pivoted
+at its joint, legs and arms in opposition, the torso dipping twice a stride. **Flap cycles:** 4–8
+frames or two hinged wings. Cut-outs turn to the camera on the vertical axis only, and mirror only
+when their heading changes side. Pixi's `AnimatedSprite` works when `animationSpeed` follows ground speed.
+
+## Technique 5: flyers and reactions
+
+A flyer flaps (frames, bones, or the shader above), banks into each turn (roll by the turn rate,
+clamped near 35 degrees), dips its nose to descend, and glides between flaps. Reactions are a
+distance with hysteresis so nothing flickers: a crab scatters under 7 m and calms after 12; a goat
+herd drifts away under 20 m; a dog follows within 4 m and sits when the hero stops; a bird lifts
+when the hero comes within 5 m and lands somewhere else. Mark flyers `flying: true` in the actors
+contract so the checks read them as flying, not floating.
+
+```ts
+const turn = wrapAngle(b.heading - b.lastHeading) / dt;
+b.roll += (clamp(-turn * 0.35, -0.6, 0.6) - b.roll) * Math.min(1, dt * 4);
+b.mesh.rotation.set(b.pitch, b.heading, b.roll);
+```
+
+## Technique 6: the place moves
+
+- Wind: one shared `uWind` uniform bends grass, flags, washing lines and tree tops by height
+  (`h * h * sin(time + worldX)`), gusting every few seconds; the sound bed swells with it.
+- Machines work: a crane's arm swings a load on a loop, a cart rolls its route, a mill turns.
+- Light breathes: lamps flicker a few percent, a lighthouse sweeps, windows light at dusk.
+- Water: two scrolling normal maps and a foam line; boats bob by a sum of sines.
+- Sky life: clouds drift, a flock crosses every 20–40 s, distant smoke rises.
+- Dust and motes: a few hundred points drifting downwind near the camera.
+
+## Technique 7: level of detail for life
+
+| distance | people and creatures | update |
+|---|---|---|
+| near (under 25 m) | full rig, clips blended, the job on top, reactions | every frame |
+| middle (25–80 m) | instanced gait cards, task loop on a coarse path | every 2nd–4th frame |
+| far (beyond 80 m) | instanced cards with an idle sway, or hidden | every 10th frame |
+
+Swap tiers with a little hysteresis and keep each actor's phase across the swap so nobody hitches.
+Budget: 12 to 20 full rigs on a phone is a ceiling, not a target; far life can be instanced cards.
+
+## Variety within the few
+
+Per person draw from pools, seeded so the town is the same every run: face (4 to 8 textures or
+painted faces, none the hero's), hair (styles and colours), clothes (tint the outfit by a palette
+from the style block), height 1.55–1.90 m, build (scale x 0.92–1.08), and the idle's phase and
+speed. The hero stays the one person drawn only once.
+
+## Proving it
+
+Expose `window.__FPX_ACTORS__()` with each person, creature and machine (positions, `task`,
+`state`, `reacting`, `scene`, `flying`, the scene `node`): skill fp:verifying, references/actors.md.
+Then `npx @funpixel/tools life` reads one view (animated vs slides like a stone, cut-outs that glide
+or sit on a stick, in place vs moving
+through space, the hero's body or face on a crowd — by content, so loading the hero's file again
+for the crowd still counts — flyers without a flap, reactions) and
+`npx @funpixel/tools walk` plays the routes from the title and says the same along the way, with a
+film per route, and judges the hero's walk while it moves (frames a cycle, a treadmill, frames on a timer). A warning names what to change; none of it blocks.