@funpixel/tools 0.0.0-stage → 0.1.1

package/plugins/kiro/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/kiro/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 (one game: 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/kiro/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 (one
+  game'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/kiro/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).

package/plugins/kiro/skills/funpixel-gdd/references/gameplay-contract.md

@@ -0,0 +1,81 @@
+# A playable contract
+
+A theme and a list of effects do not specify a game. Write the choices a player learns, the
+pressure that changes those choices, and the evidence that they work. Keep a small finished slice;
+cut roster breadth before cutting its response, readability or fair first encounter.
+
+## Content and progression
+
+In `design/gameplay.md`, give every actor a row: name, role, distinctive silhouette, behaviour,
+warning, counter, debut, reward and source definition. Two enemies with different colours but the
+same movement and counter count as one behaviour. Add pickups with the choice they create.
+
+Give each stage a row: time or wave, actors, new demand, safe introduction, success condition,
+rest/recovery and visible announcement. Teach one demand alone before combining it. Difficulty
+can change spacing, priorities or resource pressure; a health/speed multiplier alone is not a new
+stage. Specify the climax: boss phases with tells, safe space and counterplay, or a final puzzle,
+race or chain challenge. A boss bolted onto a genre whose finish is a puzzle, a race or a chain
+reads as someone else's game.
+
+For a bee chain game, a first wave might teach aim against three separated targets with no
+contact damage until the first successful shot; wave two teaches a moving target, then combines
+it with the earlier type. State the actual timing, damage and recovery rules in constants. This
+is a proposal to test, not proof that the first wave is fair.
+
+## Controls and fairness
+
+Name the player action in pixels/second, travel time, cooldown, range and buffering where
+relevant. Write the reaction budget: enemy tell, distance to impact, escape speed and time left
+for a newcomer to react. Measure input-to-visible-response and choose a genre-appropriate bound;
+an animation wind-up can delay damage while an immediate pose/sound confirms the press.
+
+Make aim rules explicit on touch: tap position, drag direction or auto-aim priority. Test taps
+near both edges, a thumb covering the hero and simultaneous move/aim when offered. A wrong input
+must fail safely and visibly. On death, show the cause and the available counter, then make retry
+immediate. Check invulnerability, overlapping hits, corner traps and recovery between waves.
+
+## Payoffs and readability
+
+Where rewards escalate, distinguish meaningful tiers; a game that needs no tiers is better
+without them. For each, specify its trigger, reward and readable response, with sound if appropriate. A rare chain should build through successive beats rather
+than deliver every particle and number on one frame. Reserve the loudest composition for a
+player-earned peak; adding more shake everywhere destroys that contrast.
+
+Record budgets at the shipped phone viewport: hero size, critical threat size, foreground versus
+floor contrast, maximum effect coverage and score text size. Verify silhouettes while effects
+are active. A pretty sprite sheet is not evidence of a readable game: first compose the relevant player,
+interactive objects and hazards on the actual floor at their actual scales, then inspect it against the
+five AD rules. Save the sheet and the decision before making the rest of the cast.
+
+## Rules and evidence
+
+| Rule | Source of value | Outcome through input | Named test | Evidence |
+|---|---|---|---|---|
+| R1 cooldown | src/sim/rules.ts SHOT_COOLDOWN_MS | a second press before expiry cannot fire; one at expiry can | R1 cooldown boundary | test run path |
+| R2 recovery | src/sim/rules.ts WAVE_HEAL | closing a wave restores the bounded amount once | R2 recovery once, never above max | test run path |
+
+A test imports the real rule and advances the real simulation. It must fail if that rule is
+removed or its comparison is reversed. Test boundary values, the negative case, and repeated
+inputs; do not duplicate the formula in the assertion. Run a fixed input replay twice and compare
+state and emitted events. A table and an existing test file prove neither execution nor coverage.
+
+Keep a seeded novice simulation beside the skilled balance bot. The novice receives only the
+observation a player could have, reacts at a declared interval, and sometimes misses or hesitates;
+it cannot inspect future spawns, exact hidden state or a solver's answer. Freeze its policy and
+seed list before tuning. A floor used on one game's first wave: 100
+fixed seeds, at least 80 runs that both survive the stage and earn score. Record both counts, elapsed time,
+deaths by cause, policy parameters and failing seeds. Other genres state the equivalent first
+success and deadline before the run. This is a regression floor, not a human success estimate.
+
+Favourable seeds or a weakened novice after a failure turn the floor into a flattering number.
+Fix the game's controls,
+telegraphing or opening pressure, rerun the same cohort, then test an additional held-out cohort.
+The blind phone player must separately find the start, goal and verb and make progress using real
+input. An expert bot passing never substitutes for that observation.
+
+## Session continuity
+
+After each completed slice, update the as-built contract from source and record command, exit
+code, source fingerprint and evidence path in `design/runbook.md`. Keep intentions and observations
+separate. Record unavailable evidence as `not observed`, not a pass. Keep old failures so the next
+session can see what changed, and list what the person still needs to play or approve.