@funpixel/tools 0.0.0-stage → 0.1.1

package/plugins/kiro/skills/funpixel-3d/references/unity.md

@@ -0,0 +1,78 @@
+# 3D models from generator to Unity
+
+A 3D model can fail in Unity without an error. glTFast (the glTF importer, package `com.unity.cloud.gltfast`) decodes textures embedded in a GLB to raw RGBA32, 4–16 MB each, and imports a web GLB packed with meshopt or WebP as nothing. That made the 3D games 3–5× bigger than the 2D ones: one idle game was 386 MB before this pipeline and 106 MB after. This skill takes a model from the generator to a compressed, collidable asset.
+
+## Tools
+
+Not shipped by the kit: the Unity starter, its checks and the studio scripts (`blender_prep.py`, `render_glb.py`, a collision audit, a size audit). Do the rest with what exists:
+
+- Generate into the project: `npx @funpixel/tools gen model3d "<subject>" --image-asset concept.png --unity .` (after `npx @funpixel/tools login`) asks for the engine's own GLB (`--raw`: glTFast reads no Draco, meshopt or KTX2 without three more packages), splits it into `.gltf` + `.bin` + `model__basecolor`/`__normal`/`__mr` textures in `Assets/_Game/Generated/Models/<name>/` (the studio's `glb_split.py`, ported), and writes an import rule that sets those textures once, ASTC 6×6 at most 1024, sRGB only for colour, and keeps `__normal` a NormalMap. Checked on 6000.6 with a Meshy and a Hunyuan model: meshes and textures import. The studio's `gen_3d.py` calls fal with a `.env` key: no metering, no cost log.
+
+- Prepare in Blender through the kit's bench: `npx @funpixel/tools model --local normalize hero.glb --height-m 1` (unit height), `model --local decimate hero.glb --target-triangles 3000`, `model --local inspect hero.glb` (triangle count). The hosted `inspect_model`, `optimize_model` and `fracture_model` do the same on a model a job made. Joining meshes and moving the origin to the base centre are not in the bench; do them in Blender by hand or in your own script.
+- Proof render: the hosted `render_model`, or `npx @funpixel/tools model --local render hero.glb --frames 3`, gives the three angles.
+- Split a GLB for Unity with gltf-transform (`gltf-transform copy model.glb model.gltf` writes `.gltf` + `.bin` + texture files); name the textures by role (`model__basecolor`, `model__normal`, `model__mr`) so the import rule can find them. gltf-transform also decodes web GLBs (meshopt + WebP).
+- Name split textures by role and keep them under `Art/` or `Models/`, so the import rule finds them: write it as an `AssetPostprocessor` in `Assets/Editor/`, or use the one `gen --unity` writes.
+- Collision and size audits are your own Edit Mode tests until the checks ship: compare each prop's `Renderer.bounds` with its `Collider.bounds`, and read the Editor's build report for texture formats.
+
+Checks: `texture_audit`, `drawn_vs_solid`, `glb_import`, `tri_budget` and `lfs_audit` are proposed, not built (partial versions exist in single games). Until then `model --local inspect` gives the triangle count.
+
+## Procedure
+
+1. Pick the generator from the bake-off: same GPT-Image input, 3-angle Blender render.
+
+   | Generator | Triangles | Result |
+   |---|---|---|
+   | Meshy v7.1 | 31K | won: crisp detail, rig in the same call |
+   | Hunyuan3D v3.1 Pro | 500K | best fidelity, hero option, $0.38 per mesh |
+   | Trellis 2 | not in the report | muddy |
+   | Tripo H3.1 | 1.4M | artefacts |
+
+2. Pin glTFast at 6.20.0. The "latest" tag pointed at an experimental 7.0.
+3. Decode a web GLB with gltf-transform before import, and keep the original in `design/art-source/`. glTFast imports meshopt and WebP GLBs as nothing, with no error; `funtools doctor` fails on one under Assets. `gen --unity` never hands Unity one: it asks for the raw GLB.
+4. Prepare the model (normalize, decimate, then join and re-origin in Blender). Conventions to leave: static fronts face −Z, characters face +Z, one material named `<name>_Mat`, emissive parts separate, scale checked against a 1 m cube. Nothing is baked for props; the generator's textures are kept.
+5. Reduce triangles by kind of model; each method breaks something different.
+
+   | Model | Method | What goes wrong otherwise |
+   |---|---|---|
+   | Small prop | Meshy remesh (re-bakes textures onto the new mesh) | plain decimation tears UVs (`RAMEN` became `RMEN`) |
+   | Big signage | not in the report | remesh garbles lettering (`SATAY` became `CATAY`) and decimation tears it too |
+   | Thin rims | keep 4K triangles or more | rims tear below 4K |
+
+   Budget (`tri_budget`, proposed): a prop at most 2.5–7K by shape, a scene at most 300K. Which shape gets which figure inside 2.5–7K is not in the report.
+6. Render the proof (`render_model` or `model --local render`) and read the three angles: lettering legible, rims whole, count in budget.
+7. Split the GLB (gltf-transform) and import the split `.gltf`. Your import rule then applies. Change the rule in code, not the `.meta`: the rule reverts a hand edit on the next import.
+
+   | Kind | Setting |
+   |---|---|
+   | Model textures | ASTC 6×6, mipmaps, sRGB only for basecolor and emissive, max 512 (props) or 1024 (stalls) |
+   | 3D models | default glTFast import of the split `.gltf`; no LODs except one game's mid LOD |
+   | Rigged characters (FBX) | Generic rig, root `Hips`, Loop Time on, Apply Root Motion off, in-place clips at 30 fps |
+
+8. Confirm the import (`glb_import`): every GLB yields at least 1 mesh with more than 0 vertices, and no `.webp` or `.woff2` sits under Assets.
+9. Size and place the model from its measured bounds. Guessed widths were 20–70% off the real model.
+10. Give it a collider that matches what is drawn, and run `drawn_vs_solid`: drawn mesh bounds against collider bounds per prop and mover, at or under the baseline per category.
+11. Reference material assets from code. `Shader.Find` on an unreferenced shader is null on device (stripped; `funtools doctor` warns). Runtime-created materials need `multi_compile_local`, not `shader_feature`.
+12. Audit the build (`texture_audit`): 0 unwhitelisted RGBA32 textures, RGBA32 total under 1 MB. Mipmapped textures must be power of two; Unity 6000.6 ships a mipmapped non-power-of-two texture as RGBA32 even with an ASTC override.
+13. Store baked binary data as `.bytes` in LFS (`lfs_audit`: 0 tracked binaries over 500 KB outside LFS, no untracked paid art).
+
+Rigs: one shared skeleton gives one Animator for the whole cast. Large crowds use no rigs at runtime: one game bakes rigged GLBs to vertex-animation textures.
+
+## Worked example
+
+A new 3D idle game, done with the studio's own scripts (proposed for the kit). Steps 2–4 are the report's general pipeline; it does not log them per game.
+
+1. Props and stalls as generated GLB; characters as Meshy-rigged FBX (the auto-rig survived import 7 of 7).
+2. Blender prep at 3,000 triangles: joined, unit height, origin at base centre.
+3. A 3-angle proof render and the triangle count.
+4. Split: `.gltf` + `.bin` + `model__basecolor`, `model__normal`, `model__mr` PNGs.
+5. The texture import rule: ASTC 6×6, max 512 for props and 1024 for stalls.
+6. Result: data 315 → 61 MB; the app 386 → 106 MB with the build size settings also on. Another game went 229 → 75 MB.
+
+## Common mistakes
+
+- Importing a web GLB as it is. One game's 12 heads "did not import at all", with no error.
+- A prop with no collider, or art bigger than its collider. 42 props in one game could be walked through; another's paperweight art was 54 px taller than its collider; a head drawn 1.15× its hitbox was removed.
+- `shader_feature` on a runtime-created material. One game's instanced sets drew at the origin on device.
+- Baked data as serialised YAML in git. One game's vertex-animation crowd assets are about 70 MB of YAML (minotaur 13.0 MB, cyclops 11.8 MB), and every re-bake adds about 70 MB to history.
+- Paid generations outside LFS: about 840 MB lived on one Mac.
+- Trusting Meshy's Idle preset. It bowed the head to the chest and was re-keyed in Blender.

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