@funpixel/tools 0.0.0-stage → 0.1.1

package/plugins/kiro/skills/fp-smoke-build/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: fp-smoke-build
+description: Use when the person types /fp-smoke-build. The 10-minute smoke build before any full build — one locked-art picture and one generated 3D model in a bare scene, captured and judged.
+---
+
+Before a full build, prove the kit end to end on this machine and account. In a new, empty folder next to
+the plan (never the game itself), run:
+
+`npx @funpixel/tools smoke-build ../smoke --plan <the folder holding design/plan.md and design/first-look/ref-*.png>`
+
+It runs the shortest path a real build takes: `init --bare`, the plan's locked sheets imported and
+pinned on the game's lock, one world picture and one 3D model through the hosted tools, both placed in
+the scene, then capture, `check --world`, `score --target` against the plan's target frame, and one
+progress card. It costs one picture and one model.
+
+Read the four verdicts (exit 0 pass, 1 fail, 3 error; the record is `.funtools/smoke-build.json`):
+
+1. **a generated 3D model in the world** — a failed model is retried, switched (provider, tier), or put
+   to the person (`progress ask … --kind scope`); it is never drawn in code;
+2. **the locked look** — the picture came back drawn to a locked sheet, and the target score is at the bar;
+3. **no primitives** — the world read holds by name (no boxes, box figures, gliding cut-outs);
+4. **a real card** — the card carries a frame of the build.
+
+Any FAIL means the full build would hand back what the last ones did. Fix the kit or the provider,
+run the smoke again, and only then start the game. Report the four verdicts as they stand.
+
+The person's words with this command: $ARGUMENTS

package/plugins/kiro/skills/fp-studio/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: fp-studio
+description: Use when building or reviewing a Funpixel game in Kiro and coordinating its specialist roles, blind player or critic panel.
+---
+
+# Funpixel in Kiro
+
+Use the shared Funpixel skills and tools. `/fp-new`, `/fp-verify`, `/fp-playtest`, `/fp-mobile-qa` and `/fp-publish` are the command
+entry points. The seven specialist roles are skills here: `fp-art-director`, `fp-audio-director`,
+`fp-level-designer`, `fp-qa-lead`, `fp-player`, `fp-critic` and `fp-mobile-qa-seat`. They carry the same role
+instructions as the Claude Code and Codex packages. Pick the roles the task needs; the full
+panel fits a requested complete-game review, not every asset or code edit.
+
+## How the hooks reach you here
+
+Kiro shows an agent hook's output to the model only at the start of a turn. So:
+
+- The brief and this project's state arrive with your first message in a game folder.
+- Reminders the other hosts give mid-turn, and anything the Stop gate finds open when you finish,
+  arrive at the start of the person's NEXT message, under "Funpixel: the last turn ended with open
+  items". Treat them as the gate's verdict on your previous hand-back: act on them first, or say
+  plainly which you are leaving open and why.
+- Kiro's stop hook cannot hold a turn open. The person sees the open items as a warning when you
+  stop, so an ending that claims "done" over an open item is visible to them. Check before you stop:
+  `npx @funpixel/tools check` (or `npm run build`, then `verify`).
+
+## Blind player and critics
+
+Delegate each seat to a separate subagent with fresh context: one `subagent` call per seat, a single
+stage whose `name` includes the role (`critic-veteran`, `critic-ux`, `critic-mobile`,
+`critic-skeptic`, `player`). Paste the role skill's instructions and only the evidence that role
+permits into `prompt_template`. The player reads the running game through funtools play, not its
+source. Critics see captures, the permitted description, AD rules, screen measurements and their
+own previous verdict; another seat's scores or the builder's code pull a seat toward them. The
+postToolUse hook reads a critic stage's reply for its surface verdicts (the critic rubric's JSON),
+so a reply without them records nothing. One seat per call, or four verdicts land in one reply and
+the seats cannot be told apart.
+
+If isolated subagents are unavailable, report that acceptance step as unverified. The gate cannot
+tell a verdict you wrote from a seat's, so the verdicts are the seats' alone.
+
+## Host setup
+
+`node install.mjs` in this package writes the `funpixel` agent to `~/.kiro/agents/funpixel.json`
+(or `--workspace` for `./.kiro/agents/`) with absolute paths to these hooks and skills; start it
+with `kiro-cli chat --agent funpixel`. The Funpixel MCP reads `FUNPIXEL_API_KEY`; without a key the
+installer leaves it disabled and the skills fall back to `npx @funpixel/tools`. Verify a real MCP
+call before recording the hosted integration as tested.

package/plugins/kiro/skills/fp-verify/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: fp-verify
+description: Use when the person types /fp-verify. Build and verify the Funpixel game in this folder, fix what fails, and stop when it passes.
+---
+
+Run `npm run build`, then `npx @funpixel/tools verify` (or `npx @funpixel/tools check`: both and
+the rules suite in one call) in the game folder now (the one with `funpixel.json`). If the Funpixel MCP is connected and the local build cannot run, use `build` then
+`probe` instead.
+
+Then, following the `funpixel-verify` skill:
+
+1. Read the exit code: 0 pass, 1 fail, 2 nothing measured (not a pass), 3 a tool error.
+2. For every FAIL line, fix the cause in the game, rebuild, verify again. A check weakened, or a
+   state field negated to pass it, makes verify report a game that does not exist (the harness
+   learned this on control checks passed by flipping a sign instead of fixing the camera).
+3. Exit 2: declare the missing `__FPX_*` hooks, then verify again.
+4. On exit 0, press the real start control once (the front door) and confirm the play screen:
+   verify enters play through its hooks and skips the title, so a dead Play button still passes it.
+5. Green is where this command ends. Report the verdict, what you fixed, and anything you could
+   not verify.
+
+The person's words with this command: $ARGUMENTS

package/plugins/kiro/skills/funpixel-3d/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: funpixel-3d
+description: Use when a 3D game needs a model or a place, or one is wrong (a character, creature, vehicle or prop; a GLB that draws black, will not animate, slides its feet or is too heavy for a phone; grey or plastic skin across a cast; a 3D level, an interior or a set, or a scene that must match a painted target). In Unity, follow references/unity.md.
+---
+
+# 3D models and places
+
+A generated GLB is paid, slow and can load without an error while it renders flat grey, stands
+frozen, skates, sinks into the floor or carries 100K triangles where a phone draws 6K. None of these
+throws, and an idle-pose screenshot hides most of them. This skill picks the lane per object, checks
+every model on the bench before code depends on it, gives a cast one skin, and builds levels from a
+spec. The person's locked choices override every default here.
+
+## Route by the job
+
+| The job | Read |
+|---|---|
+| A new character, creature, vehicle or prop: lane, concept image, price, clips, loading | [models](references/models.md), [hero-route](references/hero-route.md), [concept-image](references/concept-image.md), [three-loading](references/three-loading.md) |
+| A model that is wrong or heavy: inspect, rig, clips, optimize, finalize, proof | [bench](references/bench.md), [reading](references/reading.md), [budgets](references/budgets.md) |
+| Skin across a cast, a variant on the same mesh | [skin](references/skin.md) |
+| A level from a spec: blockout, colliders, markers, dressing | [level-spec](references/level-spec.md), [light-and-places](references/light-and-places.md) |
+| A scene that must match a painted target; skies | [painted-target](references/painted-target.md), [skyboxes](references/skyboxes.md) |
+| A Unity project | [unity](references/unity.md), [engine-targets](references/engine-targets.md) |
+
+## Tools
+
+- `generate_3d_model`: a prompt or image URL to a GLB; `style` `standard` (~160 credits), `hero` or
+  `lowpoly` (~45); `animations` rigs a humanoid biped. Long runs return a job id for `get_job`: a
+  timed-out job still runs, paid for, so collect it and never resubmit.
+- `generate_image` makes the concept image; `list_characters`, `get_character` (free) and
+  `restyle_character` give rigged characters that already move; `get_material` after
+  `find_material` for free CC0 HDRIs and PBR sets; `generate_skybox` for a sky.
+- The bench, about 1 credit a step: `inspect_model` (free), `rig_model`, `audit_clips` (free),
+  `optimize_model`, `finalize_model`, `render_model`, `lod_model`, `texture_stats` (free),
+  `fracture_model`.
+- `author_skin` (about 3 credits) and `retexture_model` for skin and variants.
+- `build_level` turns `design/level.json` into `level.glb` with `plan.png`, `view.png`, the markers
+  and the collider audit.
+- `inspect_scene`, `capture_view` and `screenshot` show it in the game at the camera you ship.
+- Local: `npx @funpixel/tools model --local inspect|render|finalize|level <file>` on your own
+  Blender (free); `npx @funpixel/tools gen model3d` with a paid key; `fidelity` scores a model
+  against its views; `look --3d` says whether the heroes are code primitives or models; `reach`
+  names markers nothing reaches. With none of these, build from palette primitives and name the
+  stand-in.
+
+## The order that avoids rework
+
+1. **A lane per object,** written in the design note with its cost: a humanoid a library character
+   fits → `get_character`; a hero the camera frames close → `standard` from a concept image; a body
+   whose size is a stat → primitives in code; animal, blob or vehicle → a static mesh animated in
+   code; crates and walls → primitives; crowds → one model instanced, with a far LOD.
+2. **A concept image first:** one subject, whole, straight on, plain light background, flat light;
+   a rig needs an A-pose, empty hands and fitted clothing. Text-to-3D invents its own design.
+3. **Say the price, start early,** and pass `confirm_cost` only when the person allowed it. Retry a
+   failed humanoid alone: parallel resubmits have all failed where serial ones passed.
+4. **The bench before wiring:** `inspect_model` (act on findings before facts; `-1` means not
+   measured), a rig check before paying for motion, `audit_clips` with `expected` set to every clip
+   name the code plays, then the contact sheet. Rig before decimating; decimate before welding.
+5. **Optimize to the device,** `phone`, `desktop` and `high` cuts from the kept source; `finalize_model`
+   with `keep_clips`; the proof render, not the success message, is the fix.
+6. **One material direction** for generated and code-built objects; compare them under the game's
+   light at phone size.
+7. **Skin:** one tone per character in a cast table; `retexture_model` before `author_skin`, never
+   after; read `marks` and `proof.png`, then fix the scene light rather than the tone per shot.
+8. **Levels:** a table of areas, doors, routes and every named point before the spec; blockout with
+   no props; walk every route in the game (a hidden `colliders` node, a kill plane under the
+   floor); dress with the kit to zero audit findings; read markers by name and fail loudly.
+9. **Report what you could not fix:** a dragging limb, a clip replaced by code motion, a model
+   checked by eye only, a scene over budget, each by name.
+
+## Worked example
+
+A runner's knight hero: lanes in the note (knight generated and rigged; coins, crates and track in
+code). A concept image, front view, A-pose, hands empty. "About 248 credits, rigged with idle, run
+and jump. Go ahead?" Yes. The call times out; `get_job` returns `knight.glb`, 98K triangles.
+`audit_clips` finds all three clips; `optimize_model` cuts it to 6K for a phone; `finalize_model`
+keeps the three clips and its contact sheet shows it lit from every side. Hand-back: "Knight rigged
+with three clips; the rest is code, one material."
+
+## Common mistakes
+
+- Text-to-3D for the hero: the model drifts from the 2D art.
+- `animations` on a dog or a slime: the rig step is skipped and the money buys nothing.
+- `root.clone()` for a second enemy: every copy shares one skeleton and stands frozen.
+- A clip name typed from memory (`hurt` against `hit`): it loads and never plays.
+- Running `author_skin` before `retexture_model`: the repaint paints over the skin.
+- Colliding against the art mesh, or dressing before walking the blockout.
+
+Adapted in part from scenario-labs/skills (MIT); see THIRD_PARTY_NOTICES.md.

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

@@ -0,0 +1,48 @@
+# The model bake-off: several candidates, one judged against the master
+
+One game tried its hero three ways (three providers' takes of the same front picture) and picked
+from turntable sheets; another made two to four models of each crew member before one held.
+A model is the most expensive asset a game makes, and the first one is rarely the keeper. The
+bake-off makes the choice cheap to see and puts it on record.
+
+Adapted from scenario-labs/skills (MIT, © 2026 Scenario; the model-comparison skill); see
+THIRD_PARTY_NOTICES.md. The words and the tools are ours.
+
+## The rules, set before the candidates exist
+
+- **One input for all.** Every candidate is made from the same master picture (the cast member's
+  `design/cast/<id>/master.png`, or the item's `from` picture). Changing the input mid-way makes
+  the comparison about the input.
+- **A budget first.** N candidates cost N models (105 credits each at `standard`): price the run
+  (`assets gen --dry-run`) and say it. Three is the hero's default; every other model makes one.
+  Three engines make three honest candidates from one picture: `engine: "meshy"` (~160),
+  `"hunyuan"` (~105) and `"rodin"` (~80, static only; `gen model3d --engine meshy|hunyuan|rodin`).
+- **The same framing for every render.** Each candidate is rendered round by the Blender bench
+  (local and free with your own Blender 4.2+; the same verb the hosted bench runs) and scored on
+  its best view against the master: outline overlap 0.65, colour 0.35.
+- **Measurements before taste.** The numbers remove the wrong design. They do not choose between
+  two good takes: when the top two are within 0.03 the run says it is a tie, and the identity seat
+  or the owner chooses.
+
+## In the manifest
+
+```json
+{ "name": "ren3d", "kind": "model3d", "cast": "ren", "draws": 3, "optimize": { "device": "phone" } },
+{ "name": "renrig", "kind": "rig", "from": "ren3d", "clips": ["idle", "walk"],
+  "retarget": { "character": "<a stocked 3D character>", "clips": ["run"] },
+  "optimize": { "device": "phone", "budget": "character" } }
+```
+
+The kept candidate is the file; every candidate's score and best render are in the lock
+(`bakeoff`), the draws under `.funtools/assets/draws/<name>/`. A mover then runs the rig chain as
+one item: `rig_model`, then authored `motions` (`author_motion`), then clips carried from a stocked
+character (`retarget_clips`), then the optimizer level for the platform. Decimate after rigging,
+never before (step 5 of the skill).
+
+## What it showed on real files
+
+On the first game's own models, rendered by the bench: each prop's model was ranked first against its own
+reference picture, by 0.03 to 0.13 over the next (crate, door, lockers, canister, bell); the three
+providers' takes of the hero scored within 0.03 of each other, and well above any prop. The team
+kept the Rodin take for reasons a silhouette cannot see (triangle budget, separable limbs). That is
+the job of the numbers: a short list of on-model candidates, never the final word on taste.

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

@@ -0,0 +1,103 @@
+# The bench: from generated mesh to shipped model
+
+A 3D model can import cleanly, pass the build and still ship broken: invisible, a flat
+silhouette, frozen in bind pose, skating, or 100K triangles where a phone draws 6K. None of these
+throws an error, and an idle-pose screenshot hides most of them. The checklist below is the order
+that avoids rework, run before code depends on a model; take the steps the model needs. Each is
+cheap next to a regeneration (a bench step costs about 1 credit; a rigged textured model 145 or more).
+
+## Tools
+
+- `inspect_model` (free): findings first, then facts (meshes, vertices, bones, clips, megabytes,
+  longest axis, height over footprint).
+- `rig_model`: keys idle, walk, attack and death onto a bare biped rig, or fits a donor biped's
+  rig and clips onto an unrigged mesh. Its free rig check refuses, uncharged and with the reason,
+  a model that is not a biped, already animates, or has nothing to borrow.
+- `audit_clips` (free): plays every clip; length, root motion, a sliding planted foot, a clip
+  frozen in one pose, and your code's clip names matched against the file's.
+- `optimize_model`: pivot at the base, +Y up, metres, decimated to a shape class's
+  triangle budget for a phone or a desktop, keeping UV seams and skin weights.
+- `finalize_model`: repairs materials that draw nothing or black, drops clips not in
+  its keep list, and renders a front view and a contact sheet as the proof.
+- `render_model`: views round any model, a front view and a contact sheet.
+- `lod_model`: 1–4 levels of detail (`model.lod1.glb` onwards) for things drawn small and often.
+- `texture_stats` (free): each texture's size and GPU memory against the device's limit.
+- `inspect_scene` and `screenshot`: the model in the game, at the camera you ship.
+- `fracture_model` pre-cuts a prop into capped pieces; `get_job` collects a paid job again.
+- `build_level`: [level-spec](level-spec.md); `author_skin`, `retexture_model`:
+  [skin](skin.md).
+- `generate_3d_model` when the mesh itself is wrong (wrong subject, fused limbs); a joint or a
+  material is a bench repair at a fraction of the price.
+- Local: `npx @funpixel/tools gen inspect|rig|optimize-model|lod|render|finalize --asset <id>`,
+  `npx @funpixel/tools model --local inspect|render|finalize <file>` on your own Blender (free),
+  and `npx @funpixel/tools scene`. With none, check by eye in a glTF viewer and say so.
+
+## The checklist
+
+1. **Inspect.** `inspect_model` on each model before wiring it: a model that loads without an
+   error can still draw nothing. Act on findings
+   before facts; the answer to each finding is in [reading.md](reading.md).
+   `-1` means not measured: it is neither a zero nor a pass.
+
+2. **Rig check before you pay for motion.** A humanoid that must move needs bones and clips that
+   drive them; "rigged" on a download page means only that bones exist. No armature on a biped:
+   `rig_model` (with a donor if you have one). Not a biped (an animal, a slime, a car): animate
+   in code; the rig check refuses it for free, and that refusal is the answer about the model.
+
+3. **Audit the clips.** `audit_clips` with `expected` set to every clip name your code plays.
+   It passes when each expected name is found, nothing is frozen in one pose, and root motion is
+   known before the game moves the object itself. A sliding foot means the clip's speed and the move speed
+   disagree. Nearest-bone weights from `rig_model` are crude: watch it move.
+
+4. **Measure, then look.** Numbers cannot show a model upside down, inside out or facing
+   backwards; a picture cannot show unweighted vertices. Each covers the other's blind spot:
+   the findings, then `render_model`'s contact sheet.
+
+5. **Optimize to the device, after rigging.** `optimize_model` with the shape class and the ship
+   device. Rig first, then decimate (one pipeline that decimated first left the rigger 6% of the
+   vertices), and decimate before welding (welding first tears UV seams). Budgets, crowds and textures:
+   [budgets.md](budgets.md).
+
+6. **Finalize, and read the proof.** `finalize_model` with `keep_clips` naming exactly the clips
+   the code plays. Its front view and contact sheet show whether the model is visible from every
+   side, the right way up, in its colours. A success message is not a fix; the proof picture is.
+
+7. **LOD where it pays.** `lod_model` pays for anything many and small (crowds, debris, trees);
+   a hero the camera frames close rarely needs it.
+
+8. **Textures and the scene.** `texture_stats` with the ship device measures each model against
+   the phone's limits (2048 px a side; JPEG normal maps band; unused maps cost memory). Then, wired in, `inspect_scene` at the
+   busiest state for draw calls and texture memory, and a `screenshot` at the game's camera.
+
+9. **Repair beats regeneration** on price and on keeping what was approved. Regenerating pays
+   when the mesh is wrong, from a better concept image ([models](models.md)).
+
+10. **Report what you could not fix.** A limb that still drags, a clip replaced with code motion,
+    a model checked by eye only, a scene over budget: each goes in the hand-back by name.
+
+## Worked example
+
+A generated `golem.glb` is the boss of a phone game:
+1. `inspect_model`: `golem.glb — 2 finding(s): material 'Stone' has alpha 0 …; mesh 'Body' has
+   11% of its vertices unweighted.` Facts: 38,210 vertices, 24 bones, 3 clips, 2.10 MB.
+2. The 11% is the left arm, fused to the torso at generation; the concept had the arms against
+   the body. A new concept with the arms held away; the golem is regenerated (145 credits, said
+   and confirmed).
+3. `audit_clips` with `expected: ["idle","walk","slam"]`: `slam` missing, the file has `attack`.
+   The code plays `attack` now.
+4. `optimize_model` with `budget: "character"`, `device: "phone"`: 98K to 6K triangles.
+5. `finalize_model` with `keep_clips: ["idle","walk","attack"]`: the alpha finding repaired, 2 unused
+   clips dropped, 2.1 MB to 0.6 MB; the contact sheet shows it lit from every side.
+6. `texture_stats`: one 4096 px map, over the phone's 2048; resized. `inspect_scene` in the arena:
+   41 draw calls.
+7. Hand-back: "The first golem had a fused arm and was regenerated once; its slam uses the file's
+   attack clip."
+
+## Common mistakes
+
+- Trusting "rigged": bones can exist with no clip that moves them.
+- Reading `-1` as zero: an unmeasured weight fraction looks like a perfectly bound mesh.
+- Claiming a fix from a success message without the proof render.
+- Wiring the model in before the bench: all rework when the model is wrong.
+- A clip name typed from memory (`hurt` against `hit`): it loads and never plays.
+- Judging a car as broken because it is wider than tall: facts are reported, not verdicts.

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

@@ -0,0 +1,48 @@
+# Device budgets
+
+Detail for steps 5 to 8 of [bench](bench.md). Phone numbers are what our 3D games drew on an
+iPhone 11 class phone; desktop is four times that, an estimate nobody has profiled yet.
+
+## Triangles per model
+
+`optimize_model` decimates to these by the class you name (`budget`) and the `device`.
+
+| Class (`budget`) | What | Shipped on phones | Phone | Desktop |
+|---|---|---|---|---|
+| `food` | pickups, food, small loot | 800–1,500 | 1,500 | 6,000 |
+| `prop` | crates, barrels, small furniture | 1,500–2,500; small textures shattered below | 2,500 | 10,000 |
+| `thin_walled` | cups, bowls, rims, frames | 4,000–7,000; tore at 1,500–2,500 | 7,000 | 28,000 |
+| `set_piece` | stalls, buildings, backdrops | 6,000–9,000 | 9,000 | 36,000 |
+| `character` | anything rigged | 4,500–6,000 | 6,000 | 24,000 |
+
+A whole phone scene shipped at about 255K triangles; generation returns about 100K per model.
+
+The same table drives quality levels: `npx @funpixel/tools optimize optimize-mesh <glb> --levels
+phone,desktop,high --class <class>` (or `optimize_asset` with `levels` in the Studio) cuts all
+three from one source at ×1, ×4 and ×16 these phone numbers, so a desktop is not handed the phone
+cut. Detail and measured results: the [models](models.md) skill, its `references/levels.md`.
+
+## Crowds and distance
+
+- Many copies of one model: one instanced mesh per kind, one draw call. A skinned mesh cannot be
+  instanced in three.js; a crowd of rigged units either bakes its clips to a vertex-animation
+  texture or keeps a handful of animated leaders.
+- `lod_model` for anything drawn small and often. One of our crowd games drew its fodder as a
+  vertex-coloured level of about 400 triangles once a unit was under about 36 px on screen, which
+  cut its peak from 3.48M to 2.45M triangles a frame. Under about 30 px a clip cannot be seen, so
+  the far level can stay static.
+- Switch levels by on-screen size, not distance: one distance is 20 px on a phone, 60 on a desktop.
+
+## Textures
+
+- `texture_stats` with the ship device: phone at most 2048 px a side, desktop 4096; power of two;
+  no JPEG normal maps; nothing unused.
+- Size a texture to the pixels the model covers. Our football game's generated heads came back
+  at 4096 px and shipped at 512 px WebP, 71–260 KB each, twelve heads in 1.35 MB.
+
+## The scene
+
+`inspect_scene` (or `npx @funpixel/tools scene`) at the busiest named state. Draw calls should
+grow with the kinds of thing on screen, not the count of them; a count that grows with the crowd
+means a material or a mesh per copy (share them, or instance). Over budget: report it with the fix; cutting the look is the person's call, since pooling,
+instancing and atlases usually buy the frames back first.

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

@@ -0,0 +1,67 @@
+# The character library (3D)
+
+Rigged characters that already move, on one humanoid rig with one set of clip names. When one
+fits, it replaces a paid, slow generation and a rig run; when none does, generate your own (the
+steps in SKILL.md) — the library is an option on the shelf, not a rule.
+
+## What is on the shelf
+
+`list_characters` with `medium: "3d"` (free): `adventurer-3d`, `robot-3d`, `goblin-3d`, each a
+biped with these clips, measured on the bench when it was made:
+
+- from the rig run: `idle`, `walk`, `run`, `jump`, `attack`, `hit`, `death`, `wave`
+- authored on the same rig from a checked spec: `nod`, `hop`, `flinch`, `celebrate`
+
+`walk` and `run` are in place and carry `ground_speed_mps`: move the body at that speed (or set
+the action's `timeScale` to speed / ground speed) and the feet do not skate.
+
+## Using one
+
+- `get_character` (free; `npx @funpixel/tools character get robot-3d`) copies `model.glb`,
+  `clips.json`, `turntable.png` and the concept picture into `public/assets/characters/<id>/`.
+  The GLB is meshopt-compressed with plain textures: `GLTFLoader` with the meshopt decoder reads
+  it, no KTX2 transcoder needed.
+- The scaffold's `src/character.ts` (Three) loads it with an `AnimationMixer`: `play(name)`
+  cross-fades, one-shots play once and hold, `rate()` follows speed, `update(dt)` every frame.
+  `src/characters.ts` picks idle, walk or run from speed inside tuned ranges.
+- One-shots end where they start, on the idle stance, so any clip blends back to idle.
+
+## Your look, the same rig
+
+`restyle_character` (`npx @funpixel/tools character restyle robot-3d "a rusty scrap robot"
+--game-id <id>`) is `retexture_model` on the master: four sides repainted, projected onto its
+textures; the rig and every clip are kept, and the job is refused if a clip went missing. `palette`
+pins up to 8 colours. It changes the paint, not the shape: a knight is not a restyled robot.
+
+## Where it is weak
+
+- Humanoid bipeds only. A quadruped or a bird is a static mesh animated in code (SKILL.md step 1).
+- Three bodies, one proportion each: a very tall or very squat hero needs its own model.
+- The rig run's clips are generic. `author_motion` adds a wave, nod, hop, strike, flinch or
+  celebrate to any humanoid rig from a few dials; `retarget_clips` carries a library
+  character's clips onto your own rig (feet not locked: `audit_clips` it). A signature move (a
+  spell, a dance) is still made per game.
+
+## When the game poses its own skeleton
+
+A three.js horror game (29 Sep 2026) posed a code skeleton from its sim every frame, and
+its enemies lose limbs, so neither the library nor an auto-rig fit: their bones carry their own
+names, rolls and rest rotations, and none splits a body for severing. What it did instead, run in
+local Blender:
+
+- Bones built at joint positions read off an orthographic render, every rest rotation the
+  identity, so `bone.rotation.x = a` means what the old code joints meant.
+- Weights by capsule distance to each bone with a short blend into the neighbours; the bench's
+  own `fit_rig` notes that bone heat gives up on generated meshes.
+- A skin rather than rigid parts per bone: rigid parts open gaps at the hip and shoulder the moment
+  a joint bends.
+- Severing without losing the skin: the mesh cut on planes at shoulders, elbows, hips and knees,
+  each piece its own `SkinnedMesh` on the one skeleton, each opening capped with its own material.
+  Weights are a function of position only, so both sides of a cut match and the body bends as one
+  until `detach()` hides a piece and bakes its current pose into a static mesh for the debris.
+- A decoration generated once (a coral crust) and instanced on six bones, reshaped to hug each
+  limb, with its own material so the game can light it on its own.
+
+A trap it met: the `death` clip started standing, so a crawling enemy cross-faded upright and out
+of the shot when stomped. A death that starts from the crawl's pose fixed it: a clip has to start
+where the state that plays it leaves the body.

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

@@ -0,0 +1,47 @@
+# The concept image a model is built from
+
+Image-to-3D follows the picture it is given; text-to-3D invents its own design and drifts from the
+game's 2D art. What the picture needs, from our runs and Scenario's 3D skills (A-pose before a rig):
+
+- One subject, whole from top to bottom with a margin.
+- A straight-on front view, or the side the camera sees: a crowd seen from behind is modelled
+  from behind.
+- A plain light background and flat, even light; no base, no scenery, no text.
+- The game's frozen style words, so the model matches the sprites and the key art.
+
+For a character headed for a rig:
+
+- A-pose: arms held 30 to 45 degrees away from the body, legs apart, hands open and empty.
+- Fitted clothing, nothing cut off at the edges of the frame.
+- Bulky or long-coated figures fuse their limbs at generation and the rig fails.
+- The auto-rig skins anything held to the body: in our cast runs a hoplite's shield crumpled and
+  a minotaur's axe warped in the walk. Weapons, shields, trays and bags are generated as separate
+  static models and attached to the hand bone.
+- Long skirts, aprons and capes are skinned to the legs and arms and tear in the walk. Keep that
+  character static, or make the cloth a separate piece.
+
+For a prop (a building, a tree, a vehicle, a rock), the generators give it a face and arms unless
+told twice: "not a character, no face" was ignored three times in three in one run (a mill, a tree
+and an arch came back with faces). This held every time after: "An inanimate object only: NO face,
+NO eyes, NO arms, NO character anywhere."
+
+Pass the image's URL to `generate_3d_model` as `image_url`. Calling fal's Hunyuan 3D v3.1 pro
+yourself: a `face_count` below 40,000 is refused (422); cut the mesh down afterwards with
+`funtools optimize optimize-mesh` instead.
+
+## When the back matters: more views
+
+One picture leaves the back to the generator, and it invents one: a character's air tank came
+back as a backpack, a scarf as hair. Draw the back (and a side when it differs) in the same style
+and pass them with the front: `view_asset_ids: { back, left, right }` (images your jobs made) next
+to `image_asset_id` or `image_url`. The model is built from every view; the price does not change.
+
+## After it is made (optional)
+
+Image-to-3D can still drift from the picture: a cape dropped, a colour shifted, a horn on the
+wrong side. Render views headlessly (`npx @funpixel/tools model --local render hero.glb` on your own
+Blender, free; or the hosted `model render`), then `npx @funpixel/tools judge identity hero.glb
+--concept concept.png`: one seat on your own agent grades each view against the concept on
+silhouette, palette, key features and proportions and names the worst view per trait. Major drift
+fails; a part the angle hides is unseen, not lost. `judge report` reads it back. In our run a
+knight's own turntable held all four traits and another character's failed three.

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

@@ -0,0 +1,31 @@
+# Blender assets and engine targets
+
+Blender produces the world and model assets; the engine runs the game. Keep the gameplay
+contract, style rules, asset provenance and test criteria shared, with engine-specific import,
+input, measurement and export adapters.
+
+The shipped GDK initializes Pixi and Three.js projects. A Three.js level can use the local
+Blender bench or the hosted level tool, then load the resulting GLB and bind colliders/markers
+to game logic. Walk the undressed blockout before adding detail. Recheck the optimized model's
+scale, axis, material, animation and collision in the engine. A Blender turntable alone does
+not prove the game's room is navigable or that its phone controls work.
+
+For a requested Unity project, state that Unity is an assessment target, not a supported
+funtools scaffold or publish path. Reuse portable GLB, PNG and audio through a verified importer;
+a GLB is not natively imported with identical materials, animation or collider data, so test it.
+Choose and record the project's importer. Test metres, orientation, animation, colliders and
+marker semantics in a small scene. The hosted bench runs
+fixed authoring and inspection verbs only, never caller-supplied Python (a security boundary).
+
+A Unity Web export includes loader/runtime code, wasm and scene/data files. It needs its own
+build adapter, serving/compression checks and a state/input bridge for the GDK verifier.
+Native exports need their own input, testing and distribution path. A Vite
+build does not stand in for those checks, and a model import does not prove full engine support. There is no
+Unity init target or Unity checker command yet.
+
+One way to assess it: build one complete playable chamber using the same asset packet in Three.js
+and the Unity spike. Keep measured startup, memory/frame timing, input, win/reset and export
+results beside the build revision. Classify each path as tested, failed or not observed; add
+the engine to supported targets only after the end-to-end evidence exists.
+
+Export structure reference: [Unity manual](https://docs.unity3d.com/6000.0/Documentation/Manual/webgl-building.html).