@funpixel/tools 0.0.0-stage → 0.1.1

package/plugins/codex/skills/funpixel-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 funpixel-verify, 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.

package/plugins/codex/skills/funpixel-world-and-story/references/opening-and-chapters.md

@@ -0,0 +1,215 @@
+# The opening, chapters, objectives and text beats
+
+Working code, checked in a scratch scaffold (pixi.js 8.21, three 0.170; captured at 844×390 with
+the waypoint, title and text beat on screen). Engine-free apart from one projection line.
+
+## An opening, beat by beat
+
+| Beat | Length | Built from | Notes |
+|---|---|---|---|
+| Title | until tapped | DOM over live key art or the running world | name, a 5–10 word promise, one button (`data-fpx-start`), a sound line; the world moving behind it is the trailer |
+| A beat | 3–8 s, skippable | a camera pan or zoom plus `say()` | show the want (someone needs help, the lights went out); one or two lines |
+| First control | as long as it takes | the space itself | a corridor that only goes one way, a gap you must jump, a lamp beside the path |
+| First objective | stays on screen | the HUD line + `waypoint()` | the chapter number and title (`01 / THE LAST LIGHT`) over the goal in words; the marker and a distance in the world |
+| First payoff | inside a minute | the objective completing | the world changes (a light comes on), a sound and a musical turn |
+
+Keep the camera inside the world during a pan (overscan the dressing by the pan distance) or the
+background shows at the edge. Let a returning player skip to control: store `seenOpening` with
+`@funpixel/sdk/save`.
+
+## Story, waypoint and text beats
+
+A mid or deep game already keeps its rooms and chapters as data the starter runs (`design/spec/rooms.json`
+and `src/chapters.ts`, from `funtools spec init`; skill `funpixel-gdd`, references/spec-folder.md). The
+story layer below sits on top of them: objectives and beats inside a room.
+
+```ts
+// Chapters and objectives as data, a waypoint that points at the current goal, and a text beat.
+// Engine-free except the waypoint's projection, which the game passes in.
+
+export interface Objective { id: string; text: string; target?: { x: number; y: number; z?: number }; done: () => boolean }
+export interface Chapter { id: string; number: number; title: string; objectives: Objective[]; enter?: () => void }
+
+/** Walks the chapters in order; `update()` each frame advances when the current objective is done. */
+export class Story {
+  chapter = 0; step = 0;
+  onObjective: (o: Objective, c: Chapter) => void = () => {};
+  onChapter: (c: Chapter) => void = () => {};
+  onEnd: () => void = () => {};
+  constructor(readonly chapters: Chapter[]) {}
+  get current(): { chapter: Chapter; objective: Objective } | null {
+    const c = this.chapters[this.chapter];
+    return c && c.objectives[this.step] ? { chapter: c, objective: c.objectives[this.step] } : null;
+  }
+  start(chapter = 0, step = 0) {
+    this.chapter = chapter; this.step = step;
+    const c = this.chapters[chapter];
+    c.enter?.(); this.onChapter(c); this.onObjective(c.objectives[step], c);
+  }
+  update() {
+    const cur = this.current;
+    if (!cur || !cur.objective.done()) return;
+    this.step++;
+    if (this.step < cur.chapter.objectives.length) { this.onObjective(cur.chapter.objectives[this.step], cur.chapter); return; }
+    this.step = 0; this.chapter++;
+    if (this.chapter >= this.chapters.length) { this.onEnd(); return; }
+    this.start(this.chapter, 0);
+  }
+}
+
+/**
+ * The waypoint: a DOM marker over the goal when it is on screen, an edge arrow with the distance
+ * when it is not. `project` maps the goal to CSS pixels (Pixi: container.toGlobal; Three:
+ * vector.project(camera) then to pixels) and says whether it is in front of the camera.
+ */
+export function waypoint(host: HTMLElement) {
+  const el = document.createElement('div');
+  el.className = 'waypoint';
+  el.innerHTML = '<svg viewBox="0 0 24 24" width="28" height="28" aria-hidden="true"><path d="M12 2 22 12 12 22 2 12Z" fill="none" stroke="currentColor" stroke-width="2.5"/></svg><span></span>';
+  Object.assign(el.style, { position: 'absolute', left: '0', top: '0', color: '#fff6d8', font: '600 13px system-ui', textShadow: '0 1px 3px #0009', pointerEvents: 'none', display: 'flex', flexDirection: 'column', alignItems: 'center', gap: '2px', willChange: 'transform' });
+  host.appendChild(el);
+  const label = el.querySelector('span')!;
+  return {
+    el,
+    /** p: the goal in CSS px; metres: the distance to show; margin keeps the arrow off the notch and thumbs. */
+    update(p: { x: number; y: number; inFront: boolean } | null, metres: number, margin = 56) {
+      if (!p) { el.style.display = 'none'; return; }
+      el.style.display = 'flex';
+      const w = host.clientWidth, h = host.clientHeight, cx = w / 2, cy = h / 2;
+      let x = p.x, y = p.y, onScreen = p.inFront && x > margin && x < w - margin && y > margin && y < h - margin;
+      if (!onScreen) {
+        let dx = x - cx, dy = y - cy;
+        if (!p.inFront) { dx = -dx; dy = -dy; }                   // behind the camera: point the other way
+        const k = Math.min((w / 2 - margin) / Math.abs(dx || 1e-6), (h / 2 - margin) / Math.abs(dy || 1e-6));
+        x = cx + dx * k; y = cy + dy * k;
+      }
+      el.style.transform = 'translate(' + x + 'px, ' + y + 'px) translate(-50%, -50%)';
+      el.style.opacity = onScreen ? '1' : '0.85';
+      label.textContent = Math.round(metres) + ' m';
+    },
+  };
+}
+
+/**
+ * One line of text at a time, typed at `cps`, tap or key to finish the line, again to go on.
+ * Resolves when the last line is dismissed. aria-live so a screen reader hears it.
+ */
+export function say(host: HTMLElement, lines: Array<{ who?: string; text: string }>, cps = 45): Promise<void> {
+  const box = document.createElement('div');
+  box.className = 'beat';
+  box.setAttribute('aria-live', 'polite');
+  Object.assign(box.style, { position: 'absolute', left: '50%', bottom: 'max(24px, env(safe-area-inset-bottom))', transform: 'translateX(-50%)', maxWidth: 'min(640px, 88vw)', padding: '12px 18px', background: 'rgba(12,14,24,0.72)', color: '#f5efe2', borderRadius: '12px', font: '500 17px/1.4 Georgia, serif', textAlign: 'center' });
+  host.appendChild(box);
+  return new Promise((done) => {
+    let i = 0, shown = 0, timer = 0;
+    const render = () => {
+      const l = lines[i];
+      box.innerHTML = (l.who ? '<div style="font:700 12px system-ui;letter-spacing:.12em;opacity:.7;text-transform:uppercase">' + l.who + '</div>' : '')
+        + '<div>' + l.text.slice(0, shown) + '</div>'
+        + '<div style="font:600 11px system-ui;opacity:' + (shown >= l.text.length ? 0.6 : 0) + '">tap to continue</div>';
+    };
+    const tick = () => { shown = Math.min(lines[i].text.length, shown + 1); render(); if (shown < lines[i].text.length) timer = window.setTimeout(tick, 1000 / cps); };
+    const next = (e: Event) => {
+      e.preventDefault();
+      if (shown < lines[i].text.length) { clearTimeout(timer); shown = lines[i].text.length; render(); return; }
+      if (++i >= lines.length) { removeEventListener('pointerup', next); removeEventListener('keydown', next); box.remove(); done(); return; }
+      shown = 0; tick();
+    };
+    addEventListener('pointerup', next); addEventListener('keydown', next);
+    tick();
+  });
+}
+```
+
+Pixi: project the goal with the world container, `const p = world.toGlobal(goal)`, then
+`wp.update({ x: p.x, y: p.y, inFront: true }, metres)`. Three:
+
+```ts
+const v = goal.clone().project(camera);        // normalised device coordinates
+const inFront = v.z < 1;                       // behind the camera, project() mirrors the point
+wp.update({ x: (v.x + 1) / 2 * host.clientWidth, y: (1 - v.y) / 2 * host.clientHeight, inFront }, camera.position.distanceTo(goal));
+```
+
+Wiring a chapter:
+
+```ts
+const story = new Story([
+  { id: 'c1', number: 1, title: 'The Last Light', objectives: [
+    { id: 'lamp', text: 'Light the lamp by the gate', target: gateLamp, done: () => state.lit.has('gate') },
+    { id: 'tower', text: 'Reach the tower', target: tower, done: () => dist(hero, tower) < 2 },
+  ] },
+]);
+story.onChapter = (c) => showChapterCard('0' + c.number + ' / ' + c.title.toUpperCase());
+story.onObjective = (o) => { hud.goal = o.text; goal = o.target ?? null; save.update({ chapter: story.chapter, step: story.step }); };
+story.start(save.data.chapter ?? 0, save.data.step ?? 0);
+// each frame: story.update();
+```
+
+## Text beats
+
+- `say(host, lines)` types at 45 characters a second; a tap finishes the line, the next tap moves on.
+  Put it in the bottom third, clear of the on-screen controls, or pause play while it shows.
+- A speaker name in small caps above the line, a portrait if you have one. One line at a time.
+- A line the player needs (the goal) goes into the HUD as well; a line that is flavour can
+  play while the player moves.
+- Voice: short lines through `generate_sound` read poorly; if a voice matters, a few words of
+  murmur or a pitched blip per character (Celeste, Animal Crossing) carry emotion cheaply.
+
+## A radio, placed rather than narrated
+
+One three.js horror game (29 Sep 2026) told its story through two sources with different
+voices, both in the world: the station speaks only in readouts (who is behind a door, open water,
+lift power, the nearest dead relay when she is lost), and a recorder plays fragments of the crew's
+last night, timestamped, with the enemies' hum rising under them until the last line ends in
+humming. What made it work, as options:
+
+- Lines fire by room and by what the player has done, not on a timer, so each one comments on
+  something just seen.
+- A line waits out fights, full-screen cards and pause, and does not start while a tutorial
+  caption or a new-tool card is being read (a line already playing goes on). On a phone, those
+  three up at once were a third of the HUD it measured.
+- One voice outranks the rest: nothing talks over the daughter's messages down the line.
+- Ten voiced lines were enough for a chapter; logs stay re-readable from pause.
+- The mix sells the source: band-limited, driven like a small speaker, a little line noise (skill
+  `funpixel-audio`, adaptive-music).
+
+Explain a strange number or name once, where it first appears. "Nkem is 8" was shown twice and
+never explained; every critic stumbled on it. One line ("the years she ages up top while you are
+down here") would have carried it.
+
+## Cards that say what happened
+
+A death card that names the cause and the place, with a tip for that cause ("Torn loose in the
+ballast tanks: breaking its grip cost the last light"), turns a loss into a lesson; the end of a
+chapter can carry what the player did (time spent, the route drawn on the in-game map). Both read
+as story when they frame the hero with the gear they carried. Two phone traps from its blind
+player: a death card offering "or ENTER" on a touch screen, and a log picked up mid-fight opening a
+full-screen card with an enemy a step behind (a log can wait for the fight to end).
+
+Credits name only what the game may name: the studio, the open-source engine and fonts, CC0
+textures, never the services or pipeline behind them (an early credits screen did, and was caught).
+
+## Chapters
+
+- A chapter is one place plus one new idea. Show a card as it starts (`02 / THE ORCHARD`) for
+  about two seconds over the world, then the first objective.
+- Three to five objectives per chapter in a slice; each should be visible in the world before
+  it is asked for, so the player has already wondered about it.
+- The end of a chapter changes the world in a way the next chapter keeps: lit lamps stay lit.
+
+## Hooks for verification
+
+- Views for each beat (`title`, `beat`, `first-goal`, and the set piece with `moment: true`) so
+  `capture` and the critic panel can see them (skill `funpixel-verify`).
+- Expose `chapter`, `objective` and `goalDistance` in `__FPX_STATE__` so a check can assert that
+  playing forward completes the first objective.
+- Write the opening into the GDD's `## Opening` (second by second from Play, a shot per row) and
+  the camera plan into `## Shots`. `npx @funpixel/tools hook` reads both back: control against the
+  plan and the card (12 s for a story line, 10 s arcade), the objective and its metres on screen at
+  the hand-over, the shot on each row.
+- Give each beat an id in `__FPX_STATE__.beat` and a shot (`shoot('reveal', 1.2)` in the 3D
+  starter's `src/shots.ts`; `__FPX_CAMERA__` reports it). `hook` calls a beat staged when the camera
+  answers it within 2.5 s, and HUD-only when only text changed: a caption over unmoved play is a
+  card, not a scene (the Silt bar J2).
+- The blind player (`npx @funpixel/tools play`) is the honest test of an opening: read its report
+  for what it thought the goal was and where it looked.

package/plugins/codex/skills/funpixel-world-and-story/references/shelf.md

@@ -0,0 +1,80 @@
+# What great looks like: worlds and stories on the shelf
+
+Notes to borrow from, not rules. Sources are linked or named; a number marked *(estimated)* is a
+working value, not a measurement. Everything is paraphrased.
+
+## Silt & Signal (Crayon, published 26 Sep 2026)
+
+Our reference for a web game that feels like a world. Seen in three frames from a headless play
+and its store text:
+"Carry Neri through seven living worlds to restore the old crossings… voiced scenes, music,
+wildlife and water that reacts to your ride."
+
+| Beat | What it does | Why it works |
+|---|---|---|
+| Title card | Small overline with the game's name, a large serif display title ("The Long *Return.*"), a one-line promise ("A small life. A very large world."), one button ("Begin the journey"), a mode line, "Headphones recommended". The card sits over live key art of the world. | The promise sets the scale and the mood in eight words; one button removes the menu decision; the headphone line says sound matters. |
+| Cinematic beat | Letterboxed, the world keeps rendering; a character kneels by a wounded companion; one line of dialogue in a serif at the bottom ("Hey. It's all right. We'll find someone who knows."), "Continue ›". Voiced. | The want is shown before control: someone needs help. One line, then the player acts. |
+| First objective | Top left: `01 / THE LAST LIGHT` in small caps over "Reach Neri at the clinic"; a diamond waypoint in the world with "115 m"; a round minimap bottom left with north and the player arrow; "Map" and pause in the top right. | The goal is a sentence, a place on screen and a distance: three ways to read one thing. The chrome is small and in the corners, so the world is the screen. |
+| The world | A paved road the eye follows between rounded white houses, dense planters and flower beds, cypress trees, lamp posts, market awnings, cliffs and an aqueduct arch as the far landmark; soft contact shadows under everything. | Dressed, not tiled: the same dozen pieces vary in scale and grouping; the road stays clear; the landmark is always in view. |
+
+What to take: the order (promise → want → control → goal with a marker), the restraint of the
+chrome, the density of a small kit used well. What to leave: its genre (a hover-bike journey) and
+its scale (seven worlds). A slice needs one chapter of this, done fully.
+
+## Hollow Knight (Team Cherry, 2017)
+
+- The world tells the story: ruins, corpses, inscriptions and a few characters with short, odd
+  lines explain a fallen kingdom. No opening cutscene of note; the first screen is a fall into a
+  dark town that says "something ended here".
+- Each area owns a palette, a musical theme and an architecture, so a player knows where they
+  are from one frame.
+- A bench is rest and save; its music and light make it a place you want to reach.
+- Landmarks are seen long before they are reached (a city through a window). Maps are bought from
+  a cartographer, so knowing the place is itself a reward.
+
+## Hades (Supergiant, 2020)
+
+- The story is inside the loop: every death returns Zagreus to the House of Hades, where
+  characters comment on the run just played. Lines are one or two sentences and voiced; there is
+  a very large pool so they rarely repeat (about 21,000 lines, per the studio *(estimated from
+  press)*).
+- Portraits appear at the side with a name bar; the player taps through; combat never waits on
+  text.
+- Rooms are hand-made set pieces with a doorway that shows the next reward, so a choice is also
+  a look ahead.
+
+## Celeste (Maddy Makes Games, 2018)
+
+- Each chapter is one place, one new mechanic and one feeling; the climb is the story's metaphor.
+- Short scenes bracket chapters; dialogue boxes carry a portrait whose expression changes per line.
+- The postcard between chapters (a single illustrated card with a few lines) frames what the
+  chapter means before you play it.
+- Collectibles (strawberries) sit where a curious player looks, so exploring is rewarded with
+  something small and seen.
+
+## Journey and Alto's Odyssey, briefly
+
+- Journey: one landmark (the mountain with a light) is visible from almost everywhere; the whole
+  game is walking toward it. No text at all.
+- Alto's Odyssey: time of day and weather change as you ride, so the same place feels new; the
+  music follows. A tiny cast, a huge sense of place.
+
+## Numbers worth starting from
+
+| What | Starting value | Why |
+|---|---|---|
+| Title promise | 5–10 words | fits one line on a phone at display size |
+| First beat before control | 3–8 s, skippable | long enough to show a want, short enough that a phone player stays *(estimated)* |
+| Text speed | 40–50 characters a second, tap to complete | readable, never slower than reading *(estimated)* |
+| Line length | up to about 90 characters | two lines in a phone text box |
+| First objective on screen | by 10–20 s after Play | the question "what do I do?" is answered before it is asked *(estimated)* |
+| First payoff | inside the first minute | the loop is felt before the story asks for patience *(estimated)* |
+| Kit size for a slice | 6–12 pieces in one style | enough to vary a place, few enough to keep one look |
+| Landmark | visible from most of the play space | the player can always orient |
+
+## Story in a slice: what fits one session
+
+Fits: one place with a landmark and three areas, a title and a short beat, one chapter with three
+to five objectives, a handful of text lines, one set piece, world changes the player causes, music
+that turns with the moment. Needs production scale: many chapters, branching dialogue, voiced
+casts, a map to buy, lore to find in every room. Aim the slice at the first list and do it fully.