@funpixel/tools 0.0.0-stage → 0.1.0

package/plugins/cursor/skills/funpixel-unity-game/references/traps.md

@@ -0,0 +1,109 @@
+# Unity traps, one line each
+
+Unity 6000.6.0f1 on iOS, from the field report §10 (and §9 for the batch runs). Each one failed
+silently or cost a build in one of the nine games. The skill that owns the fix is named where there
+is one.
+
+## Checked by `funtools doctor`
+
+Run it at project start and before every build: it reads the project's files and this Mac, never
+starts Unity, and prints each finding with its fix. One line per trap it catches:
+
+- Git LFS pointer files where binaries belong (FSBTool "Failed decoding audio clip", blank textures): fails, names the repository to pull in.
+- `activeInputHandler: 0`, the old Input Manager alone, on an iOS or Android project (no touch in a player build): fails.
+- `UnityEngine.Input` calls on a project set to the Input System only (each throws): fails.
+- The Input System hooked at `AfterAssembliesLoaded` (throws on iOS; `BackButton` hooks on first read): warns.
+- TextMesh Pro used with no Essential Resources (`CreateFontAsset` returns null): fails; a batch-mode ImportPackage of them (hangs): warns.
+- A camera in a scene or made in code with nothing adding an AudioListener (a silent build; `Sfx.EnsureListener()`): warns.
+- `Shader.WarmupAllShaders` (segfaults with URP keyword spaces; warm a ShaderVariantCollection): fails on URP.
+- A GLB glTFast cannot decode (meshopt, Draco or Basis without its decoder package, WebP ever): fails, because it imports as nothing.
+- `Shader.Find` of a project shader nothing references (null in a build): warns.
+- `enableWordWrapping`, a bare `new RenderParams{}`, runtime `QualitySettings.antiAliasing`, `-quit` with `-runTests`: warn.
+- ProjectSettings drifted from the project's setup method (Knockout Lap's iOS graphics APIs went back to automatic three times): warns; build through `Setup.Configure`.
+- A build module a target needs (Mac IL2CPP and Windows were missing): warns with the Unity Hub line.
+- No distribution certificate, Xcode account or App Store Connect key on an iOS project (each blocks TestFlight): warns.
+
+## Build and import
+
+- A mipmapped texture that is not a power of two ships as RGBA32 even with an ASTC override, and Unity
+  says nothing about it (`funpixel-art`, Unity page).
+- glTFast decodes textures embedded in a GLB to RGBA32; its "latest" tag pointed at an experimental
+  7.0, so pin 6.20 (`funpixel-3d`, Unity page).
+- `UnityRuntime.framework`'s plist says iOS 15.0 and its binary 16.0: ITMS-90208 (`IosPostprocess`).
+- High stripping removes an assembly reached only through `RuntimeInitializeOnLoadMethod`, and Unity
+  ignores a package's own `link.xml` (`com.joydle.firebase` hands its file to the linker).
+- TMP outline and underlay variants of materials made at runtime are stripped, and so are
+  `shader_feature` variants: use `multi_compile_local`.
+- TMP lives in uGUI 2.x, not a package of its own; its Essential Resources still go in `Assets/TextMesh Pro`.
+- Burst can time out under heavy host load; never ship that export.
+- Re-importing an atlas regenerates sprite ids, and a PNG of a new size keeps the old sprite rect, so
+  Unity drops the sprite.
+- iOS caches launch storyboards by name across updates: rename the storyboard (`JoydleLaunch`).
+- A project can be URP with `GraphicsSettings` saying none: the monorepo games assign the URP asset only
+  in `QualitySettings` (`m_CustomRenderPipeline: {fileID: 0}`), while Knockout Lap, Gallery Heist and
+  Particle Rush set it in `GraphicsSettings`. Read both before calling a project built-in; Floe Jam is
+  the one that is.
+- A WebGL build compressed with Brotli fails on a phone over the Mac's LAN address
+  (`ERR_CONTENT_DECODING_FAILED`: Brotli needs https or localhost): serve it with `funtools serve`,
+  which falls back to gzip there.
+- Addressables bundles built uncompressed (for a CDN to Brotli) weigh about twice as much from a
+  server that sends them raw (Gallery Heist's Room 1: 99.7 MB against 47.3 MB). `funtools serve`
+  compresses them on the fly as a CDN would, so its sizes and load times are what a player gets;
+  `--no-compress` shows the raw weight.
+
+## Runtime
+
+- Mono never sees `simctl launch` arguments: read them natively (`LaunchArgs.Get()`).
+- PlayerPrefs reads the launch-argument domain first: a flag `-coins` shadows the save key `coins`.
+- A Unity API call in a field initializer throws: move it to `Start`.
+- `OnApplicationPause(true)` also fires on resign-active (Control Center, Siri, call banners, Face ID).
+- `StopCoroutine` does not dispose the iterator, so a `finally` in a stopped coroutine never runs.
+- Static initialisation order: a cache declared after the colours it used threw
+  TypeInitializationException, and no build booted for about 7 hours.
+- Glyphs added at runtime cost a frame (48 ms): warm them behind the title.
+- `Screen.cutouts` allocates on every call: read it when the screen changes.
+- `preserveAspect` fits around the pivot; a `Slider` stretches to the row height; stretch anchors
+  plus a non-zero `sizeDelta` double the width.
+- The first scene load can eat about 1 s of a startup animation (`JoydleSplash` waits for it).
+- Unity 6 renamed the draw-call profiler counter, so an old probe reads 0.
+- C# `Math.Round` is banker's rounding, `List.Sort` is unstable, `Math.Sin` differs from V8 on about
+  6% of inputs and a naive hypot on about 40% (`references/from-a-web-game.md`).
+
+## Captures, logs and the Editor
+
+- `Debug.Log` on iOS goes to stdout, not the system log: launch with `--console-pty`.
+- `Object.Destroy` does nothing in edit-mode captures: use `DestroyImmediate`.
+- `CaptureScreenshotIntoRenderTexture` is upside down on Metal, and `ScreenCapture` stalls the next
+  frames.
+- Frames a judge scores come from a capture rig, not the Editor (Particle Rush, Oct 2026):
+  - a player build with a scripting define that turns the launch flags on and is not a development
+    build, because a development build stamps its watermark and console into every frame;
+  - `-shotscale 2` (passed to `ScreenCapture.CaptureScreenshot`'s supersize) for a full-resolution phone
+    frame from a half-size window (1172×2532 from 586×1266);
+  - a driver that plays like a person (holds, eases, misses a little), not a perfect line;
+  - a separate development build for measuring (`funtools unity probe`: SetPass calls, triangles, GC
+    per frame), whose watermark is fine because no one judges those frames; `funtools unity capture
+    --all` builds the no-watermark variant itself (`FUNPIXEL_PROBE` for that build only).
+- Unity wipes `Temp/` on launch, so a lock goes in `Logs/`; one Editor per project.
+- Every headless run rewrites ProjectSettings, AudioManager and TMP font assets, and leaves
+  `Assets/Resources/PerformanceTestRun*.json`, which ships.
+- Never pass `-quit` with a play-mode `-executeMethod` either (§9): the run ends Unity itself.
+- Never pipe a build or a check through `| tail`: it hid a failing compile and a commit went through.
+- Unity's NUnit is old: no `Assert.Multiple`, no `Does.Contain` on an enum.
+
+## Git
+
+- A file written outside Unity needs its `.meta` committed, or its GUID changes per checkout.
+- TMP dynamic font assets are rewritten by every batch run and conflict on every merge: keep shipped
+  fonts static, or clear them after captures.
+- The root `.gitignore`'s `*.csproj` silently drops hand-written test and server projects.
+- A copied project keeps its source's identity: Particle Rush's `.gitattributes` names The Hot Gates'
+  paths, its Android id is still Unity's template `com.UnityTechnologies…urpblank`, and standalone ids
+  are left as `com.DefaultCompany.2D-URP`. Check the ids and `.gitattributes` against the game's name.
+
+## Never changed by a script without a person looking
+
+Signing identity and team; the bundle id; `ITSAppUsesNonExemptEncryption` (the owner: "do not flip");
+App Privacy answers; the App Store Connect submission and the first purchase tick; the agent's own
+settings and hooks; anything in a build pipeline every game shares without a per-game opt-in marker;
+deleting "unused" assets: an agent deleted 20 files the game loads by name.

package/plugins/cursor/skills/funpixel-verify/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: funpixel-verify
+description: Use when adding or changing a mechanic, control or screen, before saying the game works or testing it, and once verify passes, to judge how good it is (the critic panel, the blind phone player, fix rounds, a genre hit). Covers the __FPX_* hooks, the checks in funpixel.json and the real Play button. In Unity (a build that starts, plays to an ending, does not crash), follow references/unity.md.
+---
+
+# Verify a Funpixel game, then judge it
+
+Verify lets you be bold: rework anything and know in a minute whether the game still plays
+through its real controls. It plays the build in a real browser and judges what the game declares,
+so the hooks below are part of the game; a runtime crash builds green and shows a blank screen.
+
+## Tools
+
+- `probe` plays a built or published game on Funpixel's browsers and returns the local verdict;
+  `screenshot` captures one view. Both take `click: "[data-fpx-start]"` to press the real Play first.
+- `capture_view` shoots a named `__FPX_VIEWS__` state; `audit_screens` measures every view's layout
+  (text under 12 px, hit areas under 44 px, overlaps, the notch); `inspect_scene` reads the scene graph.
+- Local and free: `npx @funpixel/tools verify` (`--watch` on every save), `capture`, `audit-screens`,
+  `scene`, and closer looks (`inspect`, `profile --compare`, `phone`, `clip`:
+  [references/eyes.md](references/eyes.md)); `build` and `preview` build on the platform.
+- Judging: the `player` and `critic` agents, `npx @funpixel/tools play` (blind, never the source),
+  `capture --all`, `look --read|--hud`, and `/fp:playtest` (`npx @funpixel/tools playtest`); hosted,
+  for credits, `review` and `play`.
+
+## The hooks
+
+| Hook | What it is |
+|---|---|
+| `window.__FPX_STATE__()` | The state worth checking: `{ screen, x, score, lives, ... }`; `screen` names the screen on show. |
+| `window.__FPX_VERBS__` | One function per player action: `{ jump() {...}, fire() {...} }`. Real input and verbs run the same code. |
+| `window.__FPX_VIEWS__` | Screens: `{ playing: { motion: true, enter() {...} } }`. Mark the gameplay screen `motion: true`; a `moment: true` view whose `enter()` drives the game into its payoff is what capture films ([references/checks.md](references/checks.md)). |
+| `window.__FPX_KEYS__` | Keys the game reads: `{ ArrowLeft: 1, Space: 1 }`. Phone: a swipe (`data-fpx-gesture="ArrowLeft ArrowRight"` on the play) or a control (`data-fpx-touch="ArrowLeft"`). |
+| `window.__FPX_SELFTEST__` | `[{ name, run() => boolean }]`: facts that must hold (a level is solvable, a spawn is inside the map). |
+| `window.__FPX_AUDIO__` | Set it when the game has sound: `{ sfx: ['hit'], music: true }`. A run that then starts no sound at all fails. |
+| `window.__FPX_ACTORS__()` | Where each person, creature and prop stands (feet, height, ground, task): `walk`, `life`, `framing`, `score` read it ([references/actors.md](references/actors.md)). |
+| `window.__FPX_MOMENT__(name, weight)` | Call it at a payoff (`window.__FPX_MOMENT__?.('boss_down', 1)`): the capture tour shoots at the mark, the share video cuts on it. |
+
+Named test scenes: [references/scenes.md](references/scenes.md); real-control journeys:
+[references/journeys.md](references/journeys.md).
+
+## Checks in funpixel.json
+
+```json
+"checks": [
+  { "mechanic": "left arrow moves the player", "verb": "moveLeft", "key": "ArrowLeft",
+    "field": "x", "expect": "decreases", "subject": "player", "times": 2 }
+]
+```
+`key` presses the real key, `pointer` taps a real element, neither calls the verb; the rest is in
+[references/checks.md](references/checks.md). One check per mechanic you claim, plus one that
+reaches the win or loss, lets a failure name what broke.
+
+## The loop
+
+1. `npm run build`, then `npx @funpixel/tools verify` (`check`: both, plus tests) writes
+   `verify.json`: the verdict and a fingerprint of the files that ship, which publish checks.
+2. Read the exit code. 0 pass, 1 fail, 2 not observed (nothing measured: hooks missing or the page
+   did not load), 3 a tool error.
+3. Read every FAIL line; each names the check and why. A check made to pass by changing what it
+   reads (a flipped sign in `__FPX_STATE__`) stops measuring the game, so the fix goes in the
+   camera or the input mapping.
+4. **Front door.** Verify enters play through the hooks. Once per session, and after touching the
+   title, menus, audio unlock or input setup, prove the real start works: mark the title's start
+   control `data-fpx-start` (and each choice before it `data-fpx-choice`) and run
+   `npx @funpixel/tools verify --front-door`. It presses the button instead of calling `enter()`,
+   and fails a missing button or one that changes nothing. A start drawn inside the canvas gets a
+   transparent DOM button over it carrying the attribute.
+5. **Sound.** Four of our games shipped silent past every check; silence the design chose
+   (`Sound: none`) is a style. Declare `__FPX_AUDIO__`, mark sounding mechanics `"sound": true`, and read the counts in
+   `--json` ([references/checks.md](references/checks.md)).
+6. **Idle run.** `check` times one (no input after Play): deaths before the genre's floor are
+   worth a look unless the design means them.
+7. **Green means stop.** When the verdict is 0 and the goal of this step is met, stop editing and hand back. Every later edit needs a new reason from the person or a failing check.
+   An agreed complete game keeps going until its scope is met.
+
+## Judging it, once verify passes
+
+One verdict per round: the targets (`score --target` at `accuracy_min`, default 75) and a blind
+player at phone size with no high finding (`play`). At hand-back, the panel too: three blind
+`critic` seats (veteran player, UX designer, skeptic) on fresh captures of every view at both sizes,
+each given only the frames, a store description, the AD rules, `audit-screens`' numbers and its last
+verdict; the bar our bar games passed is overall 6.0, look and feel 7.0. Settle
+last round's findings first; under the bar, a recorded fix round; when three rounds stop moving the
+means, report rather than respin. The declared style is the standard, never a finding. The panel, its seats and
+the bar: [references/review.md](references/review.md), [references/bar.md](references/bar.md),
+[references/playtest.md](references/playtest.md).
+
+## Worked example
+
+Adding a jump:
+1. `jump()` in `__FPX_VERBS__` sets the vertical speed; the Space handler calls the same `jump()`.
+2. `__FPX_STATE__` returns `y`.
+3. Check: `{ "mechanic": "space jumps", "verb": "jump", "key": "Space", "field": "y", "expect": "changed", "trace": 20 }`.
+4. `npx @funpixel/tools check` prints `FAIL space jumps — y never changed`.
+   The keydown handler was bound to `canvas`, which never had focus. Bind it to `window`, rebuild,
+   verify: exit 0.
+5. Front door: the Begin button carries `data-fpx-start`; `verify --front-door` passes.
+6. Exit 0 and the jump was the whole request, so stop and hand back: "Space or the up button jumps; nothing else changed."
+
+## Common mistakes
+
+- A verb that bypasses the input handler: the check passes and the real key stays broken. Route
+  both through one function.
+- Self-tests that assume the starting state: checks run first and change it.
+- Treating exit 2 as success: nothing was measured.
+- Polishing after a pass. Each unrequested edit risks the pass and needs a new verify.
+- Claiming a feature because the class exists: trace it from boot or an input, and check it.
+- Verifying the dev server's live files instead of a fresh `npm run build`.
+- Judging captures older than the files, or one critic playing all three seats.

package/plugins/cursor/skills/funpixel-verify/references/actors.md

@@ -0,0 +1,94 @@
+# The actors contract: where everything stands
+
+`npx @funpixel/tools walk` plays every route from the title and judges the world as it goes;
+`life`, `framing` and `score` place and judge people, creatures and the hero. They read one global
+the game answers, in metres, y up, the feet at `x, y, z`:
+
+```ts
+window.__FPX_ACTORS__ = () => ({ unit: 'm', supports: ['gantryWalk'], actors: [
+  { id: 'ren', kind: 'player', type: 'person', x, y, z, h: 1.75, r: 0.35, ground: heightAt(x, z), node: 'player' },
+  { id: 'carter-3', kind: 'person', type: 'carter', scene: 'crane', task: 'haul', state: 'walk', reacting: 'wave', facing, x, y, z, h: 1.68, r: 0.3, ground, node: 'folk-3' },
+  { id: 'crab-3', kind: 'creature', type: 'crab', x, y, z, h: 0.32, r: 0.2, ground, solid: false, state: 'flee' },
+  { id: 'kite-1', kind: 'creature', type: 'kite', x, y, z, h: 0.4, r: 0.5, flying: true, ground },
+  { id: 'container-12', kind: 'prop', type: 'container', x, y, z, h: 2.6, w: 6.1, d: 2.44, yaw, ground },
+  { id: 'late-show', kind: 'machine', type: 'ship', landed: true, x, y, z, h: 13, w: 27, d: 9, yaw, ground: pad.top, mesh: 'lateShow' },
+  { id: 'pad', kind: 'prop', type: 'landing pad', support: true, x, y, z, h: 1.1, w: 28, d: 30, yaw, node: 'landingPad' },
+] });
+```
+
+| field | meaning |
+|---|---|
+| `id` | stable per actor (`framing --actors ren`, the hero of a `score` moment) |
+| `kind` | `player`, `person`, `creature`, `machine` or `prop`; a species or role word (`crab`, `townsfolk`, `npc`, `drone`) is read into one of those and kept as `type` |
+| `type` | what it is, the key into `funpixel.json` `scale`; missing = `species`, `role`, or the id without its number |
+| `x, y, z` | the feet, world space, metres (or `pos`/`position` as `{x,y,z}` or `[x,y,z]`) |
+| `h` | height; without it scale is not judged |
+| `r` or `w, d, yaw` | the footprint: a radius, or a box turned by `yaw` about +y |
+| `ground` | the height of what is under the feet (the terrain, or the pad's deck under a landed ship); without it floating is not observed. `ground: true` (a boolean) on an entry instead marks its mesh as ground others stand on, as `support: true` does |
+| `supports` | at the top of the answer: mesh names that are ground others stand on (a deck, a walkway, a pad) when their names do not say so |
+| `flying` (or `flies`) | meant to be in the air: judged for a flap, not for floating or collisions; on a vehicle or prop, left out of grounding |
+| `landed` | a vehicle or prop that must rest on the ground under its whole footprint, judged whatever its size |
+| `gait` | the gait preset it moves on (`walk`, `run`, `sneak`, `carry`, `limp`, `old`, `child`, `quadruped`, `flyer`; the starter's `src/motion.ts`): `life` notes travel far from the preset's design speed (the feet moonwalk or scramble, measured with `h` as its height) and a declared gait that slides |
+| `scene` (or `group`) | the little scene a person belongs to (`crane`, `stall`); people of one scene may stand close. It is authoritative: untagged people are read for one (facing each other within 2.5 m, or moving together) and reported "untagged: inferred scene"; two different tags close together are a clump |
+| `facing` (or `heading`) | a person's or creature's forward as a world yaw, `atan2(forward.x, forward.z)`; without it the node's own turn is read |
+| `solid` | default true; false for what may be walked through |
+| `task` | the loop it is on (`haul`, `patrol`, `errand`) |
+| `state` | what it is doing (`idle`, `walk`, `flee`); a change near the player counts as a reaction |
+| `reacting` | what it is doing because of the player (`wave`, `look`, `yield`, `flee`) |
+| `node` (or `mesh`) | the scene node's name, so `life` ties the animation it sees to this actor and its role, and `boxes`/`walk` find its mesh. With neither, an id is matched to a mesh by a word of it (`ship-lateShow` is the mesh `lateShow`), and for a machine or a landed entry by one name containing the other; a linked landed entry's `ground` and `x, z` are used to judge it |
+
+Also read as the contract: a bare array (`__FPX_ACTORS__ = () => [...]`), an `{ id: actor }` map,
+or an `actors` array in `__FPX_STATE__()`. With none, a Three scene is read from node names (ground
+not observed) and the report says so.
+
+## What reads it
+
+- `walk`: clipping, placement, floating, scale, stalls, challenge, losses and retry, people who
+  move through space vs animate in place, the hero's face on a crowd, flyers without a flap,
+  reactions; the crowd's placement (clumps within 1.5 m with no shared `scene`, tagged or inferred, stretches of the
+  path with nobody in view, the count against `walk.crowd.people`); and every 4 s the world itself,
+  as `boxes` reads it.
+- Big props and vehicles need no entry: `boxes` and `walk` read them from the scene (anything with
+  a 2.5 m footprint, or a node named like a vehicle: ship, craft, crawler, truck…) and raycast the
+  surfaces under where each touches down (its lowest vertices cell by cell, or its box's corners):
+  hovering, hanging over a drop, sunk, judged against the nearest surface below it. Surfaces are the
+  terrain (a mesh named `ground`, `terrain` or `floor`) and the supports: a mesh whose name ends in
+  deck, pad, platform, ramp, bridge, pier, dock, floor, street, walkway, stairs (`rampDeck`,
+  `landingPad`; not `padCrates`, not `padLeg`), one the contract lists in `supports` or marks
+  `ground: true`/`support: true`, and one the player or a person is found standing on. A leg,
+  trestle, piling or post going down into a pit with its top under a support is braced, not sunk; a
+  railing or kerb within 1.5 m of its deck is attached. A painted cut-out stands where its picture's
+  lowest opaque row does. Name the node in the contract with `landed: true` to judge a small one,
+  `flying: true` to leave one out (a ship taking off). The headline lists the worst first, landed
+  things and vehicles before props.
+- `boxes` and `walk` name a person or creature of the contract (with its `node`) built of a handful
+  of boxes, whatever its size on screen (`BOX FIGURES`). A style lock that says the world is faceted
+  (`flat-shaded`, `faceted`, `low-poly` in `design/style-block.txt`, `design/plan.md` or
+  `funpixel.json` `metadata.artStyle`) keeps terrain and rock out of the boxes read ("style: faceted (not
+  judged as boxes)") unless one facet covers more than 12% of the frame.
+- Routes in `funpixel.json` `walk.routes`:
+  `[{ name, start: ["press Enter", "click .play"], hold: ["ArrowUp"], steer, progress, done, max_s, then, continue }]`.
+  `steer` holds a state field near a value (`{ field: "lat", to: 0, lower: "ArrowLeft", raise:
+  "ArrowRight" }`); with no lateral field, `waypoints: [[x, z], …]` (or a `path` in the state)
+  steers by the player's position and learns which key turns which way. `then: "run01"` goes on
+  from where a route arrives in the same page and the same film (a prologue, then the first run);
+  `--chain a,b` does it ad hoc. A chained leg skips its `start` steps (they lead from the title) and
+  plays its `continue` steps instead, if it has any. A leg that arrives in under 3 s (its `done`
+  already held, often a chained leg with no `continue` steps) is "not observed" and nothing on it is
+  judged.
+- Framing is judged on time, not the mean: more than 15% of the walk outside the `framing` band
+  warns and names the stretches (`s 44–96 at 13–14% (floor 18%)`).
+- The hero's face on a crowd is judged by CONTENT, for people only: a picture by its URL or pixel
+  hash, a mesh by vertex count, bounds and name, so the hero's file loaded twice (once for the
+  player, once for the crowd) is still the hero's body; the shared parts are named.
+- `life`: one view, the same life verdicts. Travel is labelled with its window (10 s) and defers to
+  `walk.json` when walk ran (people on task loops wait at their stops; a short look under-counts).
+  A moment whose view jumps through its payoff and fires every cue at once is flagged, not read as
+  the world answering. `framing`: each actor's share of the frame. `score`: the hero's share
+  against the target's `hero_share` (a `--capture` still has no contract: the hero is "not read").
+- `funpixel.json` beside it: `scale` (metres), `framing` (`{ "ren": [0.16, 0.22] }`), `moments` and
+  `accuracy_min`, `life` (`{ "people": "regex", "creatures": "regex" }` for node names; `"hero": "rides"`, or
+  flies, rolls, swims, for a hero with no walk to judge),
+  `walk.crowd` (`{ "people": [6, 10], "clump_m": 1.5, "gap_m": 40 }`).
+
+Every finding is a warning; what the game does not expose is "not observed", never a pass.

package/plugins/cursor/skills/funpixel-verify/references/bar.md

@@ -0,0 +1,62 @@
+# The release bar and the panel
+
+The bar is the minimum the team's best shipped games clear. The panel is how a game is judged
+against it: three critics, blind, from captures only, seven axes and an overall each (the phone
+shots re-read on the same axes by every seat, `mobile` being that phone overall), gated as in
+the bar's rule R1. The calibrated seat prompts and captures are the studio's historical
+calibration. Apply the current scope and evidence rules here;
+revised anchors have not yet been recalibrated against those games.
+
+## The bar
+
+Each item is checked from frames; `unseen` means no captured frame shows it, so capture the view
+that would.
+
+| Item | Met when |
+|---|---|
+| `art_direction` | The frames break none of the five AD rules (matching `design/target.png` is the `art-director` agent's check, outside the scored panel) |
+| `consistency` | Assets belong to the declared direction; differences in materials, outlines or detail are intentional and readable; recurring characters keep their identity |
+| `motion` | Relevant actions and state changes read clearly across frames; intentional stillness is valid, while missing promised animation or an accidental bind pose is a finding |
+| `juice` | The action has a readable result appropriate to the game; quiet placement and physical impact can use different techniques |
+| `fun` | The ramp is visible (a wave, an area, a new threat, not only speed), the end screen gives a reason to play again, and verify reached the designed resolution (a win or close, and a loss where the design has one) |
+| `screens` | A real title (the game's own art and name, a start control), play, pause, and an end screen with instant restart |
+| `hud` | Every readout reads at phone size (no text under 12 px), never covers what the player steers, and draws the design's HUD idea in the game's theme |
+| `sound` | Promised audio is checked by verify and listening; intentional silence is valid. A still-frame seat marks sound `unseen` |
+| `input` | Keyboard and touch both wired; touch controls visible at phone size and within thumb reach |
+
+## The seats
+
+Run the `critic` agent once per seat, in parallel, and name the seat in the request ("You sit as
+the skeptic."). Each seat scores the same seven axes and overall; the persona decides what it looks at first.
+
+| Seat | Looks first at | Typical finding |
+|---|---|---|
+| Veteran player | The hit frames against the juice table, the visible ramp, the reason to play again | "the before and after frames do not distinguish a hit from a miss" |
+| UX designer | What to steer, chase and press; the screen set as one system | "pause is reachable only by Esc; no touch route" |
+| Mobile producer | The first six seconds at phone size: thumb reach, safe area, text, the store-listing look | "title art is cropped under the notch at 390x844" |
+| Skeptic | What gives it away as unfinished or generated | "enemies are orange diamonds; the backdrop is in a second style"; "the crate has no ink line, every model does" |
+
+**Blind** means each seat gets what the calibrated panel gets: the frames, a store description, the
+five AD rules, the screen audit's numbers and its own previous verdict, and nothing else: no design
+note, no target frame, no verify summary, no builder's explanation, no other seat's scores, no code.
+On the same Lanternfall frames, seats briefed with the note and the builder's summary scored 7.10 where
+blind seats scored 6.90 (Sonnet, one panel each), and the whole in-loop panel ran 0.6 above the
+calibrated anchored one, which also saw the payoff frame.
+
+## Scoring
+
+- Each seat scores seven axes and an overall per surface ([rubric.md](rubric.md)); its score on an
+  axis is the mean over its surfaces.
+- The gate: the seats' `overall` mean at least 6.0 and their `lookAndFeel` mean at least 7.0,
+  on standard captures (every declared view at both sizes, play frames, the screen audit). That is
+  where all three bar games pass; 7.3 overall is the aim, on a curated set of the game's peak
+  moments, which costs about half a point less to reach.
+- A missing bar item or high finding stays open even above those means. Under the gate, run a named fix round: merge the findings, fix the highest (a `missing` bar item
+  first), verify, capture every view at both sizes again, and re-seat all three. Judge, fix, confirm once, then stop: one confirm round per milestone, and a
+  third panel on it re-reads taste (`playtest report` counts them). When rounds stop moving the
+  means, hand back both means, the open findings and the next round in the note's `## Fix round`
+  table.
+
+**The panel informs.** `playtest report` exits 0 whatever the panel says; `playtest report --min-score
+6.5` fails under a number you ask for (CI, or a creator holding themselves to a floor). Only the owner's
+`owner_gates.panel_min` in funpixel.json makes the panel stage an owner gate that may hold a session.

package/plugins/cursor/skills/funpixel-verify/references/checks.md

@@ -0,0 +1,69 @@
+# Checks in funpixel.json, and the hooks in detail
+
+## A check
+
+```json
+"checks": [
+  { "mechanic": "left arrow moves the player", "verb": "moveLeft", "key": "ArrowLeft",
+    "field": "x", "expect": "decreases", "subject": "player", "times": 2 }
+]
+```
+
+- `expect` is `increases`, `decreases` or `changed`.
+- `key` presses the real key; `pointer` taps a real element (a CSS selector); with neither, the
+  check calls the verb.
+- `trace: 12` holds the input for 12 frames and samples each one, which catches a jump that rises
+  and lands.
+- `subject` also reads that object's position on screen, along `axis`: `"x"` (the default) or
+  `"y"`, so a jump or a fall with a subject needs `"axis": "y"`.
+- `"sound": true` fails the check when its drive starts no sound.
+- A mechanic with no input (a timer, gravity, a spawn) gets a verb that lets time pass, awaited by
+  the check: `async wait() { await new Promise((r) => setTimeout(r, 500)); }`, then
+  `"verb": "wait"`. There is no wait field.
+
+One check per mechanic you claim is what lets verify say which one broke; a check that reaches the
+win or the loss is what proves the loop closes.
+
+Each check after the first starts from the play view entered again, with `window.__FPX_SEED__ = 1`
+set first when the page has none. So a check that ends the round or lights a one-shot power-up does
+not break the ones after it, as long as the play view's `enter()` starts a fresh round (the
+scaffold's does). An `enter()` that resumes a round keeps what the last check left, which is worth
+knowing when a later check fails for no reason of its own.
+
+`--front-door` reads the same state. When `__FPX_STATE__()` names a `screen` (or `phase`, `view`,
+`scene`, `countdown`, `started`), the press started the game only if one of those moved; the
+button's own pressed style or a ripple on the canvas does not count. A countdown that runs on the
+title passes once the state says so, for example `phase: 'countdown'`.
+
+## The signature moment
+
+`{ swarm: { moment: true, enter() {...} } }` in `__FPX_VIEWS__`: its `enter()` drives the game into
+its payoff through its own rules (pack the horde, fire the shot; `funtools sim` names the seed and
+time that stage the best one). A frame play cannot reach misleads
+every reviewer who sees it, so the moment is staged by the rules, not drawn. `capture` plays it as a
+burst (about 1.8 s) and keeps the frame at the heaviest `__FPX_MOMENT__` mark. A payoff that lands
+after the last frame is reported with how late it was, since then every frame shows the run-up.
+
+## Seeing the player
+
+For Pixi, set `window.__PIXI_APP__` and give the player a `.label`. For Three, set
+`window.__THREEJS_SCENE__`, `window.camera` and `window.THREE`, and give the player a `.name`. With
+those, a check can say whether the player can be seen, not just whether a number moved: a player
+hidden (`visible = false`, alpha 0, scale 0) while its position moves fails as "cannot be seen".
+
+## Listening
+
+Verify's `--json` carries an `audio` block (context state, sounds started, the most-played cues) and
+each check's `sounds` and `sound_cues`, where `hit x4` is one hit playing four times. By hand, after
+the first click `audio.ctx.state` is `'running'` (skill `funpixel-audio`).
+
+## Many mechanics
+
+The `qa-lead` agent turns a verdict into a short test plan when a game has many mechanics.
+
+## The whole manifest, held to its shape
+
+`npx @funpixel/tools schema` checks funpixel.json against every key a kit command reads (a mistyped
+key is named with the one it meant; `--strict` makes it an error) and the plan files beside it:
+`src/look.json`, `assets/assets.json`, `design/pipeline.json`, `design/spec/tunables.json` (a default
+outside its range, a number with no reason) and a forged world (doors that name rooms it lacks).

package/plugins/cursor/skills/funpixel-verify/references/experience.md

@@ -0,0 +1,67 @@
+# The experience bar: what the stills cannot see
+
+The calibrated panel scores seven craft axes from still frames: look, readability, intuitiveness,
+juice, fun as far as frames show it, mobile, HUD. Stills cannot see whether skill grows, whether new
+things keep arriving, why anyone comes back, who wants what, which places a player remembers, where
+a session breathes, or what the one idea is. The experience seats score those seven, 0–10 on fixed
+anchors, beside the craft panel and never instead of it; the craft panel's words stay as calibrated.
+The full bar, the hits' calibration and our games' scores are the studio's own record; this page carries what a run needs.
+
+## Running it
+
+1. `npx @funpixel/tools playtest` as usual. The blind player's round is now a long session
+   (`--long 10`, about ten minutes of game time; `--long 0` for a short round), ending with "would
+   you come back tomorrow, and why?" (`come_back` in its report).
+2. After the round is filed, `npx @funpixel/tools playtest experience` runs `funtools depth` for free
+   into the playtest's `experience/` folder and writes one prompt per experience seat: the designer
+   (depth, content, replay, the arc) and the storyteller (story, world, the arc, the signature).
+   `--quick` writes the designer only.
+3. Run each seat as a fresh agent handed only its prompt file, as the craft seats are.
+4. `npx @funpixel/tools playtest report` puts their means beside the genre hit's calibration, the
+   come-back answer, what the design claimed and nothing showed, and ranks their changes among the
+   next steps.
+
+`npx @funpixel/tools depth` alone gives the evidence at any time: facts X1… (the bots' skill spread
+from `sim`, the verb's windows from `feel`, the design's content tables, the shipped pictures, sounds,
+music and words, what real play reached, the beat strip's numbers, the come-back answer, which
+dimensions the GDD addresses), `text.md` (every sentence a player can read) and a beat strip.
+
+## The evidence it reads, and what makes it better
+
+| Dimension | Free evidence | What lets it measure more |
+|---|---|---|
+| depth and mastery | `sim` cohorts (skilled, naive, novice, idle), `feel` windows | `test/probes.ts` and `test/feel.json` (without them it says "not measured") |
+| content and progression | the GDD's content tables (claims), real play's places and firsts a minute | a `place` field in `__FPX_STATE__` (level, room, world, garden, wave…); a debut column |
+| replay | the long session's come-back answer | a long blind session on the current build |
+| story and storytelling | `text.md`, the beat strip, the GDD | lines the player reads in play, not only in the design |
+| world building | places reached, frames | a `place` field; each place's own look and rule on screen |
+| emotional arc and pacing | beats a minute, the longest flat stretch, tension peaks and releases | a `tension` field (0–1) in the state; `sim` timelines for music |
+| originality | the seats, the head to head | a signature named in the GDD's promise |
+
+## Reading the scores
+
+- **Delivered, not claimed.** The seats credit only what play, frames or readable text show, and
+  list the rest as `claimed`. Our games' largest gaps were claims: six gardens of which play reached
+  one, eight worlds of which play reached two levels. A playtest that plays further scores more
+  without a line of code changing.
+- **A slice is capped where only a longer game can go.** Content above about 4, replay and world
+  above about 6, and an arc above about 6 need more than one level. Compare a slice to its hit on
+  depth, story and originality, where a slice can reach the hit; read the rest as distance to a
+  full game.
+- **The two seats agreed within one point on 97 of 98 dimension scores** (the hits and our six
+  games; one split of 3 on Suika Game's originality), and re-runs on lightly changed evidence moved
+  a game's mean by 0.14 at most. Differences under 0.5 on one dimension are noise.
+- **The genre hit is not always high here.** Suika Game scores 3.1 (no story, no world, one jar),
+  Pac-Man Championship Edition DX 4.7; Hades 8.1 and Celeste 8.0. A craft score at the hit's and an
+  experience score far under it is the gap the owner named: the hits' extra point is depth.
+
+## What moves a game on this bar, cheapest first
+
+1. Wire `test/probes.ts`: the skill spread is the whole depth score's evidence, and a naive bot that
+   wins as fast as a skilled one is the most common depth finding.
+2. Put `place` and `tension` in `__FPX_STATE__`, so `depth` can count places and draw the arc.
+3. Make the reachable game match the claimed one: a long blind session that reaches the later
+   levels, or a design that claims what play reaches.
+4. One want, one turn, one payoff told through play (a place that changes as it is saved, an end
+   card that pays the first screen's want off).
+5. A reason to come back tomorrow that the title shows (a daily seed, an unlock, a best per level).

package/plugins/cursor/skills/funpixel-verify/references/eyes.md

@@ -0,0 +1,54 @@
+# Looking closer: inspect, profile, phone, clip
+
+Four local, free looks for when a verdict says *that* something is wrong and you want to see *what*.
+Each reports and never judges; pick the one that answers your question.
+
+| Question | Look | What comes back |
+|---|---|---|
+| What is this thing on screen, and where is it made? | `npx @funpixel/tools inspect --at 50%,80%` or `--name hero` | each object under the point (HUD first), its state, the source `file:line` that created it |
+| Why did it throw? | `npx @funpixel/tools inspect` | every runtime error so far at its source line, and `__FPX_STATE__()` |
+| What did my change cost? | `npx @funpixel/tools profile --views playing --compare` | the moved numbers against the last run made the same way, GPU time when the browser has the timer |
+| Does it work in real iPhone Safari? | `npx @funpixel/tools phone` | screenshots from the iOS Simulator, the controls and their sizes, WebKit's frames and errors |
+| How does it feel in motion? | `npx @funpixel/tools reel --frames-only`, then `npx @funpixel/tools clip` | 12-frame strips and one prompt per clip seat for your own agent |
+
+## inspect
+
+The platform's inspector (the one a person clicks in the Studio) answers from the game's own dev
+server, so it needs `npm install` and a Pixi or Three game; `--url` points it at a running
+`funtools dev`. `--view`, `--verbs` and `--front-door` get to the state first. On the scaffold,
+`--name player` answered `player (Container) … made at src/game.ts:18 const box = new
+PIXI.Container();` — the factory line; the call that used the factory is one step up in your
+code. Name the objects you will ask about (`label` in Pixi, `name` in Three); unnamed ones read as
+`Graphics` or `Sprite_12`. A planted `null.a` two lines under a TypeScript interface came back at
+its true line (104), where the raw transformed file said 86.
+
+## profile --compare
+
+Frame times in a headless browser sit at the display's 16.7 ms until the CPU runs out, so a heavy
+change can leave them flat. On the scaffold, 30 blurred glows left frame p95 at 16.7 ms while GPU
+p95 went 0.67 → 11.78 ms and draw calls 2 → 274; taking them out read as the same numbers falling.
+The burn rate counts frames over the budget (`--budget`, default 18 ms) against a 1% allowance: 1×
+is right at the line, 3× sustained, 10× a stutter. Runs are compared only when made the same way
+(seed, viewport, throttle, renderer, frames); a changed condition is named instead. Moves inside
+±5% are noise between two runs, `--repeat 3` narrows it.
+
+## phone
+
+Optional: an Apple Silicon Mac, Xcode 26 and `brew install baguette` (`doctor` says which is
+missing). It opens the built game in Mobile Safari, taps the start control it finds by name, plays
+for `--seconds` and screenshots each step; `--taps "20%,80% 80%,80%"` presses during play. Its
+frame numbers are WebKit's pacing on the Mac, not a phone's speed; its value is WebKit itself:
+layout under Safari's bars and the notch, a start control that answers in Chrome and not in
+Safari. On the scaffold the page measured 402x714 CSS px under Safari's bars (Chromium's phone view
+is 390x844 with no bars) with every safe-area inset 0, and Play moved `screen` from `title` to
+`playing`. `--orientation landscape` plays too (its taps are mapped to the turned screen). The four
+looks from cheapest (Chromium, `--engine webkit`, `phone`, your own iPhone through `dev --phone`)
+and when each earns its cost: skill `funpixel-mobile-ui`, `references/phone-check.md`.
+
+## clip
+
+Stills cannot judge feel. `clip` cuts strips of 12 consecutive frames, one per payoff the game
+marked with `__FPX_MOMENT__` and the rest spread over the run, and writes a prompt for a `player`
+and an `animator` seat (feel, juice, motion, clarity; each cites strips and frames). Run each prompt
+in a fresh agent with no other context, then `clip report`. Its words are separate from the
+calibrated still panel's, so its scores are not comparable to the panel's numbers or the hits'.