@funpixel/tools 0.0.0-stage → 0.1.1

package/plugins/cursor/skills/funpixel-feedback/references/memory.md

@@ -0,0 +1,99 @@
+# The game's memory: what the person changed, what was decided
+
+A diff says what moved. It cannot say that the person slowed the ghosts on purpose because their
+kids kept losing, or that tap-to-jump beat swipe after a bus ride. Without that, the next session
+"fixes" the slow ghosts back to the design number, or re-opens the control question and quietly
+reverses it. Two small files carry the why across sessions; both are private (they never ship,
+and `funtools export` leaves them behind), and both are read at session start.
+
+| File | Holds | Written by |
+|---|---|---|
+| `.funtools/journal.jsonl` | one line per change a person made: who, what, why, when, files or values | `npx @funpixel/tools journal`, and the hooks when files moved between agent turns |
+| `design/decisions.md` | each choice against its alternative, with the reason, an id (`D3`) and a date | `npx @funpixel/tools decide`, or by hand |
+
+When neither file exists the session start says nothing about them; an empty memory is not a
+problem to fix.
+
+## The creator's journal
+
+For the person's own changes: a number tuned in the editor, a sprite they redrew, a level they
+reordered, a line of copy they rewrote.
+
+- The person, in a terminal: `npx @funpixel/tools journal "ghost speed 4 → 3.2" --why "my kids lost in 20 s" --values ghostSpeed=3.2 --files src/feel.ts`.
+- You, when the person tells you in chat what they changed by hand, may record it for them with
+  the same command; the entry says it came through the agent (the host's own shell says so, not
+  a guess), with `--by` naming the person if they gave a name.
+- Detected entries: the hooks keep what the files looked like when an agent last touched them
+  (every Stop, and each file a Write or Edit call wrote). When a session starts, or the person
+  sends a message, and shipping files or design notes differ from that, one entry is added,
+  marked detected: the files certainly moved, but who moved them and why is unknown (a person, a
+  `git pull`, a turn that was interrupted before its Stop). It names no person and invents no
+  reason.
+
+What the session start shows: the last five entries, then a short line. What to do with them is
+yours to judge; what worked in the studio's games:
+- Read a changed file again before editing it, rather than trusting a copy from earlier in the
+  conversation; the person may have moved things since.
+- Keep a told change unless the person asks otherwise. If it now fights the design, say so and
+  offer both, rather than reverting it.
+- A detected change is a fact about bytes, not about intent. When it matters (a tuned number, a
+  deleted level), one question settles it; when it is plainly a pull or a formatter, carry on.
+
+## The decisions log
+
+For choices a later session could plausibly reverse: the control scheme, the camera, the art
+medium, a number a playtest settled, a feature cut on purpose, a pillar bent at the person's
+request. Not every small call: if nobody would ever argue it, it is not a decision worth an id.
+
+`npx @funpixel/tools decide "tap anywhere to jump" --over "swipe up" --because "one thumb on a bus; swipes misfired at 60 fps"`
+appends `D<n>` to `design/decisions.md`. A decision reads best against what it beat (`--over`);
+one that names no alternative is the one that gets re-argued.
+
+Changing your mind is normal and creative freedom stays whole: a later decision may replace an
+earlier one with `--supersedes D3`. The old entry stays, marked `Superseded by: D5`, so anyone can
+see the path the design took and why. The session start lists only the live ones; `decide` with
+no text lists both, and `npx @funpixel/tools gdd` shows the live ones beside the GDD's score.
+
+Why a file of its own and not a GDD section: the GDD is rewritten whole at each version (v0.1,
+v0.2, as built) and states the design as it is now. The log keeps how it got there and survives
+every rewrite. The GDD's `Decision:` lines can cite an id ("Decision: D4, tap to jump"), so the
+two agree without repeating each other.
+
+## Where each record goes
+
+| Something happened | Where |
+|---|---|
+| The person changed the game by hand | the journal |
+| A design choice with a real alternative was settled | the decisions log (and the GDD's current text) |
+| A step, test, dead end or lesson of this session, with its cost | the dev log (`feedback log`) |
+| A finding the next game of this genre should start with | `lessons add` |
+
+One event can belong in two places: a choice settled after a dead end is a `dead-end` in the dev
+log and a decision in the log. The dev log is the session's story for Funpixel; the decisions log
+is the game's own record for whoever works on it next.
+
+## Measured outcomes, the owner and what logs itself
+
+The dev log is also how the kit learns which practices work. `npx @funpixel/tools feedback collect`
+ranks what worked by its measured change, so give a `worked` or `didnt` line its numbers:
+
+```
+npx @funpixel/tools feedback log "lean AO masks and skipping frozen rigs" --kind worked --metric "phone p95" --before 34 --after 25.5 --unit ms --evidence src/view/aoLean.ts
+npx @funpixel/tools feedback log "lighting passes on melted walls" --kind dead-end --minutes-lost 600
+npx @funpixel/tools feedback log "the walk is still a cut-out" --kind owner --verdict reject --screenshot design/shots/walk.png
+```
+
+- Evidence: `--evidence` (a path in the game), `--film`, `--sha` (a commit), `--test` (a test name);
+  each is checked to exist, at once and again by `collect`. A line whose evidence is not found reads
+  as unverified; words that name no file ("the deaths page") read as unverified too.
+- A lesson that says it fixed something ("…fixed it", "now always recovers") counts as worked, and a
+  "34 -> 25.5 ms" in its words is read as its measured change.
+- The owner outranks: owner lines and every game's open pipeline notes (`note add "…" --stage <s>`,
+  closed only by evidence, reopened by the owner's `note verdict N reject "…"`) lead the report.
+- What logs itself: `sim` (the naive bot's lost runs, its warnings), `play` (high defects), `hook`
+  and `life` (warnings, movers), `profile` (frame p95) and `playtest` (the panel's mean) append a
+  `measure` line with the last value as `before` (`FUNTOOLS_NO_AUTOLOG=1` turns it off). A game's
+  post-merge hook can run `npx @funpixel/tools feedback merged`: the merge becomes a `worked` line
+  with the numbers that moved since its merge base.
+- A/B records: `feedback ab "<game>" --routes gdk,non-gdk --overall 7.0,8.0 --axes "story=7.0/8.7"
+  --winner non-gdk --judges "3 blind seats"`; `collect` says where a route keeps losing.

package/plugins/cursor/skills/funpixel-game-feel/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: funpixel-game-feel
+description: Use when an action feels unanswered, mistimed or hard to read (mushy, floaty or laggy controls), or when designing the response to a new action or payoff. Covers event-to-feedback mapping, payoff ladders, motion and audio by role, accessibility and testing. In Unity (haptics, hit-stop, screen shake), follow references/unity.md.
+---
+
+# Game feel: make the response readable
+
+Feel is why a player keeps pressing the button. Look at what the hits tune: Celeste's dash opens
+with a 50 ms freeze and a shake along its direction, and its jump still fires 0.1 s after the ledge is gone;
+Enter the Gungeon's roll is safe for only its first half, so every roll is a decision; Suika's
+watermelon is rare enough that its arrival is the story of a run. Each is one response, sized to
+what happened, and tuned for months.
+
+The player should know that an action registered, what it changed, and what they can do next.
+Choose feedback for the game: an impact, a chess move and a quiet deduction need different
+responses. More particles or shake do not automatically mean better feel.
+
+## Tools
+
+- `check_plan` reviews the design note. For a complete game, keep the event map under `## Juice`
+  in the design document (`design/GDD.md`, or an older `design/README.md`); a focused fix only
+  needs the affected event and its acceptance check.
+- `capture_view`, or `npx @funpixel/tools capture --view playing --verbs <verb> --hold 60
+  --viewport phone`, records visible responses. Use the actual verb and response timing.
+- `inspect_scene`, locally `scene --motion`, measures the sampled scene, not quality or intent.
+- `npx @funpixel/tools feel` plays `test/feel.json` through the real controls and reads timing a
+  still cannot show: the verb's jump, dash and invulnerable numbers beside the design's, tell to
+  strike, the death beat and the time back to control, and each actor's look in each state. The
+  optional `__FPX_STATE__` fields it reads, and why each helps, are in
+  [references/measure.md](references/measure.md).
+- `probe`, locally `npx @funpixel/tools verify`, checks declared self-tests and audio events.
+- `generate_sound` and `generate_sprite` supply assets when needed; reuse accepted ones first.
+- `npx @funpixel/tools play --viewport phone` lets the blind player test timing and controls;
+  the `critic` agent reviews presentation through `funpixel-verify`.
+
+## The checklist
+
+1. **Find the unanswered event.** Reproduce it through real controls. Map the core action,
+   relevant failure and resolution to feedback. Record when, what changes visually, duration,
+   motion, sound and camera response. Explicitly mark intentional silence or stillness. Use the
+   smallest set that communicates the result; a silent game still needs a readable response.
+
+2. **Tune to the role.** For physical combat, try recoil, contact poses, a local flash, particles
+   or sound, sized to impact weight. For placement, try a legal-position preview and a decisive
+   settle. For deduction, reveal the changed rule or connection. These are techniques, not a
+   compulsory bundle. Keep the most important event distinct from routine actions. In an action
+   game with several weapons, one contact function they all call keeps the feel consistent and
+   tunable in one place; a new weapon that opens or cashes a state the old verbs already make
+   (a reeling enemy) gives combos without new systems. One action game's values, its weapons as tools
+   of a pillar, and what its blind player caught: [references/contact.md](references/contact.md).
+
+3. **Protect control and fairness.** Hitstop freezes the picture, not the player: a press during
+   it that is dropped reads as lag. Telegraph danger early enough for the intended player to react; measure the timing (`feel`) rather than copying one duration.
+   Use shape and position as well as colour. Distinguish a missed action from an ignored press.
+   Linear motion can be right for projectiles or exact placement; easing is there to serve control.
+
+4. **Keep the payoff legible.** At phone size, avoid overlapping reward text, banners and the
+   action. Separate world effects from HUD feedback. Use a stored base scale for squash instead
+   of compounding transforms. Pool frequent effects and measure the target device's frame time;
+   particle counts in a recipe are starting values, not universal budgets.
+
+5. **Offer comfortable feedback.** Respect `prefers-reduced-motion` and provide controls for
+   effects the game uses. Replace camera shake, flashing or large movement with stable outlines,
+   concise state changes or other readable cues. Reduced motion may remove hitstop and local
+   flashes too. Avoid rapid flashing; a frequency cap alone does not establish accessibility.
+
+6. **Measure, play, fix.** Test that each relevant sim event reaches its intended feedback and
+   that repeated input remains responsive. Capture before, contact and aftermath at phone and
+   desktop sizes. Verify audio events when audio is promised; a started cue does not establish
+   its audible quality. Play with sound off and reduced motion. File concrete findings, change
+   one cause and repeat the affected action; `npx @funpixel/tools compare` sets the view's before
+   and after side by side, so a reported fix is seen. A still frame cannot prove timing; `feel`
+   measures it, and neither proves enjoyment.
+
+Use [references/recipes.md](references/recipes.md) for optional implementation patterns,
+[references/motion.md](references/motion.md) for gaits and strikes as tunable data, and
+[references/payoffs.md](references/payoffs.md) for reward hierarchy and fairness. Adapt their
+values and effect choices to the brief; mechanics added to fill a table make the game louder, not clearer.
+
+## Worked example
+
+A quiet tile puzzle registers a drop but gives no clue why it was refused. Preserve the static
+board style: preview legal cells, return an illegal tile to its origin, and show the conflicting
+edge with a stable outline. Replay legal and illegal drops on phone, then test reduced motion.
+No idle bob, combat flash or sound generation is needed. In an action game, the same unanswered
+input problem may instead need a contact pose and a short impact cue.
+
+## Common mistakes
+
+- Adding every effect recipe to every genre instead of making the result clearer.
+- Timing feedback for a critic's screenshot instead of the player performing the action.
+- Deleting feedback in reduced motion instead of replacing uncomfortable effects.
+- Calling effects measured in a quiet one-second sample proof that attacks read correctly.
+- A verb that exists only in the sim: with no pose, sound or visible result, players report it
+  missing (one game's shove, for weeks).
+- Limiting a helper the genre's hit never limits (one game's capped jar, reported as a bug
+  twice; Peggle's bucket never runs out). A real resource keeps its empty state visible.
+- A tell carried by sound alone: a muted phone never hears it, so the visual has to build across
+  the whole warning.
+
+Where this comes from: our own games (the juice tables, one action game's contact work, the `feel`
+measures) and the hits in research 18; the juice vocabulary from Vlambeer's talks and "Juice it or
+lose it"; review habits from Claude Code Game Studios (MIT); hitstop that freezes the picture, not
+the player, began as a platform engine note.

package/plugins/cursor/skills/funpixel-game-feel/references/contact.md

@@ -0,0 +1,110 @@
+# Contact, verbs and weapons in an action game
+
+What one 3D action game learned about hits, verbs and weapons. It is a third-person
+deep-sea horror game in three.js, built with the GDK's tools in September 2026 (its making notes:
+`design/MAKING.md`, `PERF.md`, `assets.md`). Between its first and second playtest, the round
+that added the contact work below, the blind critic panel's juice score went 5.60 → 6.17 and look
+and feel 7.15 → 7.62. The same round changed other things too, so treat these as ideas with a
+reason, not a proven recipe. A quiet puzzle needs none of this.
+
+## One contact function
+
+Every weapon in it calls one `impact(target, dir, kind)`, so a weapon added later inherits
+the feel, and tuning happens in one place. What that function did:
+
+| Part | Its value | Why |
+|---|---|---|
+| Target jolt | along the hit direction | shows where the force went |
+| Flash | the struck part goes white for a few frames | says "that one", even in the dark |
+| Hit marker | at the reticle; coral for a sever or a kill | confirms the hit where the eye already is |
+| Camera punch | a few centimetres toward the hit | weight without a shake that blurs the target |
+| Hitstop | 45–90 ms, by the weight of the hit | the contact frame is held long enough to register |
+| Slow motion | a short beat on severs and kills only | kept rare so it still means a payoff |
+
+Under reduced motion it kept the marker and the flash and dropped the punch and the slow motion,
+so the hit still reads. Two traps it met: the flash lit every enemy's arm at once until each limb
+had its own material (three.js shares materials between copies; skill `funpixel-3d`,
+its three-loading reference, "Copies"), and hitstop that
+froze input read as lag (hitstop freezes the bodies; see [recipes](recipes.md#hitstop-on-the-bodies-not-the-loop)).
+
+```ts
+export function impact(t: Target, dir: Vec3, kind: 'hit' | 'sever' | 'kill') {
+  t.jolt(dir, kind === 'hit' ? 0.06 : 0.12);          // metres along the hit
+  t.flash(kind === 'hit' ? 0.06 : 0.1);                // seconds, the part's own material
+  hud.marker(kind === 'hit' ? 'white' : 'coral');
+  if (!reduced) camera.punch(dir, 0.03);
+  hitstop([t, hero], kind === 'hit' ? 0.045 : 0.09);  // bodies only; input keeps running
+  if (!reduced && kind !== 'hit') time.slow(0.35, 0.25); // scale, seconds
+}
+```
+
+## A verb nobody can see does not exist
+
+The game's shove worked in the sim for weeks with no body animation, and the owner asked "don't we
+have a melee attack?". To a player, a verb without a pose, a sound and a visible result is not
+there. A two-handed shove and a slash fixed it. `funtools feel` reads each actor's look per state
+([measure](measure.md)), which shows a state that borrows another's pose.
+
+The same goes for touch: on the phone a tap on a joint that missed showed nothing, so the blind
+player could not tell a cut from no cut. A miss that answers (a spark, a small "miss") tells the
+player the press arrived.
+
+## Combos from what is already there
+
+The dive knife added no enemy and no system. It cashes a state several existing verbs already
+create: anything *reeling* (opened by the pendulum dodge, pinned by a rivet, thrown by a Counter or
+a gun's stagger) loses a joint to the knife for free. That turned the old verbs into combos:
+Counter → knife → knife drops one; rivet → close in → knife. The strike button becomes KNIFE, lit,
+exactly when a reeling enemy is in reach, so the HUD teaches the combo at the moment it applies.
+
+A question to ask of any new verb or weapon: which state does it open, and which verb cashes it?
+
+## Weapons as tools that serve a pillar
+
+The game's three tools each answer a design pillar and draw on the one shared resource (the gas
+canister), so adding them kept the economy:
+
+- the cutter takes joints (the core verb);
+- the rivet driver pins an enemy to the wall behind it by a limb, and its rivets are recovered from
+  the walls (the twin of the weld pillar: what you fix in place stays);
+- the scattergun throws everything back and takes limbs up close, with rare shells, and it is the
+  loudest thing she carries, so it costs stealth.
+
+The owner asked for a famous game's stake gun. The team built the *fantasy* (pin an enemy to a
+wall) as its own tool with its own name and silhouette, and sent no franchise name or image to any
+generator: the ideas are free to use, the look and marks belong to their owner.
+
+Mid-build requests can quietly break a pillar. "Add guns" broke "you have no gun", "make her
+faster" broke the gas economy, "make manoeuvres easier" softened the pendulum as a skill. Each was
+kept and folded back: every tool costs gas, the automatic dodge side became an Assist setting.
+Re-reading the pillars after a request is cheap (skill `funpixel-gdd`).
+
+## Movement numbers that held, and how they were found
+
+| Verb | Design | Measured by `feel` | Note |
+|---|---|---|---|
+| Walk / run | 2.5 / 4.5 m/s | — | 2.7 / 4.8 broke the gas economy: the chapter bots rushed into extra fights and could not afford the second weld |
+| Dodge | 2.0 m in 0.26 s | 1.92 m in 0.30 s | one press; the side follows the pendulum |
+| Untouchable window | 0.21 s | 0.217 s | |
+
+Two lessons in that table. The speed change was caught by bots that play the whole chapter on five
+seeds in the tests, not by feel. And the dodge started as Space plus a direction, which was the main
+"hard to manoeuvre" complaint; one key that picks the side the pendulum wants fixed it, offered as
+an assist so the skill stays for players who want it.
+
+A long frame (a first-use shader compile) moves a wall-clock window: one `feel` run's dodge hit the
+rail. Warm up before measuring and run it twice (skill `funpixel-art`, its frames reference).
+
+## Tells that carry without sound
+
+The blind phone player died twice at the first enemy: the white arm showed about 0.3 s before the
+swing, and the rest of the 0.7 s warning was the hum, which a muted phone never hears. A tell that
+builds visibly across the whole warning (the arm growing toward white) carries on a silent phone;
+sound can add to it without carrying it alone.
+
+## Films need a bot that fights
+
+The game's route bots only cut, so films made from their runs showed no combat and a review could
+not judge the weapons. A `fighter` bot style, for films only (the tests keep the median bot), plays
+the verbs a keen player would: Counters, knives, rivets, a death. If the payoff is a fight, film a
+fight.

package/plugins/cursor/skills/funpixel-game-feel/references/measure.md

@@ -0,0 +1,125 @@
+# Measuring feel: the verb, the tell, the death, the look by state
+
+Panels judge stills, so four things that separate the hits from generated games went unmeasured
+(research 18's craft properties 1, 2, 4 and 7): whether the verb does what the design's numbers
+say, how long a threat warns before it hits and what the player can do about it, how long a death
+takes to read and to undo, and whether an actor looks different in each of its states.
+`npx @funpixel/tools feel` answers them from a trace: a script plays the real controls on the built
+game while every frame's `__FPX_STATE__` (only the fields below) and each named actor's look are
+kept. It is a mirror, not a gate: a note never fails it, and "not measured" is never a pass.
+
+## The fields it reads
+
+All optional. Expose what your game has; a field you leave out is a measure that says "not
+measured", which is honest.
+
+| Field | Why | What it measures |
+|---|---|---|
+| `t` | the game's own clock, in seconds: every step your loop gives the rules, after its clamp | every time measured on it, so a stutter in the browser that your game clamps does not lengthen a window; without it the page's clock is used and a long frame is said beside a gap |
+| `hero: { x, y, grounded }` | where the body is and whether it stands | jump height, time in the air, apex hang (time in the top 10% of the arc); a fall off a ledge never turns back, so it is not counted as a jump |
+| `hero.body` | the hero's height in the state's units | distances in body heights, the unit the hits' numbers translate to across engines |
+| `hero.unit` | `px`, `tile`, `slot`, `m` | a design row in those units compares without `body` |
+| `hero.vx` | speed, for a hero that accelerates | top speed and time to it from rest, leaving out dash and invulnerable frames (a stepper's position jumps, so speed is read only from `vx`) |
+| `hero.state` | the game's word: `idle`, `run`, `jump`, `dash`, `hurt`, `dead` | a dash's distance, time and speed (`dash`, `roll`, `dodge`), apart from the run's; a death; the player's look per state |
+| `hero.invulnerable` | true while nothing can hurt the hero | the safe window; one that opens with a verb is a defensive verb, with its committed tail after |
+| `threats: [{ id, kind?, phase }]` | a phase naming a tell (`tell`, `windup`, `warn`, `charge`, `aim`) and a strike (`strike`, `attack`, `active`, `fire`, `slam`) | tell to strike per kind, and strikes that came with no tell |
+| `dead` | true from the fatal hit until the cut | the death beat |
+| `control` | false while input does nothing (a beat, a card, a fade) | death to control again |
+| `actors: { nodeName: state }` | keyed by the scene node's `label` (Pixi) or `name` (Three) | each actor's look in each of its states |
+
+List every threat that can hurt the hero in `threats` on each frame it exists (a spike row, a
+guard, a projectile), even one that never winds up. If the list is empty, feel sees nothing that can end
+the run: tells, strikes, the death beat and the restart all come back "not measured", and the report says why.
+
+The scaffold's demo exposes all of them (`src/expose.ts`), draws a key pose per state
+(`src/pose.ts`), and `test/feel.json` plays it: a hop, a mashed hop, standing on a spike, a retry.
+
+## The script
+
+`test/feel.json`: `{ "viewport": "desktop", "seed": 1, "steps": [...], "expect": { ... } }`. Steps are
+a journey's (tap, drag, hold, press, wait; no `view` or `verb` jumps) plus two:
+`until field=value [ms]` waits for the state (`until screen=playing`, `until control=false 9000`), and
+`retry <step>` repeats an input every 150 ms until the player has control again, so the time from
+death to control is the game's, not the script's pause. Wait for the death with `until control=false`
+rather than `dead=true`: a game with no beat never sets `dead`, and the wait would count against
+its restart. Put a retry after the card is up when the state has no `control` field. `--journey <name>` plays a journey's steps instead. To read a
+cooldown, press through it (`press Space 12`); the gap reads the cooldown to within the press spacing.
+Modifier keys hold under another key with `&`: `hold ShiftLeft 1500 & hold ArrowRight 1500` is a
+held run (`ShiftLeft`, `ShiftRight`, `ControlLeft`, `AltLeft`, `MetaLeft`…, the codes a game reads).
+
+## Forgiveness windows: a sweep across runs
+
+Coyote time (a jump pressed just after leaving the ledge still jumps) and the jump buffer (one
+pressed just before landing is kept) cannot be read from one run: it cannot tell a window from a
+missing one. `sweeps` in the script times attempts instead, each on a fresh load of the same seed:
+its setup `steps`, then the page presses the verb at an exact offset from a moment on the game's
+clock and reads whether it took. Offsets step out from the moment (0, 20, 40 … 200 ms by default,
+`offsets: [first, last, step]`) until two in a row miss; the window is the largest that took.
+
+```json
+"sweeps": {
+  "coyote": { "steps": ["until screen=title", "press Space", "until screen=playing"],
+              "anchor": "hero.grounded=false", "press": "ArrowUp", "success": "hero.state=jump" },
+  "buffer": { "steps": ["until screen=title", "press Space", "until screen=playing"], "cue": "ArrowUp",
+              "anchor": "hero.grounded=true", "press": "ArrowUp", "success": "hero.grounded=false", "within": 300 }
+}
+```
+
+`anchor` is the moment (a state turning true after it was false: leaving the ground, a strike
+starting); a coyote press comes after it. A buffer press comes before it, so the `cue` key starts
+the jump whose landing is the anchor, and a calibration run times the landing first. `success`
+must hold within `within` ms (default 300) after both the press and the anchor. The attempts are
+frame-quantized: at 60 fps a window reads to a frame either way, and the result shows the offset
+that took, the first that missed and how many runs it took. The scaffold's demo has both: a hop
+pressed up to 0.1 s before landing is kept, and a spike hits only 0.1 s after it stands, so a hop
+that late still clears it (its coyote time, since it has no ledge). Each attempt reloads the game,
+so a sweep takes a minute or so; `--no-sweep` skips them, and `playtest --quick` does too.
+
+`expect` holds the script's own numbers, read like the design's. The design wins on the same
+measure: a row of `design/GDD.md` `## The numbers` whose words name one (jump height, time in the
+air, apex hang, top speed, time to top speed, dash distance, dash time, dash speed, invulnerable
+window, cooldown, coyote time, jump buffer, tell, death beat, restart), with a unit: s, ms, frames at 60 fps, body heights, px,
+tiles, per second; a range (`0.2–0.3 s`) or a bound (`under 2 s`).
+
+## What it says, with the numbers behind it
+
+- **The verb against the design.** Each row, design beside measured, within 15% or one frame, else
+  the gap in units and per cent. The number the player feels is the measured one: change the code
+  or the design so they agree. Celeste's `Player.cs` for scale: run 90 px/s reached at 1000 px/s²
+  (about 0.09 s), jump launch 105 px/s held up to 0.2 s, half gravity near the apex while jump is
+  held, coyote time 0.1 s, dash 240 px/s for 0.15 s, dash cooldown 0.2 s, a buffered jump kept 4 frames.
+- **Tell and dodge.** A tell under 0.5 s is noted: research 18's own target is 0.5–0.8 s by shape
+  and sound, ours rather than a source's. For scale: Slay the Spire shows each enemy's next action
+  and its damage a whole turn ahead; Gungeon's dodge roll lasts about 0.7 s, invulnerable for its
+  first half and open for the rest. A game whose threats struck while no verb opened a safe window
+  gets a note, and the choice stays yours: a roll, a hop, a parry, or a line in the design saying
+  why stepping away is the whole answer. (Hades' dash invulnerability is unverified in research 18,
+  so it is not used as a reference.)
+- **Death beat and restart.** A hit that cuts straight to the card (under 0.1 s), or a pause where
+  the hero looks the same as the second before, is noted; so is a restart over 2 s. Research 18's
+  targets, ours: a readable 0.3–0.6 s beat, then control back in under 2 s (Celeste respawns in
+  about a second, an estimate).
+- **Looks by state.** An actor with one look across its states is noted. Dead Cells' rule is the
+  way in: the fewest key poses that read, frames added only around a key; Celeste stretches its
+  hero to 0.6 × 1.4 on a jump. The look key sees a picture or sheet frame change, a part shown or
+  hidden, a tint, a squash of 20% or more, a turn of 45° or more; it ignores a breath, a small lean
+  and a facing flip, so two states that differ only there share a look (said as detail, not noted).
+
+## What it cannot say
+
+A window the script has no sweep for reads "not measured": sweep it, or pin it in the rules tests
+(the scaffold's `test/rules.test.ts` does both). Without `t` in the state, times are the page's
+clock in this machine's browser: a long frame lengthens a tell by that frame, so compare runs made
+the same way. Sweep presses are synthetic key events: a game that checks `isTrusted` ignores them. `funtools playtest` runs `feel`
+when `test/feel.json` exists and puts each property's numbers in the facts every seat reads first.
+
+## Feedback on key events
+
+`feel` also reads the state's `juice` (the scaffold's `juiceLevel()`: shake, flash, squash, screen
+flash, hitstop, particles) around every key event the trace shows: the score rising, a hit, a life
+lost, a death (`dead` turning true) and a won or lost screen. An event with no rise within about
+100 ms is a note (a late answer reads as lag), and a win, loss or death that answers no bigger than
+a point is a note: each channel is sized against its own peak in the trace, so size means how many
+channels answered and how hard. The numbers live in one place, `TUNE` in `src/juice.ts`, and each
+row of the `FEEL` table in `src/feel.ts` says whether it is a small or big moment; a self-test fails a
+big one that gets no more than every small one. A game whose state has no `juice` is not measured.

package/plugins/cursor/skills/funpixel-game-feel/references/motion.md

@@ -0,0 +1,134 @@
+# Motion as data: gaits and strikes
+
+A walk, a limp, a pounce and a heavy swing are numbers before they are code. Every starter ships
+three engine-free files that hold them: `src/motion.ts` (gait presets and their dials),
+`src/motion-sample.ts` (the stride driven by distance, the pose at a phase, a clip's rate) and
+`src/strike.ts` (key poses and timed phases). Pick a preset, tune a few dials, and print the
+warnings while you tune. While you build (the dev server, or `strict: true`) a dial past its range
+is refused with the reason the edge exists, so a number you tuned never silently becomes another;
+in a shipped game nothing throws: it is held at the edge and named.
+
+Units are body heights (bh), so the same table serves a 64 px sprite and a 1.75 m person: a person
+walking 1.4 m/s moves 0.8 bh/s.
+
+## Gaits: pick a preset, tune the dials
+
+| Preset | designSpeed (bh/s) | stride (bh) | stance | What reads |
+|---|---|---|---|---|
+| walk | 0.8 | 0.8 | 0.62 | two bobs a stride, arms opposite the legs |
+| run | 2.3 | 1.6 | 0.38 | both feet off the ground, a lean into speed |
+| sneak | 0.4 | 0.6 | 0.72 | hips low (crouch 0.25), arms close, small bob |
+| carry | 0.6 | 0.65 | 0.66 | arms braced (swing 0.05), more side sway |
+| limp | 0.5 | 0.6 | 0.64 | the bad leg plants shorter, the body dips on it |
+| old | 0.5 | 0.55 | 0.68 | short steps, a forward stoop, low foot lift |
+| child | 1.0 | 0.85 | 0.58 | quick, bouncy, big arm swing |
+| quadruped | 1.2 | 1.0 | 0.6 | hind, fore, hind, fore (height = shoulder) |
+| flyer | 3.0 | n/a | n/a | 6 beats a second, 30% of each cycle gliding |
+
+The dials and their ranges (`GAIT_DIALS`): designSpeed 0.2–4, stride 0.3–2.2, stance 0.25–0.75
+(above 0.5 walks, below runs), bob 0–0.06 of height, footLift 0–0.25, lean −0.2–0.35 rad,
+armSwing 0–0.8 rad (past it the hands crest the shoulder and flail), hipYaw 0–0.3 rad (the chest
+turns back 60% of it), sway 0–0.04, crouch 0–0.35, limp 0–0.6, flapHz 0–12, glide 0–0.8.
+
+`checkGait` also names pairings that read wrong: a deep crouch above 1 bh/s (a scuttle), a run's
+stance under a walk's pace (jogging on the spot), a step rate outside 1–4.5 a second (change the
+stride, not the clock), a flyer with no beat (a stone gliding).
+
+Give each person in a crowd one asymmetry (a limp of 0.1, a swagger of hip turn, a stoop) and
+vary designSpeed ±15%: a crowd on one preset marches like a drill team.
+
+## Keep the feet on the ground
+
+A clip or a stride is tuned for one speed. Played at another, the feet slide. Two routes:
+
+```ts
+import { gait } from './motion';
+import { advance, clipTimeScale, sampleGait } from './motion-sample';
+
+const { gait: g, warnings } = gait('walk', { limp: 0.15, designSpeed: 0.75 });
+if (import.meta.env.DEV) for (const w of warnings) console.warn('gait ' + w.dial + ': ' + w.why);
+
+// A rigged clip (three.js AnimationMixer): the rate follows ground speed, held at 0.6–1.6.
+const t = clipTimeScale(g, speedMps / heightM);
+walkAction.timeScale = t.scale;
+if (t.switchTo) crossFadeTo(t.switchTo);        // a run clip, not a walk at 2×
+
+// Parts in code (a cut-out rig or a primitive body): the phase moves by distance walked.
+phase = advance(g, phase, movedThisFrameM / heightM, dt);
+const p = sampleGait(g, phase);
+hips.position.y = hipHeight + p.y * heightM;
+hips.position.x = p.x * heightM;
+hips.rotation.y = p.hipYaw; chest.rotation.y = p.chestYaw; body.rotation.x = p.lean;
+armL.rotation.x = p.arms[0]; armR.rotation.x = p.arms[1];
+p.legs.forEach((leg, i) => { feet[i].position.z = leg.x * heightM; feet[i].position.y = leg.lift * heightM; });
+```
+
+A planted foot moves backward at exactly the body's speed (it stays still on the ground), and a
+swinging foot eases forward on a sine, never a triangle wave. Standing still plays idle, never a
+walk at rate 0. A flyer's phase moves by time (`flapHz`), and `p.wing` runs −1 to 1; tilt the body
+into each turn as well.
+
+### A walk made of pictures
+
+A sheet walk follows the same rule: the frame comes from the phase, and the phase from distance.
+
+```ts
+phase = (phase + movedThisFrameM / (0.8 * heightM)) % 1;   // one cycle per ~0.8 body heights
+body.material.map.offset.x = Math.floor(phase * FRAMES) / FRAMES;
+body.position.y = Math.abs(Math.sin(phase * Math.PI * 2)) * 0.03 * heightM;  // bob at twice the step rate
+```
+
+Use 8–12 frames for the hero (contact, down, passing, up per foot) and 6+ for a background
+walker; fewer pops between poses. Hold the contact frame on a stop rather than snapping to idle
+mid-stride. `walk` reports `HERO WALK POPS` (under 6 frames), `ON A TREADMILL` (walk frames while
+standing) and `ON A TIMER` (frames that keep the clock's pace when the speed changes); contact and
+bob are for your eye on the walk film.
+
+Declare the preset in the actors contract (`gait: "walk"`, `height: 1.7`, HOOKS.md "Actors"), and
+`npx @funpixel/tools life` adds a note when an actor's travel is far from its preset's designSpeed
+(the feet moonwalk or scramble) and names the nearer preset, or when a declared gait slides.
+
+## Strikes: five keys, four phases
+
+`src/strike.ts` holds a strike as guard → wind-up → contact → follow-through → guard, with seconds
+for each phase and an easing each: the wind-up eases out and settles into the pose, the strike
+eases in and accelerates to contact, the follow-through carries past the target, the recovery
+eases home. `bodyLead` starts the hips and chest that long before the arm.
+
+| Preset | anticipation | strike | follow-through | recovery | lead |
+|---|---|---|---|---|---|
+| jab | 0.10 | 0.05 | 0.08 | 0.15 | 0.03 |
+| heavy (overhead) | 0.40 | 0.09 | 0.25 | 0.45 | 0.08 |
+| sweep | 0.22 | 0.08 | 0.20 | 0.30 | 0.06 |
+| kick | 0.18 | 0.07 | 0.12 | 0.28 | 0.05 |
+| lunge (a creature's bite) | 0.30 | 0.06 | 0.10 | 0.40 | 0.04 |
+
+Ranges: anticipation 0.08–0.6 s, strike 0.03–0.15 s (slower reads as a push), follow-through
+0.05–0.4 s, recovery 0.1–0.8 s (the window an opponent punishes), lead 0–0.12 s. `checkStrike`
+names a wind-up under 1.5× the strike (weightless) and an arm over the shoulder on a move that is
+not an overhead (out of control).
+
+```ts
+import { STRIKES, strikeAt } from './strike';
+
+let t = 0;                                       // set to 0 on the press
+function update(dt: number) {
+  const before = t; t += dt;
+  const r = strikeAt(STRIKES.heavy, t, before);
+  if (r.contact) resolveHit();                  // once, on the contact frame, never on the press
+  arm.rotation.x = -r.pose.raise * 1.6;
+  arm.position.z = r.pose.reach * 0.4;
+  chest.rotation.y = r.body.twist * 0.6;        // the body leads the arm
+  hips.position.y = baseY - r.body.crouch * heightM;
+}
+```
+
+`r.impactPhase` is where contact sits in the whole move (0–1); hitstop, the flash and the sound
+belong on that frame ([contact.md](contact.md)). The enemy's tell is its anticipation: tune it
+with `funtools feel`'s tell-to-strike reading, not by feel alone.
+
+## These are starting points
+
+The presets are reference numbers to tune, not finished motion. A game's own character (a weary
+courier, a skittish crab) comes from moving two or three dials away from the preset on purpose and
+saying why in the GDD's `## Actors` Motion column.

package/plugins/cursor/skills/funpixel-game-feel/references/payoffs.md

@@ -0,0 +1,35 @@
+# Response, reward and restraint
+
+Measure the core action before adding decoration. Record the input frame, acknowledgement frame,
+contact frame and peak pose. At 60 Hz, 3–4 frames is roughly 50–67 ms; label a duration in
+milliseconds if the game is not fixed at 60 Hz. An immediate pose and sound confirm a press even
+when the attack needs a longer wind-up. Input buffering survives local hitstop.
+
+When escalation serves the loop, make a payoff ladder in the design note, with distinct rewards where useful. A three-tier chain example:
+
+| Tier | Trigger | Visible answer | Audio | Recovery |
+|---|---|---|---|---|
+| Small | one target | directional kick, 3-frame peak, 6 fragments | dry pop | next input available |
+| Medium | three linked targets | ripples staggered 70 ms, one combined score | rising three-note phrase | readable gaps between ripples |
+| Peak | a rare six-target chain | 4-frame hero pose, expanding ring, score parked above play | short sting, music ducks | threats stay visible |
+
+These are starting values to test, not universal settings. Choose distinct poses or compositions,
+not just the same scale tween with a larger number. Keep hit effects attached to the target and
+show the direction of force. A death has a collapse or exit; the player can follow where it went.
+If a pickup flies to the HUD, its arrival updates or pulses the correct counter once.
+
+Schedule quiet beats between rewards. Music can add a layer at a higher stage and resolve on its
+clear; a repeated attack should not restart the track or replay a sting every frame. Give every
+sim event its declared answer, including failure, recovery and menu actions. At the peak, check
+hero/threat silhouettes, score overlap and phone frame cost before adding another particle.
+
+Prove timing in a short capture sequence with the input and event times alongside it. Stills can
+prove composition; they cannot prove latency, rhythm, music or a satisfying loop. Use the blind
+player's real-input report for control and comprehension, audio observations for sound, and
+clips for motion review when the reviewer can actually watch them. Mark unavailable evidence
+`not observed`. Compare the reduced-motion version too: it keeps readable poses, outlines and
+sound while suppressing camera movement and full-screen flashes.
+
+A frustrating death is a design finding: record the last safe decision, the warning and the
+available escape. Repeated unavoidable first-wave deaths mean change the opening pressure,
+controls or recovery rule. They are not fixed by a louder explosion.