@funpixel/tools 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,104 @@
+---
+name: funpixel-art
+description: Use when choosing or checking a game's look (style, colours, a target frame, eye comfort), making 2D art (sprites, sheets, poses, backdrops, tiles, icons; a little pixel knight), or adding light and effects (glow, bloom, particles, fog, night), or when captures drift from the target or effects cost frames. In Unity (sprites, atlases, TextMeshPro glyphs), follow references/unity.md.
+---
+
+# The look: direction, 2D art and effects
+
+Choose a look that serves the player, make every asset from it, and prove it in the running game.
+A simple style still owes clear silhouettes, one family and feedback; a generated image is a draft
+until it is measured and wired (an opaque "transparent" plate, a 1024 px coin drawn at 40 px and
+art never loaded all build green). Effects are how a flat scene becomes a place at a time of day,
+and the easiest way to lose a phone's frame rate. Name stand-ins as stand-ins.
+
+## Route by the job
+
+| The job | Read |
+|---|---|
+| Choose or check the look: the target frame, five AD rules, UI as art, judging captures | [look](references/look.md), [judging frames](references/judging-frames.md), [ui](references/ui.md) |
+| Make, repair or wire 2D art: which tool, keying, animation, atlases | [2d-assets](references/2d-assets.md), [animation](references/animation.md), [wiring](references/wiring.md) |
+| An asset family that stays one family | [style-file](references/style-file.md), [prompts](references/prompts.md), [cast](references/cast.md) |
+| Light, grading, particles, the reveal, and what each costs | [effects](references/effects.md), [pixi](references/pixi.md), [three](references/three.md), [cost](references/cost.md) |
+
+## Tools
+
+- `generate_image`: a target frame, backdrops, tiles (`kind: "texture"`, seamless), panel art.
+  `generate_sprite`: one transparent object (hero, enemy, pickup, prop, icon; a glow on pure black).
+- `edit_image`: the same character in a new pose or state (`mode: "pose"`). `generate_spritesheet`:
+  a character's cycles as one packed sheet from its accepted sprite.
+- `list_characters`, `get_character`, `restyle_character`: ready-made characters that already
+  fit; `slice_sheet` cuts a sheet into frames; `accept_asset` measures an image for its role, free;
+  `import_asset` brings in art no job made, free.
+- `get_job` collects a job by id; after a timeout, collect rather than submit again.
+- `capture_view` and `inspect_scene` show the look and the effects in the running game;
+  `generate_skybox` and `get_material` for 3D skies and HDRIs.
+- Local and free: `npx @funpixel/tools look --sheet` (every sprite at play heights on the real
+  ground), `look --read`, `variety` (which games a choice sits close to), `score --target`,
+  `cut` and `parts` (cut a painted sheet), `assets pixels` (an exact pixel-art grid),
+  `optimize pack-atlas|compress`, `profile --views <name>` (draw calls, texture memory, frame times)
+  and `smoke`. `npx @funpixel/tools job <id> --wait --out <path>` saves a job with provenance.
+- Without the MCP: `npx @funpixel/tools gen image|sprite|edit|sheet "…"` with a paid key; lacking a
+  key does not preclude authored or procedural art.
+
+## The look first
+
+1. **Match the scope.** A repair or a supplied look works from the accepted asset, its style guide
+   and the real background; name what is locked (identity, palette, silhouette). An open direction
+   explores a familiar option and an unexpected one; the creator's locked choices win.
+2. **State the choice** in the GDD (skill `funpixel-gdd`): medium, palette roles, camera and why;
+   a route for every asset (generated, authored, or procedural proven by a rendered study;
+   "primitives for now" is a stand-in). **Five AD rules**, each checkable in one frame.
+3. **A target frame,** `design/target.png` at the real aspect, with play area, player, threat,
+   an action moment and HUD, labelled. Capture at its viewport and measure gaps
+   in play-area share, actor size, HUD coverage and colour roles; fix framing before paying for art.
+   Match the target's quality, not its density (`score` warns on a busy or clipped frame).
+4. **Direct the UI too:** plates of the world's material, a display face, one icon family, a
+   target for the HUD and one for the title ([ui](references/ui.md)).
+
+## Making 2D art
+
+1. **List what the player sees** and start the jobs together; reuse, author or generate each.
+2. **Anchor every prompt to the style file** (`assets/style.json`): subject + medium + the family
+   clause + `never`, with the style frame (world art) or the hero reference (characters) passed as a
+   reference. A set stays one set because every item is anchored to the same accepted images.
+3. **Write the rubric first:** three to six pass/fail lines citing the AD rules ("one 4 px ink
+   outline", "reads at 48 px"). A line written after seeing the result grades the result.
+4. **Transparency:** native alpha first; glows on pure black, keyed by luminance. A pale subject on
+   white is eaten by the key: ask for a dark outline and a field colour the subject lacks.
+5. **Measure, then repair or regenerate,** one clause changed per round from the baseline. After
+   three rounds without a clean result, or two fixes failing one line, keep the best and name the
+   miss (Scenario's stop rule).
+6. **Same identity, new state:** a hurt or powered-up hero is `edit_image` of the accepted sprite;
+   a fresh `generate_sprite` redraws another character.
+7. **Pack, wire by role, finish:** one atlas per scene, sized at phone size with `setupGameResize`,
+   compressed to the displays you support, stand-ins removed ([wiring](references/wiring.md)).
+
+## Light and effects
+
+Start from the frame you want (the time of day, the light source, what glows); an effect not in
+that sentence is probably noise. Put a filter on the layer that needs it, not the whole stage; pool
+particles behind one number per quality tier; under `prefers-reduced-motion` keep light and colour
+and drop shake and big distortion. Profile the view before and after on the same seed and read the
+counts, then look at it at phone size. The shelf of recipes with measured costs:
+[effects](references/effects.md).
+
+## Worked example
+
+A side-scrolling fox, target and style file in place. AD rules include "one 4 px ink outline" and
+"coral only on the fox". Six jobs start together, each anchored to the style frame or the fox; the
+fox's `generate_spritesheet` (idle 4, run 6, hit 2) comes back aligned and `edit_image` adds its
+blink. Packed and sized (fox 16% of screen height, hitbox 70%), the `Graphics` stand-in deleted.
+At dusk, additive halos on five lanterns take the view from 1 to 3 draw calls and read as warm
+light; a full-screen grade at resolution 1 holds 4.1 MB of filter textures, against 10.2 MB at
+`'inherit'`. Smoke is clean.
+
+## Common mistakes
+
+- Text and glyphs drawn into generated art: they blur and cannot change (the wordmark excepted).
+- "Sprite sheet, walk cycle, 8 frames" as the whole prompt: you get a picture of a sheet.
+- Trusting "transparent" without measuring: a whole family has shipped at alpha 255.
+- Calling the declared medium a defect: inconsistent execution is the defect, not the medium.
+- A filter or bloom on the whole stage when one layer needed it: every pixel pays, every frame.
+- A white starburst on contact: it reads as glare; a small warm glow for about 0.16 s answers a hit.
+
+Adapted in part from scenario-labs/skills (MIT); see THIRD_PARTY_NOTICES.md.

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 a Riad Rush 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: Gallery Heist drew its keepers 6 to 13 times
+each and its crew in rest, brace and cover poses; Held Note 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 (Gallery Heist's Smudger and Carrier: 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.