@funpixel/tools 0.0.0-stage → 0.1.0

package/plugins/robin/skills/fp-lanes/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: fp-lanes
+description: "Use when the person types /fp-lanes. Run a Funpixel game's stage as lanes at once — one brief, checkout, spend cap and merge gate per lane, a verifier that did not build it, the owner's picks before a merge."
+---
+
+You are the integrator. The lanes do the building; you plan them, launch them together, and merge
+each one only when its gate says so. Work in the game folder (the one with `funpixel.json`).
+
+1. **Plan.** `npx @funpixel/tools lanes plan` splits the stage the game is at (or `--stage <id>`,
+   or `--lanes play,look,audio`, `room-2`, `rooms`) into lanes and writes each brief under
+   `.funtools/lanes/<id>/brief.md`. Before you plan, turn each open note from the owner into a
+   decision: `npx @funpixel/tools decide --from N<n>`. The briefs it touches then quote their words.
+   A brief is capped at 12,000 characters: past it, what failed before leaves first, then the other
+   lanes' paths, the standing bar, the extra reading, why now and the look's defects, each saying how
+   many it left out; the goal, the checks and the rules never leave.
+2. **Launch them at once.** `npx @funpixel/tools lanes start --all` makes one checkout per lane and
+   prints one line per lane. Send every lane in ONE message, one Agent call each, so they run in
+   parallel: `subagent_type` `fp:lane`, prompt "Read <brief> and do exactly what it says." Never
+   build a lane's work yourself. In Claude Code a lane's write outside the paths it owns is refused
+   as it is made (you are never fenced), except its one line inside a shared list's `fp:union` block.
+3. **Watch.** `npx @funpixel/tools lanes status` shows each lane's state, spend against its cap and
+   time against its box. A lane that is stuck (over its cap, past its box, silent for two
+   checkpoints) needs the owner, not a guess. Show the lane checkpoints in the chat, each with a
+   still, and keep the GDD's `## Where we are` current.
+4. **Verify with another seat.** When a lane hands back and its gate passes, launch a verifier that
+   did not build it: Agent `fp:qa-lead`, prompt "Read .funtools/lanes/<id>/verify.md and do exactly
+   what it says." The kit refuses a verdict from the lane's own builder.
+5. **The owner picks.** A lane that put candidates to the owner (`npx @funpixel/tools pick`) waits
+   for their choice in the chat. Do not answer it for them.
+6. **Merge.** `npx @funpixel/tools lanes merge <id>` refuses until the gate, the verifier and the
+   owner's picks pass, then merges with `--no-ff`, writes the lane's section into
+   `design/MAKING.md` and removes its checkout. Tell the other running lanes to take the landed work
+   first (`npx @funpixel/tools lanes sync <id>`).
+7. **Hand back.** `npx @funpixel/tools lanes report` is the lanes' making-of: what each tried, cost
+   and took, and what is still weak. Then `npx @funpixel/tools flow` names the next round.
+
+Other hosts run the same briefs. Codex: one `codex exec` per lane in its checkout with the same
+line. Cursor: one background agent per checkout. The kit only writes briefs and judges gates.

package/plugins/robin/skills/fp-mobile-qa/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: fp-mobile-qa
+description: "Use when the person types /fp-mobile-qa. Judge whether the Funpixel game in this folder is native to a phone (touch-native controls, the play area's share of the screen, thumb reach, chrome during play, safe areas, orientation, first touch) from real phone evidence, and get its findings ranked with a frame and a number each. Applies nothing."
+---
+
+Look at the game in this folder (the one with `funpixel.json`) the way a phone player meets it. The
+review is a mirror: it changes nothing, and its findings are for the person to pick from.
+
+1. Say in one line what runs: free measurements here (a few minutes; every view captured at both
+   sizes, the phone screens audited, a WebKit phone shot, key parity at phone size, five windows
+   swept with `look --fit` from wide-short desktops to the phone either way), real Mobile
+   Safari when this Mac has baguette (about a minute per orientation), then one Mobile QA seat as an
+   agent on the person's own setup.
+2. On a Mac with baguette (`npx @funpixel/tools doctor` says), build and add `--phone`: it runs
+   `funtools phone` in portrait and landscape first, so the seat sees real Mobile Safari (its bars,
+   the notch, iOS taps). It boots its own simulator and shuts it down. Without it, the seat judges
+   WebKit and Chromium at phone size and says iOS was not observed.
+3. Run `npx @funpixel/tools mobile-qa` (with `--phone` when chosen). It prints the seat's prompt file.
+4. Run the `mobile-qa` agent in the foreground as a fresh agent given only that file's contents; it
+   writes its answer beside the prompt. A seat that sees this conversation or the code judges the
+   intent instead of the phone.
+5. Run `npx @funpixel/tools mobile-qa report` and hand back its findings in order, each with its
+   frame and number, and the phone-native score. What the seat judges and why: skill
+   `funpixel-verify`, `references/mobile-qa.md`.
+6. Ask which to take on. When the phone is the game's primary platform, `"platform": "phone"` in
+   `funpixel.json` metadata says so, and a key no touch reaches ranks high.
+
+`/fp:playtest` runs the same seat with its other seats.

package/plugins/robin/skills/fp-new/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: fp-new
+description: "Use when the person types /fp-new. Start a new Funpixel game from an idea, the way our best games were made: brief back, the first look and a nice first playable the owner steers, the whole game planned around it and locked, then built round after round against the plan's target frames until the owner plays it and says yes."
+---
+
+Start a new Funpixel game from the idea the person gave with this command; with nothing given, ask
+what game they want in a sentence. You are their copilot: you plan the game with them in this chat,
+then build it with them round after round. Ask little and decide well: "you choose" is always an
+answer, and you say why. The path is the brief's (each step's why
+and tools: `funpixel-gdd`'s `references/the-path.md`). The locked plan is the job; how you build
+it is yours.
+
+1. **Brief back, on one screen, with one question.** Turn their sentence into a short brief and
+   show it once, first thing in the reply: title, kind (genre and camera), the verb, the world, the
+   length, how failing works, the look, phone and desktop, each in a line. Under it, your calls in
+   one line each (genre, engine, title, and anything you found on the way). Then the one question:
+   is the brief right? Their yes or their edit starts the work. Everything else is yours to decide
+   and say, never a second question: what they asked for outranks a standing request it
+   contradicts (a one-minute game stays one minute); a folder already there under the game's name
+   is left as it is and the game starts beside it; a file that might be reused is kept as the
+   fallback and a new one is made. A choice only they can make (the one that changes what the game
+   is) may be the question in place of "is it right", with your pick already written in.
+2. **Start.** `npx @funpixel/tools flow start <folder> --idea "<the brief in one line>" --name
+   "<title>"` (add `--framework pixi|three-world|three` when the line doesn't make it clear) creates
+   the game (it runs `npx @funpixel/tools init `, which mints the game's id when an API key is
+   set); `npm install`. If `flow start` or the first paid step says the Funpixel tools cannot be
+   reached or the key is refused, stop there and tell them in one line what to start or sign in to
+   (`npx @funpixel/tools doctor` names it): a game drawn from boxes and spheres in place of its
+   models, sounds and music is not the first playable, and is built only on their yes. Then write
+   the plan's opening from the brief before anything is drawn:
+   the pitch, the loop, the content list at the length they asked for, the look, with no template
+   line left unfilled. `npx @funpixel/tools gdd page` writes it as a page, `design/GDD.html`
+   (every later step keeps it current): show them that page, not a file path, so they read the plan
+   and decide on it while the first pictures are made. Once the game runs, show the game itself:
+   open it beside the chat where they are: your host's own browser when it has one (Cursor's, Codex's), else `npx @funpixel/tools dev --open` (the system browser, in its own tab). Do not call `create_game` as well (it mints a second, empty draft). From then on,
+   `npx @funpixel/tools flow` each turn names the owner's notes first, then the one next step.
+3. **First look, then a first playable** (the game's opening stages; `flow` names each). Make the
+   key art (the game's look in its own light, at the play framing) and the hero's reference sheet;
+   put both in the plan (`## First look`, as their paths) so they appear on its page, show them, and
+   take their words before anything 3D is paid for. Then build a first
+   playable from them, in the game itself, with real assets: the hero (rigged where it moves), the
+   place in the key art's light, the title art, a music loop, the verb's sounds. Size it by the game:
+   a short game about 1 minute (mostly the place, its look and feel, the verb once), a mid game 2 to
+   3, a long game 3 to 5 (the core loop once, a win and a loss). Judge it against the key art
+   (`score --target`, `check --front-door`) before they see it, then show it with captures and the
+   preview link. Reveal it as a moment: a 12-second clip of real play (`reel`), the game open beside
+   the chat, "try this first: …", in the game's words, never the kit's. They play it and say whether it has potential: `npx @funpixel/tools note verdict
+   prototype accept "<their words>"`; "not this" means a new key art, or dropping the idea.
+4. **Plan the whole game around it, at its real size** (skill `funpixel-gdd`), in the chat and the GDD: the
+   genre's best games beside it (what they do, what we take); pillars; the story and how deep it
+   goes; levels and the environment maps; characters and the living world; fun factors and the wow
+   moments; screens and HUD for phone and desktop; the look and its locked style; a numbers contract
+   with tests named after it; and the rest of the first look: target frames for the moments that
+   matter, the screens, the HUD over play, a frame per place. Finish with the asset list: the GDD's `## Asset script`,
+   every piece the game ships (cast, environments, props, title and HUD art, sound, music), made
+   the list with `npx @funpixel/tools assets script --write` and priced with `assets gen --dry-run`.
+   The first look's pictures are its references, never the shipped art. Ask the person the choices a studio lead decides; propose
+   the rest. Size it to the length in the brief, never smaller.
+   Lines in `~/.funpixel/owner.md` are the owner's standing requests: answer the ones that apply in
+   the plan.
+   Notes the owner writes on the plan page (a host that can mark up a page sends them with the part they
+   point at) are their words on the plan: revise `design/GDD.md` there, raise its version, run
+   `npx @funpixel/tools gdd page` so the open page comes back rewritten, and say in one line what changed.
+   Show, mark, revise, apply, as many times as they want before the lock and after it. The owner can
+   also agree to the plan a section at a time; `flow` names the sections still open, and changing an
+   agreed section's words opens it again, so say so when you do.
+   Not sure which skill or command a step needs? `npx @funpixel/tools find "<what you want to do>"`.
+5. **Lock.** `npx @funpixel/tools flow ask` readies the plan and its price; show it in the chat
+   (the GDD, its target frames, the price) and wait for their yes. Record it with their words,
+   `flow agree --by owner "<their words>"`. The lock means "good, let's build, unless I say otherwise":
+   a new direction becomes a new GDD version they lock again. Where the build later has
+   to move, write it in the plan's "Where the build moved" table, with why.
+6. **Sim first**, then **build with the assets as they land**: the rules and numbers as seeded,
+   tested code with bots (`sim`, `test`); generate every planned asset from the locked style (cast,
+   environments, props, screens, HUD art, sound, music) into `public/assets/` while you build
+   (the locked plan is the go-ahead), saying the route and cost of each paid call in one line. Out
+   of credits is a pause: say so; they top up. The slice: the player moves, one verb works, a win and a loss fire, progress
+   shows, keys and touch both work, `npx @funpixel/tools check` exits 0. Keep `dev` or `verify
+   --watch` running from the first edit.
+7. **Each round, the look-dev loop**: capture at the target moments, set each beside its target
+   (`compare --target`), fix the biggest difference, then play it on phone and desktop (`play`, `playtest`). Repeat
+   until each beat is close and you are both confident the game is good; matching the targets is the job, and only the owner relaxes one. Close the
+   round: update the GDD's `## Where we are` (each capture beside its target), show the captures in
+   the chat, then `npx @funpixel/tools flow round`; after their
+   cap of rounds (default 3), hand back and they resume with `/fp:flow`. When `flow` says the
+   whole-game look is due (after the first playable, then every few rounds), run `flow look` and
+   hand its brief to a fresh agent: it routes each defect to an owner and never vetoes.
+8. **Extend** with levels and story; fold a mid-build request into the pillars first.
+9. **Hand back** with an honest verdict: what plays now (keys and touch), how it compares with its
+   targets ("below the bar: <why>" when it is), what is out on purpose, every fallback still in the
+   game, and the next two or three steps. File `report_feedback` (skill `funpixel-feedback`).
+
+Spend is the owner's: never shrink an agreed game to save credits. Only the owner drops a game
+(when they say so in the chat: `flow drop --by owner "<their words>"`); you may recommend it, with the numbers.

package/plugins/robin/skills/fp-playtest/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: fp-playtest
+description: Use when the person types /fp-playtest. Playtest the Funpixel game in this folder between creator rounds (a long blind phone session, the calibrated critic panel, the plan-fidelity and experience seats, a head to head with the genre hit when its evidence is here, and free measurements) and get 3–4 ranked next steps with evidence. Applies nothing.
+---
+
+Playtest the game in this folder (the one with `funpixel.json`). The playtest is a mirror for the
+person: it changes nothing in the game, and its steps are suggestions they pick from.
+
+1. Say in one line what will run and how long it takes: the free measurements (2 to 4 minutes),
+   then 3 critic seats (2 with `--quick`; each re-reads the phone captures), the Mobile QA seat, the fidelity seat when the GDD has target frames, one
+   blind phone round (a ten-minute session; `--quick` plays a short one) and, when the hit's evidence
+   is on this machine, 6 head-to-head calls; then 2 experience seats (1 with `--quick`). All run as
+   agents here on the person's own setup; about 30 to 45 minutes in all. `--quick` is the fast look.
+2. If `.funtools/playtest/premise.txt` is missing, write 4 to 6 neutral sentences there: what the
+   game is and what the player does, as a store page would say it. No intentions, design notes or
+   praise; a seat told why a frame looks as it does scores it kinder.
+3. Run `npx @funpixel/tools playtest` (with `--quick` when asked; add `--phone` on a Mac with
+   baguette, so the Mobile QA seat sees real Mobile Safari in both orientations). It builds, verifies, captures
+   every view at both sizes with moments as strips, audits the phone screens, measures the HUD in
+   play and how the actors stand out from the ground, and profiles, then prints one prompt file per
+   seat. Each prompt carries those numbers as facts F1, F2, … to read before the frames (Scenario's
+   numbers first, then eyes); the report says which facts each seat cited.
+4. Run every seat now, in parallel in the foreground (a background seat answered after a session
+   had already ended, Lantern Night S3), each as a fresh agent given only the contents of its prompt
+   file: one per `seats/<name>.md`, per `versus/<name>.md` and `fidelity/fidelity.md` when printed (and `fidelity/ui.md` from step 5), each a general-purpose
+   agent (the `critic` agent's own format would override the prompt's), and the `player` agent with
+   `player.md` at phone size. The Mobile QA seat (`mobile/mobile-qa.md`, the `mobile-qa` agent: is
+   it native to a phone, `references/mobile-qa.md` in skill `funpixel-verify`) reads the blind round
+   too, so it runs in step 5. A seat that sees another seat's answer, the code or this conversation
+   drifts toward them, so each gets only its file and writes its own answer file; an answer file
+   written by anyone else is no longer a seat's verdict.
+5. Once the blind round is filed, run `npx @funpixel/tools playtest experience`: the first time, it
+   keeps the steps the blind player played as the saved route (`test/journeys/playtest-route.json`:
+   its steps, viewport and seed) and films it at the plan's timed moments, so later playtests replay
+   the same route with the same camera and compare like with like. It measures depth for free (the
+   content inventory, the pacing of real play, the come-back answer) and prints the experience seats'
+   prompts, the UI fidelity seat's when the GDD has mockups, the Mobile QA seat's with the round
+   added, the fidelity seat's again when it now has played frames, and from the second playtest on,
+   the ledger seat's (`ledger/ledger.md`: last round's blockers, judged fixed, still there or changed, and the
+   do-not-regress list, each judged held, lost or not observed). Run them the same way, each a fresh agent given only its file. What
+   they judge, and why beside the panel: skill `funpixel-verify`, `references/experience.md`.
+6. Run `npx @funpixel/tools playtest report`, then read `.funtools/playtest/<n>/report.md`. After
+   the next steps it shows the do-not-regress list (up to eight things the panel named as working, kept
+   in `.funtools/keep.json`; `playtest keep` lists it), last round's blockers with this round's verdict, and the round history
+   (`.funtools/playtest/history.json`: panel axes, the experience bar, the blind player, minutes of
+   real play, fidelity per moment and the AD lines, every round), with each drop marked. When it
+   opens with "Look at the captures first", open those frames before trusting any score: a view
+   that never reached its beat is scored as the wrong game (Held Note scored 4.9 on views stuck at
+   the opening shot, 6.55 once they reached their beats). A thing on the list that is lost is a
+   regression: the report leads with it and exits 1, the flow makes putting it back the round's first
+   step, and only the owner takes an item off (`playtest keep --drop K<n> --by owner "<their words>"`).
+   What a great playtest looks like, and
+   the review page the person read: skill `funpixel-verify`, `references/playtest.md`.
+7. Hand back the report's next steps in its order, each with its quote, frame and number, last
+   round's blockers, the round history with its drops (never leave a drop out), any staged frame
+   the played route never reached, and what ran. Ask which to take on; the playtest applies
+   nothing, so the game stays as it was until the person picks.
+8. Last, once: how did the kit do in this playtest and the rounds before it? One `report_feedback`
+   call with the kit verdict (skill `funpixel-feedback`, "The kit verdict"): what helped, what got
+   in the way or was wrong, what was missing, each naming its tool or skill, and one overall line.
+   About the kit, not the game; when the call fails, the same line goes in
+   `.funtools/kit-feedback.jsonl`.
+
+`npx @funpixel/tools playtest status` names any seat still owed. With a Funpixel API key,
+`npx @funpixel/tools playtest --hosted` runs the panel and the blind player as hosted jobs for
+credits instead, quoted first (`--yes` to spend a quote over 50).

package/plugins/robin/skills/fp-publish/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: fp-publish
+description: Use when the person types /fp-publish. Publish the Funpixel game in this folder as a draft, after a fresh passing verify and filed feedback.
+---
+
+Publishing needs a passing `verify.json` for the current files: the server refuses a missing, stale
+or failing one. So run `npm run build && npx @funpixel/tools verify` first, and fix what it names
+(skill `funpixel-verify`) until it exits 0.
+
+Then, following the `funpixel-publish` skill:
+
+1. List what will ship and check it for leaks (keys, local paths, private notes): a published game
+   is public to anyone with the link, and everything outside `.harnessignore` ships.
+2. Publish as a draft: `publish_game` when the Funpixel MCP is connected, otherwise
+   `npx @funpixel/tools publish --name "<title>"` (needs `FUNPIXEL_API_KEY`). The id in
+   `funpixel.json` makes every later publish update the same draft in place; no flag needed.
+3. Load the published URL the way a player does and confirm it renders:
+   `npx @funpixel/tools verify <play url>`. When publish printed no address, its server verify is
+   that check, so a second publish to get an address repeats it (a real Claude Code session did). A publish that
+   succeeded but does not render is its own problem: the same files give the same page, so read the
+   build rather than publishing again.
+4. File `report_feedback` (skill `funpixel-feedback`), then tell the person the draft's link and
+   that sharing it to Community is their choice in the app.

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

@@ -0,0 +1,25 @@
+---
+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.

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

@@ -0,0 +1,20 @@
+---
+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.

package/plugins/robin/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/robin/skills/funpixel-3d/references/bake-off.md

@@ -0,0 +1,48 @@
+# The model bake-off: several candidates, one judged against the master
+
+Held Note tried its hero three ways (three providers' takes of the same front picture) and picked
+from turntable sheets; Gallery Heist 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 Held Note'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/robin/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/robin/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.