@funpixel/tools 0.0.0-stage → 0.1.0

package/plugins/robin/claude/skills/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. Blue Freight 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 `fp: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. The Held Note 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/robin/claude/skills/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 `fp: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; Blue Freight 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.

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

@@ -0,0 +1,154 @@
+# A world from a kit: scatter, landmarks, the route
+
+Working code, checked in a scratch scaffold on pixi.js 8.21 and three 0.170 (captured and profiled
+at 844×390). Take what helps; change the numbers to the place.
+
+## The kit
+
+Six to twelve pieces in one style carry a whole area. Ways to get them:
+
+| Piece | Tool | Note |
+|---|---|---|
+| 2D props (rock, bush, lamp, crate, fence) | `generate_sprite`, one call per piece with the same style words | a style lock keeps them one family (skill `fp:art`) |
+| A state variant (lamp lit/unlit, bridge broken/mended) | `edit_image` on the accepted sprite | the same drawing changed, so the swap reads as the world changing |
+| Ground and paths | `generate_image` texture or strip (`funtools gen texture`) | seamless tiles under the scatter; the scatter hides the grid |
+| Characters that move | `generate_spritesheet` | idle and walk from one base |
+| 3D props | code-built (below), `generate_3d_model`, or `find_material` type `model` (Poly Haven, CC0) | instance anything placed more than a few times |
+| Sky | `generate_skybox`, or a Poly Haven HDRI via `get_material` | the sky sets the time of day and the palette |
+| A set with a plan | `build_level` (skill `fp:3d`) | interiors, a village square, anything with doors |
+
+## Scatter by rule
+
+Seeded dart-throwing with spacing: denser at the edges, sparse in the open, a clear route and a
+ring around each landmark, jittered scale, flip and tint. Engine-free.
+
+```ts
+// Dress a place from a kit: seeded, spaced, denser at the edges, the path kept clear.
+// Engine-free: it returns placements; Pixi or Three draws them.
+
+export interface Piece { name: string; radius: number; weight: number; zones?: Zone[] }
+export type Zone = 'edge' | 'field' | 'path-side' | 'landmark';
+export interface Placement { piece: string; x: number; y: number; scale: number; flip: boolean; tint: number; zone: Zone }
+export interface Area {
+  w: number; h: number;
+  /** The walkable route as points; pieces keep `clear` away from it, `path-side` pieces hug it. */
+  path: Array<[number, number]>; clear: number;
+  /** Landmarks already placed (a tower, a tree): scatter leaves a ring around each. */
+  landmarks: Array<{ x: number; y: number; r: number }>;
+}
+
+export function rng(seed: number) {
+  return () => { seed = (seed + 0x6d2b79f5) | 0; let t = Math.imul(seed ^ (seed >>> 15), 1 | seed); t ^= t + Math.imul(t ^ (t >>> 7), 61 | t); return ((t ^ (t >>> 14)) >>> 0) / 4294967296; };
+}
+
+const distToPath = (x: number, y: number, path: Area['path']) => {
+  let best = Infinity;
+  for (let i = 1; i < path.length; i++) {
+    const [ax, ay] = path[i - 1], [bx, by] = path[i], dx = bx - ax, dy = by - ay;
+    const k = Math.max(0, Math.min(1, ((x - ax) * dx + (y - ay) * dy) / (dx * dx + dy * dy || 1)));
+    best = Math.min(best, Math.hypot(x - ax - k * dx, y - ay - k * dy));
+  }
+  return best;
+};
+
+/** Where a point sits: near an edge, beside the path, or in the open field. */
+function zoneOf(x: number, y: number, a: Area): Zone | null {
+  const d = distToPath(x, y, a.path);
+  if (d < a.clear) return null;                                  // the route stays readable
+  if (a.landmarks.some((l) => Math.hypot(x - l.x, y - l.y) < l.r)) return null; // landmarks breathe
+  if (d < a.clear * 1.8) return 'path-side';
+  const edge = Math.min(x, y, a.w - x, a.h - y);
+  return edge < Math.min(a.w, a.h) * 0.14 ? 'edge' : 'field';
+}
+
+/** Dart-throwing with spacing: `tries` candidates, each kept only if no neighbour is closer than the sum of radii. */
+export function scatter(kit: Piece[], a: Area, seed: number, tries = 1500, density: Record<Zone, number> = { edge: 1, 'path-side': 0.6, field: 0.25, landmark: 0 }): Placement[] {
+  const r = rng(seed), out: Placement[] = [], total = kit.reduce((s, p) => s + p.weight, 0);
+  for (let i = 0; i < tries; i++) {
+    const x = r() * a.w, y = r() * a.h, zone = zoneOf(x, y, a);
+    if (!zone || r() > density[zone]) continue;
+    let pick = r() * total, piece = kit[0];
+    for (const p of kit) { pick -= p.weight; if (pick <= 0) { piece = p; break; } }
+    if (piece.zones && !piece.zones.includes(zone)) continue;
+    const scale = 0.8 + r() * 0.45;
+    if (out.some((o) => Math.hypot(o.x - x, o.y - y) < (kit.find((k) => k.name === o.piece)!.radius * o.scale + piece.radius * scale) * 0.9)) continue;
+    const warm = Math.round(235 + r() * 20);                     // a small tint jitter breaks the copy-paste look
+    out.push({ piece: piece.name, x, y, scale, flip: r() < 0.5, tint: (warm << 16) | (Math.round(240 + r() * 15) << 8) | 235, zone });
+  }
+  return out.sort((p, q) => p.y - q.y);                          // back to front for a 2D side or top view
+}
+```
+
+Pixi: draw the placements back to front (they come sorted by y), with the flip and tint.
+
+```ts
+for (const p of scatter(KIT, { w, h, path, clear: 30, landmarks: [tower] }, 42)) {
+  const s = new Sprite({ texture: kitTextures[p.piece], anchor: { x: 0.5, y: 1 } });
+  s.position.set(p.x, p.y); s.scale.set(p.flip ? -p.scale : p.scale, p.scale); s.tint = p.tint;
+  world.addChild(s);
+}
+```
+
+Measured in the lab: about 280 pieces on an 844×390 view drew in 3 draw calls (Pixi batches
+sprites and graphics that share a texture), JS work under 0.5 ms a frame. Put every kit piece on
+one atlas (`npx @funpixel/tools optimize pack-atlas`) so they keep batching.
+
+Three: one `InstancedMesh` per piece kind, so a few hundred props cost a few draw calls.
+
+```ts
+/** Scatter on the XZ plane (area units = metres), one draw call per piece kind. */
+export function dressGround(scene: THREE.Scene, size: number, path: Array<[number, number]>, landmark: THREE.Vector3, seed: number) {
+  const toArea = (x: number, z: number): [number, number] => [x + size / 2, z + size / 2];
+  const placed = scatter(KIT, { w: size, h: size, path: path.map(([x, z]) => toArea(x, z)), clear: 1.6, landmarks: [{ x: landmark.x + size / 2, y: landmark.z + size / 2, r: 4 }] }, seed, 4000);
+  const m = new THREE.Matrix4(), q = new THREE.Quaternion();
+  for (const piece of KIT) {
+    const mine = placed.filter((p) => p.piece === piece.name);
+    const [geo, mat] = GEO[piece.name];
+    const mesh = new THREE.InstancedMesh(geo, mat, mine.length);
+    mesh.name = 'kit-' + piece.name;
+    mine.forEach((p, i) => {
+      q.setFromAxisAngle(new THREE.Vector3(0, 1, 0), (p.x * 13.7) % (Math.PI * 2));
+      mesh.setMatrixAt(i, m.compose(new THREE.Vector3(p.x - size / 2, 0, p.y - size / 2), q, new THREE.Vector3(p.scale, p.scale, p.scale)));
+      mesh.setColorAt(i, new THREE.Color(p.tint));
+    });
+    scene.add(mesh);
+  }
+  return placed.length;
+}
+```
+
+Measured in the lab: 621 instances across the kit and trees, 16 draw calls, 17,640 triangles.
+
+## Landmarks and the route
+
+- One landmark tall enough to see from most of the map, with its own silhouette and light (a
+  tower, a great tree). Place it first; the scatter leaves room around it.
+- The route is the brightest, least cluttered band. In 2D a path texture or a stroked spline
+  (`Graphics.stroke({ width, cap: 'round', join: 'round' })`); in 3D a lighter ground strip.
+- Two or three districts, each with one colour and one material: the orchard is warm and round,
+  the quarry grey and angular. A player should know where they are from one frame.
+- Depth in 2D: two or three parallax layers (far hills move at 0.2–0.4 of the camera, near props
+  at 1.0), the far ones lighter and bluer; in 3D, fog in the sky's colour (skill `fp:art`).
+
+## Contact and life
+
+- A soft shadow under anything standing on the ground (a blurred dark ellipse in 2D; a blob
+  texture or a shadow map in 3D) glues it to the place.
+- Small ambient motion sells a place: grass sway (a sine on rotation with a per-piece phase),
+  drifting particles (pollen, fireflies, dust), water shimmer, smoke. Keep it low contrast so the
+  player and threats stay the clearest things on screen. Respect `prefers-reduced-motion`.
+- Wildlife that reacts (birds that lift off as you pass) is cheap and reads as a living world.
+
+## A minimap, cheaply
+
+A round mask over a small render of the world's layout: in 2D, draw the route and landmarks into a
+`Graphics` in a corner at 1/20 scale with the player as an arrow; in 3D, a top-down orthographic
+camera into a small `WebGLRenderTarget` shown on a plane, or a 2D canvas that draws the same
+positions. Keep it off the thumbs' zones (skill `fp:mobile-ui`).
+
+## Checking a place
+
+- Capture the play view at phone size and ask: can I see the landmark, the route and the goal?
+- `npx @funpixel/tools look --read` for whether the player and threats stand out from the ground.
+- `npx @funpixel/tools profile --views playing` before and after dressing; the draw calls and
+  object count say what the kit costs.

package/plugins/robin/mcp-servers.json

@@ -0,0 +1,25 @@
+[
+  {
+    "id": "2BD21E87-2E73-5394-A9D6-AA32951E780C",
+    "name": "funtools",
+    "transport": {
+      "local": {
+        "command": "funtools",
+        "arguments": [
+          "mcp"
+        ]
+      }
+    },
+    "isEnabled": true
+  },
+  {
+    "id": "3A6AE192-EDEB-5DF3-BA9F-D06A09ABCF0C",
+    "name": "Funpixel",
+    "transport": {
+      "remote": {
+        "url": "https://api.funpixel.ai/mcp"
+      }
+    },
+    "isEnabled": true
+  }
+]

package/plugins/robin/plugin.json

@@ -0,0 +1,20 @@
+{
+  "id": "fp",
+  "name": "Funpixel GDK",
+  "version": "0.1.0",
+  "summary": "Use Funpixel asset tools, game skills and optional studio workflows in your agent. Build, verify and publish browser games with advisory hooks and project-controlled review.",
+  "tools": [
+    "funpixel",
+    "funtools"
+  ],
+  "skills": "skills",
+  "servers": [
+    {
+      "name": "funtools",
+      "command": "funtools",
+      "arguments": [
+        "mcp"
+      ]
+    }
+  ]
+}

package/plugins/robin/skills/fp-first-look/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: fp-first-look
+description: "Use when the person types /fp-first-look. Make the game's first look from its GDD, the whole game and not a few frames (key art, every screen, the HUD on phone and desktop, a frame per place, the living world, animation, juice, sound and fun), and render a page to show it."
+---
+
+Make the first look for the Funpixel game in this folder, following the `funpixel-gdd` skill and its
+`references/first-look.md`.
+
+1. Read `design/GDD.md` (or `design/README.md`). If there is none, write v0.1 from the skill's
+   template first: the pieces below are briefed from the design's words, so without one they have
+   nothing to agree on. Read its `## Experience` lines too, or offer them if empty (depth, content,
+   replay, story, world, the arc, the signature idea; the skill's `references/experience.md`): the
+   key art and the frames are where a world's places and the signature idea first become pictures.
+2. The order is the flow's: the key art and the hero's reference sheet come first (`npx
+   @funpixel/tools flow` names them, the owner's look, then a first playable). Once the owner has played
+   it, worth: run `npx @funpixel/tools greenlight worth` and show its verdict in the chat before the rest
+   of the art (the idea may shrink, change or be dropped). Run
+   `npx @funpixel/tools firstlook`: the required set for this game (scaled by its tier; places
+   and the living world only for a world game, the reason said), each item a picture or a page shown
+   in the chat and linked from the GDD, and what closes each missing one. A missing item is listed
+   with the plan when it goes to the owner (they drop one in their words: `firstlook skip <item>
+   --by owner "<why>"`). Then plan the pieces, in this order: reference sheets first, one turnaround per recurring
+   design (hero, companion, vehicle, pursuer, the thing carried), each a `ref-*` item with its
+   `pins`, drawn from the best draft you have (a rough frame is fine) and named in `## Identity
+   lock`; then key art (the title moment), four target frames (four rungs of the
+   moment ladder, each a whole frame from the game's camera, each named in the GDD's target-frames
+   table with its moment and intent, so the fidelity seat can later hold the game against it), for a
+   game of several levels a picture per place (`place-*`, the `## Places` rows), the world's kit
+   (`kit-*` sheets of its structures, ground, props and living cast, drawn to the style block and
+   cut into pieces with `npx @funpixel/tools cut` before the slice), the cast on one sheet at one scale,
+   about eight sound cues briefed in the world's own words, and two music clips sharing one
+   identity. Every picture of a recurring design names its sheets in `references`; reuse the style
+   file's words in every picture prompt; name the game's id so its style lock applies.
+3. Estimate before anything is made: `npx @funpixel/tools assets gen --only 'look-*' --dry-run`
+   with the pieces in `assets/assets.json`, or each tool's estimate. These are Funpixel's paid tools:
+   say the total in credits in one line, and above 50 credits wait for the person's yes.
+4. Make them into `design/first-look/` (`keyart`, `frame-…`, `cast`, `sfx/`, `music/`). You cannot
+   listen, so when two sound takes exist, keep the better by measurement and say why.
+5. Draw `design/first-look/hud.html`: one target frame at a phone's size with the HUD and touch
+   controls over it, numbered, with a legend, in each orientation the plan holds, and the same HUD
+   at a desktop's 1280 × 720; then every screen the set names (title as the play world, pause, the
+   end, and past small settings, results, a level select) the same way, each in a `.phone` element
+   with `data-mockup="<screen>"`, so a playtest can hold the game's screens against them. Add the
+   animation board (the hero's key poses per state, the creatures' cycles, the UI's motion), and in
+   the GDD the juice table, the sound list (`## Audio`) and the fun (`## Core loop`, or a `## Fun` of
+   its own: the loop, goals, streaks, the 2–3-minute novelty cadence, and the arc at the game's
+   length; a nugget's is why a second run).
+6. Look at every picture against the AD rules and the sheets: lay the frames side by side and read
+   each recurring design (hair, outfit, silhouette, colours). A frame that breaks a rule or drifts is
+   a finding: fix the words, redraw it to its sheet, keep the before and after, and record it. List
+   what still breaks, kept (the honest breaks).
+7. Render the page: `npx @funpixel/tools gdd page`. Copy the accepted gameplay frame to
+   `design/target.png`.
+8. Write `## First look` into the GDD (what it settled, what changed, the cost), bump it to v0.2
+   and the stage to Greenlight (Style test when the person skips it), then run
+   `npx @funpixel/tools gdd`; the owner judges these frames in the chat, and the rounds build to them.
+   The stage line names where the track is, never the owner's sign-off: their yes is
+   `npx @funpixel/tools flow agree --by owner "<their words>"`.
+9. Hand back: the page's path, the cost, what the look settled, the open questions for the person.

package/plugins/robin/skills/fp-flow/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: fp-flow
+description: "Use when the person types /fp-flow. Resume the Funpixel game's flow — the owner's notes first, then the one next step, round after round of the look-dev loop until the owner's yes or their rounds per session."
+---
+
+Resume this game where its run stands. In the game folder (the one with `funpixel.json`), run
+`npx @funpixel/tools flow`: where the run is (the plan, waiting for the owner, or round N) and the
+ONE next step with its command. Do that step, then run `flow` again.
+
+1. **The owner's words first.** What they said in the chat, or a note they left between sessions (`funtools note`),
+   a change to the plan, an answer: act on it before anything else; the GDD's `## Where we are` says what you did with it.
+2. **The plan is locked once, by the owner.** Before the lock, finish the plan at the game's real
+   size (the brief's path: target frames, the numbers contract, the asset list and its price), then
+   `npx @funpixel/tools flow ask` readies it; show it in the chat (the GDD, its target frames, its
+   price) and wait for their yes, then record it with their words: `flow agree --by owner "<words>"`. You never agree it for them. Waiting on them is a fine place to end the
+   session. After the lock the plan is the job: only the owner relaxes a target, and a departure
+   goes in the plan's "Where the build moved" table, with why.
+3. **Each round is the look-dev loop.** Build; capture at the target moments; set each beside its
+   target (`compare --target`); fix the biggest difference; play it (`play`, `playtest`); repeat
+   until each beat is close. `check` stays green throughout. Close the round: update the GDD's
+   `## Where we are` (each capture beside its target, the gap left, the next step), show the
+   captures in the chat, then `npx @funpixel/tools flow round`. What the whole-game review named as
+   working (the flow's "do not regress" list) stays working: a fix that breaks one is a regression,
+   and `flow` makes putting it back the first step. A critic score under 3 for three playtests is
+   next: a 2 is not a resting place, so raising it is the round's fix until a playtest scores it higher.
+4. **The whole-game look.** The round after the first playable, and every three rounds after
+   (funpixel.json `flow.look_every`), `flow` says the whole-game look is due. Run
+   `npx @funpixel/tools flow look`: it writes a brief; hand it to a fresh agent with only that file
+   (it plays the whole game and answers "would you ship this today?", each defect with a severity and
+   an owner), then run `flow look` again: each defect goes to the lane of its kind, to the owner (ask
+   them in the chat) or to your round. It routes and never vetoes: a "no" stops nothing.
+5. **The locked plan is the go-ahead for its assets: make them.** Before each paid call, say the route, its
+   cost and the free alternative in one line in the chat; the owner can reverse it there. No
+   budget unless the owner sets a cap; out of credits is a pause: say so, they top up, go on.
+6. **Show every step**, in the game's words, never the kit's (no stage numbers, gates or commands
+   unless asked), ending on what comes next. After each asset, build, fix or playtest: two or three
+   lines in the chat with a capture of the build; the key art, the first playable and each chapter
+   are reveals (a clip, the game open, "try this first": `in-the-loop.md`). The owner watches and steers at any time; their message outranks
+   the step you were on. A new direction is a new GDD version they lock again (`flow ask`).
+7. **Judge before the owner sees.** Everything you show them in the chat carries the kit's read (`score`
+   against the targets, the blind player or panel when they ran). Below the bar, the first line
+   says "below the bar: <why>"; a read that never ran is "not judged yet", never a pass.
+8. **A drop is the owner's.** When they say so in the chat, `flow drop --by owner "<their words>"` ends
+   the game. You may recommend it, with the numbers.
+9. **The owner's rounds per session.** After funpixel.json `flow.rounds_per_session` rounds
+   (default 3), hand back in the chat, with the GDD's `## Where we are` current: what plays, how it compares with its targets, the next
+   round. The next session resumes with `/fp:flow`.
+
+The owner follows in the chat: the GDD (`design/GDD.md`, `## Where we are` on top) and the running game,
+side by side with the chat: open it beside the chat where they are: your host's own browser when it has one (Cursor's, Codex's), else `npx @funpixel/tools dev --open` (the system browser, in its own tab).