@funpixel/tools 0.0.0-stage → 0.1.1

package/plugins/codex/skills/funpixel-gdd/references/sections.md

@@ -0,0 +1,148 @@
+# What makes each section strong
+
+Distilled from two of the team's GDDs and five the owner wrote end
+to end on 28–29 September (a crew platformer, a deep-sea horror, a kart racer, a frozen metroidvania, a
+marionette party game). Each row: what the strong version holds, what the thin version looks like,
+and the example that made the difference. `funtools gdd` looks for the evidence in the strong
+column; it cannot tell a good design from a long one, so use it as a checklist, not a grade.
+
+## The promise, pillars and decisions
+
+| Strong | Thin |
+|---|---|
+| One line a stranger repeats; the **thesis in one frame or one number** that carries the meaning with no dialogue; a 6-second ad that is a sequence of pictures | A genre label ("a roguelike with crafting"), or a paragraph of lore |
+| References as **take and leave**: each gives one pillar, and what it would drag in is named and refused | A list of games it is "like" |
+| Decisions written **against their alternative**, with the reason, so the next session does not re-open them | Decisions stated with no alternative, or not at all |
+
+The robot game's smile (a face flickers onto every defeated robot) and the Greek crowd game's 300
+(the count over the army is health, weapon and story) are theses you can see. The owner's horror
+design adds a top-five table: the one reason each hit worked, and what a naive version of our game
+would lack. For each big choice, name the answer everyone reaches for first and the answer of someone
+merely avoiding it, then choose past both; write them down as "Ruled out: X · Y" (the horror game: guns
+and gore, then no combat at all, then a welder that cuts the enemies' limbs). A pillar with its **risk** beside it ("horror on a phone:
+risky, since a lit room and a small screen flatten fear; answered by a brightness step and sound
+drawn as arcs") is a
+decision the design can be judged on.
+
+## The loop and the numbers
+
+Strong: the loop in one sentence, then **the three to five numbers that are the whole game**, each
+with its value and why exactly that value ("fuse 3.0 s: long enough to lead a lit robot into a
+crowd, short enough that nobody can stockpile them"), and one **anti-degeneracy rule**: the boring
+optimum named, and the rule that makes it lose (panic-firing pays nothing; welding every door runs
+you out of gas). Thin: numbers with no reasons, or a loop with "and also" in it, which is two games.
+The numbers are targets until a test pins them; say so. Give each verb its **price** (weld a door:
+hold 1.5 s, 25 gas, and the room beyond is gone for good): a verb that costs nothing stops being a
+choice. Play one level's economy on paper before code, as a middling player would (the horror game's
+chapter 2 needed 187 gas across cuts, burns, a pin and a door, so it placed 1.3 × 187 = 243).
+
+## Opening (the first minute)
+
+Strong: from Play, each row's shot and what the player can do, control by 12 s (story) or 10 s
+(arcade) with the objective's metres on screen, a **moment ladder** (0:10, 1:00, 5:00, 20:00,
+60:00), first input, payoff and signature through the real controls. Thin: "a tutorial teaches the controls". The breakpoint (the one moment only this game has:
+the Seam, the Knockout, the Snip, the Mend) belongs here and in the target frames.
+
+## Content
+
+| Strong | Thin |
+|---|---|
+| A roster table: kind, what it looks like, **debut**, **its one idea**, a tell of at least 0.6 s by sound first and shape second | "Enemies get harder" |
+| Stages that each **add one thing**, taught alone before it is combined; a shape per level (teach → develop → twist → test → celebrate) | Levels that differ in paint or speed |
+| A climax in **named phases**, each teaching a rule, with no health bar where the world can show damage | A boss bolted onto a genre that wants a different finish |
+
+The robot game's "one chassis, nine heads" is also an asset economy: eleven images for nine
+enemies, so adding a kind means one more picture and one more row of data. Rules the roster keeps (only one enemy
+in its tell at a time; never spawn in view; each kind debuts alone) are what make a crowd fair.
+Give each kind something it **takes** besides health (the resource, time, the route, a connection,
+your attention, your plan): a roster where every kind only takes health is one enemy in different
+coats. A tell stays honest when an enemy that chooses a target takes the nearest, never a random one,
+and online it adds the round trip (the marionette party game uses 0.8 s against about 300 ms of phone lag).
+
+## Look
+
+Strong: the look in one sentence; **colour as assignment** (each colour owns one meaning: one
+colour for "you", one for "hurts", one for "you can touch this"); a font chosen for the theme; the
+asset economy (what is generated, what is built in code, how many); **five AD rules**, each
+checkable in one frame (a colour count, a size at which a thing reads, where grime may and may
+not live); and **target frames**: the key art plus four whole frames of the ladder's moments, each
+saying which claim it pins. The horror game's were timed to its ladder (0:10, 1:00, 2:00, 3:00, 5:00), so
+captures of the same seconds could be laid beside them (skill `funpixel-art`).
+Thin: "stylised and colourful". The owner's docs keep the style words
+in one file and repeat them word for word in every prompt; reference sheets pin each recurring
+design ([world-and-identity.md](world-and-identity.md)).
+
+## Actors and animation
+
+Strong: every actor with its role, motion (moves, animates or still) and states, and **how it is
+made**: a sheet, a part rig posed from the simulation, a code skeleton with generated parts. The
+team's lesson, repeated in four of the owner's docs: nothing that animates is left to a generated
+rig; the hero is built or posed in code, props and backdrops are generated. Thin: a character list.
+
+## Audio
+
+Strong: a sound sheet **in the world's own words** (source, material, action, space; "one event,
+no music, no voice"), a leitmotif that tells the story (a dying factory jingle, a lullaby the
+monsters hum), and **one music identity written once** (instruments, motif, key) so only tempo and
+energy move between states. Timed cues (a countdown, beat-synced tells) are composed in code from
+single hits; generators do not place sounds on a clock. Thin: "upbeat music and satisfying sounds".
+
+## HUD, screens and controls
+
+Strong: the HUD mostly **on the actor** (lights on a collar, a gauge on a tank), the glass kept for
+the thumbs; a **phone mockup** drawn at the phone's own points over a target frame with numbered
+callouts; every screen listed (loader, first run, title, how to play, settings, pause, the end card,
+death, the rotate gate); controls per device (touch zones and 44 px targets, keys, pad) and an
+assist mode that never removes the design's point. Thin: "a score in the corner".
+
+## Feel and juice
+
+Strong: a row per event with visual, motion, sound, camera and time, and haptic, each with a
+number (hitstop 0.05 s, shake 0.4, slow-motion 0.5× for 0.6 s); a payoff ladder where rewards
+escalate; a **readability budget** (the hero's share of the screen, effect caps, the play layer
+always clearest). Thin: "screen shake and particles".
+
+## Criteria, scope, the track and risks
+
+Strong: criteria a stranger can check from the screen; a scope that says what is in, what is cut
+and why, and what waits; the **track** with a gate and evidence per stage; the risks beside the
+pillars. The owner adds an honest read ("how fun will it be": a score per pillar, its confidence and
+its risk) and a runbook for agents: steps with a gate, evidence and a state, and one handoff line per
+stop. Put the milestones that are cheap to fail first (the light on a phone at half brightness, the
+controls) before any content; when time runs short, the dressing shrinks, never the loop.
+
+## Requests against the pillars, and the pillar audit
+
+The owner's deep-sea horror game (September 2026) was audited against its own GDD
+mid-build: an agent graded every beat on both platforms, about 6.6 of 10 against the plan. The
+lesson was that requests made mid-build can quietly break a pillar. "Add guns" broke "you have no
+gun", "make her faster" broke the one-canister economy (its chapter bots could no longer afford the
+second weld), "make manoeuvres easier" softened the dodge as a skill. Each request was kept and
+folded back into the design: every tool draws on the one canister, the automatic dodge side became
+an Assist setting, slow motion stayed reserved for payoffs. Re-reading the pillars after a request
+is the cheap moment to do that folding, and the version line records it.
+
+Its playtest page carried the audit as a table the next round can be compared with, one row per
+pillar:
+
+| Pillar | Grade | Matches the GDD | Still drifting |
+|---|---|---|---|
+| Art direction | 7.5 | amber lamps, a cyan torch, coral only at joints and only in the beam | the dark is too total outside the torch (threat against ground ΔE 0.7): it hides the threat, not only the mood |
+| Mobile | 5.5 | thumb stick under the thumb, a context button, 44 px targets, 60 fps on the phone profile | the blind phone player died twice at the first enemy; the HUD reaches a third of the screen at busy moments |
+
+The audit reads the captures, the films, the sim's traces and the code, not the panel's scores,
+so it says where the build left the plan even when the critics liked it.
+
+## Part 2: as built
+
+The team's two GDDs end in a port spec written from the code, and it wins wherever it disagrees
+with Part 1: world units and the fixed step, every actor's numbers and states, levels as data,
+events and saves, performance budgets, and the behaviour contract (tests named after the rules).
+That is what let a Unity port match the web game exactly. See [as-built.md](as-built.md).
+
+## Versioning
+
+v0.1 is written before code. v0.2 follows the first look: what the pictures and sounds settled, and
+every rule they changed (a colour that hurt moved off a reward, a missing pause button placed). Each
+later version records what changed and why. Once the game runs, Part 2 is rewritten from the code;
+from then on the document describes the game, not the plan.

package/plugins/codex/skills/funpixel-gdd/references/spec-folder.md

@@ -0,0 +1,131 @@
+# The big tier: a spec folder the game loads
+
+A small game stays one GDD. A mid or deep game (`funpixel.json` `production.tier`) also gets a
+spec folder, `design/spec/`: the build contract a building agent, or a lane, works from. The GDD
+says what the game is and why. The spec says what to build, in numbers and data that the game
+loads at build time.
+
+## Why
+
+Our real games were built this way, and the GDK's games were not.
+
+- **One heist game** was built against `design/gdd/spec/`, written before code. Its README set the
+  order of reading. Its `tunables.json` held every number with an id, a default, a range, a unit,
+  a why and the tests that pin it. It grew from 652 to 941 tunables while lanes built, because each
+  lane wrote its numbers back. It had six rooms whose pars add up to an 18-minute night.
+- **Two others** kept their levels as data with tested laws, and their bots
+  finished every level on several seeds.
+- The GDK games were one screen and one GDD, with the numbers in a markdown table that nothing loaded.
+
+What makes a game long is content as data, grown room by room from a slice that passed. What makes
+it consistent is one home for every number.
+
+## Making it
+
+`npx @funpixel/tools spec init` (or `--tier mid|deep` to grow a small game on purpose). It also runs
+by itself at `pitch lock` for a mid or deep game that has been scaffolded. It writes:
+
+| File | Holds | Read by |
+|---|---|---|
+| `README.md` | what to read first, the slice-first rule, every file and what it covers | every agent and lane, first |
+| `tunables.json` | every number the game plays by, grouped (`rules.goal`, `move.run`) | `src/tune.ts`, `spec lint` |
+| `rules.md` | the simulation in rules, each citing its tunables by id | the rules lane |
+| `rooms.json` | every room in order: par, exit, waves, what it teaches, its beat, its numbers | `src/chapters.ts`, `funtools rooms` |
+| `screens-and-tutorial.md` | every screen and its way out, the HUD, the first minute | the UI lane |
+| `difficulty.md` | the curve room by room, and who it is for | the design lane |
+| deep only: `rooms.md`, `cast.md`, `story.md`, `audio.md`, `juice.md` | the rooms in words, everyone who acts, the beats, every cue, every payoff | their lanes |
+
+`tunables.json` starts from the numbers the code already holds: every `export const NAME = <number>`
+and every all-number table such as `MOVE`. Each one keeps the comment that explains it as its why,
+and records where it came from. Scaffold files still as the kit wrote them are rewired to read the
+numbers; a file you changed is left alone, and `spec lint` names every number still typed into it.
+
+`rooms.json` starts as two chapters of three rooms built from the starter's own round: more to
+collect, sooner threats, a bigger floor. That is a working example of the shape, not a campaign.
+Replace it with the game's own rooms, one per place in the GDD.
+
+The plan page draws the rooms as a map: a box per room by chapter, each `exit` as a route, and the
+chain from the first room to `"end"` as the critical path. A room's `exits` that name rooms (`[{ "to":
+"secret" }]`) are drawn as other ways out, and its `look` (what the player should look at there) is
+written on its box; without one, the GDD's `## Places` Landmark of the same name is used. A
+`build_level` spec (`design/level.json`, `design/levels/*.json`) is drawn from above with the route
+from the spawn through each checkpoint to the exit, the spawn's facing and any `camera` marker.
+
+The data the game loads ships with it (`.harnessignore` keeps `design/spec/tunables.json` and
+`rooms*.json`). The words stay private.
+
+## Numbers as data
+
+```json
+{ "version": 1, "groups": { "spike": {
+  "every": { "default": 2.5, "unit": "s", "range": [1.5, 4], "why": "a spike every few seconds keeps the feet moving", "tests": ["a hop late in the tell clears the strike"] }
+} } }
+```
+
+- One home for each number. Every other file cites the id (`spike.every`) and never repeats the
+  value. When the two disagree, the file wins.
+- In code, `tune('spike.every')` is typed from the file, and a missing id throws with its name.
+  `group('move')` is a live table: its fields change in place when a room or a dev edit changes
+  them. `onTune(fn)` re-reads what a module keeps in its own bindings. An edit to the file lands
+  in `npm run dev` without a rebuild.
+- Give each number a unit, a range and a why. A number with no why gets tuned by feel and drifts,
+  and a range says how far a lane may move it.
+- The file grows while the game is built. A lane that adds a number adds its tunable in the same
+  commit.
+
+## Rooms and chapters as data
+
+A room is a par, an exit, its waves, what it teaches, its beat and its numbers. Rooms are never
+placed by hand in code. `src/chapters.ts` loads the rooms, enters one (its `tune` laid over the
+defaults), plays it wave by wave with a checkpoint before each wave, and leaves by its exit.
+`src/levels.ts` saves where the player got to through `@funpixel/sdk/save`, so a reload resumes at
+the checkpoint. The endings show the map of progress (`src/room-map.tsx`).
+
+- **A par** is the seconds a good first run takes. The pars add up to the game's length, which must
+  reach the play floor: 15 minutes for a complete game (`play_min_minutes` moves it).
+- **`funtools rooms`** plays every room in order over 5 seeds. The players are a careful player at
+  a human rate (12 decisions a second, 200 ms to react), the sharp bot, a naive player and a novice.
+  A room passes when the careful player clears it on every seed within half its par either way and
+  the sharp bot clears it too. The naive and novice rows show where people fall back: that is the
+  curve.
+- `test/rooms.ts` plays the same round as `test/probes.ts`. When you rewrite the rules, rewrite both.
+- `sim` takes the game's play length from a fresh rooms record, because one round is one wave.
+
+## Slice first
+
+Nothing in a later room is built until the room before it passes its gates. For the slice, those are
+the core test and the slice stage (`check`, `sim`); for every room, the careful player clearing it
+near its par.
+
+- `funtools rooms open <room>` opens the next room for building. It refuses while any earlier room
+  is closed or the one before does not pass, and it names the gate that holds it.
+- Only the owner releases a room early: `rooms open <room> --by owner "why"`. Their words are kept.
+- A room changed before it was opened has been built early. `spec lint` names it, and the expand
+  stage's gate holds on it.
+- Rewriting rooms on paper is planning, not building: `funtools rooms plan` records the rooms as
+  planned now. It is free until the owner agrees the plan, and the owner's call after that.
+
+## The lint
+
+`funtools spec lint` checks the folder against itself and the code, and records `.funtools/spec.json`.
+The GDD stage reads that record past the small tier. It checks:
+
+- the sections the tier needs (the heist game's names count: `crew.md`, `fun-and-difficulty.md`, `sfx.md`);
+- every default inside its own range, ids used once, and the tests they name;
+- unknown ids in the code, the rooms or the spec files (a `P-TUNE-` proposal is a note);
+- tunables the code never reads, and a tunable's number still typed into `src/`;
+- rooms without a par or an exit, or that no exit reaches;
+- the pars against the floor;
+- a room changed before it was opened.
+
+Notes count the unwritten outlines, numbers with no why, unit or range, and numbers written into
+the prose.
+
+## Common mistakes
+
+- Copying a value into prose or code "for now". It drifts within a day; cite the id.
+- Pars nobody measured. `rooms` says when a par is more than half off the careful player's time.
+- Building room three while the slice still fails. The slice decides the feel every later room
+  repeats.
+- Keeping the starter's six rooms as the game's content. They show the shape; the game's places are
+  yours.

package/plugins/codex/skills/funpixel-gdd/references/start.md

@@ -0,0 +1,110 @@
+# Starting a Funpixel game
+
+What complete browser games have taken, in an order that has worked; a path, not a procedure
+(each step's purpose, tool and signal: [the-path.md](the-path.md)). The
+hooks mirror evidence gaps back (advisory unless `gdk.gate: "block"`) and say whether this session
+is a complete game ([floors.md](floors.md)).
+
+## Tools
+
+- `npx @funpixel/tools init <folder> --idea "<one line>"` picks engine, recipe and orientation
+  with reasons, seeds `design/GDD.md`, mints the id with a key and commits the game to git:
+  never a temp folder; push it (the-path.md, "Keep the game"). `create_game` is for
+  an agent with no local files; beside `init` it leaves an orphan draft.
+- `generate_image` makes target frames, `generate_sprite` sprites; long jobs return an id for
+  `get_job`. Without the MCP, `npx @funpixel/tools gen image|sprite`.
+- `build`, `probe`, `capture_view` without the local toolchain; else `npx @funpixel/tools
+  verify` and `capture`. `check_plan` grades the note free.
+
+## A path that has worked
+
+1. **Route by the request and existing project.** A missing `verify.json` is an evidence gap,
+   not a request to rebuild a game. Use `funpixel-game-spine` for an existing-game change and the
+   relevant focused skill for an asset or mechanic. For a new complete game or replacement core
+   loop, continue below; preserve the requested ambition and finish the agreed scope.
+
+2. **Use a fitting genre recipe.** Read the relevant reference for starting points,
+   then choose camera, body and controls from the brief:
+   [card](genre-card.md), [platformer or maze chase](genre-platformer.md),
+   [puzzle](genre-puzzle.md), [racing](genre-racing.md),
+   [rpg](genre-rpg.md), [shooter](genre-shooter.md),
+   [simulation](genre-simulation.md), [strategy](genre-strategy.md),
+   [survival](genre-survival.md); starting code: [starters.md](starters.md);
+   the frame: [frame.md](frame.md). Recipes: the creator's choices win. Where a choice is open, [variety moves](design-note.md#variety-moves) steer off the average game. Record the chosen controls and checks so the implementation is testable.
+
+3. **First look, then a first playable** (the opening stages): the key art and the hero's sheet,
+   steered in the chat; then a playable built from them with real assets, sized by the game,
+   judged against the key art. The owner plays it and says whether it has potential.
+
+4. **The design around it, experience first.** The plan critics, hooks and the next session
+   read. The GDD, `design/GDD.md` (skill
+   `funpixel-gdd`; what hooks read: [design-note.md](design-note.md)),
+   `/design/` in `.harnessignore`: the player's journey through the real controls, the core loop in
+   one sentence, the look and why, five AD rules checkable in one frame, the juice table (skill
+   `funpixel-game-feel`) and each actor's motion. About 7–10 outside-checkable criteria in `funpixel.json` `criteria` let the blind
+   player judge from the screen; the gameplay tables are in
+   [gameplay-contract.md](gameplay-contract.md).
+
+   Every asset has a route (generated, authored, or procedural with a proof; never "primitives for
+   now"); agreed in the chat at the game's real size, its asks scaled by length:
+   [production-tiers.md](production-tiers.md).
+
+5. **Prove the loop: the slice.** Narrow feature breadth, not the requested visual
+   ambition, with the interface the loop needs. Done when: the player acts; one core verb works through real input; a win and a loss (if the design has
+   one) fire in real play; something on screen reports progress;
+   `npm run build && npx @funpixel/tools verify` exits 0 with a check per mechanic and one reaching
+   the resolution (skill `funpixel-verify`).
+
+6. **Build the chosen look** (skill `funpixel-art`) by the
+   bible's routes. Replace stand-ins and check the loaded visuals.
+
+7. **The release bar** is what the team's best shipped games had in common: coherent art, the
+   juice table in the game, the signature on screen early, a moment view, the full screen set, a
+   phone-size HUD, keyboard and touch, a passing rules suite. The list with its reasons:
+   [floors.md](floors.md). One backlog item per pass.
+
+8. **Stay honest.** A cut for performance is the creator's to accept. Claim only what a key, a
+   button or the loop runs, and name what nothing observed (the hooks list it).
+
+9. **One verdict per round, two at hand-back** (skill `funpixel-verify`). Each round: the targets
+   (`score --target` at the accuracy bar, funpixel.json `accuracy_min`, default 75, on every target
+   moment) and a blind player on phone and desktop with no high finding (`play`). At hand-back, add
+   the critic panel at the bar games' floor (overall 6.0, look and feel 7.0). Every other tool finds
+   why, never adds a verdict. Stop when the agreed goal is met and its evidence is current; a passing
+   panel floor alone does not finish the requested work.
+
+10. **A hand-back in three parts:** what plays now, with the literal controls on keyboard and touch;
+    what is not in yet, on purpose; the next two or three steps, ranked. Work
+    already authorized continues. Name every stand-in (a shape where art belongs, a skipped model,
+    a cut mechanic) and everything no evidence observed; `progress report` gathers them. Judge before showing: below the bar, say so first. Feedback: skill `funpixel-feedback`.
+
+**Gray-box only when asked.** If the person asked for a gray-box or prototype, skip steps 4, 6 and
+9, write the stand-ins into `.funtools/graybox`, and say "gray-box" in the hand-back with every
+stand-in listed.
+
+## Keep the person in the loop
+
+The person is in the chat: show the first built frame by minute 10, then each round's captures
+beside their targets, with the GDD's `## Where we are` updated and the preview link. Ask only at forks (taste, spend, scope); decide the rest ([in-the-loop.md](in-the-loop.md)).
+
+## Worked example
+
+Brief: "a game about a window cleaner on a skyscraper".
+1. Empty folder: a new game, read as a one-thumb climber.
+2. Card: platformer. Kept: the tower is the level, a fall ends the run. Departure noted: no jump;
+   the verb is swinging the cradle.
+3. Chosen: a noon screen-print poster. AD rules: three inks (cobalt, tomato, cream); hard offset
+   shadows; only the cleaner is tomato; windows read as a grid at 40 px.
+4. Greenlight: three pitches, the cradle one picked; four phase frames cleared beside the hit; locked v1.0.
+5. Slice: drag swings the cradle; a wiped window scores; a falling pot costs a life. Verify 0.
+6. Cleaner, pots, pigeons and the skyline generated from the style file; code shapes gone.
+7. The juice table built; every screen in; a `rush` moment view drops three pots mid-wipe.
+8. Panel: 6.3. Fix round 1: pot silhouettes, HUD labels. Panel 6.8.
+9. Hand back: "Drag or the arrow keys swing the cradle. Not in yet: tower two. Next: 1. wind
+   gusts, 2. pigeon variety."
+
+## Common mistakes
+
+- Calling unfinished stand-ins a deliberate style.
+- Expanding an asset family before choosing its look.
+- The design document left at its first draft while the game moved on.

package/plugins/codex/skills/funpixel-gdd/references/starters.md

@@ -0,0 +1,175 @@
+# Starting code per genre
+
+A recipe per genre card: the loop as engine-free rules, the conventions players bring already
+implemented as defaults, and the screen flow. Copy what fits into `src/rules.ts` (seeded, no engine,
+no DOM), keep the numbers in one table at the top, and pin each convention in `test/rules.test.ts`
+so a later change cannot drop it silently. The scaffold's `session.ts`, `screens.tsx` and `hud.tsx`
+already carry the screens; these recipes are the rules under them. `funtools init` has written the
+same genre's defaults into `design/GDD.md` (marked "starter default") and its cast into
+`assets/assets.json`; change both when the game changes. A 3D game starts from the 3D world starter
+instead (skill `funpixel-game-spine`, `references/three.md`), whose controller already has these
+forgiveness windows.
+
+Breaking a convention is a design choice: write it in the GDD's "Conventions players bring" and tell
+the player in the game, or it reads as a bug.
+
+## The screen flow every starter shares
+
+Title → play → pause → won or lost → play again, plus how to play and settings, each a declared view
+(`__FPX_VIEWS__`) so verify, capture and the playtest can open it. Present them as a game, not a web
+page (the owner's rule: the UI is art):
+
+- **Title in the world.** The play's own scene behind it, moving (an orbiting camera, drifting
+  particles, the idle cast), no full-screen dimmer; the name in big display type with depth or as
+  art from the style frame; one line of promise; one big lit start in the thumb zone.
+- **Banners, not forms.** Pause and the endings stamp a big word in over the world softened behind
+  (a blur, a vignette), the numbers in the display face, one raised primary button and a quiet
+  secondary link. No grey cards, no rows of equal buttons.
+- **Endings count.** The score counts up, the best is named, a new best is celebrated, and play
+  again is one tap that lands in under a second.
+
+```css
+/* A raised, lit primary button and a stamped banner word (2D or 3D; tokens from src/look.json). */
+button.primary { font-family: var(--font-display); border: 0; color: #2a140e;
+  background: linear-gradient(180deg, #fff1b8, var(--primary) 45%, var(--accent));
+  box-shadow: 0 5px 0 #8a4424, 0 0 0 3px rgba(255,255,255,.85), 0 10px 30px rgba(255,190,100,.45); }
+button.primary:active { transform: translateY(3px); box-shadow: 0 1px 0 #8a4424, 0 0 0 3px rgba(255,255,255,.85); }
+.veil { backdrop-filter: blur(5px); background: radial-gradient(ellipse, transparent, rgba(0,0,0,.45)); }
+.banner-word { font-family: var(--font-display); font-size: clamp(44px, 12vw, 84px); -webkit-text-stroke: 2px #2a140e;
+  paint-order: stroke fill; text-shadow: 0 4px 0 #8a4424, 0 8px 0 rgba(0,0,0,.5); transform: rotate(-2deg);
+  animation: pop .35s cubic-bezier(.2, 1.6, .4, 1); }
+```
+
+Bundle the faces (`@fontsource/<face>` imported in `main.tsx`) and name them in `funpixel.json`
+`metadata.fonts`; `funtools look --hud --view title` then reports no system type.
+
+## Platformer: coyote time, a jump buffer, a variable jump, a checkpoint
+
+```ts
+export const JUMP = { coyote: 0.1, buffer: 0.1, rise: 2.5 /* bodies */, apex: 0.35, cut: 2.5, respawn: 1 };
+const g = (2 * JUMP.rise) / JUMP.apex ** 2, v0 = (2 * JUMP.rise) / JUMP.apex;
+export function press(run: Run) { run.buffer = JUMP.buffer; }               // keydown or touch
+export function step(run: Run, held: boolean, dt: number) {
+  run.coyote = run.grounded ? JUMP.coyote : run.coyote - dt;
+  run.buffer -= dt;
+  if (run.buffer > 0 && run.coyote > 0) { run.vy = v0; run.buffer = run.coyote = 0; run.grounded = false; }
+  run.vy -= g * dt * (run.vy > 0 && !held ? JUMP.cut : 1);                    // a released jump cuts the rise
+  // … integrate, land, collide …
+  if (run.dead && (run.deadFor += dt) > JUMP.respawn) Object.assign(run, { ...run.checkpoint, dead: false });
+}
+```
+
+Pin: a jump 0.09 s after the ledge fires, 0.12 s does not; a press 0.08 s before landing fires
+on landing; a tap peaks lower than a hold; a death is back at the checkpoint in about a second.
+
+## Maze chase: turns queued before the corner
+
+```ts
+export const MAZE = { queueFor: 0.25 /* s a turn is held */, speed: 6 /* tiles/s */ };
+export function turn(run: Run, dir: Dir) { run.want = dir; run.wantFor = MAZE.queueFor; }   // a swipe anywhere
+export function step(run: Run, dt: number) {
+  if (run.want && open(run.tile, run.want) && centred(run)) { run.dir = run.want; run.want = null; }
+  else if (run.want && run.want === opposite(run.dir)) { run.dir = run.want; run.want = null; } // a reverse is instant
+  if ((run.wantFor -= dt) <= 0) run.want = null;
+  if (open(run.tile, run.dir)) advance(run, MAZE.speed * dt); else snapToCentre(run);
+}
+```
+
+Pin: a swipe up 0.2 s before an opening turns there; a reverse turns at once.
+
+## Merge or drop: a drop line, the next piece, an undo
+
+```ts
+export const DROP = { previewNext: 1, loseLine: 0.85 /* share of the jar's height */, settle: 1.2 /* s over the line before it loses */ };
+export function aim(run: Run, x: number) { run.aimX = clamp(x, run.held.r, W - run.held.r); }   // the drop line follows the finger
+export function drop(run: Run) {
+  run.history.push(snapshot(run));                         // one undo (a power-up or a setting)
+  run.pieces.push({ ...run.held, x: run.aimX, y: 0 });
+  run.held = run.next; run.next = randomPiece(run);        // the next is always on screen
+}
+export const losing = (run: Run) => run.overLineFor > DROP.settle; // a bounce over the line is not a loss
+```
+
+The HUD shows the held piece, the next one and the drop line from the held piece to the floor.
+
+## Tactics: previews before commit, a turn that resets
+
+```ts
+export function preview(run: Run, unit: Unit, to: Tile, target?: Unit) {
+  return { path: route(run, unit, to), damage: target ? hit(unit, target) : 0, counter: target ? hit(target, unit) : 0, kills: target ? hit(unit, target) >= target.hp : false };
+}
+export function commit(run: Run, move: Move) { run.turnStart ??= snapshot(run); apply(run, move); }
+export function resetTurn(run: Run) { if (run.turnStart) restore(run, run.turnStart); }   // free until End turn
+export function endTurn(run: Run) { run.turnStart = null; enemyPhase(run); }
+```
+
+Show the path, the numbers and the enemy's intent before the tap that commits. A tower defence
+shows the next wave and has a speed-up instead.
+
+## Survivors-like: auto-fire and a pick of three
+
+```ts
+export const LEVEL = { first: 5, growth: 1.25, picks: 3, magnet: 2.5 /* m */ };
+export function step(run: Run, dt: number) {
+  for (const w of run.weapons) if ((w.cool -= dt) <= 0) { fire(run, w, nearestEnemy(run)); w.cool = w.every; } // no fire button
+  for (const gem of run.gems) if (dist(gem, run.hero) < LEVEL.magnet) pull(gem, run.hero, dt);
+  if (run.xp >= run.need) { run.xp -= run.need; run.need = Math.ceil(run.need * LEVEL.growth); run.choosing = offer(run, LEVEL.picks); }
+}
+export const paused = (run: Run) => run.choosing !== null;    // the world waits while the player picks
+```
+
+The pick is its own screen (`levelup` view): three cards, what each changes in numbers, one tap.
+
+## Racing: catch-up, the position always on screen
+
+```ts
+export const PACK = { rubber: 0.08 /* speed share per 10 m */, cap: 0.12 };
+export function rivalSpeed(run: Run, rival: Car) {
+  const gap = run.player.distance - rival.distance;           // + behind the player
+  return rival.top * (1 + clamp((gap / 10) * PACK.rubber, -PACK.cap, PACK.cap));
+}
+export const position = (run: Run) => 1 + run.rivals.filter((r) => r.distance > run.player.distance).length;
+```
+
+A crash costs seconds (a respawn on the line facing forward), never the race. The finish is a set
+piece (skill `funpixel-world-and-story`, `references/atmosphere.md`), then the results screen.
+
+## Shooter: a small hitbox, shots that read
+
+```ts
+export const SHIP = { hitbox: 0.3 /* share of the drawn size */, fireEvery: 0.12, invuln: 1.5 };
+export const hitBy = (run: Run, s: Shot) => dist(s, run.ship) < run.ship.size * SHIP.hitbox + s.r;
+```
+
+Fire is automatic or one held press on a phone. Enemy shots take a colour nothing else uses.
+
+## Action RPG: attacks that warn, a safe place that heals
+
+```ts
+export const FOE = { windup: 0.6, strike: 0.2, recover: 0.8, sees: 6 };
+export function think(f: Foe, run: Run, dt: number) {   // PATROL → WINDUP → STRIKE → RECOVER
+  f.t += dt;
+  if (f.state === 'patrol' && dist(f, run.hero) < FOE.sees) set(f, 'windup');
+  else if (f.state === 'windup' && f.t > FOE.windup) set(f, 'strike');
+  else if (f.state === 'strike' && f.t > FOE.strike) set(f, 'recover');
+  else if (f.state === 'recover' && f.t > FOE.recover) set(f, 'patrol');
+}
+export function rest(run: Run) { run.hero.hp = run.hero.max; save(run); }   // at the safe place; saving is automatic
+```
+
+## Simulation: decide paused, see the price first
+
+```ts
+export function quote(run: Run, item: Item) { return { cost: item.cost, afford: run.coins >= item.cost, gain: item.perMinute }; }
+export function buy(run: Run, item: Item) { if (run.coins < item.cost) return false; run.coins -= item.cost; place(run, item); save(run); return true; }
+export const tickRate = (run: Run) => (run.menuOpen ? 0 : run.speed);   // time waits while you choose
+```
+
+## Card: see it before you play it
+
+```ts
+export function lift(run: Run, card: Card) { run.preview = resolve(clone(run), card); }   // the outcome, not just the text
+export function play(run: Run, card: Card) { run.undo = snapshot(run); apply(run, card); run.preview = null; }
+```
+
+Draw, discard and the counts stay on screen; an undo where the rules allow it.