@funpixel/tools 0.0.0-stage → 0.1.1

package/plugins/robin/skills/funpixel-feedback/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: funpixel-feedback
+description: Use when a step, test, dead end, lesson or decision happens while building a game, when the person changed the game by hand, and before ending a session that changed one. Covers the dev log with costs, the end-of-session report, the kit verdict and the game's memory (journal and decisions).
+---
+
+# The dev log and feedback
+
+Funpixel improves from what sessions report: which tool was missing, what the agent rebuilt by
+hand, which trap cost an hour. Our studio's dev log, which a
+Stop hook enforced and a person read, gathered 412 entries in two days (49 dead ends and 44
+lessons, most with a cost). This skill is that log, and the Stop hook reminds you of it until it is
+filed.
+
+## Tools
+
+- `report_feedback` files the session's entries, its report and the kit verdict with Funpixel. The
+  game is optional: a game the server has never seen is filed without one.
+- Without the MCP, or when the call fails: the same entries, one JSON object per line, in the
+  game's `.funtools/devlog.jsonl` (the kit verdict in `.funtools/kit-feedback.jsonl`), written with
+  your file tools, or one line per call: `npx @funpixel/tools feedback log "…" --kind lesson`.
+- `npx @funpixel/tools feedback collect <folders…>`: the owner first, what worked ranked by its
+  measured change, dead ends by hours burned, A/B records, kit tools; `--propose` drafts kit
+  edits, `--html page.html` writes one page.
+- The game's own memory, read at session start: `journal` (what the person changed and why) and
+  `decide` (choices against their alternative, `--supersedes` to replace one). Which record
+  goes where: [references/memory.md](references/memory.md).
+
+## 1. Log as you go
+
+One entry per event, written when it happens, not reconstructed at the end:
+
+| kind | When | Example text |
+|---|---|---|
+| `step` | a milestone reached; a progress card writes it (one event, not two) | "first slice passes verify: drag swings the cradle, windows score" |
+| `test` | a check added or a measurement taken | "levels 1-50 solvable; median solver depth 9 rising to 21" |
+| `dead-end` | something tried and abandoned | "keyed the pigeon sprite three times; the white feathers kept the green" |
+| `lesson` | a fact the next session needs | "Pixi deltaTime is frames; use deltaMS / 1000" |
+| `decision` | a choice with an alternative | "platformer card without a jump; the verb is swinging" |
+| `worked` / `didnt` | a change measured to help, or not | "lean AO masks: phone p95 34 -> 25.5 ms" |
+| `owner` | the owner's words or verdict | "the walk is still a cut-out; legs must stride" |
+
+Fields: `kind`, `text` (one or two sentences), and where known `cost_usd` (a number), `minutes`,
+`minutes_lost`, `evidence` (a path), `sha`, `test`, and for `worked`/`didnt` `metric`, `before`,
+`after`, `unit`. Unfound evidence reads as unverified. Dead ends carry their time and cost. More:
+[references/memory.md](references/memory.md).
+
+## 2. Report what was missing
+
+Before finishing, one report with one category per item:
+
+| category | Use when |
+|---|---|
+| `tool_gap` | a Funpixel tool was missing or too narrow |
+| `workaround` | you built something the platform should have done; say where it lives and what it cost |
+| `provider_failure` | a generation was refused, failed or came back wrong; say whether a retry cleared it |
+| `verification_gap` | something you could not prove with verify, probe or review |
+| `knowledge_gap` | a trap a skill would have prevented |
+| `platform_trap` | build or publish behaviour that silently broke the game |
+| `built_custom` | you hand-wrote a system a package or the SDK could have given |
+| `package_gap` | an npm package you wanted and could not use |
+| `prompt_feedback` | an instruction in this kit was wrong, unclear or contradicted another |
+| `quality_note` | anything else about the result's quality |
+
+Each item: `category`, `text`, and where they apply `pipeline_step` (plan, assets, code, verify,
+review, publish), `blocking` (true or false), `attempted_first`, `cost`, `evidence_path`, and
+`suggested_home` (`mcp_tool`, `cli`, `skill` or `server`). Nothing was missing is a valid report:
+say so in one `quality_note`, with what went well.
+
+## 3. File it
+
+With the MCP: one `report_feedback` call carrying the dev-log entries since the last report and the
+items above.
+
+Without it (or when the call fails), write lines to `.funtools/devlog.jsonl` in the game folder
+with the Write or Edit tool; hosts refuse a shell redirect and your home folder. It never ships.
+Each line carries the time, and the report goes in a line with `"kind": "feedback"`, which is what
+the Stop hook looks for:
+```json
+{"at":"2026-09-26T14:02:11Z","kind":"dead-end","text":"keyed the pigeon sprite three times; the white feathers kept the green","cost_usd":0.39}
+{"at":"2026-09-26T14:40:05Z","kind":"feedback","items":[{"category":"tool_gap","text":"no key for near-white sprites; drew the feathers in code instead","pipeline_step":"assets","blocking":false,"suggested_home":"mcp_tool"}]}
+```
+
+## 4. The kit verdict
+
+At the hand-back of a complete game (the Stop hook asks once; `/fp:playtest` ends with it) say how
+the kit did: the tools, skills, hooks and commands, not the game. Each item adds `kind` (`worked`,
+`hurt` or `missing`) and `tool` (what it is about: `verify`, `capture --all`, `funpixel-art`,
+the Stop hook). Pick the category that fits; one line with `tool` `kit` says whether the kit did
+well or let you down, and why. Honest either way: a tool that cost an hour is worth more to us
+than praise.
+```json
+{"at":"2026-09-29T18:02:11Z","kind":"kit-verdict","items":[{"category":"verification_gap","kind":"hurt","tool":"audit-screens","text":"flagged below-the-fold scroll content as clipped; paged the list to pass"},{"category":"quality_note","kind":"worked","tool":"kit","text":"Overall: did well; verify caught two real bugs"}]}
+```
+That line is the fallback in `.funtools/kit-feedback.jsonl`; with the MCP the same items go in the
+`report_feedback` call.
+
+## When a person played it
+
+Ask for, or record, four things: in the first five minutes, did they know the goal and the
+controls; where were they confused; what delighted them; their top three changes. Log their words as
+`owner` lines; they outrank any agent's claim.
+
+## Worked example
+
+A session added a boss to a shooter. The log gained: `step` "boss fight passes verify", `dead-end`
+"generated the boss as one sheet of 16 frames; frames 13-16 were one pose; regenerated as 4x3"
+(cost 0.26), `lesson` "sheets over 12 frames repeat poses". The report: `workaround` "wrote a
+frame-difference check to find repeated sheet frames" (suggested home `mcp_tool`, blocking false),
+`verification_gap` "verify cannot tell whether the boss's attack telegraph is readable". One
+`report_feedback` call filed both.
+
+## Common mistakes
+
+- Writing the log at the end from memory: the dead ends and their costs are gone.
+- "Everything worked" when you rebuilt a platform feature by hand: that is a `workaround`.
+- Costs typed as `$0.26` in a shell command: the shell expands `$0`.
+- Filing feedback about the person's idea; this is about the tools and the kit.
+- A `worked` line with no numbers or evidence: it ranks last and reads as unverified.
+
+Where this comes from: our studio's dev log and the kit-verdict loop.

package/plugins/robin/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/robin/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/robin/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/robin/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.