@funpixel/tools 0.0.0-stage → 0.1.1

package/plugins/cursor/skills/funpixel-gdd/references/invent-first.md

@@ -0,0 +1,131 @@
+# Invent first, then fill the template
+
+Two plans were written from one brief on 1 Oct 2026 (a first-person paint shooter in
+a museum at night). The plan that followed this skill's template was clearer (8.4 against 8.1) and
+more buildable (7.2 against 6.4), and lost 3 of 3 blind seats, 7.0 against 8.0. It trailed on level
+design by 1.8, story and world by 1.7, fun by 1.2 and phone controls by 1.0. It spent its extra
+seven minutes on process: more pictures, two judged rounds, a gray box. The winning plan spent its
+time on design: what the paintings mean (they watch the thieves, so they are radar, conscience and
+stakes at once), rooms that differ, enemies that bend the rule, a villain whose want is half right,
+14 cited sources and about 75 named behaviour tests. The template's sections scored the losing plan
+10 out of 10 complete. Completeness is not design. So the order is: invent, research, pitch and
+pick, then the template.
+
+## 1. Six forcing questions
+
+Answer each for this game, in `## The invention`, before any other section. A generic answer is a
+sign the idea is not there yet: rewrite it until it names something only this game has.
+
+The examples are for a different game (paper boats racing down a rainy gutter) on purpose: answer
+for yours; never borrow an example's answer.
+
+| Question | A generic answer | An answer that invents |
+|---|---|---|
+| What the core object means | "boats to race" | each boat carries a child's message home; a sunk boat loses a line of it |
+| Why the verb exists in this world | "racing is fun" | the storm drain swallows the street's mail at dusk; only a boat gets a letter home before it |
+| Who wants what, by name | "the rival wants to win" | Odile wants her letter read before the move; the gutter-keeper wants the drains clear, and he is half right: blocked drains flood the houses |
+| What the twist costs, in feeling and in play | "it's harder" | a lost line is a message that never arrives (feeling); the next race starts with less paper (play) |
+| The one system that lives and reacts | "ambient rain" | the rain on the window: it is the race clock, it floods the shortcuts, and it eases when you help another boat |
+| What only this game has | "a unique art style" | the current: where you let go decides the race, not how fast you steer |
+
+The living system earns its place by a job in play the player reads and uses (warns, shows,
+remembers, blocks, opens). Decoration that does nothing is a wonder, named as one, or cut.
+
+**Widen before you answer.** Every agent asked one brief reaches for the same first idea. Run
+`npx @funpixel/tools pitch widen` (a new seed per session, printed; `--seed N` replays a draw;
+`--dial tight|open|wide` sets how far the cards go). It draws four or five cards, each an operator
+(break one unstated rule, blend, read the brief through another domain, ban the first three
+associations), a domain and a facet per axis, near to far, with one labelled wildcard. Answer each
+card in `design/widen.json`, then `pitch widen score`: each answer, and `## The invention`, against
+the control (the generic answer for this brief) and against what was kept before. A high number is
+distance, not quality: strange is not unexpected unless it still answers the brief. Keep the card
+you pitch with `pitch widen keep W2`; the wow ledger (the game's and `~/.funpixel`) steers the next
+run of this brief away from it, and a repeat is a warning, not a refusal.
+
+## 2. Research: a hit per axis, with a source each
+
+One genre hit is not research: for a first-person shooter the kit's default bar was a top-down
+survivor game, and its verdict could only read "not observed". Each axis has its own best game, and
+the best one for touch controls is often outside the genre.
+
+| Axis | What to find |
+|---|---|
+| mechanic | the game whose core decision is closest to yours |
+| feel | the controller numbers people praise (aim, jump, weight) |
+| touch controls | the best phone answer to this verb, even from another genre |
+| layout | rooms or levels that teach by their shape |
+| surface satisfaction | the one sound, splash or snap players remember |
+| readability | how threats, targets and the goal read at phone size |
+| market | what sells in this genre, its price and its reviews' complaints |
+
+Write each as a row of `## Hits, per axis`: the hit, what we take, what we avoid, and a link to the
+source (a store page, a talk, a review). Name what was left out unverified. `funtools gdd` lists the
+axes with no row and the rows with no source.
+
+## 3. The studio pitch: pitch, pick, lock
+
+Then pitch the choices that shape the game as cards (`npx @funpixel/tools pitch`, or on the Plan
+Canvas): genre and fidelity, depth (5 minutes, 30 minutes or chapters), the core that burns
+(gameplay fun, the world, the story or the feel), the story standard (none, light, or deep: goal,
+clock, question, antagonist, frame), extras with their cost (voice per character, cutscenes, photo
+mode, multiplayer, and for a deep game two takes: two parallel builds of the locked plan, played
+side by side from the title by `npx @funpixel/tools compare-takes`, the mix keeping what each won;
+on one game, one take won the environment and the other the dynamics). Propose a pick per card with its reason for this game
+(`pitch propose core world --why "…"`); the plan shows your picks and the owner approves them with it
+at the lock (`flow ask`). Under their autonomy "ask", each card is theirs instead: `pitch ask` posts each
+as a question in the chat, and `pitch lock` waits for their answers. From then on the core gets the art budget, the tests and the hardest checks, and
+what was not picked stays light. Autonomy is the OWNER's setting (funpixel.json `flow.autonomy`,
+from their brief), never a card you propose: under `ask` and `plan-then-go` every pitch card waits
+for their answer; only their `go` lets you pick, record each pick with its reason, and lock.
+(One game, 4 Oct: under "ask" the agent proposed and locked all seven cards itself.)
+
+## 4. Named behaviour tests, before code
+
+Part 2 is written now, as targets, and rewritten from the code once it runs: the numbers, a state
+machine per actor that decides, the level or room data as a file, events and saves, and the rules
+as test names under `### Behaviour tests`:
+
+- `a miss lands on what is behind the target`
+- `every attack tells for 0.6 s or more before it lands`
+- `the first input comes within 5 s of Play`
+
+`funtools gdd` counts them and `funtools test` reads them back from the test files, naming those not
+written yet. A name is a promise the build can be held to; prose is not.
+
+A name that states a player goal ("a new player wins the round within 20 s") is also played:
+`funtools test --goals` writes `test/goals/<id>.json` (how met shows in `__FPX_STATE__`, a route,
+caps), replays the route and asks a fresh agent seat, and answers met, not met, blocked (stuck or
+unable to act) or not observed, citing the sentence. A goal nobody could observe has no verdict.
+
+## 5. Our lessons, as defaults
+
+Defaults from our best games. Each is a starting point: keep it, or say why this game differs.
+
+- **Modelled places.** Rooms built as geometry with their own shape, not one corridor repainted
+  (`funtools variety --within` compares the place pictures).
+- **A GPU device tier.** Pick quality by the phone's GPU and recover resolution when frames drop;
+  budgets as p95 frame times.
+- **Every attack tells.** A wind-up the player can read, 0.6 s or more on a phone.
+- **Teach once, at the element.** The first time a thing appears it teaches itself in place; no
+  manual screen.
+- **A player-owned camera.** It follows on its own and never fights the player; look-drag is an
+  option, not a chore.
+- **Controls off the play.** No button over the play area or the held object; one gesture per thumb
+  zone.
+
+## 6. What waits for later
+
+These cost time at plan stage and did not pay; they belong to the slice:
+
+- **Scaffolding before the design.** `funtools init` before the GDD names the genre and the controls
+  wrote third-person conventions and arrow-key checks into a first-person game. Write the GDD to
+  its genre card and controls, then scaffold.
+- **A gray box and identity redraws.** A 3D gray box and redraw loops belong to the slice, after the
+  plan is applied.
+
+## Check it
+
+- `funtools gdd`: the invention answered or generic, hits per axis, named tests, the locked core,
+  then a lint of missing sections (no score).
+- `funtools pitch`: the cards, the picks, what the locked core still asks of the GDD.
+- `funtools test`: the named tests read back from the code.

package/plugins/cursor/skills/funpixel-gdd/references/level-and-fun.md

@@ -0,0 +1,112 @@
+# Levels, a world that plays, fun and the phone
+
+Where a plan made with the kit lost to the owner's own workflow (one game, 1 Oct 2026: two
+GDDs from one brief, three blind judges, 7.0 against 8.0). The kit's plan led on clarity and
+feasibility and trailed on level design (−1.8), story and world (−1.7), fun (−1.2) and phone UX
+(−1.0). Every judge named the same four things, so this page is those four, with what our best
+games did. Options with reasons; the creator's vision wins.
+
+## 1. Places that differ
+
+The kit's six galleries each had their own rule on paper, and their six pictures showed one teal
+hall with gold frames and the same parquet. The winning plan's rooms differed in **plan shape, wall
+colour, era and light** (a long red gallery, an enfilade of small green cabinet rooms, a grand stair,
+a glass court with a fountain, a white cube, a dark rotunda lit by one lamp), and the judges saw it
+in the pictures before reading a word.
+
+| Each place gets | Why |
+|---|---|
+| Its own **plan shape** (corridor, enfilade, ring, stair, open court) | the shape changes the decisions: sightlines, cover, where a threat can come from |
+| Its own **material and colour** | a player knows where they are from one frame; a still that could be any room is a reskin |
+| Its own **era or story** | the place says something about the world, not only the level |
+| Its own **light** (one key light, its colour, how dark) | light is the cheapest way to make two rooms feel unlike each other, and it sets the mood the rule needs |
+| Its own **rule that bends the core verb** | the room changes what the verb means (a room whose every wall is one painting: any miss hits art, so you aim low or lure the target out) |
+
+Write the place row before drawing its picture, and draw each picture from its row. Then hold the
+pictures to each other: if two could swap captions, one of them is not a place yet.
+
+**Shape of a level.** Teach the new thing alone, test it, twist it, then combine it with what came
+before (teach, develop, twist, test, celebrate). One game gave each of its eight islands one
+rule; another debuts each of its nine kinds alone at the head of its wave before it
+joins a crowd (41, 82, then 100 robots per floor). A third calmed its level after watching the
+gray-box: a plan is allowed to lose to the game in front of you.
+
+**Layout laws as tests.** The winning plan wrote its rooms as data with laws a test can read: a
+bare-wall share per room (the kit's plan had one too: 70% in the first gallery, 20% in the second,
+which is a difficulty curve you can measure), a longest sightline, at least two routes to a target,
+no spawn in view. A law in a table drifts; a law in a test holds.
+
+One place on purpose is an answer. Say so in `## Places`, and the mirrors stay quiet.
+
+## 2. A world that answers the core verb
+
+The judges' deciding line, three times over: the winning plan's paintings were alive. Their eyes
+followed the nearest thief within 20 m, so the art was the radar (there was no minimap); a splashed
+subject covered her face and stopped helping, so a miss cost a point and a friend; each room's
+keeper did one more thing (a dog barks, a figure points). One system did three jobs: **radar,
+stakes and conscience**. The kit's living-world table produced a cat and motion lights.
+
+Ask of the world: **what does it do when you play?**
+
+- **One living system with two or more jobs in play.** Information (where the threat is), stakes
+  (what you lose), feeling (who you are protecting). If it only decorates, it is scenery; scenery is
+  fine when named as such.
+- **The rule works both ways.** The thieves aimed at the guard, so if she stood in front of a
+  painting their misses hit it: where you stand protects the art behind you as much as the art
+  behind them. A rule the enemies are also bound by doubles the decisions for free.
+- **An antagonist whose want is half right.** The winning plan's villain had a reason a player could
+  agree with; the judges called him sympathetic and scored the story 1.7 higher. A villain who is
+  only evil gives the story nothing to turn on.
+- **Enemy kinds that bend the core rule**, each read by silhouette at 40 px. In the winning roster
+  one kind is a painting to the gun (auto-fire skips him), one sidesteps after 0.3 s of lock so your
+  burst flies into the art, one always perches against a dark backdrop, one carries a canvas as a
+  shield. Each asks a different question of the same verb. The kit's roster was one striped body
+  with five props: one enemy in five coats. One game's "one chassis, nine heads" works
+  because each head is a different idea, not because the chassis is shared.
+
+## 3. Fun with depth
+
+| Ask | A strong answer | Where it showed |
+|---|---|---|
+| How many decisions a minute does the verb make? | every shot is a choice about where you stand | the winning plan: "the game rewards the step before the shot" |
+| What is the boring optimum, and what makes it lose? | named, with the rule that beats it | panic-firing pays nothing; in one horror game, welding every door runs you out of gas |
+| Does risk pay? | a riskier line scores more, never only costs more | one game's kill ladder (10 in 2 s up to 100 in 3 s, slow motion on the top rung) |
+| What does each verb cost? | a price in time, resource or the route | the horror game: hold 1.5 s, 25 gas, and the room beyond is gone |
+| Why play the next room? | it asks a new question of the same verb | each kind debuts alone (the nine-kind game above) |
+| Why play again? | a grade, a medal for clean play, a best to beat | the winning plan's results screen grades splashes, and only your own cost the clean-hand medal |
+
+The horror game added weapons only when each answered a different situation, all drawing on one canister;
+two answers to the same situation are one tool wearing two looks.
+
+## 4. Phone UX: two thumbs, 852 × 393
+
+The phone is where a plan is cheapest to fix and most often lost.
+
+- **Controls off the play and off the held thing.** Both plans first put Fire and Cover on the gun;
+  the kit's HUD v2 moved them to the right edge and shrank the gun to a sixth of the screen.
+  Whatever the hero holds is part of the frame budget; a mockup that breaks its own cap breaks it in
+  the build. One game's HUD covered 41% of the phone screen until it was measured.
+- **One gesture per thumb zone.** The winning plan put aim, tap-for-cover and hold-to-wipe all in
+  the right thumb's zone: three gestures that collide. Give each zone one gesture, or make one a
+  button.
+- **An assist that keeps the point.** The kit's plan asked for a tap-tap-breathe fire rhythm while
+  auto-fire set the cadence, so the rhythm could not be played on a phone. The winning plan's
+  steady mode let the gun change rhythm itself: with art inside a 4° cone behind the target, bursts
+  became single shots at half the spread, flagged by gold corners. The assist never aims at what the
+  player must not hit. Two of three judges took it.
+- **First input by 0:05.** The kit's plan got this right (first input 0:05, first payoff 0:25); fold
+  loaders and first-run screens into the title.
+- **A warning the phone player needs is not a crutch.** The concept seats removed the art warning;
+  the frames seats asked for it back. On a 6-inch screen a dense wall cannot be read at a glance:
+  a tell that replaces reading is the design, not a hint.
+
+## Check it
+
+Free mirrors that read these, each a mirror, never a gate:
+
+- `npx @funpixel/tools gdd`: the places, living-world and content rows, thin ones named.
+- `npx @funpixel/tools variety --within`: the game's own place pictures beside each other; a pair
+  that reads as one room is named.
+- `npx @funpixel/tools reach`: every exit, pickup and target reached from its spawn.
+- `npx @funpixel/tools sim`: the boring optimum and the skill spread, per level.
+- `npx @funpixel/tools phone`: the controls and HUD on a real phone viewport.

package/plugins/cursor/skills/funpixel-gdd/references/pages.md

@@ -0,0 +1,47 @@
+# Pages made for the game
+
+The plan page (`design/GDD.html`, from `gdd page`) is the base every game gets. It is not the only page a
+game can have, and it is not a template every page must follow: the studio's own design documents differ
+from game to game, each designed for what it has to show.
+
+The plan page draws the level map itself when the game has its levels as data (`design/spec/rooms.json`, a
+`build_level` spec): rooms or areas as boxes, routes, the critical path, where to look. A game with no level
+data gets none; a map drawn by hand is a page of its own.
+
+## The bar: the studio's best GDD pages
+
+The owner judges a plan page against the studio's own bespoke design pages, not against the base
+`gdd page` writes. Ask the owner for them (one is kept locally by the owner, the others by link),
+name them when you show yours, and say where yours falls short.
+
+What makes them strong, and how much of it `gdd page` draws:
+
+| Strength | `gdd page` | What the agent adds by hand |
+|---|---|---|
+| The board: where the game stands | drawn on top (done, doing now, next, your move) from the flow's status | keep `## Where we are` current, in the owner's words |
+| An honest "how fun will it be" read | not drawn; `greenlight worth` answers the length only | a `## How fun will it be` section: what is fun already and how you know (played, measured), what is still a guess, the biggest risk to the fun; below the bar when it is |
+| Owner-decision rows | drawn under the board as "Yours to decide": one row per bullet of `## Open questions`, with `— recommend: …` as our pick and `decided: …` (or `[x]`) as the owner's call | write each open question as one decision with a recommendation, never a vague worry |
+| A playable feel toy in the hero | not drawn (the plan page has no script) | a page of its own whose hero is the core verb live on a canvas, tuned to `## The numbers`, so the owner feels the plan before it is built; link it from `## Linked pages` |
+| Part 2 as tables | tables are drawn as tables | write each actor's numbers, states and events as tables, not prose |
+| The behaviour contract by group | drawn as written | group the named tests under `####` sub-headings in `### Behaviour tests` (input, the core rule, the living world, the phone…); `funtools gdd` still counts them |
+
+Pictures drawn in place: write a target and its capture as paths in one table row and they sit side
+by side. What those three pages hold beyond the strengths above is not written here: never describe
+one from memory as if you had read it.
+
+## Pages of its own
+
+Make a page of its own when a part of the plan reads better drawn than written:
+
+- a board of where the game stands, a cast sheet, a map of the places, a level's layout, a HUD mockup,
+  a timing chart, a comparison of two looks, the pitch as one screen;
+- in the game's own look: its palette, its type, its key art; not the kit's;
+- one self-contained HTML file in `design/pages/<name>.html`, pictures by relative path from the game's
+  folder (`../first-look/key-art.png`), no network, a `<title>` that says what it is;
+- linked from the plan's `## Linked pages` with one line on what it shows and what it is for.
+
+A host that draws the game (Robin's game bench) lists every page in `design/`, `design/pages/` and
+`design/first-look/` by its title, opens it beside the conversation, and lets the owner write notes on any
+part of it; those notes come back as their words on the plan, the same as notes on the plan page.
+
+Rewrite a page when the plan it shows changes; never leave one saying what the plan no longer says.

package/plugins/cursor/skills/funpixel-gdd/references/plan-at-size.md

@@ -0,0 +1,140 @@
+# The plan at the size of a real game
+
+The owner's good games named their whole content before code: four to ten areas, four to ten kinds
+of enemy or piece, a boss, endings, story beats, and 70 to 250 assets made under one frozen look.
+Our weaker games planned one level and discovered the rest while building, which is why they read
+well in stills and thin in play. This reference is five offers for step 2 of the path (planning
+together in the chat). Each is a default the creator can resize, and any of them can be
+declined; a decline written down is a decision, not a gap.
+
+## 1 · A content list, sized to the game
+
+What play must reach, counted. It goes in the GDD's `## Content list`:
+
+```markdown
+## Content list
+| Content | Count | Names | Reached in play |
+|---|---|---|---|
+| Areas | 4 | the Gutter, the Drain, the Culvert, the Harbour | |
+| Enemy kinds | 6 | leaf, bottle cap, rat, grate teeth, cat paw, eel | |
+| Bosses | 1 | the Storm Grate | |
+| Endings | 2 | out to sea; home in the puddle | |
+| Story beats | 5 | launch, the drain, the dark, the grate, the sea | |
+```
+
+- **Why counts:** a count is something a playtest can hold play to. "Six kinds" is either reached
+  by a blind player or it is not; "varied enemies" never fails. The `Reached in play` column is
+  where later rounds write what play actually got to, so a claimed kind and a reached kind stop
+  looking the same.
+- **Size it to play length:** a game is at least 15 minutes of real play by a first-time
+  player, even with one level: escalation (a new idea per stage, not only speed), variety, a twist
+  around the middle, and an ending worth reaching. Write the `Play length:` line and count the
+  content that fills it (two of our games: "at least 15 minutes play, to be a game", owner,
+  3 Oct); a 2-minute arcade round is a choice the line states "on purpose". `funtools sim` holds
+  the skilled bot's run to that line and asks that it reaches the ending, and `playtest experience` fills `Reached in play` for areas,
+  levels and waves from the long blind player and the bot (marked `(measured)`). Play reaching half
+  the claimed areas or less is a warn: one game claimed 8 worlds and play reached 2.
+- **Size it to the game:** a one-screen toy can honestly say "Levels 1"; say that it is the choice
+  in the list ("one screen on purpose") and the ambition read leaves it alone. A full game names
+  its areas, kinds with a debut each (the `## Content` roster), a climax and at least one ending.
+- **Names over numbers alone:** a named area is an idea; an unnamed one is padding.
+- **A row and a picture per place** under `## Places`: its atmosphere, the one play number it
+  changes and its landmark. `funtools gdd` warns when a counted level has no row.
+- On the canvas the list is a wide tile stamped with its totals ("4 areas · 6 kinds · 1 boss"),
+  and `funtools gdd` prints it beside the score under "ambition".
+
+## 2 · An art budget
+
+How many assets of each kind the content list needs, and how each gets made. `## Art budget`:
+
+```markdown
+## Art budget
+| Asset | Count | Made how | Credits |
+|---|---|---|---|
+| Boats (hero and rivals) | 4 | generated 2D sheet from the style file | 40 |
+| Area backdrops | 4 | generated plates, three layers each | 60 |
+| Enemies | 6 | generated sprites, one family | 48 |
+| Icons | 12 | inline SVG, one family drawn like the boats | 0 |
+| UI plates and buttons | 3 | generated from the style frame, nine-sliced | 6 |
+| Wordmark | 1 | generated in the world's material | 2 |
+```
+
+- **Why:** the owner's games made 70 to 250 pieces; ours made 0 to 21 and drew the rest in code.
+  A budget makes the gap visible before it ships, and lets the creator choose it on purpose.
+- **The UI is art too:** plates, buttons, frames, the icon family and the wordmark are rows like
+  the cast (skill `funpixel-art`, ui.md).
+- **Every row has a route:** generated (2D or 3D), authored, or procedural with a rendered proof.
+  "Shapes for now" is a stand-in to name, not a route.
+- **The size is the creator's.** Scope, time and spend belong to them: their own subscription
+  pays for the host's time, Funpixel credits pay for our paid tools. The kit never shrinks a game
+  to save either; the plan is as big as the person agrees on the canvas. A code-drawn look is a
+  choice they may make, with a style test to prove it reads, never one made for them.
+- **An honest estimate:** fill `Credits` from `npx @funpixel/tools estimate` or
+  `assets gen --dry-run`. It prices only Funpixel's tools, never the host's time. The canvas stamps
+  the tile with the total ("26 pieces · about 148 credits"), so the person agrees the plan knowing
+  what its art would take. Anything above 50 credits is still priced in one line before it starts.
+- **Running out is a pause.** If the credits run out mid-plan, say so plainly with what is left
+  to make; the creator can top up and continue the agreed game. It is never an ending, and never a
+  reason to cut the scope they agreed.
+
+- **Rolled up from an asset script.** Each picture as a row (what, the story beat it serves, the
+  sheets it was drawn to, cost, status), each family of game assets in the same shape; the budget is
+  their totals, so a row added to the script is a row the budget already counts
+  ([world-and-identity.md](world-and-identity.md)).
+
+## 3 · The art direction, in a few clear lines
+
+The creator's own look, written as three to six lines a viewer can check in one frame. They live
+under `## AD rules` (the hooks and the fidelity seat read that heading):
+
+```markdown
+## AD rules
+1. Only the player's boat is tomato #FF5A4E.
+2. Every threat reads at 40 px on the wet grey ground.
+3. Rain never covers the lane the boat is in.
+```
+
+- **Offer them and explain why:** every playtest round, the fidelity seat judges each line held,
+  partly held or broken beside the target frames. Without lines, "does it still look like the plan"
+  has no answer. One game's six lines caught a darker art pass that hid its threats.
+- **They are the creator's words.** Offer drafts from the pitch and the first look; the creator
+  rewrites, keeps or cuts them.
+- **Declining is fine, and kept:** `Declined: I will judge the look by eye (the creator, 30 Sep)`.
+  The canvas shows "declined, on record" and nothing asks again.
+
+## 4 · A style test on a scale sheet, before building
+
+After the first look, lay the cast at play size on the real ground colour:
+
+```
+npx @funpixel/tools look --sheet --sizes 24,48,96 --ground '#3A4048'
+```
+
+Free and local. It measures each sprite's contrast against the ground (ΔE) and shows the sheet.
+Read each art line against it: a threat that merges with the floor, two kinds in one colour, a hero
+lost at 24 px. Fix the style words or the line, redraw once, and write the verdict per line into
+`design/style-test.md` (skill `funpixel-art`). Code-drawn casts get the same test: render
+them once to PNGs.
+
+## 5 · Pause points, never gates
+
+Moments that invite someone to look: after the plan is applied, after the first look, after the
+first slice. The someone can be a friend, the owner, a player, or the creator's next-morning self.
+Offer the pause, record who looked and what they said in the GDD's `## Pause points` table, and
+carry on either way. One game waited four days for its owner's "go ahead"; another built twenty
+minutes after its approval; a third never paused and still reached its gate. The pause is there
+because a second pair of eyes is cheapest before code, not because the path needs permission.
+
+## 6 · The plan grows with the game
+
+Size the plan, and what you ask, by the game's length ([start](start.md), production-tiers.md):
+a nugget's plan is its core sections and one lock; a short game adds the content list, places and the
+story; a long game adds `## Chapters` (one row per chapter: place, what it adds, story beat, length,
+target frames), the world map and the story arc, and each chapter is planned and agreed with the owner
+when the build reaches it, never all at once up front.
+
+## In the chat
+
+Show the content list, the art budget and the art-direction lines with the look. The person's notes
+land on them like anything else ("a fifth area at night", "the eel as a 3D model", "line 2 is too
+strict for the dark level"); revise them with the rest, and the lock agrees them with the rest.

package/plugins/cursor/skills/funpixel-gdd/references/production-tiers.md

@@ -0,0 +1,117 @@
+# Production at the game's size: three loops, one dial
+
+A small arcade game and a two-hour story game are made with the same three loops. What changes is how
+far each one turns. **Direct** says what the game should be and keeps every hand pointed at it.
+**Keep consistent** makes every piece look like it belongs to one world. **Verify** proves it plays,
+from the rules up to a stranger holding a phone. The tier is that dial, read from the plan. It is not
+a ceiling and not a recipe: the games below are what each setting has looked like, as inspiration.
+The creator's choices win, and a game can turn one loop up without the others.
+
+What is locked: the creative direction (the plan, target frames, identity locks, the palette and what
+each colour means, the style block, the story), the quality bar, and the outcomes. Rules replay from a
+seed where the game needs it. Frames hold on a phone. Nothing flashes the full screen. Assets look like
+one world. Nothing private ships. A blind player can play from the title. What is free: folder layout,
+file names, state management, which SDK modules you use, and how you reach each outcome.
+
+## How the tier is picked
+
+`funtools init` reads the creator's line and writes `production.tier` into `funpixel.json` and a
+`**Production:**` line into `design/GDD.md`, with its reasons:
+
+Said to the owner by length (stored as small, mid, deep):
+
+| Size | Length | First playable | The GDD grows to | The owner is asked | Built as |
+|---|---|---|---|---|---|
+| **nugget** (small) | a few minutes | about 1 min: the place, its look and feel, the verb once | the core sections | the brief, the first playable's verdict, the lock | one piece |
+| **short** (mid) | 15 to 30 min | 2 to 3 min | plus the content list, places, story | plus the story and the level list | the slice, then room by room |
+| **long** (deep) | an hour or more | 3 to 5 min: the core loop once, a win and a loss | plus `## Chapters`, the world map, the story arc, the cast | plus each chapter's plan and its verdict | the slice, the first chapter's rooms, then chapter by chapter |
+
+- **small**: no length, chapters or story stated, or a one-second mechanic (merge, one-thumb, endless),
+  however many levels.
+- **mid**: 15 to 59 minutes of play, a story, two chapters, or 3 to 20 levels in a game that is not a
+  one-second mechanic.
+- **deep**: an hour or more, three or more chapters, or 3D and story-led across five or more levels
+  or half an hour.
+
+The tier is the size of the production, not a licence to be short: every tier plays at least 15
+minutes to an ending (the floor `sim` holds, funpixel.json `play_min_minutes`). A small game reaches
+it with escalation, variety and runs; a mid or deep one with places and chapters.
+
+`funtools check` prints what the dial means for this game today (notes and warnings, never a
+failure). When the GDD grows past the recorded tier, it says so once. Set `production.tier` by hand
+and that wins.
+
+## Direct
+
+| Setting | What it adds | Seen in |
+|---|---|---|
+| small | The GDD and one target frame of the moment that sells the game; the meta layer (stars, collection, a map of levels) planned with the mechanic, not after it. | Four casual puzzle games: a one-second mechanic, a meta layer, many levels. |
+| mid | A target frame per place or level, the story's beats as ids the game reports, progress saved per level or chapter, and a runbook of what proves each step. The plan is also a spec folder the game loads (`design/spec/`: every number in `tunables.json`, rooms and chapters as data with pars, slice first; `funtools spec init`, skill `funpixel-gdd`, references/spec-folder.md). | One game (`GAME.md`, `QUALITY_BAR.md`, design addenda per pass), another (`RUNBOOK.md`, `runbook.json`), a third. |
+| deep | A making-of log (`design/MAKING.md`: decision, numbers, lesson, one entry per lane). Show first: films or a proofs page the owner picks from, then build behind a flag, measure, merge. One lane per worktree. | One game (`design/MAKING.md`, `PERF.md`, frames at 0:10, 1:00, 2:00 as the definition of done), another, and one game's plan. |
+
+Lanes at deep: `npx @funpixel/tools lanes plan` splits a build stage into lanes, each with a brief,
+its own paths, a spend cap, a time-box and a merge gate; `lanes merge` lands one only after a seat
+that did not build it passes it and the owner has picked between any candidates (`/fp:lanes`).
+Lane hygiene, from one game's builder. Use one worktree per lane, never `git stash` (it is
+shared across worktrees), and never rewrite history. Never run two headless Blender jobs at once:
+their dialogs land on the owner's screen. A stale build fools a screenshot, so rebuild before every
+capture. The owner's screenshots become named before-frames.
+
+## Keep consistent
+
+| Setting | What it adds | Seen in |
+|---|---|---|
+| small | One palette in code (a `palette.ts` or the style tokens) and one verbatim style block every generation carries. | The studio's casual games. |
+| mid | Reference sheets before any art (`ref-*` in `assets/assets.json`). Several draws per item, the most on-palette one kept (`assets gen` scores each by hue against the palette and warns under 55%). Every provider original kept in `assets/raw/`, with a line per job in `assets/costs.jsonl`. Colour ownership: one colour, one meaning. | One game (`tools/luminance.mjs`, `contact-sheet.mjs`, `asset-coverage.mjs`), another (`ASSETS.md`), the harness games' `forge.mjs` palette scoring. |
+| deep | Identity locks for every recurring design (GDD `## Identity lock`, skill `funpixel-gdd`). The 3D line: reference images, then the model, then the original kept with its request id and seed, then cleanup on the bench, then two tiers (phone and HD). Hard-surface pieces are rebuilt or baked from the high-poly onto clean geometry. A decimated AI mesh looks melted, and no shader fixes it. Materials are normalised in code and in the files. | One game (`sources/`, `design/assets.md`, models and models/hd), another (raw art kept with request ids and seeds), a third (seven redraws on-model at the first try once the sheets existed). |
+
+## Verify, the QA loop
+
+| Setting | What it adds | Seen in |
+|---|---|---|
+| small | Rules tests with a seed (same seed and inputs, same round), `verify`, `look --hud` at phone size, `feel`, and one blind phone player. | Every funtools starter ships the seed test. |
+| mid | Bots on several seeds through every level (`sim`, per-level curves; `rooms` for a spec folder's rooms, each against its par), a replay test, a boot test where storage throws (the starter's `test/platform.test.ts`), and fixed-framing before and after on every visual change: `capture --all` then `compare` at desktop 1280x720 and phone 844x390, plus a short film (`clip`). | One game (`src/test/sim.test.ts`, `platform.test.ts`, `tools/release-check.mjs`, `bless-check.mjs`), another (`scripts/screen-audit.mjs`, `smoke.mjs`, audio pause tests), a third (`src/test/`). |
+| deep | Blind phone players from the title, with no view jumps, as the gate a panel cannot replace (a wrong kit fact sank one version that panels passed). An interleaved A/B phone profile: 844x390 at 3x, CPU slowed four times, a fixed seed, reading p95, long frames and mid-play shader compiles (`profile --viewport phone --throttle 4 --seed 7 --compare`). Evidence per lane in the making-of log. | One game (`design/PERF.md`, `tools/profile.mjs`, `tools/compare.mjs`), another (a 3.7 s splash fooled the captures; the fixes were level design: practice zones, camera volumes, a landing ring). |
+
+## One structure that has worked
+
+Not required; the outcome is what checks read. The owner's deeper games split an engine-free
+`src/sim/` (fixed step, seeded, cloneable, so a save is a `structuredClone` and bots play whole
+chapters) from `src/view/` (the engine draws the sim and decides nothing) and `src/ui/` (Preact
+screens and HUD). Tests drive the sim with bots on several seeds. Every view lane can then prove the
+sim untouched. The funtools starters keep the
+same split in small: `rules.ts` engine-free and seeded, `game.ts` drawing it.
+
+The 3D starter's quality tier follows the GPU, never `pointer: coarse` (one game's
+`src/view/device.ts`). A desktop window in touch emulation reports a coarse pointer and would get the
+phone's budget; the touch layout still follows the pointer.
+
+## Beyond deep
+
+Bigger games are not a different method: an online world, a massively multiplayer game or a live game keeps the same three
+loops at a higher setting, plus systems of its own. The server decides what is true (server
+authority). Content pipelines run at scale (generated chunks kept only when bots reach them, skill
+`funpixel-game-logic` content-at-scale). Live operations add events, balance patches and telemetry.
+Start from the multiplayer relay and `@funpixel/sdk/multiplayer` (skill `funpixel-game-spine`).
+
+## The upload contract
+
+This applies only when the game will be uploaded to Funpixel (`funtools pack`, `publish`, the
+Studio). A game hosted elsewhere is free of it. `init` scaffolds it, and `pack` and `publish` warn
+when an item is missing, naming the tool that would break:
+
+| Item | Who reads it |
+|---|---|
+| `package.json`, `index.html`, `tsconfig.json`, `src/` at the root; no nested project | the builder (pnpm, `tsc`, vite) and `crates/funpixel-linter/src/game_layout.rs` |
+| generated art and sound under `public/assets/` | the Studio's file tree and runtime URLs (`game_layout.rs`) |
+| `funpixel.json` | publish and the Studio |
+| `__FPX_STATE__`, `__FPX_VIEWS__` | verify, capture and the hosted probe (`fpx-hooks.ts`, `HOOKS.md`) |
+| `__THREEJS_RENDERER__`, `__THREEJS_SCENE__`, `__THREEJS_CAMERA__`, or `__PIXI_APP__` | the inspector and profiler devtools |
+| the engine bundled from `dependencies` (no CDN, no import map) | the preview's engine mapping (`engine_gate.rs`) |
+| `.harnessignore` | the staged copy `funtools pack` and `publish` upload: notes, tools, raw art, tests and env files stay private |
+
+The builder passes `--base ./` and replaces `vite.config.ts` with its own, so keep shipping values
+in `src/`. `pack` also flags leak words (vendor names, scratch paths), dependencies that are not plain
+semver, and tooling packages in `dependencies`.
+
+A showcase-grade game runs its creator on the strongest model you have, as well as its critics.