@funpixel/tools 0.0.0-stage → 0.1.1

package/plugins/kiro/skills/funpixel-gdd/references/gdd-template.md

@@ -0,0 +1,417 @@
+# The GDD template
+
+Copy the block below to `design/GDD.md` and write v0.1 before code or assets, starting with
+`## The invention`, `## Hits, per axis` and `## The studio pitch` ([invent-first.md](invent-first.md)):
+the rest of the template serves what they decide. It is the game's one
+design document: the short design note grown up. The hooks read four of its headings as they are
+(`## AD rules`, `## Actors`, `## Juice`, `## Fix round`) and `funtools gdd` mirrors every section,
+so keep those names; everything else is yours to rename, merge, reorder or drop. Delete a row the
+game does not need rather than inventing one to fill it: a puzzle has no boss, a calm game may have
+no loss. What makes each section strong or thin is in [sections.md](sections.md); the
+`## Experience` lines and the target-frames table are options explained in [experience.md](experience.md);
+`## Places`, `## Identity lock`, `## Getting around` and `## Asset script`, sized to the game (a line
+for an arcade round, the full tables for a game of many places), in [world-and-identity.md](world-and-identity.md). A `## The numbers`
+row whose words name a verb number (jump height in body heights, apex hang, time to top speed, dash
+distance, invulnerable window, cooldown, tell, death beat, restart) is read back against the running
+game by `funtools feel` (skill `funpixel-game-feel`, `references/measure.md`). `## The spine` and
+`## Elements` are optional; with the `Play length:` line, the chapters' Length, a `**Hook at:**` line and a
+`**Platforms:**` line they feed the design measures `funtools gdd` prints as advice
+([design-measures.md](design-measures.md)).
+
+**Sized by the tier, owned by the creator.** The core is short and always there: the pitch (the
+header), `## The invention`, `## The studio pitch`, `## Core loop` and `## The hook`. A small game
+adds the hits, the vision (the direction it grows toward, which the lock never freezes), the numbers, the first minute, the content list (its play length line is what `sim`
+reads), the living world, the look and its AD rules, actors, juice, controls and Part 2's behaviour
+tests. A mid or deep game starts at about that size: it adds only its spine (versions, scope, the build
+plan, open questions; deep also experience and the identity lock) and what its line names (places, a
+story). The rest waits under `## Grows with the game`: `funtools pitch lock` moves what the picks call
+for off that shelf, and `funtools flow` what the stage the build reaches calls for (the first look's
+art sections, the slice's places and living world, the walk's getting around). Add a section when the
+game needs it, never to complete the template. The
+stages and their gates live in `design/pipeline.json` (`npx @funpixel/tools flow`), not in this document.
+
+```markdown
+# <Title>
+
+**Version:** v0.1 · <date> · **Stage:** Design
+**Pitch:** <one line a stranger understands>
+**The 6-second ad:** <what someone sees in the first seconds that makes them want to play>
+**The player's journey:** <what they see first and press (the real control) → the first objective → the first payoff>
+**Genre card:** <card, or "none fits"> · kept: <camera, body, how a run ends> · adapted: <choices for this game>
+**Orientation:** <portrait | landscape> · **Input:** <keyboard, touch, pad>
+
+## Where we are
+<updated every round; the owner reads it here, in the chat's link to this file: the round and what it
+did; each target frame beside the game's capture at the same moment (picture links) and whether that
+beat is close; the biggest gap left and the next step; the preview link; the price approved and the
+credits spent; what the owner asked last, in their words, and what was done with it>
+
+## Where the build moved
+| What | The plan said | The game does | Why | The owner's word |
+|---|---|---|---|---|
+
+## Linked pages
+<everything lives in this document; a page made apart from it (a HUD mockup, an animation board, a cast
+sheet, a comparison) is linked here with one line on what it shows and what it is for>
+| Page | What it shows | What it is for |
+|---|---|---|
+
+## Versions
+| Version | Date | What changed | Why | The person's notes |
+|---|---|---|---|---|
+| <v0.1> | <date> | <first draft> | <the brief> | <what they said, in their words> |
+
+## The invention
+<six answers for THIS game; a generic one means the idea is not there yet (invent-first.md)>
+- What the core object means: <what it is to the people in this world, not its function>
+- Why the verb exists in this world: <who made it necessary, and what it costs them>
+- Who wants what (names): <the player's side; the other side, whose want is half right; the bystanders>
+- What the twist costs (feeling and play): <what the player feels, and what changes in play>
+- The one system that lives: <what moves and reacts to the player, and its two jobs in play: it warns, shows, remembers or blocks>
+- What only this game has: <the mechanic or the moment, not an adjective>
+
+## Hits, per axis
+| Axis | Hit | We take | We avoid | Source |
+|---|---|---|---|---|
+| mechanic | <the game whose core decision is closest> | <one thing> | <one thing> | <link> |
+| feel | <> | <> | <> | <link> |
+| touch controls | <the best phone answer to this verb, any genre> | <> | <> | <link> |
+| layout | <> | <> | <> | <link> |
+| surface satisfaction | <> | <> | <> | <link> |
+| readability | <> | <> | <> | <link> |
+| market | <price, what sells, the reviews' complaints> | <> | <> | <link> |
+Left out unverified: <claims we could not source>
+
+## Worth against the genre
+<3–5 of the genre's best; every number with a source URL in the row or "approx, from memory"; no prices or review counts. `npx @funpixel/tools greenlight worth` reads it against ## The numbers and ## Content list (references/worth.md)>
+| Game | Length | Distinct places | Verbs / mechanics | Characters | Progression / meta | Source |
+|---|---|---|---|---|---|---|
+| <a hit in this genre> | <~2 h, or endless> | <count> | <count> | <count> | <none, or what> | <link, or approx, from memory> |
+
+## The studio pitch
+<`npx @funpixel/tools pitch` writes this block from design/studio.json: genre and fidelity, depth,
+the core that burns, story standard, extras with their cost; you pick each with why and the owner approves
+them with the plan at the lock (under their autonomy "ask", each card is theirs: `pitch ask`); the work goes hard on the core>
+
+## The promise
+<the fantasy in two or three sentences: who you are, what you do, why it matters>
+The thesis in one frame: <one picture or one number that carries the game's meaning with no words>
+
+## The vision
+<five lines at most: the scale the game grows toward (places, length, cast, the size of the world) and the
+two or three set-pieces it builds up to. Never locked: the lock pins the numbers, controls and scope; this
+is the direction, and critics read it to name the next step toward it>
+
+## The spine
+<optional: the one sentence the game hangs on, its clauses split by ";", and every system against the clause it serves; a system that serves none is a cut to consider (design-measures.md)>
+Spine: <clause; clause; clause>
+
+| System | Clause it serves | Genre beat |
+|---|---|---|
+| <the system> | <the clause, quoted or by its number> | <the genre beat it carries> |
+
+## Pillars and references
+| Reference | We take | We leave |
+|---|---|---|
+| <a hit or an era> | <the one thing it gives this game> | <what would make this a copy or a chore> |
+
+- Pillar: <what the game must feel like, and the risk to it>
+- Decision: <a choice made against its alternative, and why, so nobody re-litigates it; `npx @funpixel/tools decide` gives it an id (D3) to cite here>
+
+## Core loop
+<one sentence: you <verb> <what> to <goal> while <what pushes back>>
+30 seconds: <the verb and its answer> · 5 minutes: <the ramp> · session: <why a second run>
+Depth: run length <m:ss> · events per minute <n> · first pressure at <s> · after the level: <score attack | endless | stages | daily seed | none yet> · best: <what is saved>
+
+## The numbers
+| Number | Value | Why exactly this |
+|---|---|---|
+| <the core timer, radius, cost or count> | <value with unit> | <what a smaller or larger value breaks> |
+
+Anti-degeneracy: <the boring optimum and the rule that makes it lose>
+
+## The hook
+The opening and the first minutes decide whether people keep playing: 2 to 4 wow moments on the
+clock, each proven twice (a fixed-framing strip beside its target, `npx @funpixel/tools compare
+--target`, and a blind player who mentions it unprompted).
+
+| When | Wow moment | What makes it land | Proven by |
+|---|---|---|---|
+| <title> | <the one picture people remember> | <light, motion, sound that sell it> | <strip title-phone.png; the player names it> |
+| <0:40> | <the world opens up> | <camera pull-back, the landmark rises, the bed swells> | <strip at 0:40; "the valley"> |
+
+## Opening
+<from Play, second by second: the title is a live frame of the play world, a cold open the engine acts (or none), then control by 12 s for a story line (10 s for arcade) with the objective and its distance on screen at that frame; `funtools hook` reads it back: first control, the objective at the hand-over, the shot on each row, every beat staged or HUD-only>
+
+Cold open: <the beat the engine acts before control: who does what, in which shot; or "none: Play hands over at once">
+First control: <0:08> · Objective on screen: <"Reach the lighthouse"> · Distance: <"115 m to go", or "none: an arena round">
+
+| When | Shot | What the player sees and hears | The player can | Proven by |
+|---|---|---|---|---|
+| <0:00> | <title> | <the play world behind the wordmark, alive> | <tap Play> | <hook: title vs play alike> |
+| <0:03> | <reveal> | <the beat, acted by bodies; the line captioned over the shot> | <skip> | <hook: the beat is staged> |
+| <0:08> | <play> | <the hero; the objective and its metres on the HUD> | <move> | <hook: control at 8 s, objective on screen> |
+| <0:20> | <play> | <the first payoff the player feels> | <the verb> | <hook: first success> |
+| <0:30> | <play> | <the signature on screen> | <the verb> | <hook: the moment mark> |
+| <5:00> | <play> | <the first real test> | <the verb> | <sim: the naive bot can lose> |
+
+## Shots
+<the camera plan: one row per moment, beat and target frame; each shot is a named entry in src/shots.ts (`shoot(name, seconds)` blends to it), so `funtools score --target` names the line to edit. In a first-person game a shot is where the player stands and looks when the moment happens on its own timing>
+
+| Moment | Shot | Lens | Height · distance | Motion | Target frame |
+|---|---|---|---|---|---|
+| <title> | <title> | <50°> | <7.5 m up, 21 m out> | <slow orbit over the play world> | <design/first-look/title.png> |
+| <play> | <play> | <50°> | <4.4 m up, 9.5 m behind> | <follow, framing 0.35 s ahead> | <design/first-look/play.png> |
+| <the first beat> | <reveal> | <45°> | <9 m up, 15 m behind> | <blend in 1.2 s, back in 0.8 s> | <design/first-look/beat-1.png> |
+
+## Wow
+<chosen before the build: one signature and up to three more from the genre card's wow catalogue (`funtools wow`), or invented as custom-<name>; `funtools wow pick` writes the rows and flags a signature another game already used, expressed alike; `wow check` reads each one's evidence>
+
+| Pick | Move | Expression | Why it pays off the pitch | Checked by |
+|---|---|---|---|---|
+| <signature> | <survival-chest> | <what this game makes of it: the subject, the axis, the payoff> | <how it pays off the pitch> | <event chest, or frame title> |
+
+## Content
+### Roster
+| Kind | Silhouette at phone size | Debut | How it bends the core rule | Tell |
+|---|---|---|---|---|
+| <threat, piece or pickup> | <reads by shape, not by a prop on one body> | <stage> | <the new decision it forces: sidesteps when locked, so the shot hits the art> | <warning and its time, 0.6 s or more> |
+
+### Stages
+| Stage | Adds one thing | Teach, test, rest |
+|---|---|---|
+| <level, wave, chapter> | <new demand> | <how it is introduced alone first> |
+
+### Climax
+<boss phases, each teaching a rule, or the final challenge this genre wants>
+
+## Content list
+<the whole game at its real size, counted; a playtest sets each count beside what play reaches. One level is fine when it is the choice: say so here>
+Play length: <minutes of real play for a first-time player to the ending, e.g. 15–20 minutes; 15 is the floor (funpixel.json play_min_minutes), a smaller scope or an endless round is a choice: write "on purpose" and why on this line> (`funtools sim` reads this line against the sharp bot's run)
+
+| Content | Count | Names | Reached in play |
+|---|---|---|---|
+| <areas or levels> | <count> | <each one's name> | <filled by playtests> |
+| <enemy or piece kinds> | <count> | <names> | |
+| <bosses or climaxes> | <count> | <names> | |
+| <endings> | <count> | <names> | |
+| <story beats> | <count> | <names> | |
+| <living world: who reacts, beds, set pieces> | <count> | <names> | |
+
+## Elements
+<optional: every new mechanic, enemy, tool and system the first playthrough introduces, one row each; `funtools gdd` counts them per hour of the play length (good games about 1.4–3) and names any used fewer than twice after its teach>
+| Element | Kind | Debut | Uses after the teach |
+|---|---|---|---|
+| <name> | <mechanic, enemy, tool or system> | <place or chapter, and the minute> | <where it comes back, or a count> |
+
+## Places
+<one row per level or area, each with its picture; one place on purpose is an answer: say so>
+
+| Place | Shape · material · era · light | In the air | Sound bed | The play number it changes | Landmark | Picture | Wow | Fun | Hook |
+|---|---|---|---|---|---|---|---|---|---|
+| <level or area> | <plan shape (enfilade, rotunda, stair), wall material and colour, era, light: no two places alike> | <what moves in the air> | <the bed> | <the one number, and how it is foreshadowed: kites flatten 0.8 s before a gust> | <what you walk toward> | <design/first-look/place-name.png> | <the one thing remembered or shared> | <what feels good to do here> | <why go on: a question, a promise, a reward ahead> |
+
+World chart: <design/first-look/chart.png, the whole world in one picture: map, system or hub>
+Layout laws: <rules a test can check per place: bare-wall share, the longest sightline, two routes, no spawn in view; `funtools variety --within` compares the place pictures>
+
+## Story
+<a want said by a person, a turn, an ending that changes the world; or a line "Story: declined, and why" for an arcade round (funpixel-world-and-story, story-at-size)>
+Want: <who asks for what, in their words>
+Turn: <what the player does or learns that changes the want>
+Ending: <what the world looks like after, and the last line>
+Goal: <10 min and up: where on the map the player is going, and how far; the HUD can show it>
+Clock: <the whole game's deadline and where the player sees it (a sky, a count); or "none">
+Question: <the mystery asked in the first minute; the piece each chapter answers>
+Antagonist: <who wants what, and why they are half right; the plan; their mark in each chapter; what the player gives them without knowing; or "none">
+Frame: <episodic games: what each episode adds to the spine besides its own job>
+
+| Beat | When | Who says it | The line | Seen in play |
+|---|---|---|---|---|
+| <beat id, also __FPX_STATE__.beat> | <time or place> | <speaker> | <one short line> | <filled by funtools depth --fill> |
+
+## Chapters
+
+(A long game: built chapter by chapter after the slice, each to its own target frames and the owner's yes. Mark the chapter where the hook lands "(hook)": the Steam two-hour check reads it.)
+
+| Chapter | Place | What it adds | Story beat | Length | Target frames |
+|---|---|---|---|---|---|
+| <C1 · name> | <where> | <the new verb, threat or twist> | <the beat it carries> | <minutes> | <target-c1-*.png> |
+
+## Living world
+<what moves on its own, the sound bed, and what answers the player's big moments (funpixel-world-and-story, atmosphere); `funtools life` shows what play has>
+
+| Place | Who lives there | Bed | Reacts to | Made how |
+|---|---|---|---|---|
+| <stands, streets, rooftops> | <crowd, passers-by, birds> | <crowd murmur, rain> | <overtake: roar swells; finish: confetti and a cheer> | <instanced cards, one bed + stings> |
+
+The living system: <the one thing in the world that answers the core verb (it watches, warns, remembers, flinches) and its two or more jobs in play>
+
+Creatures and machines: every one has a job in play and a cost; nothing only decorates, except a wonder named as one.
+
+| Creature or machine | Where | Its job in play | Its cost or catch | Motion |
+|---|---|---|---|---|
+| <the walker> | <from level 2> | <carries 12 kg of the load> | <loud: heard at 18 m; slips on ice> | <bouncy gait, the basket sways> |
+
+## Experience
+Depth and mastery: <what a skilled player does that a new one cannot; how far apart the bots should be>
+Content and progression: <how many distinct things, and when each arrives>
+Replay: <why a player comes back tomorrow, and what they do first>
+Story and storytelling: <a want, a turn, a payoff, and which of them play itself tells>
+World building: <the places, each with a rule and a landmark of its own>
+Emotional arc and pacing: <where tension rises, where it rests, the peak>
+Signature idea: <the one idea the genre hit does not have, or the familiar genre done exceptionally well>
+
+## Look
+<one sentence: medium, palette with roles, light>
+Palette: <#hex role, #hex role, #hex role> · Font: <display face and why>
+Target frames: <the key art and four moments from the ladder>
+
+| Moment | Target | Game frame | Intent | Pins |
+|---|---|---|---|---|
+| <1:00 the first threat> | <design/first-look/frame-1.png> | <at 1:00 (the playtest's saved route), view firstThreat, or journey level1 threat> | <what the frame must carry: the feeling or idea it pins> | <AD-2, AD-3> |
+Asset economy: <how each asset is made (generated 2D or 3D, authored, or procedural with a rendered proof) and how many pieces; the style bible's routes table when the greenlight ran>
+
+## Asset script
+<every picture tied to the beat it serves, the locks it used, its cost and its state; the next picture is a row here first. Families of the same shape make the production list; the art budget is their totals>
+
+| ID | What | Beat it serves | Locks used | Cost | Status |
+|---|---|---|---|---|---|
+| <KA-01> | <title key art> | <the promise> | <REF-HERO, style block> | <credits> | <drawn, redrawn, locked> |
+
+## Art budget
+<how many assets of each kind the agreed content list needs, and how each is made, rolled up from the asset script; Credits is the estimate for Funpixel's paid tools (host time is never priced)>
+
+| Asset | Count | Made how | Credits |
+|---|---|---|---|
+| <hero, cast, enemies, areas, props, UI, cues, music> | <count> | <generated sheet, plate, 3D model, authored, code with a rendered proof> | <the estimate> |
+
+## AD rules
+<the creator's art direction in a few clear lines, each checkable in one frame; the fidelity seat judges them every round. Rather not write them? Say so on a "Declined:" line, which is kept>
+1. <a rule a viewer checks in one frame: "only the hero is tomato #FF5A4E">
+2. <"every silhouette reads at 40 px on the real ground">
+3. …five in all, colour meaning and hero size among them
+
+## Identity lock
+<one reference sheet per recurring design (hero, companion, vehicle, pursuer, the thing carried), drawn from the best draft, and one style block every prompt repeats word for word; or "Declined:" and why>
+
+| Ref | What it pins | Source | Used in |
+|---|---|---|---|
+| <REF-HERO> | <face, hair, outfit and its colours, what she carries> | <design/first-look/ref-hero.png, from the best frame> | <key art, every frame> |
+
+Style block (verbatim): <medium · palette by hex, each colour's one use · bans>
+Proportions: <the hero in heads; each actor against her>
+
+## Actors
+| Actor | Role | Motion | States and visible transitions | Made how |
+|---|---|---|---|---|
+| <hero> | player-controlled | moves | <idle, move, act, hit: pose or frames, timing> | <sheet, part rig, code skeleton> |
+| <piece> | <role> | still | <how availability or danger reads> | <sprite, code> |
+
+State machines (one per actor that decides): <`PATROL ─ sees the player within 6 u ▶ WINDUP 0.6 s ▶ STRIKE 0.2 s ▶ RECOVER 0.8 s ▶ PATROL`>
+
+## Audio
+| Event | In the world's words | Why |
+|---|---|---|
+| <the core action> | <source, material, action, space; one event, no music> | <what it tells the player> |
+
+Music: <one identity written once (instruments, motif, key); only tempo and energy move per state>
+
+## HUD and screens
+- HUD: <what is on the actor, what is on the glass, where the thumbs rest>
+- Phone mockup: <design/first-look/hud.html, the HUD drawn over a target frame at 852 × 393, each element numbered with its spec; the same for any other key screen, with the view that opens it>
+- Screens: <title, how to play, settings, play, pause, the win or end card, the loss and retry>
+- Look: <every screen in the world's kit: the plates' material, the faces, the icon family, the wordmark as art; a screen not specified gets invented by whoever reaches it first>
+
+| Screen | What is on it | The one thing it must do | Entered by | Leaves to | Wow | Fun | Hook |
+|---|---|---|---|---|---|---|---|
+| <title> | <the title, one start control> | <start in one tap> | <load, or quit from pause> | <play> | <the key art, alive> | <the first tap answers> | <the world behind the wordmark, unvisited> |
+
+## Getting around
+<how the player moves between the hub and play: menu screens, or camera moves through one space>
+
+| # | The move | What you see | Length | Why |
+|---|---|---|---|---|
+| <1> | <the hub: a map or chart, idle> | <what moves on it> | <idle loop> | <progress in one glance> |
+| <2> | <into a level> | <the camera dives, the landmark rises> | <2.5 s, skippable> | <arrival as a place; the level loads under it> |
+
+Budgets: <60 fps on a mid-range phone; under 3 s after the first viewing; reduced motion cuts to a cross-fade>
+
+## Juice
+| When | Visual | Motion | Sound | Camera and time | Haptic |
+|---|---|---|---|---|---|
+| <the core action resolves> | <visible response> | <recoil, squash or stillness> | <cue or silence> | <hitstop ms, shake> | <ms or none> |
+
+Readability budget: <hero share of the screen, effect caps, the play layer clearest>
+
+## Controls
+| Device | Move | Act | Other |
+|---|---|---|---|
+| Touch | <floating stick, drag, tap zone> | <button or gesture, 44 px or more> | <pause corner> |
+| Keys | <WASD or arrows> | <keys> | <pause, mute> |
+| Pad | <stick> | <button> | <if the genre expects one> |
+
+Assist: <what it widens or slows, and what it never changes>
+
+## First look
+<filled after it: what the pictures settled, each redraw with its before and after, the cost>
+- Honest breaks: <where the pictures still break the plan's own rules, kept: "the lanterns are amber, which AD-1 keeps for the cargo; the level makes them cream">
+
+## Criteria
+- C1 mechanic: <what a player sees the core verb do>
+- C2 feedback: <"a hit reads within 100 ms">
+- C3 presentation: <"hero, threats and pickups told apart at phone size">
+- …7 to 10, copied into funpixel.json "criteria"
+
+## Lessons that apply
+<our defaults, each kept or replaced with why (invent-first.md §5), plus `npx @funpixel/tools lessons` for this genre>
+- Modelled places: <kept / why not>
+- A GPU device tier and p95 frame budgets: <>
+- Every attack tells (0.6 s or more): <>
+- Teach once, at the element: <>
+- A camera that never fights the player: <>
+- Controls off the play and off the held object: <>
+
+## Scope
+- In v1: <the agreed scope>
+- Cut, with why: <what was considered and left out>
+- Later: <what waits for a later version>
+- Money model: <premium, ads plus remove-ads, cosmetics and a pass, or a first act free then one unlock, per platform; what is never for sale> (skill funpixel-store, references/money.md)
+
+## Build plan
+| Milestone | What it proves | Built (it runs) | Passing (its gate) | Cost |
+|---|---|---|---|---|
+| <M0 controls spike on a phone> | <the verb feels right in two thumbs> | <date> | <a blind player does it unprompted> | <credits> |
+| <M1 slice: one place in art and sound> | <the core loop, a win and a loss> | <> | <named tests green; panel 7.3> | <> |
+Scope guard: <the cut that happens if M1 runs late: which places, kinds or extras go first>
+
+## Track
+<the stages, their gates (named evidence) and their state live in design/pipeline.json; `npx @funpixel/tools flow` prints the next step and the evidence that closes it. Note here only what the file cannot say: a stage skipped on purpose and why, or a gate the creator added>
+
+## Pause points
+<optional moments that invite someone to look (a friend, the owner, your next-morning self), never a gate>
+
+| When | Who looked | What they said | What changed |
+|---|---|---|---|
+| <plan applied, first look, first slice> | <name> | <their words> | <the version it went into> |
+
+## Risks
+| Pillar | Risk | Handled by |
+|---|---|---|
+| <what must work> | <how it could fail on a phone> | <the design answer> |
+
+## Open questions
+- <one decision per line, everything you had to guess; ask after the person has seen the first look or played> — recommend: <your pick and why>
+
+## Fix round (only while a round is unfinished)
+| Finding | Next step |
+|---|---|
+
+## Part 2 · Build spec (targets now; rewritten from the code once it runs, and from then on Part 2 wins)
+<world, step and units · each actor's numbers and its state machine · levels or rooms as a data file (design/levels/*.json) · events and saves · performance: GPU tiers, p95 frame budget>
+
+### Behaviour tests
+<the rules as test names, written before code; `funtools gdd` counts them and `funtools test` reads them back from the test files>
+- `<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>`
+```

package/plugins/kiro/skills/funpixel-gdd/references/genre-card.md

@@ -0,0 +1,109 @@
+# Card games
+
+Solitaire and its cousins, deck-building runs, scoring roguelikes, duels. What the genre's best
+games give players comes first, then the choices open to you, then the checks. The creator's brief
+wins over anything here.
+
+## What players remember
+
+- **The hand that went off.** A combo that chains card after card, each one adding, until the
+  total blows past the target. The best card games stage scoring as a performance, not a sum.
+- **The card that broke the run open.** One pick that turned an ordinary deck into a machine. The
+  story of a run is the story of a few cards.
+- **The win cascade.** Classic Windows Solitaire's cards bouncing off the table after a win is
+  still what many people picture when they think of the game: the ending gets its own show.
+- **A table with a mood.** Felt under a lamp, a smoky back room, a CRT glow, a wizard's desk. A
+  card game is set somewhere, even when nothing on it moves.
+
+## The look and the world
+
+- Cards are objects with weight: a thickness, a shadow, a slight tilt when held, a back design that
+  belongs to the world.
+- The face design is the game's typography and iconography; it must read at phone size, so a large
+  corner index and one clear symbol beat illustrated detail.
+- The table, the lighting and a few props (a candle, a coin stack, chips) set the world.
+
+## Characters
+
+A dealer, an opponent with a face, a jester on the joker, enemies with intentions: card games
+borrow warmth from characters. Even solitaire gains from a small companion who reacts.
+
+## HUD
+
+Scores, multipliers, targets and deck counts sit at the edges; the hand and the play area own the
+centre. The running total is the loudest element on screen during scoring, and nothing should cover
+it.
+
+## Feel
+
+- A card lifts under the finger, follows it with a little lag and tilt, snaps to a legal spot and
+  springs back from an illegal one. Legal places light up the moment a card is picked up.
+- Tap-to-play beside the drag, because dragging small cards on a phone is slow.
+- The deal is staggered; scoring counts up with a pitch that rises card by card; a multiplier gets a
+  pause before it lands.
+
+## Hits to study
+
+- **Balatro.** Watch a scoring hand: cards fire one at a time, each number animates as it adds, and
+  a really good hand sets the score on fire. Notice that nothing on screen changes without moving,
+  and the CRT-and-felt look makes a card table feel like a place.
+- **Slay the Spire.** Every enemy shows what it will do next and how much damage, before you commit.
+  A loss becomes a misread, never a surprise. Look at how a choice of three cards after each fight
+  shapes the run, and how the map shows risk ahead.
+- **Classic Solitaire** (Windows, and the many phone versions). One rule set everyone knows, an
+  auto-complete when the game is won, and a celebration that has become part of the culture. Study
+  how short the path is from opening the app to moving a card.
+
+## Conventions players bring
+
+The genre hit's defaults its players expect without being told (Peggle's free-ball bucket never runs out; Suika's drop line; Pac-Man's queued turn; a survivors-like's auto-fire). Kept as defaults; breaking one is a choice stated in the design doc and told to the player.
+Starting code with these as defaults, and the screen flow: [starters.md](starters.md), "Card".
+
+## Wow catalogue
+
+- A green felt table with default card faces is every card prototype. Pick a world and let it
+  reach the card backs, the table and the sounds.
+
+Pick one signature and up to three more before building (`npx @funpixel/tools wow` prints what to build and how each is checked; `wow pick <id> --signature` records it in the GDD's `## Wow`):
+
+- `card-hand-goes-off` (signature): The hand that goes off, Balatro
+- `card-intent` (presentation): Every enemy shows its next move, Slay the Spire
+- `card-jiggle` (juice): Cards that feel held, Balatro
+- `card-run-breaker` (signature): The pick that breaks the run open, Balatro
+- `card-pick-three` (feel): A choice of three after each fight, Slay the Spire
+- `card-table-is-place` (presentation): The table is a place, Inscryption
+
+## Open choices
+
+A starting contract you may keep or break; write down which in the GDD's genre-card line.
+
+- **Camera.** A fixed table view is usual; a slight perspective, a close-up for the scoring moment
+  or a scene around the table are all yours to choose.
+- **Body.** No avatar by default; an opponent, a companion or the player's own hand can be the
+  character.
+- **Core systems.** Pick, move, play. Then choose: deck building, a shop, jokers or relics that bend
+  the rules, a daily deal, a duel.
+- **How a run ends.** A cleared board, a target score, a hand count or a deck run through a set of
+  fights; a results screen and instant restart.
+- **Orientation.** Portrait suits a phone; a wide table can go landscape.
+
+## Depth and replay
+
+Options with reasons; more in skill `funpixel-game-logic`, its depth reference.
+
+- A deck run of 10 to 20 minutes (estimated) or a solitaire deal of 3 to 5; the first choice comes
+  in the first hand.
+- A daily seeded deal with a share card, the best score saved, and one unlock (a deck, a rule)
+  opened by the first win.
+- Undo is free and restart is instant: a card game punishes misclicks with frustration, not depth.
+
+## Engineering checks
+
+- **Seeded deals.** Every deal comes from a seeded random source, so a bug, a daily and a share
+  code all replay the same cards. For solitaire, an unwinnable deal is either detected or impossible
+  by construction (skill `funpixel-game-logic`).
+- **State the checks can read.** Expose `score`, `cards_left` or `hand`, and `seed`. One check
+  proves a legal move through a real drag (`pointer`, with `cards_left` falling).
+
+**Shelf** (libraries that fit, none required): gsap for the deal; a seeded RNG (alea); DOM or Pixi.
+No physics.