name: asset-pipeline
description: Generate game-ready 3D assets for World of ClaudeCraft with the AI asset pipeline (Tripo API + optional gpt-image-2). Use when asked to create or generate game assets, a new weapon model, a prop, a creature or mob model, a player-class skin, or any 3D model or texture for the game. Drives scripts/asset_pipeline/pipeline.mjs through the full loop: generate, review the rendered previews, fix orientation, apply the registry wiring, run the guard tests, and finish the manual follow-ups the pipeline cannot judge.
user-invocable: true
Asset pipeline: generate, review, integrate
Full reference: scripts/asset_pipeline/CLAUDE.md. This is the operational loop.
0. Prerequisites
TRIPO_API_KEY in the repo-root .env (gitignored). OPENAI_API_KEY optional (better
concept images, skin --prompt repaints). Never commit .env or keys.- Confirm credits before spending:
node scripts/asset_pipeline/pipeline.mjs balance.
A P1 image-to-model run is ~40 to 50 credits; rig 25; retarget 10 per animation.
1. Pick the lane
| Ask | Lane | Command core |
|---|
| Held weapon (sword, axe, staff, ...) | weapon | weapon --name <key_with_family> --prompt "..." |
| World object / building / scenery | prop | prop --name <key> --height <units> --prompt "..." [--building] |
| Mob / NPC / animated character | creature | creature --name <key> --prompt "..." |
| Player-class skin (texture swap) | skin | skin --class <cls> --suffix <x> --tripo --prompt "..." |
| League-style themed CHARACTER skin | skinmodel | skinmodel --class <cls> --theme "pool party" --name <key> |
| Free rig of a raw mesh (KayKit skeleton) | rig-manual | rig-manual --raw <job>/raw.glb --name <key> |
skinmodel is the flagship: it renders the REAL base class model, has gpt-image-2 redesign
that exact character around the theme (same identity, chibi proportions), builds it with
Tripo's best model (v3.1 + smart_low_poly), retargets the FULL KayKit clip vocabulary
in-place (so clips: kaykit([...]) drives it unchanged), and injects calibrated
handslot.r/.l bones (pose transplanted from the knight reference) so it holds weapons
through the game's own attach path. Review preview/held_attack.png to see it swing a sword.
Weapon keys MUST contain a family token (sword, dagger, staff, hammer, axe, halberd, spear,
scythe, wand) or the tests/held_weapon_models.test.ts contract fails. For skins,
--tripo --prompt "..." is the RECOMMENDED mode (real re-texturing); --recolor is the
cheap deterministic fallback, and a bare --prompt repaint needs OPENAI_API_KEY
(mode details: scripts/asset_pipeline/CLAUDE.md).
2. Generate, then ALWAYS review the previews
Run the lane command WITHOUT --apply first. Then Read (the Read tool, they are images) the
preview PNGs under tmp/asset_pipeline/<job>/preview/: front.png, right.png, back.png,
left.png, hero.png, plus clip_<Name>.png per animation for creatures. Check:
- Weapon: blade/tip up (head up for axe/hammer/staff), looks like the request; the preview
dir carries
held_hero/right/attack.png (knight) AND held_<model>_{hero,right,attack}.png
for ALL 7 class bodies with mid-attack frames: a weapon must hold correctly on every
character. In the live viewer (library --serve) use the "held by" dropdown to watch any
character (including generated skinmodel bodies) swing it.
- Prop: upright, front facing the camera in
front.png.
- Creature: every clip frame posed (a T-pose clip frame means a broken retarget); for
non-biped rigs the walk clip is reused for Idle/Run/Attack/Death, judge if that reads OK.
3. Fix by resuming the job (paid stages never re-run)
- Weapon upside down: rerun the same command with
--flip --job <id>.
- Prop facing the wrong way: rerun with
--rotate-y <deg> --job <id>.
- Crash or timeout: rerun with
--job <id> (the job.json ledger skips finished steps).
- Force specific steps to re-run after a parameter change:
--redo <step1,step2> --job <id>
(e.g. --redo retarget,assemble); cleared paid steps re-pay, so prefer the targeted flags.
- Wrong shape entirely: new run with a sharper
--prompt or a --image concept
(T-pose reference for creatures). This is a new paid generation; check balance.
status [--job id] lists jobs; validate / inspect / inplace-check re-check a GLB.- Lane and viewer detail beyond this loop (the
library viewer and --serve live 3D
inspector, skin --tripo real re-texturing vs the --recolor filter, skinset whole
roster sets and their SKINS/SKIN_COUNTS lockstep) lives in the full reference,
scripts/asset_pipeline/CLAUDE.md; read the matching section there before running those
lanes. One rule worth repeating: skins are texture swaps on the SAME rig; a radically
new body silhouette is the cosmetic-body path (SkinCatalog union change, not automated
by the skin lanes).
3b. QA gate (mandatory before apply)
node scripts/asset_pipeline/pipeline.mjs qa --job <id>
Lane-aware structural re-verification (rig + required clips, grip convention + HUD icon +
held-on-all-7-characters renders for weapons, handslots + KayKit vocabulary for skinmodels,
preview coverage) plus the REAL itemized cost: each recorded Tripo task is priced from the
API's own credits_consumed (1 credit = $0.01) and gpt-image-2 usage at token rates.
PASS/WARN/FAIL scorecard; qa.json in the job dir; exits 1 on FAIL (fix with --redo or a
regenerate before integrating). ALWAYS report the printed TOTAL cost per asset to the user.
4. Apply, guard tests, manifest
Rerun with --apply (still --job <id> so nothing regenerates). Then:
- weapon:
npx vitest run tests/held_weapon_models.test.ts
- skin:
npx vitest run tests/skin_event.test.ts
- creature/prop: place the printed snippet (step 5), then
npx tsc --noEmit
- All lanes:
node scripts/build_media_manifest.mjs generate (auto in npm run build; dev
needs no regen). Never hand-edit src/render/assets/manifest.generated.ts.
- CREDITS.md was auto-appended by
--apply; npm run asset:budget is advisory.
5. Manual follow-ups per lane (the pipeline will not do these)
- weapon: place the printed ItemDef snippet in
src/sim/content/items.ts (or map existing
item ids via --items); real vanilla-style stats are your judgment.
- prop: add the printed
PROP_ASSET_DEFS entry (src/render/props.ts) and place it, either
ZonePropsDef in src/sim/content/zone*.ts with a collider matched to the visuals
(src/sim/colliders.ts), or the GROUND_OBJECTS interactable lane (no collision).
- creature: add the printed VisualDef to
VISUALS and wire the mob template in MOB_KEYS
(src/render/characters/manifest.ts); set the real world-unit height and tint.
- New player-facing entities also need:
src/ui/world_entity_i18n.ts name entries and wiki
regen (npm run wiki:content, npm run wiki:stills for models). Every new ITEM id also
owes committed WebP art (tests/item_art_consistency.test.ts) in the same change, and a
wordy English name owes its M16 non-Latin fills too (root CLAUDE.md i18n bullet);
"English only at PR tier" does not cover those two.
- Never extend
SkinCatalog (src/sim/types.ts): it is a closed sim/wire union. Class
variants go through the skin lane; new bodies are mobs/NPCs.
- Verify in game:
npm run dev, screenshot the asset in place.
6. Commit
Conventional Commits with a scope, e.g. feat(assets): add emberfang sword weapon variant.
Commit the GLB/texture/icon under public/, the registry edits, CREDITS.md, and your
snippet placements. Never commit tmp/asset_pipeline/ artifacts, .env, or keys.
