@funpixel/tools 0.0.0-stage → 0.1.0

package/plugins/robin/skills/funpixel-gdd/references/as-built.md

@@ -0,0 +1,40 @@
+# Part 2: the game as built
+
+Part 1 is the plan and its reasons. Part 2, once the game runs, is the game: written from the code,
+not from memory of the plan. From then on, where the two disagree Part 2 wins, and Part 1 is
+corrected or points to the Part 2 section that replaced it. The test of a good Part 2: someone new
+to the game could rebuild it in another engine from Part 2 and the tests alone. The
+team's robot game passed that test: its Unity port matched the web build exactly.
+
+## What it holds
+
+| Part | From the code |
+|---|---|
+| World, step, units | the unit, the fixed step and its cap, the random generator and how it is seeded, the order of one step, the rule that the simulation imports nothing from the renderer |
+| Each actor | every constant with its unit (speed, radius, health, cooldown), its state machine, its tell, strike and recover times, what it emits |
+| Levels as data | the data shape, one real level in it, and the level laws each checked by a test (every room reaches the exit; finishable with no upgrades; resources at least 1.3 times what a median bot uses) |
+| Events and saves | every event the simulation sends the view; the save's fields and version; what a suspend or resume keeps |
+| Performance | frame, draw-call, light, memory and download budgets per device, and how the game degrades before the device does |
+| The behaviour contract | tests named after the rules they pin, a determinism test (same seed, same inputs, same events), bots over several seeds |
+
+## How to write it
+
+- Read the constants file, the step function and the tests, not the design. Copy numbers with
+  their unit and the file they live in.
+- Rewrite rather than patch: a Part 2 that starts as the plan's targets and is edited toward the
+  code keeps plan numbers nobody checked.
+- Keep a drift list: each number where the code and Part 1 differed, which one won, and why. A
+  deliberate change is a decision; an accidental one is a bug to decide on.
+- Name what is not built yet as not built. A planned feature stays in Part 1 until a test or a
+  recorded playthrough shows it running.
+- Write each value beside where it lives (`src/tuning.ts · FUSE_S = 3.0`), a shape a short script
+  can compare to the code on every build (The Hot Gates checked 213 numbers that way). Where a value
+  moved from its target, "the reason was not recorded" is better than a guessed one.
+- Keep a list of the defects writing the spec found; writing Pocket Crew's found five.
+- Say what nothing has observed yet (unheard, never played on a phone, fun unproven) and leave the
+  person's own play as a question for them until it happens.
+
+The owner's platformer shows the moment it pays: after the first world was playable, the design was
+rewritten from the code as a port spec, and the bots that walk every level found design bugs (a
+ledge 0.2 units too high, a boss attack you could stand beside and never be hit by) before any
+person played.

package/plugins/robin/skills/funpixel-gdd/references/design-measures.md

@@ -0,0 +1,24 @@
+# The design measures
+
+`npx @funpixel/tools gdd` ends with six numbers read off the GDD, each with why and the peers' figures. They come
+from the Don't Die field report (10 Oct 2026), and its owner's rule holds them: "Advise, never gate." Each is advice.
+Read them, decide what to do, and leave the call on the game's size and scope to the owner. A dense, systemic game
+can be the choice; the lint then says "dense: is each element learned (used again after its teach)?", never "too
+many".
+
+A field the GDD does not have is **not given**: no verdict, never a failure. Every field below is optional. Only
+`npx @funpixel/tools gdd --strict` makes a warn fail (exit 1), for a CI that asks for it; nothing in the kit passes
+it.
+
+| Measure | What it reads | The line |
+|---|---|---|
+| Elements per hour | `design/spec/elements.json` (`[{id, kind, name, debut_place, debut_beat_t, uses}]`), else `## Elements`, else the tables under `## Content` (`### Roster` and its kin, the player's row left out) | new mechanics, enemies, tools and systems ÷ first-playthrough hours; good games sit at about 1.4–3 (Prey 1.4, Scorn 2.2, Superhot 2–3); warns above about 4; any element used fewer than twice after its teach is "check by hand" |
+| The spine | `## The spine`: a `Spine:` sentence, clauses split by `;`, and a table of system, the clause it serves (quoted or by number), genre beat | a system that serves no clause warns: Don't Die cut the systems that mapped to none |
+| Sources | every table with a Source column (the identity lock's and the asset script's are pictures, not claims), footnotes `[^n]` with their `[^n]: …` line, `[source?]` markers | a marked claim with no source line warns; "approx, from memory" is kept and listed as secondhand; `gdd --sources` lists them all |
+| Peers | `## Worth against the genre` or `## Peers` | each peer's length and elements per hour: the report's figures where it has them, the GDD's own figure when its row carries a link, else unknown, never guessed |
+| Length totals | the parts' minutes: `design/spec/places/*.json` `target_minutes.first_time`, else a Length column in `## Chapters`, `## Places` or `### Stages` | summed against `Play length:` (or `**Length:**`), the difference shown; warns past 10% (or 2 minutes); the owner's `target_minutes` is shown, never judged |
+| Steam two-hour check | `**Hook at:**`, else a part marked `(hook)` (the hook lands as it begins), else the first timed row of `## The hook`; Steam named in `**Platforms:**` or `store/answers.json` | Steam refunds anything played under 2 h: warns when the GDD's own timeline puts the hook later; a first playthrough under 2 h is told to frame the first ending as one of several |
+
+Elements per hour uses the parts' summed minutes when every part has them (the report's method), else the stated
+length. The peers are games of hours, so a game under an hour reads dense by this rate; say so in the GDD when it is
+the choice.

package/plugins/robin/skills/funpixel-gdd/references/design-note.md

@@ -0,0 +1,88 @@
+# The design note
+
+The design note is the game's design document: `design/GDD.md`, from the template in skill
+`funpixel-gdd` (`references/gdd-template.md`), with `/design/` listed in `.harnessignore`. An older
+game's `design/README.md` is read the same way, with `design/gameplay.md` for tables that outgrew
+it; there is one document, never a note and a GDD beside it. A small game fills only the sections
+it needs. It is what the next session and the person read first, so it states decisions, not
+intentions. Update it when a decision changes; a stale note is worse than none.
+
+The hooks and funtools read these parts by name: `**Pitch:**` and `**The 6-second ad:**`, `## Look`,
+`## AD rules` (five numbered rules), `## Juice` (a table with a visual and a sound column), `## Actors`
+(a table with a Motion column), `## Criteria` and, only while a round is unfinished, `## Fix round`.
+`funtools gdd` mirrors every section of the template; `check_plan` grades the older short fields.
+
+What each line is for:
+- **The 6-second ad** keeps the pitch concrete: if nothing in the first seconds would make a
+  stranger tap, the concept needs a sharper hook before it needs code.
+- **Core loop** in one sentence tests the concept: a second "and also" means two games.
+- **Depth** is where a finished level still loses to the genre hit: critics picked the hit for a
+  longer, denser run and a reason to replay. Fill the `Depth:` line under the core loop from bot
+  runs; the options and genre numbers are in the game-logic skill's depth reference.
+- **The first minute** puts the signature on screen early: Dead Letter's first cut showed it at
+  3:45, and the fix moved it under 30 s.
+- **Juice** maps actual events to visible responses and explicit audio choices, including silence.
+  Remove inapplicable example rows: a loss or reward tier invented to fill the template is a
+  promise the game then has to keep.
+- **The player's journey** keeps the design about play: every later table serves that walk from a
+  visible start to the first payoff, through controls a stranger can find.
+- **Actors** describes the role, how it moves and its state feedback. Motion is `moves` (seen
+  moving), `animates` (its picture or pose changes) or `still` (it may rest: a board piece, a
+  sign). `scene --motion` samples about a second and judges each actor against that column; an
+  actor it cannot find is reported as not observed, and a still piece and a missing attack
+  response differ.
+- **Fix round** exists only while a round is unfinished: each open panel or player finding by
+  name with its next step. The Stop hook reads it to report an honest unfinished hand-back;
+  delete it when the round is done.
+- **Genre card and adaptation** (the GDD's header) record choices for continuity. Recipes do not
+  restrict the creator; derive the controls and checks from the intended game when no recipe fits.
+- **AD rules** are the art's pass/fail lines. Every prompt is built to satisfy them and every
+  capture is judged against them, so each must be checkable in one frame: a colour count, a line
+  weight, a size at which a thing still reads. "Moody" or "polished" is not a rule. Change one only
+  on purpose, and write the change here first.
+- **Criteria** say what a player must be able to see, each checkable from the running game with no
+  code open: a mechanic, how the run ramps, the feedback on a hit, what tells actors apart, how a
+  newcomer learns the goal. Agents fail most at feedback and presentation (research 15), so two
+  or more of those earn their place. `funpixel.json` takes strings or `{ "id", "kind", "text" }`; `funtools doctor` warns when a
+  made game has none.
+- **Open questions** hold everything you had to guess. Ask them in the hand-back, after the person
+  has played, not before you start.
+
+## Variety moves
+
+Left alone, an agent answers a brief with the average game for it: on one machine, two fresh games
+became a lantern on a night pond, and six shipped the same title card (centred panel, big word, pill
+Play, three round icons) in different colours. When a choice is still open, these are options, not
+steps; whatever the person fixed in their own words (a palette, a genre, a verb, a title) stays.
+One move per game is plenty.
+
+- **Write the obvious game down first,** and the version that only dodges it (darker, cosier,
+  colours inverted). Then pick something that is neither, or keep the obvious one on purpose.
+- **Flip one rule the brief never stated:** the player moves, time runs forward, the screen is lit,
+  the hero is small. Reverse one and see what the game becomes.
+- **Take a spine from another genre:** a racing line through a puzzle, a merge inside a platformer,
+  a rhythm to a builder.
+- **Find the verb outside games** (pour, fold, stitch, sweep, blow, herd) before the stock ones
+  (tap, jump, shoot); it often brings its own feel and sound.
+- **Change the stage, not the subject:** the hour, the material, the scale, the camera.
+- **Let the title screen be the game:** the world or the hero under the name, not a card over a
+  blur.
+
+`npx @funpixel/tools variety` measures the result against the other games on this machine
+(palette distance, core verb and genre, title-screen layout, motif nouns, title words) and names
+what is close; each signal is "not observed" when a side declares nothing. Record a move you made
+with `npx @funpixel/tools decide`, so the next session keeps it. Naming the reflex and flipping one
+rule are ideas from scenario-labs/skills (MIT; THIRD_PARTY_NOTICES.md).
+
+## As-built truth and the runbook
+
+Read [gameplay-contract.md](gameplay-contract.md) when filling the gameplay tables. Values come
+from the simulation constants, not a second independently maintained set of numbers; once the game
+runs, the GDD's Part 2 is written from them (skill `funpixel-gdd`). Label a planned feature
+`planned` until a test or a recorded playthrough shows it running. `check_plan` checks the older
+note fields; a pass does not validate these tables.
+
+Keep `design/runbook.md` as a small table: step, status (`planned`, `active`, `proved`, `blocked`),
+source revision/fingerprint, test or capture path, finding, next action. At session end record the
+literal resume command, outstanding jobs/assets and spend actually recorded. A generated target
+or agent verdict is not the person's approval; link their actual decision or say `not reviewed`.

package/plugins/robin/skills/funpixel-gdd/references/experience.md

@@ -0,0 +1,92 @@
+# Experience: what the design decides before any picture
+
+A still frame shows the look, the HUD and a readable moment. It cannot show whether skill grows,
+whether new things keep arriving, why anyone comes back tomorrow, who wants what, which places a
+player would describe to a friend, where a session breathes, or what the one idea is. Our games
+reached their genre hits on stills and still lost the head to head on "a dense, escalating score
+attack", "puzzles that take minutes" and "ten minutes that keep escalating". Those are design
+decisions, and cheaper to make in the GDD than to discover in a playtest.
+
+Seven questions follow, each with why it matters (a fact about a hit), the evidence that will
+measure it once the game runs, and a slice-sized answer. Answer the ones this game needs, in its
+own words, in the GDD's `## Experience` block; a toy may answer two, a three-hour game all seven.
+None is a requirement: a calm game may have no arc of danger, a pure systems game no story, and
+saying so on purpose is an answer. `funtools gdd` reports which you answered, outside its 0–10.
+
+## Depth and mastery
+
+*What does a skilled player do that a new one cannot, and how far apart are they after ten runs?*
+Pac-Man Championship Edition's director changed only the mazes and the speed, and in DX a reviewer
+saw ghost trains of more than 30 behind an expert. Celeste's golden strawberries ask for a whole chapter without a
+death. Measured by `funtools sim` (skilled, naive and novice bots on the rules: progress, wins,
+run length) and `funtools feel` (the verb's windows). Slice-sized: one risk that pays (a bigger
+chain from a closer shave), and a skilled bot that goes clearly further than a naive one.
+
+## Content and progression
+
+*How many distinct things are there, and when does each arrive?* Celeste debuts one to three
+mechanics a chapter and remixes them all in the last; Monument Valley builds each level on a
+different central mechanic; Hollow Knight has 164 journal entries and 47 bosses. Measured by
+`funtools depth` (the design's content tables against what real play reached, places and firsts
+a minute, the longest stretch with nothing new). Slice-sized: three stages that each add one idea
+introduced alone, and a debut column in the content table. A one-level slice cannot score high
+here, and should not pretend to.
+
+## Replay
+
+*Why would a player come back tomorrow, and what would they do first?* Vampire Survivors carries
+27 permanent upgrades between 30-minute runs; Balatro has 15 decks and 8 stakes to clear with each;
+Suika Game has daily, monthly and all-time leaderboards and nothing to unlock. Measured by the
+blind player's long session (`funtools play --long 10`), which ends with exactly that question.
+Slice-sized: a best to beat that is visible on the title, a seed or a mode that changes the next
+run, one unlock the first win earns.
+
+## Story and storytelling
+
+*Who wants what, what turns, what pays off, and how much of it does play tell?* Hades returns
+Zagreus to the House on every death and the story moves on there; Celeste's reconciliation with
+Badeline is also the double dash; Monument Valley 2 tells a mother parting from her child and their
+reunion through its levels, with no voiced line. Measured by the experience seats from the text a player can read
+(`depth`'s `text.md`), the beat strip of real play and the GDD. Slice-sized: a want on the title or
+the first screen, a turn the level's mechanic carries, a payoff on the end card; no cutscene needed.
+
+## World building
+
+*Which places would a player remember, and what rule does each have of its own?* Hollow Knight's
+City of Tears rains without end and Kingdom's Edge falls with ash, each with its own creatures;
+Celeste's chapters are one mountain climbed, each with mechanics of its own. Measured by the
+places real play reached (a `place` field in `__FPX_STATE__` lets `depth` count them) and the
+frames. Slice-sized: one place with a landmark and a rule of its own, and a second place glimpsed
+(a door, a view, the next chapter's colour on the end card).
+
+## Emotional arc and pacing
+
+*Where does tension rise, where does it rest, and what is the peak?* Vampire Survivors' clock is
+its arc: Arcana chests at 11:00 and 21:00, the Reaper at 30:00; Hades' drums enter with combat and
+stop at its end; Celeste's sixth chapter stops for a quiet campfire scene. Measured by `depth`'s pacing
+timeline (a `tension` field from 0 to 1 in the state draws the arc; without one it is not measured)
+and `sim` timelines for music that follows play. Slice-sized: ramps with a rest between them, one
+peak, and a quiet moment after it.
+
+## Originality
+
+*What is the one idea the genre hit does not have?* Balatro turned poker hands into a roguelike of
+multiplying jokers; Vampire Survivors made movement the only input; Suika Game is derived from an
+earlier Chinese merge game and, by our reading, won on polish, price and streams. A familiar genre done
+exceptionally well is a valid answer; say which you chose. Measured by the experience seats and
+the head to head against the genre hit. Slice-sized: name the signature in the promise and make it
+the first minute's payoff.
+
+## Target frames tied to moments
+
+The critic panel never sees the plan, so it cannot see a missing seam, a walker drawn at arm's
+length or a stencil drifted off its colour; the fidelity seat in `funtools playtest` can, if each
+target frame names its moment and its intent. The template's target-frames table carries both, and
+a game frame to set beside it: a declared view (`view firstWalker`) or a journey mark
+(`journey chapter1 walker`).
+
+Shoot the moment the plan means, not a fixed timestamp: the walker at the six metres the target
+drew, the splice as it completes, the chain at its longest. A view whose `enter()` replays a
+recorded run to that beat, or a journey mark placed at it, lands there every time; a clock time
+drifts the first time the level changes. Where the plan's words and its own picture disagree (the
+plan names a miss of its target), the plan wins, and the fidelity seat is told so.

package/plugins/robin/skills/funpixel-gdd/references/first-look.md

@@ -0,0 +1,226 @@
+# The first look and the greenlight
+
+It comes in two steps. **First, two pieces only:** the key art (the game's look in its own light,
+at the play framing, kept as a target) and the hero's reference sheet; the owner steers them in the
+chat, and the first playable is built from them (the `key-look` and `prototype` stages). **Then,
+while the whole game is planned around what they played,** the WHOLE game is settled as pictures and
+pages, never a few frames of one place. `npx @funpixel/tools firstlook` names this game's set, grouped: Look, Screens (the title as the play world, pause, the end, and what `## Screens`
+names), HUD (phone and desktop), Places & story (a frame per place, named at its beat), Living world,
+Animation, Juice, Sound (the GDD's `## Audio`), Fun (the GDD's `## Core loop`, or a `## Fun` of its own:
+loop, goals, streaks, cadence, and the arc at the game's length; a nugget's is why a second run). Places
+and the living world only for a world game. The worth read (`greenlight worth`) comes between the two
+steps: after the owner played the first playable, before the rest of the set is made. Reuse what exists. Every picture is a target the build is later judged against, never an engine capture: generated,
+or, for a look drawn in code, composed from the game's own draw code (below, "Drawn in code"). Paid
+Funpixel jobs (240 to 360 credits per past first look): read the estimate first and ask above 50
+credits.
+
+## What to make, and what each piece settles
+
+| Piece | From the GDD | It settles |
+|---|---|---|
+| Reference sheets, first | the recurring designs: hero, companion, vehicle, pursuer, the thing carried | one turnaround each (front, side, back), drawn from the best draft; every later picture is drawn to them |
+| Key art | the title screen and the thesis | the mood, the palette at full strength, space left for the title |
+| 4 target frames | four rungs of the moment ladder, each a whole frame from the game's camera | camera height, the hero's share of the screen, colour as assignment, the AD rules in a real composition |
+| A picture per place | `## Places`, for a game of several levels or areas, and a chart of the world | each place's sky, air and landmark; that the places read as one world and not one level repainted |
+| The world's kit | the places' structures, ground, props and living cast | `kit-*` sheets cut clean (`funtools cut`); the slice is built from them, never plain shapes |
+| The cast sheet | the roster, one line-up at one scale | silhouettes that read alone, one family of shapes, which two actors look too alike |
+| The phone HUD mockup | the HUD section and the controls | where the thumbs rest, what sits on the actor, whether pause has a corner |
+| The title and the HUD, dressed | the UI section of the look (skill `funpixel-art`, ui.md) | the wordmark, the plates and the icons as the world's own art; the title as the game's first promise |
+| ~8 sound cues | the sound sheet, in the world's words | whether the vocabulary makes usable sounds; which cues must be composed in code |
+| 2 music clips | the music identity, written once, at two tempos | whether one identity holds from calm to tense |
+
+A frame that breaks an AD rule is the most useful result: it shows a rule the prompt does not yet
+enforce (a decorative colour that means harm, a rival that borrows another game's look). Fix the
+style words or the rule, redraw that frame once, and write what changed into the GDD (v0.2).
+
+## Identity lock first
+
+Make each recurring design's sheet from its best draft before anything else, then draw every picture
+to the sheets and one verbatim style block (Blue Freight: seven of seven redraws on-model). Drift
+check: frames side by side, each design part by part (hair, outfit, silhouette, colours, a vehicle's
+shape); `funtools judge identity <frames…> --concept ref-hero.png` asks a seat. Keep a before/after
+of each redraw, then list the honest breaks. Details: [world-and-identity.md](world-and-identity.md).
+
+## With funtools assets (one manifest, one lock, an estimate first)
+
+Name the pieces `look-*` in `assets/assets.json` with an `out` under `design/first-look/`, so the
+style file composes every prompt, the game's style lock (the game's id in `funpixel.json`) keeps the
+pictures one family, and the lock records what each cost. A sheet is a `ref-*` item with `pins`
+(the design in words); a picture naming it in `references` gets those words verbatim, is made after
+it and goes stale when it is redrawn. The hosted image tool takes no sheet pictures yet: the words
+carry the lock there. `assets process` leaves `design/` alone.
+
+```json
+{ "items": [
+  { "name": "ref-hero", "kind": "image", "size": "1536x1024", "subject": "<turnaround on a plain ground: front, side, back of the hero>", "pins": "<the hero in words: hair, outfit and its colours, silhouette, what she carries>", "references": ["design/first-look/draft-2.png"], "out": "design/first-look/ref-hero.png" },
+  { "name": "look-keyart", "kind": "image", "size": "1536x1024", "subject": "<the title moment>", "references": ["design/first-look/ref-hero.png"], "out": "design/first-look/keyart.png" },
+  { "name": "look-frame-1", "kind": "image", "size": "1536x1024", "subject": "<0:10 on the ladder, from the game camera>", "references": ["design/first-look/ref-hero.png"], "out": "design/first-look/frame-1-first-input.png" },
+  { "name": "look-place-harbor", "kind": "image", "size": "1536x1024", "subject": "<the place: sky, air, landmark>", "out": "design/first-look/place-harbor.png" },
+  { "name": "look-cast", "kind": "image", "size": "1536x1024", "subject": "<every actor in a row at one scale on a plain ground>", "out": "design/first-look/cast.png" },
+  { "name": "look-sfx-hit", "kind": "sound", "subject": "<source, material, action, space; one event, no music, no voice>", "variants": ["a", "b"], "params": { "duration_seconds": 0.8 }, "out": "design/first-look/sfx/hit.mp3" },
+  { "name": "look-music-title", "kind": "music", "subject": "<the identity, written once> at <tempo>", "out": "design/first-look/music/title.mp3" }
+] }
+```
+
+```
+npx @funpixel/tools assets gen --only 'look-*' --dry-run   # every prompt as sent, and the estimate
+npx @funpixel/tools assets gen --only 'look-*'             # asks above 50 credits
+npx @funpixel/tools gdd page                               # design/GDD.html and design/first-look/index.html
+```
+
+A variant (`_a`, `_b`) lands beside its sibling; keep the better take by measurement (loudness,
+onset, silence), and note the pick. With the
+Funpixel MCP instead: `generate_image`, `generate_sound` and `generate_music` with the game's id,
+each file saved to the same paths.
+
+## Drawn in code (budget 0, or the owner's code-drawn look)
+
+The first look comes from the code the game draws with, so pictures and game are one family. Keep
+the drawing in a module (`src/draw/`, one palette file) and write `design/first-look/draw.html`: a
+module script that imports it, stages each picture at the play framing (1280 × 720, 852 × 393; a
+sheet 1536 × 1024) and sets `window.__FPX_FIRSTLOOK__` to an async function returning
+`{ "<name>": "data:image/png;base64,…" }` (`canvas.toDataURL`, Pixi's `renderer.extract.base64`).
+Names as the set reads them: `keyart`, `ref-<hero>`, `frame-…`, `cast`, `animation`.
+
+```
+npx @funpixel/tools firstlook render     # the game's Vite serves the page; each study → design/first-look/<name>.png
+```
+
+- **Relaxed:** no estimate, 50-credit ask, `look-*` items or style lock. The draw module is the
+  identity lock (the sheet is the hero's own function in its views and states) and the palette file
+  is the style block. Sound is composed in code; `## Audio` lists it the same.
+- **Kept:** a study is a staged composition, never a frame of play (`capture` is evidence, not a
+  target); the hero's sheet and the key art first, the owner's look before the first playable, the
+  key art as its target.
+
+## When the image tools are down
+
+A 401, a hosted tool that does not answer, no MCP: the plan goes on without generated pictures.
+
+- Tell the owner, with the error, and keep writing the GDD: the invention, the numbers and Part 2
+  need no pictures.
+- Stand in with code-drawn place vignettes or `firstlook render` (the game's own draw code, above),
+  each captioned a stand-in on the page and in the GDD.
+- Put "pictures owed: <which>" in `## Open questions`; make them when the tools are back.
+- Never fake a picture: no capture of play as a target, no stand-in named as finished.
+- `funtools whoami` checks the sign-in; `funtools login` signs in again.
+
+## The HUD mockup
+
+Write `design/first-look/hud.html`: one target frame as the background of a landscape (852 × 393)
+or portrait (393 × 852) screen, the HUD and touch controls drawn over it in HTML at the phone's own
+points, each numbered, with a legend saying what each is and where the thumb rests. It decides placement,
+not polish: 44 px targets, the notch side and the pause corner are drawn to scale.
+
+Dress it: the plates, the icons and the type are the UI section's, not the scaffold's dark pills.
+The title gets its own target (`look-title`, the game's scene behind a wordmark made in the world),
+and so can the HUD in play (`look-ui-hud`); they are pictures, judged like the frames.
+
+Other key screens (a message screen, the end card, a map) are drawn the same way, each in its own
+`<div class="phone">` (or `data-mockup="name"`) with a `.scr` child and the legend beside it. `funtools playtest` renders each one and hands it to
+the UI fidelity seat beside the game's same screen, so name the game's view in the GDD
+(`| Screen | Mockup | Game frame |` with `view messageScreen`). Open a screen that waits for input
+through a view: a still presses past it.
+
+## The page
+
+`funtools gdd page` writes two pages. `design/GDD.html` is the design document to read and rate (what
+it holds, and the studio's pages it is judged beside: [pages.md](pages.md)); show it whenever the
+document changes. It also writes `design/first-look/index.html` from the folder: the sheets (`ref-*`), key
+art, frames, places (`place-*`), the cast, the HUD mockup, sound and music, each with its brief and
+credits, the GDD's `## First look` bullets, and what is still missing. Show it to the person.
+
+## Afterwards
+
+Copy the accepted gameplay frame to `design/target.png` (the target the hooks and critics read),
+write `## First look` into the GDD (what settled, what changed, the cost), bump the version to v0.2
+and move the track's stage to Greenlight (or Style test when you skip it).
+
+## The style bible and the review in the chat
+
+The plan is judged by the owner in the chat, with the first playable in hand; the panel judges the
+built game at hand-back. Two pieces make that review worth having:
+
+1. **Style bible** (`design/greenlight/style-bible.md`, the art director's): a named direction,
+   palette as roles, shape language, material and light, how every asset gets made, the HUD's place
+   in the world, the directions tried, and one target frame per phase of play plus a HUD mockup.
+   - Try several directions and push a plain one up with a concrete note ("too simple: richer
+     colour, lit edges, more contrast") before accepting any; the first image is rarely the one.
+   - Each asset route is generated (2D or 3D), authored, or procedural with a rendered study from
+     the engine as its proof. "Primitives for now" is a stand-in, never a route. One workable split:
+     environments procedural from one source of truth, heroes (vehicles, characters) as models on
+     the same simulation.
+   - Targets are gameplay, not posters: the game's own camera, the player, the thing to beat, room
+     for the thumbs, at the phone's aspect. One per phase (a racer: the start, an overtake, the
+     drift and boost, the results), an establishing wide frame among them, and the player's view.
+   - Once the person accepts a target, pass it as the style reference for every later image of the
+     game (`generate_image` references and the style lock), so the art stays one family.
+2. **Think it through together in the chat.** Show the person the first look there: each target
+   frame, the HUD mockup, the cast and the GDD sections they belong to (`gdd page` writes
+   `design/GDD.html`, the plan as a page they mark up and agree to a section at a time). Take their notes in
+   the chat, revise every one in a single pass, bump the GDD's version with a `## Versions` row, and
+   say what changed per note. When they are happy, the lock is `flow ask`, then their yes recorded
+   with `flow agree --by owner "<their words>"`.
+3. **Reference-match rounds.** After the lock, `funtools playtest`'s fidelity seat holds the build
+   to the locked targets, the establishing view first, then the player's; its top fixes are the
+   biggest differences between the accepted pictures and the running game.
+
+`funtools gdd` prints the ambition lines: how the heroes get made, the targets, the owner's lock.
+For a showcase-grade game, run the creator on the strongest model you have as well.
+
+```markdown
+# Pitches · <game>
+**Brief:** <the person's words>
+
+## P1 · <name>
+- **Do:** <verbs the player has, before any look or tech>
+- **Feels like:** <session length, hands, pace, the feeling>
+- **Hook:** <one sentence>
+- **Signature moment:** <the moment a trailer opens on>
+- **Tell a friend:** <"you have to try the bit where…">
+- **Not generic because:** <what the genre's default game does not have>
+- **Concept:** design/greenlight/concept-p1.png
+```
+
+```markdown
+# Style bible · <game>
+**Direction:** <name> — <one sentence>
+
+## Directions tried
+| Direction | Frame | Note | Kept? |
+|---|---|---|---|
+| <first try> | design/greenlight/dir-1.png | <too plain: what to push> | no |
+
+## Palette
+<#hex role, one per line: ground, hero, threat, reward, UI ink>
+## Shape language
+<silhouettes, corners, proportions; what reads at 40 px>
+## Material and light
+<surfaces, the light, the grade; how the hero catches it>
+## Asset routes
+| Asset | Role | Route | Proof |
+|---|---|---|---|
+| <the hero> | hero | <generated 3D (generate_3d_model), animated> | |
+| <the track> | environment | <procedural from the level data> | design/greenlight/study-track.png |
+## HUD direction
+<where it sits in the world, the type, how dense; what lives on the actor>
+## UI
+<the world's material and edge for plates and buttons, the display and body faces, one icon family
+drawn like the art, colour roles with their contrast, how panels enter; the UI pieces made as art>
+## Screens
+| Screen | Its look in the world's kit | Its one job |
+|---|---|---|
+| <title> | <the scene, the wordmark carved or lit, the start as a thing of the world> | <start in one tap> |
+## Target frames
+| Moment | Target | Intent | Game frame |
+|---|---|---|---|
+| <establishing: the whole course> | design/greenlight/frame-1.png | <what it pins> | <view vista> |
+| <player's view: the first overtake> | design/greenlight/frame-2.png | <…> | <view overtake> |
+
+**HUD mockup:** design/greenlight/hud.png
+**Title target:** design/greenlight/title.png
+```
+
+Adapted ideas, in our own words: several visual directions iterated with concrete notes, one
+approved target per game phase, procedural worlds with modelled heroes, and the brief before the
+tech (OpenAI's "How to build games with Astra").

package/plugins/robin/skills/funpixel-gdd/references/floors.md

@@ -0,0 +1,62 @@
+# Complete-game checks
+
+Use these checks for the agreed complete-game scope. They guide implementation, not the genre,
+art style or feature list. A focused asset or mechanic task does not inherit this whole checklist.
+
+The hooks treat a session as a complete game when it began without a game, when the person used
+the new-game command (`/fp:new`, `$fp-new`, `/fp-new`) or asked to finish or complete the game,
+when it wrote the game's first design note, or when the game carries `.funtools/complete-game`.
+`funtools init` writes that marker and an in-scope session keeps it, so a new chat on a half-built
+game keeps the checks; a Stop with nothing open or deferred removes it. Delete it to end the scope.
+
+## The release bar, in short
+
+What the team's best shipped games had in common (research 08, 17, 20), each with why:
+- coherent art and readable actors, scenery and UI in the chosen medium;
+- every row of the juice table in the game, with its limits (skill `funpixel-game-feel`);
+- the signature on screen within about 30 seconds, and controls taught where first needed (Dead
+  Letter's first cut showed its signature at 3:45);
+- a signature-moment view (`moment: true`) that plays the payoff, since critics judge stills
+  (skill `funpixel-verify`);
+- the full screen set: a real title, how to play, settings (sound, motion), play, pause, and the
+  designed resolution and retry (no invented loss state for a lossless game);
+- a HUD that reads at phone size;
+- readable core-action feedback, with audio where the brief calls for it;
+- keyboard and touch both wired, a gamepad where the genre expects one;
+- a rules test suite that passes, recorded on the current files by `npx @funpixel/tools test`.
+
+## Presentation and operation
+
+- Provide a clear entry, objective, working input, relevant pause/settings and the designed
+  resolution or continuation. A lossless puzzle needs no invented defeat; an endless game can
+  record `endless` or `no win` in the note. Expose relevant states in `__FPX_VIEWS__` for capture.
+- Teach actual keyboard and touch controls where needed; support gamepad when promised. Check
+  thumb access, safe areas and HUD readability during the busiest meaningful action.
+- Show a loading state while needed assets arrive. Transitions may move or cut according to the
+  style and accessibility needs; they must preserve orientation and control.
+- Make core actions visibly readable, with audio where promised. Intentional silence is valid.
+  Respect reduced motion and provide controls for sound, shake or flashes when used.
+- Test meaningful rules with `npm test`, real-input verification and blind phone play. Test count
+  alone proves nothing. Name missing evidence, including physical-device performance or sound.
+
+## Engagement
+
+- Identify what the player learns, chooses and anticipates. Escalation can add a new demand or
+  deepen an existing one; some games deliberately offer a calm, consistent activity.
+- Give failure a readable cause and recovery route where failure exists. Test first encounters
+  for fair reaction time and accidental taps; do not substitute visual polish for control fixes.
+- Choose a session length and replay reason for the audience. A satisfying finite puzzle does
+  not need a leaderboard or an endless reward ladder.
+
+## Opening and payoff
+
+- Make the first meaningful action easy to find and acknowledge it promptly.
+- Choose when the central experience should arrive, then measure the opening in real play.
+  A first score at five seconds or payoff at thirty can be useful arcade targets, not universal
+  rules for narrative, simulation or creative play.
+- Capture the actual payoff through the game's rules at phone and desktop sizes. A staged
+  illustration cannot replace working gameplay.
+
+The local hook checks a limited set of declared views and evidence. Its warnings are neither a
+complete interpretation of these checks nor release certification. Finish the agreed goal, fix
+observed defects and carry remaining uncertainty honestly into review.

package/plugins/robin/skills/funpixel-gdd/references/frame.md

@@ -0,0 +1,75 @@
+# The frame: needs → systems
+
+Every game needs the same basics around its rules: a title with a real Play, news the player can
+read, input on both doors, a save, a pause when the phone rings, a HUD clear of the notch. The
+starters carry each one as a small part. Keep a part, restyle it or replace it with your own: the
+table is what any replacement must still do, and `npx @funpixel/tools check` measures each row
+(warnings only; it never blocks). A part still as `init` wrote it holds by construction; a part you
+replaced is measured for its basic, and a replacement that lost one is named with the need.
+
+| Need (what the player gets) | Starter part | What check reads |
+|---|---|---|
+| News read one message at a time, never over the middle of play | `toasts.ts` message lane | a lane in the code (`toast()`, a read-time floor, `aria-live`) |
+| A title that is a scene, with a real Play | `screens.tsx` | the start control marked `data-fpx-start` |
+| A gesture on a phone, keys on a desktop, for every verb | `input.ts` | pointer or touch input and keys |
+| Progress survives a reload; boots where storage is blocked | `save.ts` | a `SaveManager` or a stored progress key |
+| An old or corrupt save falls back, never a crash | `save.ts` | a versioned save with defaults |
+| Paused and quiet when the tab hides | `platform.ts` | `visibilitychange` or `__FPX_HOLD__` |
+| The HUD in the safe band, clear of the notch and home bar | `frame.ts` | the band (`--band-*`, `__FPX_FRAME__`) or safe-area insets |
+| The page reaches under the notch | `index.html` | `viewport-fit=cover` |
+| The 3D world keeps its frame rate on a phone | `budget.ts` | a frame budget or a capped pixel ratio |
+| A level list, when the game has levels | `levels.ts` | `LEVELS` as data, the furthest reached in the save |
+| The look as one value | `look.ts` + `look.json` | the look read from one file, a line per fallback |
+
+`check --phone` adds what only a phone shows: pieces under the notch, the status bar or the home
+bar in every declared view (the audit-screens insets), and the HUD's cover of the play (`look
+--hud`). Code reading proves a part exists; the phone run proves it works.
+
+## The safe band
+
+`frame.ts` measures the band on every resize and rotation: the phone's own safe-area insets, never
+under the floors a phone needs even where the browser reports 0 (48 px on the notch sides held
+sideways, 48 px over the status bar held upright, a home-bar margin below). It publishes
+`--band-top|right|bottom|left` for the stylesheets and `window.__FPX_FRAME__ = { band, play }` for
+the game: keep world markers and floating numbers inside `play`. The HUD row, the pad, the message
+lane and the title's sides read the band, so a rotation moves them all.
+
+## Levels
+
+A game with more than one level, chapter or stage keeps them as data in `levels.ts`: id, name, an
+optional par and an optional `file` that `funtools reach` reads. The furthest reached and the ones
+done live in the save, so a reload returns there; a won round completes the level being played.
+`check` warns when the GDD's content list plans several levels and the code keeps no list.
+
+## The look
+
+`src/look.json` holds the UI role tokens the stylesheets read (`bg`, `ink`, `plate`, `plate-ink`,
+`accent`, `button-ink`, `font-display` …). `look.ts` applies it at load and logs one
+`[frame] look fallback: …` line per token it cannot apply; `check` reads those lines.
+`npx @funpixel/tools look set plate-ink=#3a2618` refuses an unknown token (naming the closest) or a
+bad value, and every write prints each text/background pair's contrast with a proposed ink for any
+that fails. `look report` reads the file as the game does. The prose half of the look (material,
+never, moods) stays in `assets/style.json`'s `ui` block (skill `funpixel-art`).
+
+## The first minute and the idle run
+
+`check` plays an idle run: Play through the real front door, then no input for 20 s. It records
+when the player had control, every death and how the run ended (`.funtools/idle.json`), and warns
+when an idle player dies sooner than the genre's floor after the first control. `hook` adds the
+clock: seconds from load to the first control, the first success and the hook moment, against the
+genre's defaults and the GDD's `## The hook` table.
+
+| Card | Idle floor | First control | First success | Hook moment |
+|---|---|---|---|---|
+| arcade, shooter | 8 s | 10 s | 30 s | 60 s |
+| platformer | 10 s | 10 s | 30 s | 60 s |
+| survival | 10 s | 15 s | 30 s | 60 s |
+| racing | 15 s | 15 s | 30 s | 60 s |
+| puzzle, card | the whole run | 10–15 s | 45 s | 90 s |
+| strategy, simulation | the whole run | 20 s | 60 s | 90 s |
+| rpg | the whole run | 30 s | 60 s | 120 s |
+
+A game that means otherwise states its own numbers in `funpixel.json` `firstMinute`
+(`{ "idleFloorS": 3 }`) and says why in the design note. The clock reads `__FPX_STATE__`
+(`control`, `screen`, `dead`, `lives`, `score`, `wins`, `success`) and the moment marks
+(`window.__FPX_MOMENT__?.('the valley opens')` at the payoff).