@funpixel/tools 0.0.0-stage → 0.1.1

package/plugins/cursor/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/cursor/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.

package/plugins/cursor/skills/funpixel-world-and-story/references/story-at-size.md

@@ -0,0 +1,159 @@
+# Story at the right size: 5 to 15 minutes
+
+Story was missing in nine of our GDK games, and the experience bar measured story as the widest
+gap to the top tier. The fix is rarely more words. Silt & Signal (research 19) tells a whole arc
+in 12–15 minutes with 7 chapters, 29 objectives and 61 short lines, most under ten words. This
+page sizes a story to a small game and shows how to prove play reaches it.
+
+Declining story is a real choice. An arcade round, a score attack or an abstract puzzle can say
+`Story: declined — the world and the score carry it` in the GDD, and every check below then
+reports "no story declared" as fine.
+
+## The shape
+
+| Piece | What it is | In Silt & Signal |
+|---|---|---|
+| An opening beat | who, where and what is wrong, in under 15 seconds, before or as control starts | a kneeling rider, a sick creature, "We'll find someone who knows" |
+| A goal said by a person | a character asks for it in a line; the HUD repeats it | the healer: "Her kind needs the old crossings" |
+| Chapters | one place and one new idea each, with a card and a line as it opens | `02 / THE BROKEN AQUEDUCT` and Mira's "The official road is closed" |
+| Lines that change as you go | the same person says something new each time, and remarks on what just happened | the rider's tone moves from "Hold on, little light" to "You don't have to stay" |
+| A turn | something the player did, or learned, changes what the goal means | sending the coordinates is the betrayal |
+| An ending worth reaching | the world visibly changed, a last line, an end card that names what happened | the lamps waking in the village, "The road belongs to her" |
+
+## Sized to the game
+
+| Length | Chapters or beats | Lines | Speakers | A turn? |
+|---|---|---|---|---|
+| 3–5 min (a short round, on purpose) | 3 beats: want, test, payoff | 8–12 | 1–2 | optional |
+| 5–10 min (a smaller scope, on purpose) | 3–5 chapters | 15–30 | 2–3 | one, near two thirds |
+| 15 min and more (the floor for a game) | 5–7 chapters | 30–60 | 3–5 | one, plus a quiet beat before the end |
+
+A line is one sentence a player reads in about two seconds. Past 60 lines the cost is not the
+words, it is the voice, the timing and the testing of each one.
+
+## The outer story, at 10 minutes and up
+
+A want inside the hero is not enough past ten minutes; the player needs something to point at.
+Five lines in the GDD, each something the player sees or does. One of our games lacked all five.
+
+| Line | What it is | From |
+|---|---|---|
+| Goal | a place on the map and a distance, said by a person, shown by the HUD | A Short Hike's summit; Silt & Signal's crossings |
+| Clock | one deadline for the whole game, visible in every play frame | Majora's Mask's moon; 80 Days |
+| Question | a mystery asked in minute one, one piece answered per chapter | Outer Wilds; "what happened here?" |
+| Antagonist | a plan that moves while you play, a reason that is almost right, marks in every chapter, seen in few; the turn is the player having helped it | Silt & Signal's Director; Cowboy Bebop's Syndicate |
+| Frame | in an episodic game, each episode also moves the spine one step | Edith Finch; Death Stranding's network |
+
+Make the core verb the plot (each delivery wakes the network), and let the hero's want be
+active and out in the world while the ending pays what she needs.
+
+## The GDD section
+
+The design's `## Story` section carries the beats as a table a check can read. `funtools depth`
+reads the story table and sets each beat beside what real play reached.
+
+```markdown
+## Story
+Want: <what the hero wants, in the words of the person who asks for it>
+Turn: <the moment the want changes meaning, and what the player does to cause it>
+Ending: <what the world looks like after, and the last line>
+
+| Beat | When | Who says it | The line | Seen in play |
+|---|---|---|---|---|
+| opening | 0:00, over the title pan | Narrator | "The city went under in one night." | |
+| goal | 0:15, at the first rooftop | Ada | "Get the medicine to the hospital before the tide turns." | |
+| ch2 | 2:00, the market district | Old Tomas | "You again? The bridge is gone, take the wires." | |
+| turn | 7:30, the hospital roof | Ada | "There's no hospital. There's only us." | |
+| ending | 10:00, dawn | Ada | "Look. The water's going down." | |
+```
+
+The first column is the beat's id. Expose the current id as `__FPX_STATE__.beat` when a beat
+plays (`state.beat = 'ch2'`), so a play log records which beats were really reached. The
+`Seen in play` column is filled from real play (`funtools depth --fill`), never by hand.
+
+## Lines as data
+
+Lines live in one file, keyed by what triggers them, so the writing can change without touching
+code and a voice pass can walk the same list. A trigger is a place entered, a deed done, or a
+count reached; a variant picks by how many times it has fired, so the second visit gets a new line.
+
+```ts
+// src/story/lines.ts: every line in the game, with its trigger and optional voice file.
+export interface Line { id: string; who: string; text: string; voice?: string }
+export interface Cue { trigger: string; lines: Line[][]; once?: boolean }
+
+export const CUES: Cue[] = [
+  { trigger: 'enter:market', lines: [
+    [{ id: 'm1', who: 'Tomas', text: 'A courier? In this weather?', voice: 'voice/m1.mp3' }],
+    [{ id: 'm2', who: 'Tomas', text: 'Back so soon. The wires still hold.', voice: 'voice/m2.mp3' }],
+  ] },
+  { trigger: 'deed:first-delivery', once: true, lines: [
+    [{ id: 'd1', who: 'Ada', text: 'One down. The hospital is past the bell tower.' }],
+  ] },
+];
+
+/** Picks the line for a trigger: the nth variant on the nth firing, the last one after that. */
+export class Script {
+  private fired = new Map<string, number>();
+  constructor(private cues: Cue[], private play: (lines: Line[]) => void, private busy: () => boolean = () => false) {}
+  private queue: Line[][] = [];
+  fire(trigger: string) {
+    const cue = this.cues.find((c) => c.trigger === trigger);
+    if (!cue) return;
+    const n = this.fired.get(trigger) ?? 0;
+    if (cue.once && n > 0) return;
+    this.fired.set(trigger, n + 1);
+    this.queue.push(cue.lines[Math.min(n, cue.lines.length - 1)]);
+  }
+  /** Each frame: play the next queued line when nothing else is being read (a fight, a card, a tutorial). */
+  update() { if (this.queue.length && !this.busy()) this.play(this.queue.shift()!); }
+  save() { return Object.fromEntries(this.fired); }
+  load(s: Record<string, number>) { this.fired = new Map(Object.entries(s)); }
+}
+```
+
+Wire `play` to `say()` from [opening-and-chapters.md](opening-and-chapters.md), or to the voiced
+version in [voice.md](voice.md). Save `script.save()` with `@funpixel/sdk/save` so a returning
+player does not hear the opening twice.
+
+## Craft notes
+
+- **The goal comes from a mouth.** "Deliver 5 parcels" in a HUD is a task; "Get the medicine to
+  the hospital before the tide turns", said by someone waiting for it, is a want. Put both on screen.
+- **Remark on what just happened.** Hades's trick: a line that names the last death, the new
+  weapon, the room you just cleared. Trigger lines on deeds, not timers, and the game feels like
+  it is watching.
+- **One new idea per chapter, said once.** The chapter card names the place; the first line names
+  the new rule in the world's words ("Point them down" for a jet under the bike).
+- **A quiet beat before the end.** A moment with no threat and one line ("Sleep. I'm right here.")
+  makes the ending land. On a pacing chart it is the long release before the last peak.
+- **The ending changes the world.** Go back to the first place and show it changed: the lamps
+  lit, the water down, the crowd on the rooftops cheering. The end card names what the player
+  did, not only "You win".
+- **Let a character come back.** Three to five speakers who each return beat a new face per
+  chapter; a returning face carries the arc.
+- **Keep lines short and in the player's thumb's way.** One sentence, a speaker name, bottom third,
+  clear of the controls (skill `funpixel-mobile-ui`), and never a line a fight has to wait behind.
+
+## Staged versus played
+
+A beat that exists only in a staged view is not in the game. One game's playtest caught a
+showcase frame play never reached; the same happens to story. Three places see it:
+
+- `funtools depth` reads the `## Story` table and the `beat` field in real play logs (blind
+  rounds, journeys) and lists each beat as seen or never seen. It warns about a declared beat
+  play never reached; it never blocks.
+- `funtools playtest` sets each planned moment beside the frame play reached, and flags a staged
+  frame the played route never saw.
+- The blind player's report: ask it who asked for what, and what happened at the end. If it
+  cannot say, the story is in the files, not in the game.
+
+## Common mistakes
+
+- A story told only on the title card, then never again.
+- The goal only in the HUD, with no one asking for it.
+- Lines on a timer that fire during a fight or over a tutorial caption.
+- An ending that is a text card over black, with the world gone.
+- A voice line that holds its caption until the file loads: advance on the clip's end or a timeout,
+  whichever comes first (Silt & Signal's first caption waited 30 s for a slow file).
+- Chapters that are only colour changes: each needs one idea the player uses there.

package/plugins/cursor/skills/funpixel-world-and-story/references/voice.md

@@ -0,0 +1,175 @@
+# Voiced lines: what the platform can make, and the creator's own voice
+
+Silt & Signal voices all 61 of its lines, and the voice teaches as much as the text: the tutorial
+for the jets is a joke said aloud. A voice is worth having when a game is about people. This page
+is honest about what Funpixel's tools make today and gives a path for the rest.
+
+## What the platform makes today (1 Oct 2026)
+
+| Want | Funpixel tool | Works? |
+|---|---|---|
+| A spoken sentence with the exact words | `cast_voice`, then `voice_line` | yes: **the default offer for a story game** (below), with its price, made only when the creator picks it. `generate_sound` is the wrong tool: asked for speech it makes murmurs or the wrong words |
+| A murmur, a gasp, a laugh, a crowd | `generate_sound` | yes, 2 credits each: "a woman's short warm murmur, no words, 1.5 seconds" |
+| A voice-like blip per letter | none needed | yes, in code (below), free |
+| Music that swells under a line | `generate_music` + a duck | yes (skill `funpixel-audio`) |
+
+So for real words, four honest options: the platform's voice, then three cheaper ones.
+
+## Option 0: the platform's voice (the default offer for a story game, priced, picked by the creator)
+
+**A story game offers voice by default** (the Silt bar S3:
+at least one voiced line before first control, every line voiced and captioned, a line advancing on
+its clip's end). Silt voiced 57 lines heard by objective 33; one of our games typed its radio lines and
+lost on it. So for a game with a story, characters who speak or a cold open, the plan's Art budget
+lists the voiced lines with their price as the default, and the creator picks voice, one of the
+cheaper options below, or none: still priced, still the creator's choice, never made unasked. For an
+arcade round without people, voice stays an extra you mention once. An ordinary line is charged
+1 credit (each job holds a little more while it runs), so a cast of six with 40 lines each is about
+240 credits plus a sample per voice; `funtools estimate` or the tool's price list says the
+current numbers.
+
+1. **One voice per character, once.** `cast_voice` with the character's `name`, a `preset` (one of
+   30 voices: Kore firm, Puck upbeat, Charon informative, Algenib gravelly, Achernar soft, …) and up
+   to four delivery words as `tags` (`gruff`, `weary`, `whispering`). It answers `voice.json` and a
+   `sample.mp3`: play the sample to the creator before any line is made.
+2. **Every line in that voice.** `voice_line` with the line's `text` and voice.json's asset id as
+   `voice_asset_id`, so each line gets the same preset and tags; `emotion` adds up to three words
+   for that line only. Inside the text, `[sighs]`, `[laughs]` or `[pause]` steer the delivery and
+   are not spoken. Never write a direction as words ("Say it angrily: …"): it is read aloud.
+3. **The lines file stays the source of truth.** One job per line, named by the line's id
+   (`funtools gen line "<text>" --voice .funtools/voice/<who>.json`), saved under
+   `public/assets/voice/`, mastered for speech (trimmed, one loudness). Record each in the Art
+   budget with its credits.
+4. **A scene played as one piece (a cutscene, a cold open, a radio exchange): `dialogue`.** One call with the scene's lines (`{speaker, text, voice?, tags?, pause_after_ms?}`, the voices from `cast`) speaks each in its speaker's voice and lays them on tracks: `dialogue.mp3` (the scene mixed into one file at one loudness), each line also as `line-NN.mp3`, and `dialogue.json`, the timeline (each clip's track, start and length) to cue captions from. Priced as its lines; `funtools gen dialogue scene.json`. Lines the game plays one at a time stay `voice_line`.
+
+A local option, never the default: `funtools gen line "<text>" --voice <who>.json --model kokoro-82m` (or `gen dialogue scene.json --model kokoro-82m` for a scene) speaks the line with Kokoro on the creator's Apple Silicon Mac, once `funtools models install kokoro-82m` has set it up. Ours stays the recommended pick: Kokoro is free and offline, but slower and not checked by us, so offer it only when the creator asks for free or offline voice, and never run it unasked or in place of ours.
+
+No cloning: a real person's voice needs their consent recording, and the platform does not take
+one.
+
+## Option 1: a voice in code (free, always works)
+
+A pitched blip per letter, one pitch and waveform per speaker, the way Celeste and Animal
+Crossing give each character a voice without a single recorded word. It reads as speech because
+it follows the text's rhythm: a pause at commas, a longer one at full stops.
+
+```ts
+/** One voice per speaker: a short blip per letter, pitched and shaped by who is talking. */
+export interface Timbre { base: number; spread: number; wave: OscillatorType; gain: number }
+export const TIMBRES: Record<string, Timbre> = {
+  Ada: { base: 520, spread: 90, wave: 'triangle', gain: 0.12 },
+  Tomas: { base: 180, spread: 40, wave: 'square', gain: 0.06 },
+  Narrator: { base: 300, spread: 30, wave: 'sine', gain: 0.1 },
+};
+
+export function blipVoice(ctx: AudioContext, out: AudioNode, who: string) {
+  const v = TIMBRES[who] ?? TIMBRES.Narrator;
+  return (ch: string) => {
+    if (!/[a-z0-9]/i.test(ch) || Math.random() < 0.35) return;          // not every letter, not spaces
+    const o = ctx.createOscillator(), g = ctx.createGain(), t = ctx.currentTime;
+    o.type = v.wave;
+    o.frequency.value = v.base + ((ch.toLowerCase().charCodeAt(0) * 37) % v.spread);  // same letter, same pitch
+    g.gain.setValueAtTime(v.gain, t); g.gain.exponentialRampToValueAtTime(0.001, t + 0.06);
+    o.connect(g).connect(out); o.start(t); o.stop(t + 0.07);
+  };
+}
+```
+
+Call the returned function from `say()`'s typing tick with the character just shown.
+
+## Option 2: a platform murmur per speaker (a few credits)
+
+One or two `generate_sound` clips per speaker, a wordless sound with the character's feeling
+("an old man's amused grunt", "a young woman's worried breath, short"), played at the start of each
+of their lines under the typed text. Three speakers, two moods each, is 6 clips, about 12 credits.
+It gives presence without claiming words the clip does not say.
+
+## Option 3: the creator's own text-to-speech (an outside tool)
+
+The creator may own a voice tool: a text-to-speech subscription, an open local model such as
+Piper, or the system's voices. The kit can drive it and record what it made. This is the
+creator's tool on the creator's account: Funpixel neither bills nor meters it, and the licence of
+each voice is the creator's to check before publishing.
+
+| Tool | Where it runs | Licence to check |
+|---|---|---|
+| macOS `say` | the creator's Mac, free | Apple's licence allows the system voices for personal, non-commercial projects: fine for a prototype or a private proof, not for a published game |
+| Piper (open source) | local, free, CPU | each voice model has its own licence; many allow commercial use, some do not |
+| A hosted text-to-speech service on the creator's own key | their account | their plan's terms for games; the price is theirs (a 60-line script is about 3,500 characters) |
+
+The pipeline: the lines file is the source of truth, a script makes one file per line, then every
+file is trimmed and levelled to one loudness so no speaker is louder than another.
+
+```js
+// scripts/voice.mjs — run by the creator: node scripts/voice.mjs [say|piper]. Reads the lines the
+// game already uses (exported as JSON by the build or kept in src/story/lines.json) and writes
+// public/voice/<id>.mp3 plus public/voice/voice.json, the record of what made each file.
+import { execFileSync } from 'node:child_process';
+import { mkdirSync, readFileSync, writeFileSync, existsSync } from 'node:fs';
+
+const tool = process.argv[2] ?? 'say';
+const VOICES = { Ada: 'Samantha', Tomas: 'Daniel', Narrator: 'Moira' };   // per speaker; Piper: a model path
+const lines = JSON.parse(readFileSync('src/story/lines.json', 'utf8'));  // [{ id, who, text }]
+mkdirSync('public/voice', { recursive: true });
+const record = { tool, made_with: tool === 'say' ? 'macOS say (system voices)' : 'Piper', billed_by_funpixel: false, lines: [] };
+for (const l of lines) {
+  const raw = 'public/voice/' + l.id + (tool === 'say' ? '.aiff' : '.wav'), mp3 = 'public/voice/' + l.id + '.mp3';
+  if (tool === 'say') execFileSync('say', ['-v', VOICES[l.who] ?? 'Samantha', '-o', raw, l.text]);
+  else execFileSync('piper', ['--model', VOICES[l.who], '--output_file', raw], { input: l.text });
+  // Trim silence at both ends, level to -16 LUFS (dialogue), mono 64 kbps: about 10 KB a second.
+  execFileSync('ffmpeg', ['-y', '-loglevel', 'error', '-i', raw, '-af',
+    'silenceremove=start_periods=1:start_threshold=-50dB,areverse,silenceremove=start_periods=1:start_threshold=-50dB,areverse,loudnorm=I=-16:TP=-1.5',
+    '-ac', '1', '-b:a', '64k', mp3]);
+  execFileSync('rm', [raw]);
+  record.lines.push({ id: l.id, who: l.who, voice: VOICES[l.who] ?? null, file: mp3.replace('public/', '') });
+}
+writeFileSync('public/voice/voice.json', JSON.stringify(record, null, 2) + '\n');
+console.log(lines.length + ' lines voiced with ' + record.made_with + '; not billed by Funpixel');
+```
+
+Record it where the game's other assets are recorded: a row in the GDD's Art budget with
+`Made how: the creator's own TTS (macOS say)` and `Credits: 0 (outside tool)`, and the tool named
+in the hand-back. The credits screen names only what the game may name (the voice's owner if the
+licence asks for it), never the pipeline behind it.
+
+## Playing a voiced line
+
+The caption is the source of truth; the voice is a layer on it. A line advances when the clip ends
+or when a timeout passes, whichever comes first, so a slow or missing file never holds the game.
+Music dips under the voice and comes back.
+
+```ts
+/** Plays one voiced line under its caption. Resolves on the clip's end, a tap, or the timeout. */
+export async function speak(ctx: AudioContext, out: AudioNode, line: { text: string; voice?: string }, music?: GainNode, cache = new Map<string, AudioBuffer>()): Promise<void> {
+  const timeout = 1500 + line.text.length * 55;                       // reading time plus a margin
+  let buf: AudioBuffer | undefined;
+  if (line.voice) {
+    try {
+      buf = cache.get(line.voice) ?? await Promise.race([
+        fetch(line.voice).then((r) => r.arrayBuffer()).then((b) => ctx.decodeAudioData(b)),
+        new Promise<undefined>((r) => setTimeout(() => r(undefined), 800)),   // late file: go on unvoiced
+      ]);
+      if (buf) cache.set(line.voice, buf);
+    } catch { buf = undefined; }
+  }
+  if (music) music.gain.setTargetAtTime(0.35, ctx.currentTime, 0.08);
+  await new Promise<void>((done) => {
+    const end = () => { clearTimeout(t); removeEventListener('pointerup', end); done(); };
+    const t = setTimeout(end, buf ? Math.min(timeout, buf.duration * 1000 + 400) : timeout);
+    addEventListener('pointerup', end, { once: true });
+    if (buf) { const s = ctx.createBufferSource(); s.buffer = buf; s.connect(out); s.start(); }
+  });
+  if (music) music.gain.setTargetAtTime(1, ctx.currentTime, 0.4);
+}
+```
+
+Load the next chapter's lines while the current one plays, not all at once before the title
+(Silt & Signal fetched 3.9 MB of voice). A game with voice says "Sound on for voices" on the
+title, and keeps working with the phone on silent: captions carry every word.
+
+## Hooks for checks
+
+- `__FPX_STATE__.beat` names the line's beat as it plays (see [story-at-size.md](story-at-size.md)),
+  so `funtools depth` can say which lines play reached.
+- `funtools verify`'s audio check counts starts; a voiced game should show one per line played.
+- The blind player cannot hear. Say in the hand-back which lines are voiced and with what.