@funpixel/tools 0.0.0-stage → 0.1.1

package/plugins/codex/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, in one game's third session), 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 (one game 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/codex/skills/fp-playtest/agents/openai.yaml

@@ -0,0 +1,12 @@
+interface:
+  display_name: "fp-playtest"
+  short_description: "Playtest the Funpixel game in this folder between creator rounds (a long blind phone session, the calibrated critic pane"
+policy:
+  allow_implicit_invocation: false
+dependencies:
+  tools:
+    - type: "mcp"
+      value: "funpixel"
+      description: "Funpixel MCP (generation, build, probe, publish)"
+      transport: "streamable_http"
+      url: "https://api.funpixel.ai/mcp"

package/plugins/codex/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/codex/skills/fp-publish/agents/openai.yaml

@@ -0,0 +1,12 @@
+interface:
+  display_name: "fp-publish"
+  short_description: "Publish the Funpixel game in this folder as a draft, after a fresh passing verify and filed feedback."
+policy:
+  allow_implicit_invocation: false
+dependencies:
+  tools:
+    - type: "mcp"
+      value: "funpixel"
+      description: "Funpixel MCP (generation, build, probe, publish)"
+      transport: "streamable_http"
+      url: "https://api.funpixel.ai/mcp"

package/plugins/codex/skills/fp-qa-lead/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: fp-qa-lead
+description: Use when asked to act as the Funpixel qa-lead, or assigned that role by the Funpixel studio workflow.
+---
+
+You are the QA lead for a browser game built on Funpixel. You decide what must be proven, get it
+proven with the tools, and sign off on evidence. You do not fix bugs; you hand the builder a
+precise failing case.
+
+## The evidence each kind of change needs
+
+| Change | Evidence | Blocking |
+|---|---|---|
+| Rules and logic | a unit test on `src/sim` (skill `funpixel-game-logic`) | yes |
+| A mechanic the player drives | a `funpixel.json` check through the real key or pointer | yes |
+| The start flow | the front door: pressing `[data-fpx-start]` reaches the play screen | yes |
+| Sound | the audio context runs after a real input; the core verb's cue plays once | yes |
+| Look and feel | screenshots and a review (the `critic` agent) | no |
+| Layout on phones | screenshots at a small and a large phone size | no |
+
+When a change fits two rows, the stricter row's evidence covers both. Rewrite a subjective promise ("the jump
+feels snappy") as two or three measurable ones ("input to lift-off within one frame; apex after
+0.35 s") before work starts, and flag what cannot be measured.
+
+## How you work
+
+1. Read the design note and `funpixel.json`: list each promised behaviour and the check that
+   proves it. Missing checks are the first gap.
+2. Run `npm run build && npx @funpixel/tools verify` (or `probe`). Read `verify.json`.
+3. Classify each result: pass; fail (with the check and the reason); not observed. Not observed is
+   not a pass: it means a manual check is needed or a hook is missing (counting it as a pass once
+   turned 13 of 100 corpus games green on the platform's own probe).
+4. The idle run `check` records (`.funtools/idle.json`: no input after Play, time alive, deaths,
+   how it ended) shows whether the game kills a player who is still reading the screen; a death
+   under the genre's floor is worth a finding.
+5. Severity: S1 crash, unreachable play, no sound where sound is promised, broken save; S2 a mechanic broken or a control
+   dead on one input type; S3 cosmetic or an edge case; S4 polish.
+
+## Verdict
+
+Begin with one line: `QA: APPROVED`, `QA: APPROVED WITH CONDITIONS` or `QA: NOT APPROVED`, then the
+table of promises with pass, fail or not observed, and for each failure a reproduction (the check,
+the input, the observed state). Any open S1 or S2 means not approved.
+
+## You do not
+
+- Fix bugs or change the design.
+- Approve a failed or unmeasured check because time is short; say what is missing instead.
+- Invent test cases the design does not promise; ask for the promise first.
+
+Credit: adapted from Claude Code Game Studios' qa-lead and qa-tester (MIT, © 2026 Donchitos); see
+`THIRD_PARTY_NOTICES.md`.
+
+
+## Codex adapter
+Read [the Codex workflow](references/codex.md). Its review envelope replaces the critic's final output format in this host.

package/plugins/codex/skills/fp-qa-lead/agents/openai.yaml

@@ -0,0 +1,12 @@
+interface:
+  display_name: "fp-qa-lead"
+  short_description: "asked to act as the Funpixel qa-lead, or assigned that role by the Funpixel studio workflow."
+policy:
+  allow_implicit_invocation: false
+dependencies:
+  tools:
+    - type: "mcp"
+      value: "funpixel"
+      description: "Funpixel MCP (generation, build, probe, publish)"
+      transport: "streamable_http"
+      url: "https://api.funpixel.ai/mcp"

package/plugins/codex/skills/fp-qa-lead/references/codex.md

@@ -0,0 +1,54 @@
+# Funpixel in Codex
+
+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 package. Pick the roles the task
+needs; the full panel fits a requested complete-game review, not every asset or code edit.
+
+The blind player and critic workflow works through separate agents with fresh context. A seat
+that inherits the builder's conversation, or one agent playing four critics, scores what it was
+told rather than what it sees (briefed seats scored 0.2 above blind ones on the same frames), so
+give each agent its role skill and only the evidence that role permits. The player reads the
+running game through funtools play, not its source. Critics see captures and the permitted
+description, AD rules, screen measurements and their own previous verdict; another seat's scores
+or the builder's code pull them toward it.
+
+Run each critic seat separately, and let all four finish before handing back: a seat left running
+in the background answered after one session had ended (one game's third session). Codex's SubagentStop
+hook records their final messages, including asynchronous completions. If the host cannot
+provide isolated agents or trusted hooks, report that acceptance step as unverified. The gate
+cannot tell a verdict file the builder wrote from a seat's, so the files are the seats' alone. Role skills express access rules; they do not implement a host permission
+sandbox.
+
+## Review identity
+
+After build, verify, blind play and the full capture matrix, prepare an evidence packet. Take
+the source fingerprint from the current `verify.json` and SHA-256 of the exact bytes of
+`.funtools/capture/index.json`. Pass these two strings to each critic with its frames; the
+critic takes them as given, since reading source would unblind it. The receipts are tied to
+those two strings, so an edit or recapture before all seats finish makes them stale: that needs a
+new packet and a fresh review.
+
+For `$fp-critic` in Codex only, wrap the role's surface verdicts in one JSON object as the entire
+final message (no Markdown fences or trailing prose):
+
+```json
+{"kind":"funpixel-critic","fingerprint":"<provided source fingerprint>","capture_digest":"<provided capture index SHA-256>","surfaces":["<surface verdict objects from the critic rubric>"]}
+```
+
+`surfaces` contains actual objects, with at least a `phone WIDTHxHEIGHT` and a
+`desktop WIDTHxHEIGHT` surface. Use the same persona on every surface and score all seven axes
+plus overall from 1–10. Keep prior findings and new findings in those objects. The hook writes
+one receipt per agent under `.funtools/critic/`, preserving independent seat results without
+racing on a shared state file. The Stop gate ignores receipts with stale source, changed captures or
+malformed scores, and lists incomplete seats as open items. These local records are evidence for the workflow, not proof of
+human approval or a server publishing policy.
+
+## Host setup
+
+Enable the plugin, then review its hooks in `/hooks`; installation alone does not trust them.
+Use the plugin's Funpixel MCP when authenticated, otherwise the skills' funtools fallback.
+Hosted credentials may be absent; a second server inserted to work around missing authentication
+sends the person's work somewhere they did not choose. A real MCP read call is what shows the
+hosted integration works; record it as tested only after one.

package/plugins/codex/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/codex/skills/fp-smoke-build/agents/openai.yaml

@@ -0,0 +1,12 @@
+interface:
+  display_name: "fp-smoke-build"
+  short_description: "The 10-minute smoke build before any full build — one locked-art picture and one generated 3D model in a bare scene, cap"
+policy:
+  allow_implicit_invocation: false
+dependencies:
+  tools:
+    - type: "mcp"
+      value: "funpixel"
+      description: "Funpixel MCP (generation, build, probe, publish)"
+      transport: "streamable_http"
+      url: "https://api.funpixel.ai/mcp"

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

@@ -0,0 +1,59 @@
+---
+name: fp-studio
+description: Use when building or reviewing a Funpixel game in Codex and coordinating its specialist roles, blind player or critic panel.
+---
+
+# Funpixel in Codex
+
+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 package. Pick the roles the task
+needs; the full panel fits a requested complete-game review, not every asset or code edit.
+
+The blind player and critic workflow works through separate agents with fresh context. A seat
+that inherits the builder's conversation, or one agent playing four critics, scores what it was
+told rather than what it sees (briefed seats scored 0.2 above blind ones on the same frames), so
+give each agent its role skill and only the evidence that role permits. The player reads the
+running game through funtools play, not its source. Critics see captures and the permitted
+description, AD rules, screen measurements and their own previous verdict; another seat's scores
+or the builder's code pull them toward it.
+
+Run each critic seat separately, and let all four finish before handing back: a seat left running
+in the background answered after one session had ended (one game's third session). Codex's SubagentStop
+hook records their final messages, including asynchronous completions. If the host cannot
+provide isolated agents or trusted hooks, report that acceptance step as unverified. The gate
+cannot tell a verdict file the builder wrote from a seat's, so the files are the seats' alone. Role skills express access rules; they do not implement a host permission
+sandbox.
+
+## Review identity
+
+After build, verify, blind play and the full capture matrix, prepare an evidence packet. Take
+the source fingerprint from the current `verify.json` and SHA-256 of the exact bytes of
+`.funtools/capture/index.json`. Pass these two strings to each critic with its frames; the
+critic takes them as given, since reading source would unblind it. The receipts are tied to
+those two strings, so an edit or recapture before all seats finish makes them stale: that needs a
+new packet and a fresh review.
+
+For `$fp-critic` in Codex only, wrap the role's surface verdicts in one JSON object as the entire
+final message (no Markdown fences or trailing prose):
+
+```json
+{"kind":"funpixel-critic","fingerprint":"<provided source fingerprint>","capture_digest":"<provided capture index SHA-256>","surfaces":["<surface verdict objects from the critic rubric>"]}
+```
+
+`surfaces` contains actual objects, with at least a `phone WIDTHxHEIGHT` and a
+`desktop WIDTHxHEIGHT` surface. Use the same persona on every surface and score all seven axes
+plus overall from 1–10. Keep prior findings and new findings in those objects. The hook writes
+one receipt per agent under `.funtools/critic/`, preserving independent seat results without
+racing on a shared state file. The Stop gate ignores receipts with stale source, changed captures or
+malformed scores, and lists incomplete seats as open items. These local records are evidence for the workflow, not proof of
+human approval or a server publishing policy.
+
+## Host setup
+
+Enable the plugin, then review its hooks in `/hooks`; installation alone does not trust them.
+Use the plugin's Funpixel MCP when authenticated, otherwise the skills' funtools fallback.
+Hosted credentials may be absent; a second server inserted to work around missing authentication
+sends the person's work somewhere they did not choose. A real MCP read call is what shows the
+hosted integration works; record it as tested only after one.

package/plugins/codex/skills/fp-studio/agents/openai.yaml

@@ -0,0 +1,12 @@
+interface:
+  display_name: "fp-studio"
+  short_description: "building or reviewing a Funpixel game in Codex and coordinating its specialist roles, blind player or critic panel."
+policy:
+  allow_implicit_invocation: true
+dependencies:
+  tools:
+    - type: "mcp"
+      value: "funpixel"
+      description: "Funpixel MCP (generation, build, probe, publish)"
+      transport: "streamable_http"
+      url: "https://api.funpixel.ai/mcp"

package/plugins/codex/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/codex/skills/fp-verify/agents/openai.yaml

@@ -0,0 +1,12 @@
+interface:
+  display_name: "fp-verify"
+  short_description: "Build and verify the Funpixel game in this folder, fix what fails, and stop when it passes."
+policy:
+  allow_implicit_invocation: false
+dependencies:
+  tools:
+    - type: "mcp"
+      value: "funpixel"
+      description: "Funpixel MCP (generation, build, probe, publish)"
+      transport: "streamable_http"
+      url: "https://api.funpixel.ai/mcp"

package/plugins/codex/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/codex/skills/funpixel-3d/agents/openai.yaml

@@ -0,0 +1,12 @@
+interface:
+  display_name: "funpixel-3d"
+  short_description: "a 3D game needs a model or a place, or one is wrong (a character, creature, vehicle or prop; a GLB that draws black, wil"
+policy:
+  allow_implicit_invocation: true
+dependencies:
+  tools:
+    - type: "mcp"
+      value: "funpixel"
+      description: "Funpixel MCP (generation, build, probe, publish)"
+      transport: "streamable_http"
+      url: "https://api.funpixel.ai/mcp"

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