@funpixel/tools 0.0.0-stage → 0.1.1

package/plugins/cursor/skills/funpixel-art/references/2d-assets.md

@@ -0,0 +1,108 @@
+# 2D assets for a Funpixel game
+
+The art is what players see first. Study how the hits hold together:
+Hollow Knight's hand-drawn cast reads by silhouette, Dead Cells animates tiny heroes pose to pose,
+Ori glows white over painted parallax. One family, the hero clearest, motion by state. Generated,
+authored and procedural art all qualify ([look](look.md) sets the look). A generated image
+is a draft until measured and wired: an opaque "transparent" plate, feet that jump between frames, a
+1024 px coin drawn at 40 px and art never loaded all build green.
+
+## Tools
+
+- `generate_sprite`: one transparent object (hero, enemy, pickup, prop, icon).
+- `generate_image`: opaque art (backdrops, the far parallax plane, tiles, panel art).
+- `edit_image`: a second drawing of an accepted picture, the same character (`mode: "pose"`, [cast](cast.md)). `generate_spritesheet`: a character's cycles as one packed
+  sheet and a manifest, every frame an edit of one base (`body`: biped, quadruped, flyer).
+- `list_characters`, `get_character`, `restyle_character`: [the character library](characters.md).
+- `slice_sheet` cuts a sheet into frames, one animation per row; `npx @funpixel/tools parts` cuts
+  a character sheet into parts or poses, an item sheet into items; a 2D hero in 3D: `funpixel-3d` references/painted-target.md. `accept_asset`
+  measures an image for its role; free.
+- `npx @funpixel/tools job <id> --wait --out public/assets/<file>` saves a job.
+- Local and free: `npx @funpixel/tools optimize pack-atlas|compress` (step 9) and
+  `npx @funpixel/tools smoke`, which warns on a shapes-only game.
+- Without the MCP: `npx @funpixel/tools gen sprite|image|edit|sheet "…"` with a paid key.
+- A manifest that re-makes only what changed: `npx @funpixel/tools assets gen` (optional;
+  [pipeline.md](pipeline.md)).
+
+## Which tool, which background
+
+| Asset | Tool | Background | Notes |
+|---|---|---|---|
+| Hero, enemy, pickup, prop | `generate_sprite` | transparent | hero reference for characters |
+| A character the library fits | `get_character` | transparent | restyle it |
+| Idle, walk, attack, hit, death cycle | `generate_spritesheet` | transparent | from the accepted sprite, step 5 |
+| Blink, hurt face, happy pose | `edit_image`, mode `pose` | kept | step 8 |
+| Effect cycle | `generate_image` | transparent | grid spec, [sheets.md](sheets.md) |
+| Glow, spark, smoke, flash | `generate_sprite` | pure black | luminance key, step 6 |
+| Backdrop, far parallax plane | `generate_image` | opaque | screen aspect, style frame reference |
+| Near parallax plane, panel art | `generate_sprite` | transparent | [planes.md](planes.md) |
+| Floor or wall tile | `generate_image`, `kind: "texture"` | opaque | seamless (a seam is refused, uncharged; `gen texture` without the MCP), same reference |
+| Pause, mute, arrows, close | none | none | inline SVG in code |
+
+## The checklist
+
+1. **Use the direction the job needs.** A new family starts from a target and a style file
+   ([look](look.md)); a repair or a supplied style works from the accepted references and
+   the real background.
+
+2. **List what the player sees.** From the target: backdrop, player, threats, pickups and effects.
+   Reuse, author or generate each; jobs started together arrive while you code.
+
+3. **Build every prompt from the style file, anchored.** Subject + `medium` + the family's clause
+   + `never` from the style file or supplied brief; vary only the intended change. Pass the style
+   frame (world art) or the hero reference (characters) as a reference: a set stays one set
+   because every item is anchored to the same accepted images, not because the words match.
+
+4. **Write the rubric before each asset type.** Three to six pass/fail lines a viewer can check,
+   citing the AD rules ("one 4 px ink outline", "reads as one shape at 48 px"). A line written after
+   seeing the result grades the result, not the brief.
+
+5. **Animate for the role and promised state changes.** A walking character wants readable
+   locomotion, an attack its warning, contact and recovery; a board token may rest still. Cycles
+   from `generate_spritesheet` of the accepted sprite, a pose from `edit_image`, or authored motion,
+   switched by state. Techniques, code and what `scene --motion` can and cannot say:
+   [animation.md](animation.md).
+
+6. **Transparency and keying.** Native alpha first: the transparent flag, and "the subject alone on
+   a plain field". Glows: pure black, then luminance as alpha, or additive blend on purpose. A pale
+   subject on white, or a green one under a green key, gets eaten: ask for a dark outline and a
+   field colour the subject lacks.
+
+7. **Measure, then repair or regenerate.** Read the verdict the tool returns; where there is
+   none, measure ([measure.md](measure.md)): transparent share, clear
+   corners, hues inside the style roles, the trimmed box fits its role. Each verdict cites a rubric
+   line. One clause changed per round, each from the baseline, keeps a change and its effect
+   paired. After three rounds without a clean result, or two fixes failing one line, keeping the
+   best and naming the miss usually beats another respin (Scenario's stop rule). Repair on a copy
+   and recheck it on the real background.
+
+8. **Same identity, new state.** A hurt, happy or powered-up hero is `edit_image` of the
+   accepted sprite (`pose` for a pose, `edit` for a change): a fresh `generate_sprite` redraws
+   another character. Art no job made: `import_asset` (free), `gen … --asset <file>`.
+
+9. **Pack, wire by role, finish.** Pack sprites that share a scene into one atlas
+   (`optimize pack-atlas`, loaded once by a relative path), size and collide by role at phone size
+   with `setupGameResize` and a stored `baseScale`, compress to the displays you support (or deliver
+   at that size: `target_size`), and remove the stand-ins the new art replaces. Steps, code and
+   why: [wiring.md](wiring.md).
+
+## Worked example
+
+A side-scrolling fox; the target and style file exist. The list: meadow backdrop, fox, crow,
+berry, log, a spark burst. Rubric: "one 4 px ink outline", "reads at 48 px", "coral only on
+the fox". All six jobs start together, the style frame or fox as reference. The fox passes; the
+fox's `generate_spritesheet` (idle 4, run 6, hit 2) comes back aligned, and `edit_image` adds
+its blink. Everything is packed and sized (fox 16% of
+screen height, hitbox 70%); the fox's `Graphics` stand-in is deleted; smoke is clean.
+
+## Common mistakes
+
+- "Sprite sheet, walk cycle, 8 frames" as the whole prompt: you get a picture of a sheet.
+- Sliding an action character without its promised state feedback, or idle bob added only to
+  satisfy a motion counter.
+- Trusting "transparent" without measuring: a whole family has shipped at alpha 255.
+
+Where this comes from: style-file anchoring, rubric-first, one clause per round, the stop rule and
+the sheet recipes adapted from scenario-labs/skills (MIT; THIRD_PARTY_NOTICES.md); the tools,
+keying, measures, wiring and character library are ours.
+

package/plugins/cursor/skills/funpixel-art/references/animation.md

@@ -0,0 +1,126 @@
+# Animation by actor role
+
+Choose state changes for the brief. A walking fox needs locomotion and readable contact; a chess
+piece can remain still until moved. Missing promised animation is a defect; an idle bob is not a
+universal quality requirement. Evaluate normal play and reduced motion.
+
+## Optional action-character recipes
+
+| Role | Meaning to communicate | Techniques to try |
+|---|---|---|
+| Hero | movement, action, damage, resolution | walk cycle, contact pose, recoil, a clear end state |
+| Enemy | intent, danger, damage | readable wind-up, directional attack, defeat transition |
+| Pickup | availability and collection | distinct silhouette, collection cue; idle glint only if useful |
+| Board piece | selection, legality, committed move | outline, preview, settle; stillness between actions |
+
+Use drawn frames, pose edits or authored transforms as appropriate. Timing and frame counts
+below illustrate a fox; choose them from the action, budget and readability at the real size.
+
+## Frames: `generate_spritesheet`
+
+Once the sprite is accepted, animate it, never a fresh prompt: the sprite is the base every frame
+is edited from, so the frames stay that character.
+
+```json
+{ "asset_id": "<the accepted sprite's asset id>", "prompt": "the fox knight",
+  "animations": [{ "name": "idle", "frames": 2 }, { "name": "walk", "frames": 6 },
+                 { "name": "attack", "frames": 4 }, { "name": "hit", "frames": 2 }],
+  "frame_size": 256, "game_id": "<the game's id>" }
+```
+
+- Names: idle, walk, run, jump, attack, act, hit, death. Each frame's pose is the server's own beat
+  for that cycle (a walk is contact, down, passing, up for each leg).
+- Check the current per-frame estimate against the authorized budget before submitting.
+  Without the MCP: `npx @funpixel/tools gen sheet --asset public/assets/sprites/fox.png
+  --cycles idle:2,walk:6,attack:4,hit:2`.
+- A frame whose colours or mass drift from the base is redrawn once, then the job fails
+  uncharged; `result.frames` shows each frame's match. Look at `sheet.png` before wiring: count
+  the distinct poses per cycle.
+- The frames share one scale and one ground line; the feet are each frame's anchor.
+- The sheet draws every frame from the side or the front. An actor seen from above (a maze
+  chase, a twin-stick arena) has no ground line, and one run got a side-view gecko back
+  for a top-down maze (57 credits, discarded). Give such an actor its two to four key poses as
+  `edit_image` pose edits of the top-down sprite (below), stepped at the stride rate.
+- Measured (the studio's animation evals): the character holds across frames, but each
+  frame is its own drawing, so a stance can shift between idle frames. Keep the idle at the
+  low end of the sheet table's 2–4 frames and add `living.ts` breathing only where the role wants
+  motion at rest; in that eval a walk of six (the top of its 4–6) read as walking.
+
+```ts
+import { AnimatedSprite, Assets } from 'pixi.js';
+
+const sheet = await Assets.load('assets/sprites/fox-sheet/sheet.json');
+const cycles = sheet.data.meta.funpixel.animations; // { walk: { fps, loop, frames } }
+const fox = new AnimatedSprite(sheet.animations.idle); // the anchor is the feet
+fox.label = 'player';
+function play(state: 'idle' | 'walk' | 'attack' | 'hit') {
+  if (fox.textures === sheet.animations[state]) return;
+  fox.textures = sheet.animations[state];
+  fox.animationSpeed = cycles[state].fps / 60;
+  fox.loop = cycles[state].loop;
+  fox.gotoAndPlay(0);
+}
+```
+
+Switch by state; never loop the whole sheet. Match a walk's fps to the move speed so the feet do
+not slide, and land the hit on the attack's contact frame, not on the press.
+
+## Poses: `edit_image`
+
+For a state with no cycle, one pose from the accepted sprite: `mode: "pose"` and the one change,
+for example "eyes closed", "recoiling from a hit, eyes squeezed shut", "arms up, cheering", "mid
+stride, left leg forward". The source rides as the reference and a cut-out stays a cut-out.
+Show a blink for 80–120 ms every 2–5 s; swap two step poses at the step rate under the bob.
+Seen from above, name the view in each edit and the limbs by side: "the same gecko seen from
+directly above, left front and right back legs reaching forward", then the mirror pair, a mouth
+wide open for the bite, a curled-up frightened pose.
+
+## Motion in code: `src/living.ts`
+
+The scaffold's optional living layer (use it when its motion fits the actor). Each actor's motion is data in
+tuned ranges; a value outside a range throws, naming the actor and the field.
+
+```ts
+import { Living, ROLE } from './living';
+
+const life = new Living('player', ROLE.hero);          // or ROLE.enemy, ROLE.pickup, or your own dials
+// every frame, with speed as a share of top speed (its sign is the heading):
+const p = life.update(dt, vx / TOP_SPEED);
+sprite.scale.set(baseScale * p.scaleX * (p.flip ? -1 : 1), baseScale * p.scaleY);
+sprite.rotation = p.rotation;
+sprite.y = groundY + p.offsetY * bodyHeight;
+if (blinkTexture) sprite.texture = p.blink ? blinkTexture : idleTexture;
+// on landing or being hit:
+life.squash();                                        // held 3–6 frames at 20–45%, then springs back
+```
+
+What it does: breathe 3% at half a cycle a second at rest, a phase of its own per actor; a step bob
+of 8% of the height, a tilt of 8° per step and a lean of 8° at full speed; a facing flip toward the
+heading; a blink; a squash held at its peak so a capture sees it. Tune the timing for play, then capture the relevant
+phase; never lengthen a response solely to please a still-frame critic.
+
+## Read the motion evidence
+
+`npx @funpixel/tools scene --motion --view playing` samples about a second from the engine's
+scene graph and records `.funtools/scene/motion.json` with the source fingerprint. Re-run after
+source changes. Its `still`, `slides` and `animated` labels describe that sample, not quality.
+
+- Name the Pixi node or Three object, or configure `actors` in `funpixel.json`, to inspect a
+  particular character. No supported graph or named actors means unobserved, not a pass.
+- Compare the sample with the actor's role. A still board token is fine. A promised walk cycle
+  that slides is a finding when the action was actually sampled.
+- Trigger attack, hurt and resolution through real inputs and capture their response. Use blind
+  `play` reports for controls and timing; the critic checks visible state feedback. Keep missing
+  feedback open even when a motion counter or average score is green.
+
+## A cycle from a clip, eight ways from one model
+
+- **A generated clip as a cycle.** `funtools gen video` from the accepted sprite (it is the still),
+  then `npx @funpixel/tools loop <clip> --name walk`: it samples frames, finds the window whose next
+  frame matches its first, keys the ground, cuts every frame to one shared box (no jitter) and packs a
+  sheet with the cycle as one animation. It reports the jump back against an ordinary step; a still clip
+  (the model held the pose) is named, not looped.
+- **Eight directions from one GLB.** `funtools gen render` makes the turntable; `npx @funpixel/tools
+  directions <render folder>` names the views S, SW … SE (angle 0 faces the viewer), keys the stage and
+  packs one sheet with an animation per direction, the feet on one line. Repainting each view in the
+  game's 2D style is a paid image edit per view, printed, never run.

package/plugins/cursor/skills/funpixel-art/references/cast.md

@@ -0,0 +1,73 @@
+# The cast: lock first, check second
+
+A game with a cast draws each member dozens of times: one heist game drew its keepers 6 to 13 times
+each and its crew in rest, brace and cover poses; another kept front, back and left pictures of
+every character. What kept them on model was never a better sentence. It was the same picture
+attached to every call, and a look at each result against that picture before it was kept.
+
+Adapted from scenario-labs/skills (MIT, © 2026 Scenario; the identity-library, consistency and
+refine-loop skills); see THIRD_PARTY_NOTICES.md. The words and the tools are ours.
+
+## 1. Accept one master per recurring design
+
+At the first look, pick the best picture of each character, creature, vehicle or structure the
+game keeps returning to, and accept it:
+
+```bash
+npx @funpixel/tools cast add ren --master design/first-look/ren-best.png \
+  --turnaround design/first-look/ref-ren.png --name Ren \
+  --pins "short dark hair, scar through the left brow, burnt-orange flight jacket, brass goggles" \
+  --features "scar;orange jacket;goggles" --may-change "the pose and the expression" --by owner
+```
+
+That writes `design/cast/ren/`: `master.png`, `turnaround.png`, `palette.json` (measured from the
+master), and the identity card (`card.json`, `card.md`). The pins are the design in words: what
+must never change. A sheet is assembled from accepted pictures, never generated as one.
+
+## 2. Every later picture is made from it
+
+A manifest item of the member (`"cast": "ren"`, or any name that is the id or starts with it:
+`ren_walk`, `ren-hit`, `ren3d`) is made from the master with no extra field:
+
+| Kind | How the master rides |
+|---|---|
+| `image`, `sprite`, `texture`, `strip` | reference 1 (the turnaround 2), and the card's keep-line in the prompt: "Keep this design exactly as in the first reference image: … Change only the pose." |
+| `pose` | the job is an edit of the master (`edit_image`, mode pose): the subject names the pose |
+| `sheet` | the strip is cut from the master (`asset_id`), one action per sheet |
+| `model3d` | the model is made from the master (`image_asset_id`) |
+
+The same holds for one-off calls: `npx @funpixel/tools gen sprite "Ren vaulting" --cast ren`, and
+on the MCP: the first `assets gen` batch pins every master as the game's `ref-<id>` sheet, so
+`generate_image` / `generate_sprite` with `game_id` and a name like `ren_walk` (or `cast: "ren"`)
+are drawn to it by the server.
+
+The default pose set by role (research 16 §7): a hero idle, step, act, hit and a second step; an
+enemy idle and act; a pickup one. A pose is cheaper and closer than a fresh draw: one edit of a
+picture that is already right.
+
+## 3. Every result is held to the master
+
+When a picture of a member lands, `assets gen` measures it against the master, free: the outline's
+overlap after framing both the same way, the share of its colour on the master's colours (on the
+saturated ones for a mostly dark design), the signature colours it lost, its proportions. A pose
+is allowed a new outline; a redraw of the master view is not.
+
+A drift gets one round at a time, one change per round, and two rounds at most:
+
+1. **One targeted edit** of the result, the fix in words from the facts ("restore the colours
+   #b1116b, #4d1535 where the design has them … The design: …").
+2. **One redraw** of the same request, if the edit did not bring it back.
+3. **Kept as the best and named.** The item is `off_model` in the lock and on the next progress
+   card. Read the flaw list, not the score, before a third try: a change to the subject or the
+   master beats a fourth draw.
+
+Every round is in `.funtools/assets.lock.json` (`identity.rounds`: made, edit, redraw, each with
+its numbers, job and credits). `npx @funpixel/tools cast check ren <pictures…>` runs the same
+measure on any picture.
+
+## What the numbers cannot see
+
+They catch a recolour, a lost signature colour, the wrong subject and a changed build. Two crew
+members in one uniform read close by numbers (one heist game's two crew members: 58% outline
+overlap, the same colours). Named features (the face, the earring, what the hand holds) are the
+identity seat's: `npx @funpixel/tools judge identity --concept design/cast/ren/master.png <views…>`.

package/plugins/cursor/skills/funpixel-art/references/characters.md

@@ -0,0 +1,49 @@
+# The character library (2D)
+
+Characters that already move. When one fits the game, it is the fastest way to a living
+character; when none does, draw your own (steps 3–8) — the library is an option on the shelf,
+not a rule.
+
+## What is on the shelf
+
+`list_characters` (free) answers the shelf: each character's id, body, what it suits, and its
+cycles. Today's 2D characters (`medium: "2d"`, side view, facing right, flat cartoon with a dark
+outline):
+
+| id | body | cycles |
+|---|---|---|
+| `adventurer-2d` | biped | idle 2 · blink 1 · walk 6 · run 6 · jump 4 · attack 4 · hit 2 · death 4 |
+| `goblin-2d` | biped | the same |
+| `fox-2d` | quadruped | the same, walking and galloping on four legs |
+| `bat-2d` | flyer | idle 4 (a hover) · blink 1 · walk 6 · run 4 (flying) · attack 4 · hit 2 · death 4 |
+
+Every character has the same cycle names, so the code that plays one plays any.
+
+## Using one
+
+- `get_character` with the id (free; `npx @funpixel/tools character get fox-2d`) copies
+  `base.png`, `sheet.png`, `sheet.json` and `clips.json` into
+  `public/assets/characters/<id>/`. `sheet.json` is the `generate_spritesheet` manifest: every
+  frame's anchor is the feet, `animations` lists each cycle, `meta.funpixel.animations` gives
+  each cycle's fps and whether it loops.
+- The scaffold's `src/character.ts` (Pixi) loads it as one `AnimatedSprite` with `play(name)`,
+  `face(dx)` and `blink()`; `src/characters.ts` picks idle, walk or run from speed with tuned
+  ranges (a value outside one throws, naming the field, like `living.ts`).
+- Keep `living.ts` on top: breathe at rest, squash on land and hit, blink on its timer.
+
+## Your look, the same motion
+
+`restyle_character` (paid, per frame; `character restyle fox-2d "an arctic fox in blue" --game-id
+<id>`) redraws the base in the new look, then every frame of the cycles you name with that base as
+the look to match, so the pose comes from the master and the look from one drawing. Each frame is
+checked against the new base and redrawn once if it drifted. Name only the cycles the game plays
+(`animations: ["idle", "walk", "blink"]`) to pay for fewer frames. With `game_id`, the game's style
+lock and anchors shape it. Check the estimate first; the answer's `frames` has each frame's colour
+match and mass.
+
+## Where it is weak
+
+- Side view only: a top-down or four-direction game still draws its own.
+- A drawn cycle is poses more than tweens: at 6 frames a walk reads as walking, not as
+  hand-animated. `living.ts` and speed-tied rates help.
+- A flyer's frames stand on the ground line like the others: hover it in code.

package/plugins/cursor/skills/funpixel-art/references/cost.md

@@ -0,0 +1,107 @@
+# What effects cost, and how to find out
+
+Numbers from the recipe lab (28 Sep 2026): a scratch scaffold per engine, each recipe a declared
+view, profiled with `npx @funpixel/tools profile` at the phone viewport (844×390 CSS px, DPR 2, so
+a 1688×780 canvas). "Desktop GPU" = Apple M4 Max through ANGLE/Metal, where everything held the
+display's 60 fps. "Software" = SwiftShader (`--software`), a CPU renderer much slower than any
+phone GPU, which is exactly why fill cost shows there. The machine was busy (load average near 34
+from other jobs), which is why the timing numbers carry their spread.
+
+## The profile loop (the Astra method)
+
+1. Name a view (`playing`, `boss`, `reveal`) and pin what varies: viewport, seed (`--seed`, which
+   sets `window.__FPX_SEED__` before the game runs; read it in your RNG), renderer.
+2. `npx @funpixel/tools profile --views reveal,playing --repeat 3` before the change. The file
+   lands in `.funtools/profile/<view>-<viewport>.json`.
+3. Change one thing. Run the same command. It prints each number that moved, with its percentage.
+4. Keep a control view in the same run (a view you did not touch). If the control moved as much as
+   the view you changed, the timing difference is the machine, not your change.
+
+Which numbers to trust:
+
+| Signal | Stable between runs? | What it tells you |
+|---|---|---|
+| draw calls, triangles | yes | how many times and how much the GPU is asked to draw |
+| scene counts (sprites, meshes, instances, particles, filtered objects, shadow lights) | yes | what the frame is made of |
+| texture MB (estimated) | yes | memory the effect holds (filters and bloom allocate render textures) |
+| fetched KB, dist KB by kind | yes | what a player downloads |
+| JS work a frame | fairly | CPU time in the game's frame callbacks; not capped by vsync |
+| frame ms p50/p95 | no, on a busy or fast machine | on a desktop GPU it sits at 16.7 (vsync); on software it moves with load |
+
+## Measured, Pixi 8.21 (phone viewport)
+
+| View | Draw calls | Texture MB | Notes |
+|---|---|---|---|
+| base (the lab world) | 1 | 0.1 | everything batches into one call |
+| additive glow sprites | 3 | 0.2 | cheapest way to make light |
+| `AdvancedBloomFilter` on the lantern layer | 9 | 2.1 | filters allocate render textures |
+| `OutlineFilter` on the hero | 3 | 0.1 | |
+| grade: colour matrix + vignette on the world, `resolution: 'inherit'` | 3 | 10.2 | full-screen at DPR 2 |
+| the same grade at resolution 1 | 3 | 4.1 | softer on a DPR 2 screen |
+| `DisplacementFilter` on the pond | 4 | 0.3 | |
+| 400 particles in a `ParticleContainer` | 2 | 0.1 | one call for all particles |
+| `MeshRope` trail | 2 | 0.1 | |
+| night (multiply layer + additive lights) | 3 | 0.4 | |
+| godrays + shockwave + blur on the world | 8 | 8.1 | a moment, not a steady state |
+
+Software renderer, grade at `'inherit'` vs resolution 1, median of 3: frame p50 66.6 → 50 ms,
+while the untouched base view moved 50 → 83 ms between the same runs. The texture memory
+(10.2 → 4.1 MB) is the reliable part of that comparison.
+
+## Measured, three 0.170 (phone viewport)
+
+| View | Draw calls | Triangles | Software p50 (median of 3) |
+|---|---|---|---|
+| base (60 instanced trees, pond, hero, lanterns) | 15 | 5,168 | 16.7 ms |
+| `UnrealBloomPass` + `OutputPass`, half-res on phones | 29 | 5,182 | 49.9 ms |
+| fog + sky dome | 16 | 5,696 | 16.7 ms |
+| shadow map (PCF soft, fitted camera) | 28 | 10,256 | 16.7 ms |
+| blob shadow instead | 16 | 5,170 | 16.7 ms |
+| AgX tone mapping | 15 | 5,168 | 16.7 ms |
+| 1,200 additive points | 16 | 5,168 | 16.7 ms |
+| inverted-hull outline on the hero | 16 | 5,576 | 16.7 ms |
+| wow (bloom swell + camera ease + 1,200 sparks) | 30 | 5,182 | 66.7 ms |
+
+Reading it: post-processing is the expensive thing (a full-screen pass per bloom mip, every
+frame); a shadow map doubles the draw calls and triangles (the scene is drawn again from the
+light); fog, tone mapping, points and a hull outline are nearly free.
+
+## Quality tiers
+
+Decide once, from the device, and step down if the first seconds run slow:
+
+```ts
+const coarse = matchMedia('(pointer: coarse)').matches;
+export const quality = {
+  dpr: Math.min(devicePixelRatio, coarse ? 2 : 2.5),
+  bloomScale: coarse ? 0.5 : 1,          // UnrealBloomPass resolution, or a Pixi filter's resolution
+  shadowMap: coarse ? 1024 : 2048,       // or 0 for blob shadows
+  particles: coarse ? 300 : 1200,
+  filterResolution: coarse ? 1 : 'inherit' as const,
+};
+// After the first 2 s of play: if the median frame is over ~22 ms, drop a tier (bloom off, fewer particles).
+```
+
+Headless numbers are not a phone's. When a phone is at hand, play the heaviest view on it; the
+profile tells you what changed, the phone tells you whether it matters.
+
+## Reduced motion and comfort
+
+- `matchMedia('(prefers-reduced-motion: reduce)')`: keep colour, light and glow; drop camera
+  moves, screen shake, big distortion (shockwave, heavy displacement), fast flicker; cut particles.
+- Avoid full-screen flashes brighter than the scene for more than a frame or two, and anything
+  flashing three or more times a second.
+- A settings toggle for effects the game leans on (bloom, shake, particles) is cheap and kind.
+
+## Silent traps met in the lab
+
+- Pixi: a top-level `await app.init()` in the entry module never resolved (Vite's renderer chunk
+  imports the entry back). No error; the canvas never appeared. Initialise inside a function.
+- Pixi: a custom filter redeclaring `uInputSize` in its fragment shader failed to link
+  ("precisions differ"), and everything under it rendered black. Pass a varying from the vertex.
+- Pixi: filters render at resolution 1 by default, soft on a DPR 2 phone.
+- Three: with an `EffectComposer`, tone mapping and sRGB conversion happen in `OutputPass`; leave
+  it out and the image is dark.
+- `profile` reads Three through `window.__THREEJS_RENDERER__` and `__THREEJS_SCENE__`, and Pixi
+  through `window.__PIXI_APP__`; without them it still counts WebGL draw calls but cannot say what
+  the scene holds.

package/plugins/cursor/skills/funpixel-art/references/effects.md

@@ -0,0 +1,85 @@
+# Visual effects: light, air and the big moment
+
+Effects are how a flat scene becomes a place at a time of day, and how a payoff becomes a moment
+someone remembers. They are also the easiest way to lose a phone's frame rate. This skill is a
+shelf of working recipes for Pixi 8 and Three.js, each run and captured in a scratch scaffold, with
+what each one measured. Pick what serves the look the game chose; a clean flat style may want none.
+
+## Tools
+
+- `capture_view`, or `npx @funpixel/tools capture --view <name> --viewport phone`, to see an effect
+  at phone size; `capture_view` on a `moment: true` view shoots a burst of the payoff.
+- `npx @funpixel/tools profile --views <name>`: frame times, the JS work of a frame, draw calls,
+  triangles, the scene by kind, texture memory and load, saved per view; the next run prints the
+  change. `--software` renders on the CPU so fill cost shows; `--repeat 3` steadies a noisy machine.
+  Funpixel's in-app builder samples with the same page script, so the numbers read alike.
+- `inspect_scene`, locally `npx @funpixel/tools scene`, lists what the scene holds.
+- `generate_skybox` for a 3D sky, `find_material` and `get_material` for Poly Haven HDRIs;
+  `generate_image` for a light cookie, a noise map or a painted sky gradient if code will not do.
+
+## The shelf
+
+| Effect | Pixi 8 | Three.js | Recipe |
+|---|---|---|---|
+| Glow around bright things | additive light sprite; `AdvancedBloomFilter` on the bright layer | emissive + `UnrealBloomPass` | [pixi](pixi.md#glow-and-bloom), [three](three.md#bloom) |
+| Mood and colour | `ColorMatrixFilter` + a custom vignette/shadow-tint filter | tone mapping (ACES, AgX) + exposure | [pixi](pixi.md#grade), [three](three.md#tone-mapping) |
+| A readable hero | `OutlineFilter` | inverted-hull outline | [pixi](pixi.md#outline), [three](three.md#outline) |
+| Water, heat, magic | `DisplacementFilter` with a scrolling noise map | a shader on the surface | [pixi](pixi.md#water) |
+| Particles | `ParticleContainer` + `Particle`, a fixed pool | `Points` with an additive soft sprite | [pixi](pixi.md#particles), [three](three.md#particles) |
+| Trails | `MeshRope` along recent positions | a ribbon or `Points` history | [pixi](pixi.md#trail) |
+| Night and lights | multiply darkness + additive lights | light colour, intensity, fog | [pixi](pixi.md#night), [three](three.md#time-of-day) |
+| Depth and air | lighter, bluer far layers | fog in the sky's colour + a sky dome | [three](three.md#atmosphere) |
+| Shadows | a soft blob under each actor | fitted shadow map, or blob shadows | [three](three.md#shadows) |
+| Time of day | keyframed tints | sun angle, colours, fog, sky | [pixi](pixi.md#time-of-day), [three](three.md#time-of-day) |
+| The reveal | shockwave + godrays + a blur settle | camera ease-in + bloom swell + sparks | [pixi](pixi.md#the-wow-beat), [three](three.md#the-wow-beat) |
+
+## Craft on the shelf
+
+1. **Start from the frame you want.** Name the time of day, the light source and what should glow.
+   An effect that is not in that sentence is probably noise.
+2. **Effect the few, not the stage.** A filter on the whole stage re-renders every pixel every
+   frame; put it on the layer that needs it (the lanterns, the water, the hero). Save full-screen
+   passes for the grade and the reveal.
+3. **Glow picks its source.** In Three, bloom whatever is emissive above the threshold and keep
+   the rest under it; in Pixi, bloom the bright layer only, or fake glow with additive sprites.
+4. **Budgets as constants.** Particles come from a fixed pool whose size is one number you can
+   change per quality tier; a burst reuses dead particles.
+5. **Quality tiers.** Decide once at start (and after a slow first second): phones get half-res
+   bloom, a 1024 shadow map or blob shadows, fewer particles, a DPR cap of 2. Details and the
+   measured costs: [cost.md](cost.md).
+6. **Reduced motion.** Under `prefers-reduced-motion`, keep light and colour, drop shake, big
+   distortion and camera moves, cut particle counts. The recipes read this flag.
+7. **Measure the change.** Profile the view before and after an effect, same viewport, same seed.
+   Counts (draw calls, triangles, texture MB) are stable; frame times move with the machine, so
+   repeat and compare against a control view in the same run.
+8. **Look at it at phone size.** Capture before, during and after a reveal; effects that read at
+   1440 px can turn to mush at 390.
+9. **In a whole 3D game, read the slow frames.** Averages hide hitches: read p95/p99 at a named
+   beat (the first fight, not the whole run), and name what appeared on each slow frame (a shader
+   compile, a texture upload) before fixing it. Warm-up, culling skinned actors, a pixel budget,
+   pacing to the refresh, and the leaks one game met: [frames.md](frames.md).
+
+## Worked example
+
+A dusk valley in Pixi with five lanterns. The lab's base view profiled at 1 draw call; additive
+halos per lantern took it to 3 with no change in JS work, and read as warm light in the capture.
+`AdvancedBloomFilter` on the lantern layer only: 9 draw calls and 2.1 MB of filter textures. A
+full-screen grade (colour matrix and vignette) at `resolution: 'inherit'` held 10.2 MB of filter
+textures; at resolution 1 it held 4.1 MB, and on the software renderer its frame p50 went 66.6 →
+50 ms (the control view moved 50 → 83 ms in the same runs: the texture number is the solid one). The game kept the halos, the lantern bloom and a resolution-1 grade.
+
+## Common mistakes
+
+- A filter or bloom on the whole stage when one layer needed it: every pixel pays, every frame.
+- Top-level `await app.init()` in the entry module: Vite's renderer chunk imports the entry back
+  and the page never starts, with no error. Initialise inside an async function.
+- A custom Pixi filter that redeclares `uInputSize` in the fragment shader: the precisions differ
+  from the vertex stage and the program fails to link (a black screen). Pass a varying instead.
+- `EffectComposer` without `OutputPass`: colours come out dark and tone mapping is skipped.
+- A white starburst or full-screen flash on contact: one racer's (Oct 2026) read as glare, one 38% clipped.
+  A small warm glow at the contact point, about 0.16 s, answers the hit.
+- Dither or halftone transparency in a shader: at phone size it reads as a glitch. Fade in broad, slow bands or
+  real alpha. To find which module owns a fault, capture with one module off
+  ([judging-frames.md](judging-frames.md)).
+- An additive volume checked only at the hero distance: seen down its own axis at melee range, a
+  summed beam became a white disc that hid the enemy. Soft-clip the sum and look up close.

package/plugins/cursor/skills/funpixel-art/references/frames.md

@@ -0,0 +1,87 @@
+# Smooth frames in a whole 3D game
+
+The recipe lab ([cost](cost.md)) measures one effect in a small scene. A whole game adds things a
+lab never meets: first-use compiles, a crowd of skinned actors, level rebuilds, big retina windows
+and displays faster than 60 Hz. This is what one game (a three.js third-person horror game, 29 Sep
+2026, `design/PERF.md` in its repo) measured, and what each fix bought. The numbers are that game's
+on that machine; the causes recur.
+
+## Smooth is a distribution, not an average
+
+At 78 fps average that game still stuttered. Read p95, p99 and the worst frame, and where the slow
+frames land. Then name each slow frame's cause before changing anything: on a hitch frame, read
+`renderer.info` for what appeared (new shader programs, textures, geometries). Every hitch it
+found had a cause that showed there.
+
+Profile the named beat, not the whole run. A whole-run phone profile read p95 16.8 ms, mostly
+exploring; `funtools profile --views firstWalker --viewport phone --throttle 4` on the first fight
+read p95 33.4 ms (about 41 fps). The fight is the phone's worst case, and the average hid it.
+
+Profile vsync-capped, as a player sees it. An uncapped run (`--disable-frame-rate-limit`) fooled
+the game's own refresh detection into cutting resolution at 2.5 ms frames. And profile on a machine
+nobody is playing on: films and profilers share the GPU and read as lag to the player.
+
+## What that game found, and what each fix bought
+
+| Symptom | Cause (measured) | Fix |
+|---|---|---|
+| 57–88 ms hitches at 0.7–1.3 s and at the first fight | a new shader program compiling on first use (her first steps; the first severed limb, a static copy of a skinned material, is its own program) | a warm-up behind the chapter card: `renderer.compile`, `initTexture` on every texture, then one frame with everything visible and nothing culled, plus one throwaway of each thing that can spawn mid-play. All 88 programs compiled before play |
+| a 76 ms phone frame at 1.2 s | 57 bone textures created lazily when the rigs first updated, after the warm-up | build every rig before the warm frame |
+| phone frames flipping 15 ↔ 33 ms (p95 31.5) | CPU-bound on three's per-object work: 506 draw calls, 1.3 M triangles, 274 shadow casters | the next five rows |
+| every enemy drawn, animated and shadowed everywhere | skinned meshes run with `frustumCulled = false` (bind-pose bounds lie), so nothing culled them | cull by hand: drawn and animated within 8 m, or on screen within 30 m (a sphere against the frustum); hidden rigs set `matrixWorldAutoUpdate = false` so three skips their bones |
+| the torch's shadow pass redrew most of the level | 274 casters, every wall module and prop | the environment receives but does not cast; one merged wall mesh still casts so light never leaks through a wall |
+| static geometry never culled | batches merged per material across the whole level | merge per material and per 10 m tile |
+| everything drawn to 80 m | fog is total by about 34 m (FogExp2 0.058) | `camera.far = 36` |
+| 594 matrices recomputed a frame | statics left with `matrixAutoUpdate` on | off for statics, and `matrixWorldAutoUpdate = false` once placed |
+| 3–4% of main-thread time in one HUD helper | reading `innerWidth` after the HUD wrote styles forces a layout, several times a frame | cache the size on `resize`; read the cache |
+
+Results on the same recorded run: desktop 1600×900 @2x worst frame 87 → 29 ms (5 hitches → 0 over
+33 ms); phone 844×390 @3x with the CPU ×4, p95 31.5 → 16.8 ms; draw calls 506 → 298 and triangles
+1.3 M → 0.69 M on the first-fight frame.
+
+## Big windows and fast displays
+
+A 1950×1090 window at pixel ratio 1.5 is 4.8 M pixels through AO, depth of field and bloom:
+GPU-bound (p99 26 ms). On a 120 Hz display, 9 ms frames flip between 8 and 16 ms and judder.
+
+- **A pixel budget** caps the ratio by pixel count (that game: 2.6 M on desktop, 1.3 M on a phone);
+  the DOM HUD stays at full retina.
+- **Pace to the refresh.** Detect the refresh from the fastest frames, judge each second's p90
+  against that slot, and when 120 cannot hold, lock to 60 (render every other refresh) before
+  lowering resolution.
+- **Hysteresis.** Each resolution change rebuilds the post-processing targets (41 textures, a 70–100
+  ms frame), so an oscillating scaler stutters every few seconds. Its rule: no step up within
+  12 s of a step down, five fast seconds to earn one, none after two downs.
+
+Result: 119.2 fps on a 120 Hz display at 1950×1090 @2x, p99 9.4 ms, worst 17.5 ms, zero hitches.
+
+## Leaks that read as "it gets laggy after a while"
+
+The Funpixel profiler (`funtools profile`, and `window.__funpixelProfiler.getReport()` in dev) found
+what the game's own tools missed: +405 textures on every level rebuild, never freed, which every
+death's Retry triggered. `renderer.info.memory` went 957 → 1362 → 1767 → 2172 → 2577 over four
+rebuilds. A rebuild disposes each old `SkinnedMesh.skeleton` (its bone texture), the per-build
+materials and their canvas textures, and keeps the shared model materials whose images are reused.
+Reading `renderer.info.memory` before and after a Retry catches it.
+
+Draw calls counted at the WebGL call (verify's renderer note: 494 desktop, 511 phone) include
+every pass (shadow, AO, beauty, post); one `composer.render()` counted 298. Know which one a number
+is before comparing.
+
+A title faded to opacity 0 kept animating its Ken Burns and motes over the canvas every frame, and
+`audit-screens` saw it cover the play in 25 of 25 views. `visibility: hidden` once the fade ends,
+with its animations paused, removed it.
+
+## When something glows that should not
+
+"Anything that looks like a white ball is a light" held four times in that game: the torch's
+hotspot on a close surface, the beam cone seen end-on, coral pushed past the bloom's white point,
+and the worst one, an additive ray-marched beam seen down its own axis. From the camera behind her,
+the view ray ran down the whole lit cone and eight summed samples bloomed into a white disc that
+hid an enemy at knife range. It was found only by asking "what is that?" of a melee still and hiding
+one thing at a time.
+
+- Soft-clip any additive sum (`1 - exp(-x)`), and thin a volume when the view runs along its axis.
+- Check effects at melee range, not only at the hero distance the recipe was tuned at.
+- An on/off A/B is only honest when the frame's own update does not re-set what you turned off
+  (the torch and emissives were re-posed every frame; the albedo was not).