@genex-ai/cli-demo 0.81.0-dev.214 → 0.84.0-dev.215

package/templates/skills/genex-game-director/SKILL.md

@@ -45,10 +45,31 @@ missing.
 
 ## 3. The design contract — DESIGN.md
 
-Before rendering code, write `DESIGN.md` at the project root from
-[references/design-contract.md](references/design-contract.md). Post a short
-summary in chat (the plan-message duties from `$genex-threejs-game-ui` fold
-into this file plus that summary). The file is the single source of truth:
+**First, the design interview — before DESIGN.md is written.** Ask the
+player 2–4 build-forking questions, batched in ONE round — use your
+structured question / ask tool if your harness has one, with answer options
+for the user. Ask only what genuinely forks the build:
+
+- the one-line pitch, confirmed or corrected ("a co-op scythe hunt in a
+  ruined cathedral — right?");
+- the solo / co-op / versus shape (it decides netcode and scope);
+- scope ambition, when the request could honestly be read small or large
+  (compact arena vs. open world);
+- any real ambiguity in the request itself.
+
+Never ask about SDKs, engines, renderers, file layout, or anything
+technical — those are your decisions. If the player is silent or has no way
+to answer, proceed on your own stated assumptions and write each one into
+DESIGN.md → Decisions as "assumed — player didn't answer"; the build never
+stalls on the interview.
+
+Then, before rendering code, write `DESIGN.md` at the project root from
+[references/design-contract.md](references/design-contract.md). The moment
+the file lands, post a 5–6 line summary of the contract in chat — pitch,
+core loop, content counts, screens, multiplayer shape, what you build
+first — and keep building immediately: the summary is information, not a
+gate (the plan-message duties from `$genex-threejs-game-ui` fold into this
+file plus that summary). The file is the single source of truth:
 sub-agents build against it, and after any long break it is how work resumes.
 Keep it current — decisions land in its log the moment they're made.
 
@@ -65,13 +86,24 @@ steps live in each owning skill — load it when its lane fires:
   outdoors → `$genex-ai-skybox`
 - `npx genex sfx "<prompt>"` — the core verb and every impact →
   `$genex-ai-sfx`
+- `npx genex music "<prompt>"` — ONE looping instrumental gameplay track
+  (~90 s default; the menu reuses it quieter; settings gets Music + SFX
+  sliders) → `$genex-ai-music`
+- `npx genex voice "<line>"` — short spoken lines: NPC barks, narrator
+  beats, tutorial VO (curated cast via `--voice`; keep lines short,
+  subtitled, skippable) → `$genex-ai-voice`
 - `npx genex image "<prompt>"` — posters, signs, sprites, decals, HUD art
-  (`--transparent` for anything laid on a surface) → `$genex-ai-image`,
+  (`--transparent` for anything laid on a surface; `--glass` for real-
+  translucency glass panels) → `$genex-ai-image`,
   `$genex-ai-hud`
-- `npx genex video "<prompt>"` — in-world screens, billboards, an animated
-  menu backdrop (`--loop` for seamless) → `$genex-ai-video`, `$genex-ai-menu`
-- `npx genex character "<prompt>"` — a custom playable humanoid (REQUIRED
-  player approvals — §7) → `$genex-ai-character`
+- `npx genex video "<prompt>"` — in-world screens and billboards (`--loop`
+  for a seamless in-world loop) → `$genex-ai-video`; the animated menu
+  backdrop is its own lane — `$genex-ai-menu`'s `--frame` flow, never `--loop`
+- `npx genex character "<prompt>"` — the game's themed character (approval
+  flow — §7) → `$genex-ai-character`
+- `npx genex creature "<desc>"` — a rigged enemy/creature in one shot
+  (biped-shaped bodies only — the creatures skill routes the rest to
+  static + procedural) → `$genex-threejs-creatures`
 - `npx genex controller character|car|drone|touch|quality` and
   `npx genex animations search "<intent>"` — ready-made, tuned movement and
   motion; never write movement physics from scratch →
@@ -89,6 +121,12 @@ variation); prefer these generators for concrete, describable, photoreal
 assets — they complement each other. Assets you didn't plan don't exist: if
 the menu has a lane this game needs, put a row in the Assets table.
 
+**No eternal `proposed`.** At every preview and publish, walk the Assets
+table and resolve every `proposed` row — promote it to `planned` (and
+enqueue it when its turn comes) or cancel it, saying which in one visible
+line ("cancelled: UI hover sfx — out of scope for v1"). A row parked at
+`proposed` across a whole session is a decision you didn't make.
+
 **Generate a core asset set by default — don't wait to be asked.** For any
 game that needs concrete objects or surfaces, decide a small core set from the
 game IDEA — and from the Content lines when there are any (locations and the
@@ -102,7 +140,9 @@ each in as it lands, with a procedural placeholder until then:
 - the **hero model** the player controls or chases (`npx genex model`),
 - one key **texture** for the ground/main surface (`--terrain` for ground),
 - a **skybox** when the scene is outdoors,
-- a **sfx** or two for the core action and its feedback.
+- a **sfx** or two for the core action and its feedback,
+- one looping **music** track for the gameplay bed (`npx genex music`,
+  ~90 s; the menu reuses it at lower volume).
 
 Skip generation only for purely abstract/geometric games. For three.js
 questions no skill covers, use the official three.js documentation
@@ -207,36 +247,59 @@ agent: you stay the director.
   enqueues. (Whoever wires the HUD after a worker finishes follows
   `$genex-ai-hud`'s handoff rule: read the produced mask/bbox JSON from disk,
   never wire from a prose summary.)
-- Do NOT spawn workers to write extra test suites or audits — one
-  verification worker at most, running the smoke checks the scaffold prompt
-  already requires.
-
-## 7. A custom playable character (Meshy) — approvals are the product
-
-Use the existing VRM + UAL character controller by default
-(`npx genex controller character`). Use `npx genex character` when the game
-needs a custom generated humanoid or an action unavailable in UAL. Before
-generating a Meshy character, discuss two or three visual directions. When the
-user names a visual reference, inspect references before writing the concept
-prompt. Recommend a neutral A-pose for characters that will be rigged.
-
-Generate concept images first and show the actual images to the user. Do not
-start Image-to-3D until the user explicitly selects a candidate. Generate
-exactly three concepts, all neutral A-pose; never use a dynamic concept pose
-or silently fall back to T-pose. Warn that held, slung, or overlapping props
-and straps can fuse into the body or obscure limbs, and recommend separate
-gameplay props. Only after the explicit choice, run
-`npx genex character preview <concept-id> --candidate <1|2|3> --user-approved`.
+- Do NOT spawn workers to write extra test suites, audits, or verification
+  passes — the per-milestone smoke pass is yours, the director's, and it is
+  ONE pass (§8; the scaffold prompt owns the ceilings).
+- If you build a module the table planned for a sub-agent inline, say why in
+  one line in chat ("built enemies inline — the arena worker was still
+  holding the only free slot"). The table is accountability, not ceremony —
+  inline can be the right call.
+
+## 7. The game's character (Meshy) — themed by default
+
+**A themed character is the DEFAULT for any game whose protagonist is
+VISIBLE** — third-person, or first-person with co-op/remote players who see
+each other. Put its row in the Assets table up front and install the
+VRM + UAL controller (`npx genex controller character`) as the instant
+placeholder. The VRM stays the FINAL character only for games with no
+themed protagonist to sell (a generic exploration toy, a faceless solo
+first-person game — say which in one line). A capsule or hand-built
+primitive standing in for a person is never a shipped state, for the local
+player or a remote one.
+
+**The default lane has ONE user stop, and it rides the concept review.**
+When the user names a visual reference, inspect references before writing
+the concept prompt. Generate exactly three concepts, all neutral A-pose;
+never use a dynamic concept pose or silently fall back to T-pose. Warn that
+held, slung, or overlapping props and straps can fuse into the body or
+obscure limbs, and recommend separate gameplay props. Show the actual
+images in the SAME beat as the game-concept keep-or-change question — one
+review, two picks. The player's pick carries the lane end to end:
+`npx genex character preview <concept-id> --candidate <1|2|3> --user-approved`,
+then finalize below. **If the player hasn't picked by the time the
+character blocks progress (or ~10 minutes), pick the strongest candidate
+yourself, say which and why in chat, and proceed** — this auto-proceed is
+owner-ratified platform policy (2026-07-23), not an agent liberty; record
+it in DESIGN.md → Decisions ("auto-picked candidate 2 — cleanest
+silhouette; player away").
 
 Meshy Image-to-3D first produces an unremeshed high-detail model. Show its
-front, back, left, and right views and report its measured face count. Preserve
-that model in R2. Before rigging, ask the user to approve a separate
-10,000-face triangle remesh. The 10k remesh—not the high-detail source—is
-rigged and animated. Keep every pre-animation generation in the selected
-neutral A-pose. Wait for that explicit approval before
+front, back, left, and right views and report its measured face count.
+Preserve that model in R2. The 10,000-face triangle remesh—not the
+high-detail source—is rigged and animated. In the default lane the remesh
+proceeds on the same authorization as the pick (say it plainly: "building
+the 10,000-face rigging copy now"):
 `npx genex character finalize <preview-id> --user-approved --approve-remesh 10000 [--animation <action-id>…]`.
-(`npx genex character "<prompt>" --direct-text` is the explicit legacy
-one-shot path, not a substitute for these approvals.)
+Keep every pre-animation generation in the selected neutral A-pose.
+
+**When the user themselves asked for a custom character** (an explicit
+custom-character request, not the game default), the ceremony is two
+separate stops and the approvals are the product: do not start Image-to-3D
+until they explicitly select a candidate, and before rigging ask them to
+approve the separate 10,000-face triangle remesh — wait for that explicit
+approval before finalize. (`npx genex character "<prompt>" --direct-text`
+is the explicit legacy one-shot path, not a substitute for these
+approvals.)
 
 Load `$genex-ai-character`, search Meshy actions first with
 `npx genex animations search "<intent>" --json`, and use returned action IDs;
@@ -248,13 +311,34 @@ Before handoff, visibly check idle, walk, run, crouch-idle, crouch-move, and
 jump — shoulders, elbows, wrists, hands, both leg cycles, and feet — and press
 every control the HUD advertises.
 
-## 8. Fresh-eyes review — before publish
-
-Take the game's current screenshots (desktop and phone sizes) and hand them,
-with DESIGN.md only, to a fresh reviewer — a sub-agent if you have one,
-otherwise re-read them yourself adversarially, looking to refute "it's done":
-untextured surfaces, a bare HUD, missing screens, Content lines not in the
-game, Assets rows never flipped to `wired`. Fix or honestly report what it
+## 8. Verification — the smoke pass's captures grow with the build
+
+The per-milestone smoke pass and its ceilings belong to the scaffold prompt
+(ONE pass per milestone, never test suites, never re-verify after cosmetic
+tweaks) — this section only defines WHAT that one pass captures once the
+relevant piece exists:
+
+- **Always:** the gameplay screenshot + the main controls responding the
+  right way (the scaffold prompt's baseline).
+- **Once the generated HUD is wired:** take the gameplay screenshot AFTER
+  taking damage once, with an enemy in frame facing the player. A full-HP
+  shot cannot show a broken meter (a painted trough hides behind a 100%
+  fill), and an enemy you never faced head-on may be looking sideways at
+  everyone.
+- **Once the menu video is wired:** watch one full loop cycle as rendered
+  (`$genex-ai-menu`'s seam check). A metadata probe can't see a seam, a
+  hidden video, or a leftover panel covering it.
+
+Judge each capture against DESIGN.md once, fix only what is visibly broken,
+and move on — the captures are eyes, not a test suite.
+
+**Fresh eyes before publish.** The pre-publish check is just the last
+milestone's pass, plus this: take the game's current screenshots (desktop
+and phone sizes) and hand them, with DESIGN.md only, to a fresh reviewer —
+a sub-agent if you have one, otherwise re-read them yourself adversarially,
+looking to refute "it's done": untextured surfaces, a bare HUD, missing
+screens, Content lines not in the game, Assets rows never flipped to
+`wired`, `proposed` rows never resolved. Fix or honestly report what it
 finds; never publish over an unacknowledged gap.
 
 ## 9. Say it straight

package/templates/skills/genex-game-director/references/design-contract.md

@@ -13,7 +13,10 @@ Rules the director enforces about this file:
   sections as decisions land and keep it current (stale is worse than short).
 - **The Modules table is the delegation contract**: one row per independent
   lane, and a row's "Owns files" set never overlaps another row's. One writer
-  per file.
+  per file. "Sub-agent when available" stays flexible — but if a
+  planned-sub-agent module gets built inline, the agent says why in one line.
+  Verification is never a module row: the milestone smoke pass belongs to the
+  director (the scaffold prompt owns its ceilings).
 - **The Assets table is the budget**: the asset list falls out of Content
   (enemies → models, an arena → a ground texture, outdoors → a skybox).
   Status flow per row: `proposed → planned → generating (id) → landed (URL) →
@@ -22,6 +25,8 @@ Rules the director enforces about this file:
   flips statuses and never enqueues. Re-rolls follow the player's notes only.
   The `Wired?` column exists because "generated but never wired in" is the
   most common way finished art gets lost — a row isn't done at `landed`.
+  And no eternal `proposed`: at every preview/publish, every `proposed` row
+  gets promoted or cancelled with one visible line — never silently parked.
 - Shrinking any Content line is a question to the player first, never a
   silent cut.
 
@@ -63,6 +68,7 @@ References: <2–3 named games> · Menu archetype: <name>
 | Concept + HUD    | image       | landed → <URL> (candidate <n>)  | n/a    |
 | <main surface>   | texture     | generating (<id>)               | —      |
 | <hero model>     | model       | planned                         | —      |
+| Background music | music       | planned (one ~90s looping track)| —      |
 | Menu still+video | image+video | blocked on concept yes → queued | —      |
 Status flow: proposed → planned → generating (id) → landed (URL) → wired.
 (Optionally note the prompt gist per row — it makes style-change re-rolls one
@@ -84,7 +90,6 @@ click (when a Play screen exists).
 | Quests & dialogue data | src/content/** | sub-agent when available | counts match Content lines |
 | Enemies/AI | src/enemies/** | sub-agent when available | roster matches Content |
 | HUD chain (style-dependent) | src/ui/** | sub-agent AFTER concept yes | all screens from Screens & UI |
-| Verification | (no source files) | one sub-agent max | smoke check notes per milestone |
 
 ## Decisions & changes
 - <date> — <one-liner per decision, including anything the player said no or

package/templates/skills/genex-game-director/references/routing-map.md

@@ -21,7 +21,9 @@ Three.js release or branch, and do not blindly copy demo architecture.
 | --- | --- |
 | shot composition, chase/side/orbit rigs, camera handoffs, projection ownership, pointer look, mouse-aimed action (shooter, FPS/first-person, sniper, turret, crosshair/reticle), mouse-look, hand-rolled steering/pan/look input signs (screen-direction contract), floating origins | `$genex-threejs-camera-direction` |
 | on-foot player movement: walk/run/jump/crouch, third-person character, slopes, stairs, moving platforms, personal VRM animation, directional locomotion, transitions, action motion | `$genex-threejs-character-controller` |
-| a custom generated playable humanoid or Meshy animation coverage beyond UAL: reference-informed A-pose concepts, explicit candidate + 10k-remesh approvals, exact action IDs, same-rig adapter | `$genex-ai-character` + `$genex-threejs-character-controller` |
+| the game's themed character — the DEFAULT whenever the protagonist is visible (third-person, or first-person with co-op/remote players); one user stop riding the concept review, owner-ratified auto-pick on silence (director §7) — or Meshy animation coverage beyond UAL: reference-informed A-pose concepts, exact action IDs, same-rig adapter | `$genex-ai-character` + `$genex-threejs-character-controller` |
+| remote player bodies in multiplayer — NEVER hand-built primitives: the themed character model in themed games, the player's `p.avatarUrl` VRM otherwise | `$genex-threejs-multiplayer` + `$genex-threejs-character-controller` |
+| the game has enemies, NPCs, or creatures — **load whenever an enemy roster exists**: rigged bipeds via `npx genex creature`, static + procedural motion for other body shapes, plus the mechanical floor every enemy owes (collider, verified facing, hit reaction, death moment) | `$genex-threejs-creatures` |
 | the player drives or flies something: cars, drones, vehicle physics, gearbox, enter/exit between character and vehicle | `$genex-threejs-vehicle-controllers` |
 | playable on phones: touch/mobile input for any game — joystick, virtual buttons, drag zones, per-genre touch recipes, rotate-device overlay — wired by default for every NEW game when a recipe fits (skip with a one-line reason) | `$genex-threejs-touch-controls` |
 | phone-survivable rendering — device tiers, DPR/shadow/post budgets, the runtime quality governor, per-tier asset rungs for generated skyboxes/textures, the Quality picker, dispose-on-swap discipline — **mandatory for every game at boot wiring** | `$genex-threejs-adaptive-quality` |
@@ -53,6 +55,7 @@ Three.js release or branch, and do not blindly copy demo architecture.
 | the 2D interface — HUD, menus, pause/win/lose screens, loaders, lobby, on-screen text and buttons, UI state flow — **mandatory for every game**, and its "Plan the UI first" gate runs right after the concept is locked | `$genex-threejs-game-ui` |
 | a cinematic menu — main menu/title/pause/victory/defeat/lobby/credits with a looping generated video backdrop behind DOM buttons | `$genex-ai-menu` |
 | a cohesive art-directed HUD — generated sprite set (matched frames, masks, icons in one style) wired with masked fills | `$genex-ai-hud` |
+| background music — the looping instrumental track under gameplay and menu (default ONE ~90 s track; Music + SFX sliders in settings) | `$genex-ai-music` |
 | the game works but feels flat, floaty, or unresponsive: input response, acceleration curves, camera shake, hit feedback, hitstop, cooldowns, difficulty ramp, fail/retry loop | `$genex-threejs-game-feel` |
 | realtime multiplayer: movement sync, a shared ball/NPC, host-run scores/enemies, shots/emotes, persistence | `$genex-threejs-multiplayer` |
 | player identity, sign-in, guests, saves/progress, per-player state, a shared persistent world, leaderboards — **mandatory for every game** | `$genex-threejs-embed-auth` |

package/templates/skills/genex-threejs-camera-direction/SKILL.md

@@ -45,7 +45,10 @@ the build plan:
 - **MANDATORY** — first-person of any kind (FPS, walking sim, horror) and any
   mouse-aimed action (third-person shooter, turret/range). Lock is on by default;
   leave it on. Shipping this unlocked is a defect, not a style choice — validation
-  fails it.
+  fails it. For first-person on the bundled controller, use the REAL mode —
+  `firstPerson: true` on `FollowCamera` (eye-height target, no zoom, no
+  collision pullback) + `setFirstPersonBody()` to hide the local body while
+  keeping its shadow — never a pinned tiny follow distance.
 - **HIGHLY RECOMMENDED** — third-person free-camera action/adventure (the default
   `genex controller character` game). On by default; leave it on. Opt out with
   `pointerLockAim: false` only for a stated reason (a cursor-heavy UI at the core

package/templates/skills/genex-threejs-character-controller/SKILL.md

@@ -316,7 +316,12 @@ they leave) — move it with the interpolator from `$genex-threejs-multiplayer`,
 and **never** create a rigid body, a `CharacterController`, or any physics for
 it. Simulating remote players' physics locally guarantees divergence — every
 client would compute a different world. Never render every remote with your
-own avatar file: players picked their looks, show them.
+own avatar file: players picked their looks, show them. And a remote player's
+body is **never hand-built primitives** (no capsule-plus-cone "person"): in a
+themed game remotes wear the SAME themed character model the local player
+uses; otherwise they wear their `p.avatarUrl` VRM. First-person games are not
+exempt — the local player may be invisible to themselves
+(`setFirstPersonBody`), but every remote is a full character on screen.
 
 - **Publish `character.netState()`** on the fixed 10–20 Hz tick (never per frame):
   `room.me.set(character.netState())`. It bundles the network-safe position, a four-number

package/templates/skills/genex-threejs-character-controller/references/wiring.md

@@ -118,8 +118,19 @@ Rules that matter:
   non-recursive) and must never include the character or vehicle meshes — the
   rays start at the character's head and would hit them every frame. The array
   is public — mutate it after level loads.
-- `minDistance` defaults to 0.02, so zooming all the way in is effectively
-  first-person; clamp with `minDistance`/`maxDistance` for your scale.
+- **First-person is a real mode, not a zoom trick**: pass
+  `firstPerson: true` (or flip the public `followCam.firstPerson` field at
+  runtime) — the camera sits AT the follow target and looks out along the
+  aim direction, wheel zoom is ignored, and collision pullback is skipped.
+  Feed the follow target the character's EYE height (~1.6–1.7 m up the
+  capsule, not the head-top orbit anchor), hide the local body with
+  `setFirstPersonBody(model, true)` (`first-person.ts` — keeps the shadow,
+  clones materials so shared remote-player materials are untouched), and
+  parent the viewmodel (held weapon/hands) to the CAMERA so it moves with
+  the view. Pointer lock stays mandatory (`$genex-threejs-camera-direction`).
+  Do NOT fake first-person by pinning a tiny follow distance — the old
+  0.02-min-distance trick leaves collision pullback and zoom live, and both
+  fight the player.
 - Feel: `smoothTime` (0.05 snappy → 0.25 cinematic, default 0.1),
   `initialDistance` (default 4), `initialAzimuthAngle` (default `Math.PI` —
   camera starts behind a +Z-facing character).

package/templates/skills/genex-threejs-creatures/SKILL.md

@@ -0,0 +1,193 @@
+---
+name: genex-threejs-creatures
+description: Build enemies and creatures that hold up in play — rigged Meshy bipeds via `npx genex creature` or static models with procedural motion, plus the mechanical floor every enemy owes the player regardless of rigging - a physics collider (no walking through bodies), verified facing, hit reactions, and a death moment. Load whenever the game has enemies, NPCs, or creatures.
+---
+
+# Genex Three.js · Creatures & Enemies
+
+An enemy the player can walk through, that faces sideways, and that dies by
+vanishing is the fastest way for a finished-looking game to feel broken. This
+skill owns the enemy-quality floor: which generation lane each creature takes,
+and the four mechanical rules that apply to ALL of them.
+
+## Choose the lane per creature — by body shape
+
+**Meshy rigs biped-shaped bodies only.** This is a measured platform limit
+(live-tested 2026-07-23), and it starts at the MODEL stage: a prompt for a
+four-legged stance comes back standing upright, and wings get no bones (they
+skin to the spine/arms and move rigidly — a wing flap is impossible through
+the rig). Route by silhouette:
+
+- **Biped-shaped** (werewolf, orc, skeleton, gargoyle, zombie, knight — two
+  legs, two arms, upright): the **rigged lane** below. Real skeleton, real
+  library animations. This is the DEFAULT for every enemy that fits it.
+- **Everything else** (true quadrupeds, serpents, swarms, fliers mid-flight,
+  blobs): the **static + procedural lane** — `npx genex model` for the body,
+  motion authored in code. Say it honestly in the Assets table:
+  `hound: static + procedural — Meshy rigs bipeds only`. Never pretend a
+  procedural creature is rigged.
+
+## The rigged lane — `npx genex creature`
+
+One shot, no approval ceremony (an enemy is production scenery, not the
+player's identity piece — the themed PLAYER character keeps its review beat,
+`$genex-ai-character`):
+
+```bash
+# 1. Find real clip ids first — never invent them:
+npx genex animations search "zombie walk" --json
+npx genex animations search "melee attack" --json
+npx genex animations search "death backward" --json
+
+# 2. One command: model → rig → bind those clips (enqueue and keep building):
+npx genex creature "hulking bone seraph, tattered wing membranes, upright stance" \
+  --animation <walk-id> --animation <attack-id> --animation <death-id> --no-wait
+```
+
+Each creature is one Assets-table row (visible spend — the usual budget
+rules). The result is a rigged GLB whose clips play on a standard
+`THREE.AnimationMixer`; Meshy limb rotations play unchanged — never apply
+post-mixer limb corrections. Prompt the body UPRIGHT and unpropped (held
+props fuse into bodies); prompt "facing the viewer" but never trust it —
+facing is verified below.
+
+### State → clip wiring (one mixer per creature)
+
+```ts
+import * as THREE from "three";
+
+interface CreatureRig {
+  root: THREE.Object3D;
+  mixer: THREE.AnimationMixer;
+  actions: Record<"walk" | "attack" | "hit" | "death", THREE.AnimationAction>;
+  current?: THREE.AnimationAction;
+}
+
+function play(rig: CreatureRig, name: keyof CreatureRig["actions"], fade = 0.18): void {
+  const next = rig.actions[name];
+  if (rig.current === next) return;
+  next.reset();
+  if (name === "attack" || name === "hit" || name === "death") {
+    next.setLoop(THREE.LoopOnce, 1);
+    next.clampWhenFinished = true; // death holds its last frame
+  }
+  if (rig.current) next.crossFadeFrom(rig.current, fade, false);
+  next.play();
+  rig.current = next;
+}
+// drive from the enemy state machine: chase → play(rig, "walk");
+// windup+strike → play(rig, "attack"); damaged → play(rig, "hit");
+// hp <= 0 → play(rig, "death") and only AFTER the clip finishes, run the
+// death VFX moment (embers/dissolve) — animation first, particles second.
+// mixer.update(dt) every frame; one mixer per creature, clips cloned per
+// instance (THREE.AnimationUtils / SkeletonUtils.clone for shared GLBs).
+```
+
+## The mechanical floor — ALL enemies, rigged or not
+
+### 1. A collider — the player never walks through a body
+
+An enemy that is only a `THREE.Group` is a ghost. Give every enemy a physics
+presence. The recipe (Rapier, matching `$genex-threejs-physics-rapier` and
+the bundled character controller):
+
+```ts
+import RAPIER from "@dimforge/rapier3d-compat";
+
+/** One kinematic capsule per enemy: the CONTROLLER collides with it (no
+ *  walk-through) but the enemy's own movement stays script-driven — AI code
+ *  keeps teleport-free authority via setNextKinematicTranslation. */
+function addEnemyCollider(world: RAPIER.World, e: { root: THREE.Object3D; halfHeight: number; radius: number }) {
+  const body = world.createRigidBody(
+    RAPIER.RigidBodyDesc.kinematicPositionBased().setTranslation(
+      e.root.position.x, e.root.position.y + e.halfHeight + e.radius, e.root.position.z,
+    ),
+  );
+  world.createCollider(RAPIER.ColliderDesc.capsule(e.halfHeight, e.radius), body);
+  return body;
+}
+// every frame AFTER the AI moves the root:
+//   body.setNextKinematicTranslation({ x, y: y + halfHeight + radius, z });
+// Size from the model's real bounding box (new THREE.Box3().setFromObject),
+// not guessed numbers. Gameplay range tests (aggro, melee reach) keep using
+// your own distance math — the collider exists so BODIES are solid.
+```
+
+If the game has no physics world at all, the minimal honest fallback is a
+controller-side overlap resolve: each frame, push the player out of each
+enemy's XZ radius (`if (dist < r) player.position.addScaledVector(away, r - dist)`).
+Solid beats elegant.
+
+### 2. Verified facing — walk in front of each enemy type once
+
+Generated models are NOT reliably authored front-toward-+Z, and a
+`lookAt`-driven enemy with a sideways-authored model walks sideways forever —
+invisible from behind-the-player camera angles, glaring head-on. Two steps:
+
+```ts
+/** Wrap the GLB so +Z is the FORWARD your code can trust: rotate the child
+ *  inside the wrapper until its face agrees, then aim only the wrapper. */
+function wrapForward(model: THREE.Object3D, yawCorrection: number): THREE.Group {
+  const wrapper = new THREE.Group();
+  model.rotation.y = yawCorrection; // 0, ±Math.PI/2, or Math.PI — per MODEL, found by looking
+  wrapper.add(model);
+  return wrapper; // enemy code does wrapper.lookAt(...) / aims the wrapper only
+}
+```
+
+The verification is human and takes ten seconds per enemy TYPE: stand in
+front of it once — it must face you. This is part of the milestone smoke
+pass once enemies exist (an enemy in frame, facing the player). Set the
+`yawCorrection` constant per model and move on.
+
+### 3. Hit reaction — damage reads on the body
+
+Rigged: the `hit` clip above. Procedural: a 100–150 ms flinch — scale pulse
+(`1 → 0.92 → 1`), a brief emissive/color flash, and a small recoil along the
+hit direction. Pair it with the HUD hit marker; a bullet that changes nothing
+on the body reads as a miss even when the numbers moved.
+
+### 4. A death moment — never blink out of existence
+
+Rigged: play `death`, hold the final frame (~0.5 s), THEN dissolve/embers and
+remove. Procedural: collapse (scale Y toward 0 with a topple rotation) into
+the same dissolve. Either way the death VFX is a `$genex-threejs-procedural-vfx`
+moment that EARNS its beat (the target dissolves and awards score) — one
+pooled burst, not a particle bath.
+
+## Procedural motion recipes (the static lane, done well)
+
+Give an unrigged body three layered motions — enough life that "static +
+procedural" is a real choice, not a downgrade: a **gait bob** (body
+`position.y += sin(t * stride) * 0.05` with a slight roll for quadrupeds), a
+**lunge stretch** (scale Z up 8% during attack windup, snap back on strike),
+and an **idle sway** (low-amplitude yaw/pitch noise so nothing stands
+morgue-still). Author them against the wrapper from rule 2 so facing math
+stays clean. `$genex-threejs-procedural-animation` has the timeline tools for
+anything staged.
+
+## Multiplayer
+
+Enemies are host-simulated shared objects (`$genex-threejs-multiplayer` —
+the host owns `room.objects` for every enemy; remotes render interpolated
+state). The collider rule applies on every client — bodies are solid locally
+even when the HOST owns the movement; clip/state changes ride the shared
+object's state field, never a per-frame broadcast.
+
+## Troubleshooting
+
+- **"Out of credits" (`insufficient_credits`)** — tell the user the facts the
+  CLI printed (balance, cost, refill), continue with a procedural-placeholder
+  enemy body, and mark the spot with
+  `// TODO(genex): regenerate when credits refill`. Do not stop the session.
+- **"Email not verified" (`email_verification_required`)** — hand over the
+  verify link the CLI printed, wait, re-run.
+- **The creature came back standing when you wanted four legs** — that is the
+  documented platform limit, not a bad roll: re-rolling the prompt will not
+  produce a rigged quadruped. Switch that creature to the static + procedural
+  lane and say so in the Assets table.
+- **Clips look wrong on the body** (arms clip the torso on a bulky model) —
+  pick a different library action id (`animations search`); never patch limbs
+  post-mixer.
+- **Every instance animates in sync** — you shared one mixer or one clip
+  instance; clone per creature (`SkeletonUtils.clone` + a fresh mixer each).

package/templates/skills/genex-threejs-game-ui/SKILL.md

@@ -27,7 +27,7 @@ in another.
 | Pause | always — opens on the Escape key | 1 — menu backdrop under a dark overlay |
 | Fail / retry | always | 1 — a *graded* variant of the menu screen |
 | Win / next | always | 1 — graded variant, warm |
-| Settings | always — every game carries the Quality picker (Auto/Low/Medium/High, `$genex-threejs-adaptive-quality`), plus whatever else it has to set | 1 |
+| Settings | always — every game carries the Quality picker (Auto/Low/Medium/High, `$genex-threejs-adaptive-quality`), and any game with generated audio carries **Music + SFX volume sliders** (persisted, applied live; music default 0.30, sfx ~0.7 — `$genex-ai-music`; a paid track with no volume control is a failure mode), plus whatever else it has to set | 1 |
 | Lobby / waiting | multiplayer only | 1 over the menu backdrop |
 | HUD | always | 2 — generated sprite HUD (`$genex-ai-hud`), enqueued at this gate for EVERY game; plain CSS is the placeholder until the sprites land, never the final HUD |
 
@@ -531,6 +531,10 @@ architecture and consume the shared style brief.
   text or padding, a lost focus ring or glow, a jagged aliased edge, or a
   border/frame that stops at the cut instead of following it — the
   technique is fine; the sloppy cut is the defect.
+- A plate shaped by `npx genex ui plate` (the frame's traced silhouette as
+  the plate's `mask-image`) is the fix for shaped backing — see
+  `$genex-ai-hud`'s silhouette-plate rule; a bare rounded rectangle behind
+  generated art is the defect below.
 - A rectangular semi-transparent plate protruding past an opaque/angular
   widget frame — a dark box floating over the scene. The frame's own art is
   the backing; a plate is only for bare-text/outline widgets and stays inside

package/templates/skills/genex-threejs-multiplayer/SKILL.md

@@ -541,7 +541,12 @@ fights (many writers). A ball on `objects` glides and has one owner. That's the
   `loadVrmClone(p.avatarUrl || "./assets/avatar.vrm")` (the vendored loader's shared-GPU clone:
   N remotes share one set of geometry/textures instead of re-parsing per player — retarget
   clips once on `loadVrmClone.base(url)` and play them on each clone's own mixer); never
-  publish avatar URLs through `me.set`. On phone tiers, animate and fully draw only the
+  publish avatar URLs through `me.set`. **A remote player's body is NEVER hand-built
+  primitives** (no capsule + cone "person" — the single most common shipped co-op defect):
+  a themed game renders remotes with the SAME themed character model the local player
+  uses; everything else renders `p.avatarUrl` VRMs. This applies with full force to
+  first-person games — the local player may be invisible to themselves, but every
+  remote hunter/partner is a full character on screen. On phone tiers, animate and fully draw only the
   nearest `tier.remoteAvatarCap` remotes (`$genex-threejs-adaptive-quality`) — freeze the
   mixer and billboard or hide the rest; a room allows up to 64 players and 64 live avatars
   is a real phone memory kill on its own.