@genex-ai/cli-demo 0.81.0-dev.214 → 0.85.0-dev.216

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` |
@@ -85,24 +88,28 @@ Three.js release or branch, and do not blindly copy demo architecture.
    decided silently. FIRST of all art, generate the gate's **concept mockup** —
    a playable-moment shot (verb + threat + objective in frame, per the
    game-ui gate) WITH the full HUD composited over it: the `$genex-ai-hud`
-   Stage-1 image, one generation serving as concept, style checkpoint, and
-   HUD blueprint (never a separate UI-free concept first). Show it to the user
-   the moment it lands and get a keep-or-change answer through your question
-   tool (a short numbered list in chat when you have none). This answer
-   GATES — but only the style-dependent pipeline: until the user approves a
-   frame, do NOT enqueue the Tier-2 art that builds on the look (the
-   `$genex-ai-hud` Stage-2 chain, and the `$genex-ai-menu` still + video
-   whenever the menu decision is yes — the default for every game, "it's only
-   a draft" is not a reason to decide no — plus the logotype). The instant
-   they say yes, fire those with `--no-wait` (pick them up with
-   `npx genex wait <id>`); the game-ui skill owns the re-anchor loop when notes
-   arrive, and later `--edit`-able generations anchor to the approved frame for
-   STYLE while the game contract owns content. Everything that does NOT depend
-   on the look — scaffold, boot wiring, the core loop, and the
-   concept-independent worker lanes (the director's Delegate section) —
-   keeps building in parallel while the answer is pending, so the wait is
-   never idle. Skipping this enqueue is the #1 way a finished game ships an
-   ugly HUD — by step 12 there is nothing to swap in.
+   Stage-1 image, ONE generation serving as concept, style checkpoint, and
+   HUD blueprint (never a separate UI-free concept first, and no candidate
+   variants unless the player asks for them). **The moment it lands, the
+   cheap style chain fires — nothing waits for the player here**: decide the
+   HUD lane as art director and record the `HUD lane:` line in DESIGN.md
+   (director §5), then enqueue with `--no-wait` the `$genex-ai-hud` Stage-2
+   sheet, the `$genex-ai-menu` still (the menu is the default for every
+   game — "it's only a draft" is not a reason to decide no), and the
+   logotype. THEN show the player the frame and ask keep-or-change through
+   your question tool (a short numbered list in chat when you have none) —
+   the answer is INFORMATION, never a gate: silence means the concept
+   stands; "change" loops the concept with their notes and the chain re-runs
+   from the new frame (image-priced — cheap by design; the game-ui skill
+   owns the re-anchor loop). Only the menu VIDEO waits, for the FIRST of:
+   the player's yes · the next `genex preview` after the menu still landed ·
+   style work being the only work left — and never while a player objection
+   is open (two failed videos → ship the still). Later `--edit`-able
+   generations anchor to the standing frame for STYLE while the game
+   contract owns content. Everything concept-independent — scaffold, boot
+   wiring, the core loop, the worker lanes — keeps building in parallel.
+   Skipping this enqueue is the #1 way a finished game ships an ugly HUD —
+   by step 12 there is nothing to swap in.
 4. Lock the visual direction — the same plan-first logic as the UI gate, in
    the same plan block, before any rendering code:
    - **camera**: the rig type and the pointer bucket
@@ -247,12 +254,15 @@ Three.js release or branch, and do not blindly copy demo architecture.
     `$genex-threejs-game-ui` (HUD, pause on Escape, fail/retry, win, and the
     full loading state grown from the step-6 loader), then `npx genex wait`
     the step-3 UI generations and wire them in — the sprite HUD replaces the
-    placeholder CSS, the menu video replaces the still frame (wired with the
-    menu skill's loop crossfade), and the scene's planned generated models
-    replace their placeholder primitives — a shipped wave of enemies may not
-    be untextured boxes. This swap is a
-    completion gate, not an option: a game still on the placeholder CSS HUD,
-    or without a working Escape pause, is not done. Then run a feel pass via
+    placeholder CSS (or the recorded `HUD lane: CSS` build lands finished to
+    its brief), the menu video replaces the still frame (wired with the menu
+    skill's loop crossfade), the logotype lands on the menu and loader, and
+    the scene's planned generated models replace their placeholder
+    primitives — a shipped wave of enemies may not be untextured boxes. This
+    swap is a completion gate, not an option: a game still on the
+    placeholder CSS HUD (with no recorded CSS lane), without the menu video
+    playing (or its recorded still fallback), or without a working Escape
+    pause, is not done. Then run a feel pass via
     `$genex-threejs-game-feel` (input response, camera, impact feedback,
     retry speed).
 13. Validate in a real browser with fixed seeds, captures, interaction checks,
@@ -261,8 +271,9 @@ Three.js release or branch, and do not blindly copy demo architecture.
 ## Delegation
 
 Fan-out is owned by the director: sub-agents own DESIGN.md Modules rows,
-concept-DEPENDENT lanes wait for the player's yes on the concept, one writer
-per file, workers never spawn workers, and the Assets table is the budget —
+concept-DEPENDENT lanes launch the moment the concept lands (only the menu
+video waits for its event triple — step 3), one writer per file, workers
+never spawn workers, and the Assets table is the budget —
 the full rules and the worker prompt shape live in the Delegate section of
 `$genex-game-director`. This map adds no separate delegation rules; it is the
 routing source the director and its workers read.
@@ -282,7 +293,9 @@ routing source the director and its workers read.
 done = a screenshot plus an interaction smoke check (load the page, press each
 control, assert a visible response in its labeled direction — `$genex-threejs-visual-validation` has the
 procedure), **plus the UI floor from `$genex-threejs-game-ui` (the generated
-sprite HUD wired in — not the CSS placeholder — pause on Escape, the branded
+sprite HUD wired in — not the CSS placeholder — or the DESIGN.md-recorded
+`HUD lane: CSS` build finished to its brief; the menu video playing, or its
+recorded still fallback; the logotype placed; pause on Escape, the branded
 loader with its key-art background, the brief's font pair actually loaded)
 and the look floor (the step-4 renderer baseline + named post stack actually
 built; every placed 2D/media piece — decals, posters, in-world screens —
@@ -320,7 +333,9 @@ A routed Genex scene is incomplete until it exposes:
 ## Publish and multiplayer awareness
 
 **Publishing IS calling it done.** Before `npx genex publish`, every completion
-gate above must pass — sprite HUD wired, Escape pause working, branded loader
+gate above must pass — sprite HUD wired (or the recorded CSS lane finished),
+the menu video playing (or its recorded still fallback), the logotype placed,
+Escape pause working, branded loader
 with its key art, fonts loaded, renderer baseline + one built post effect
 (tier-aware), the adaptive-quality tier wired at boot, world dressing placed
 or validly waived, and the content contract's countables present or

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
@@ -334,6 +339,25 @@ own avatar file: players picked their looks, show them.
 - Load `$genex-threejs-multiplayer` before writing any networking code; it is
   mandatory for any 2+ player game.
 
+## Placing rigs outside the controller — facing is explicit
+
+The vendored controller owns the local player's facing. Any rig you place
+YOURSELF — a duel opponent, an NPC, a fighter in a side-view game — obeys
+three hard rules:
+
+- **Meshy / Mixamo / VRM rigs rest facing +Z** — from a side camera that
+  means straight at the lens. Set the yaw explicitly from the character's
+  ROLE the moment you place it (`model.rotation.y = …`); never leave the
+  rest pose and assume it reads right.
+- **Never mirror a SkinnedMesh with negative scale.** `scale.x = -1` is a
+  2D-sprite trick: on a 3D rig it flips triangle winding and normals
+  (broken lighting and culling) and does NOT turn the character. Turning is
+  always a yaw rotation.
+- **Duel / side-view / two-character scenes: the combatants face EACH
+  OTHER along the duel axis.** Two fighters staring into the camera is a
+  bug, not a pose — verify it in the milestone smoke capture (an enemy in
+  frame facing the player's CHARACTER, never the lens).
+
 ## If the user asks for ecctrl
 
 ecctrl is a React / React Three Fiber component; a Genex game is plain

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,201 @@
+---
+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.
+
+Two hard rules alongside it: **never mirror a rig with negative scale** —
+`scale.x = -1` is a 2D-sprite trick that flips winding and normals on a
+SkinnedMesh and does NOT turn a 3D body; turning is always a yaw
+(`rotation.y`), set explicitly from the creature's role. And in any
+**duel / side-view / two-character scene**, the combatants face EACH OTHER
+along the duel axis — a fighter staring into the camera is a bug, not a
+pose, and the smoke capture is where it gets caught.
+
+### 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 |
 
@@ -71,66 +71,62 @@ and how the space reads (route, scale) — plus the brief's palette,
 materials, and light. A beautiful empty vista with nothing to fight and
 nowhere to go is a FAILED concept; so is one that invents mechanics the
 game doesn't have (a lap counter in a game without laps). Generate it
-`--size 2560x1440 --quality high --candidates 2 --no-wait`, enqueued FIRST
-of all art; the picked candidate's URL goes into the style-brief comment.
-
-**Describe the concept, show it, then get a YES before the style-dependent
-work fans out.** First lay the concept out in WORDS — the playable moment
-(the verb), what threatens the player, what they chase, how the space reads,
-and the brief's palette / materials / light / references — so the user is
-weighing a stated direction, not guessing at a picture. Generate the mockup
-FIRST of all art (`--candidates 2`) and get it in front of the user AS FAST
-AS POSSIBLE: pick the stronger candidate yourself, pick it up with
-`genex wait <id> --open` (or generate it with `--open`) so it opens in the
-user's browser AND prints the links, and paste BOTH candidates' URLs as
-clickable links saying which one you picked and why — a URL is invisible in a
-terminal, and "do you like it?" with no picture in front of the user is the
-#1 way this checkpoint fails (they end up digging logs for the file path).
-
-**Then ask for the yes with your question tool** — the one that shows the
-user clickable options; a short numbered list in chat only where there is
-none. ONE question — "this is roughly
-how the game and its HUD will look — keep this direction, or change
-something?" — with concrete keep / change options. This confirmation is
-REQUIRED for every game: the concept sets the STYLE every later asset
-inherits, so the user gets a real say before that style is committed. This
-reverses the old "advisory, never gate" rule — the concept now gates, but
-ONLY the style-dependent work (below), never the whole build.
-
-**The yes gates the STYLE-DEPENDENT work — nothing else.** Until the user
-approves a frame, do NOT fan out the art or subagents that build ON the
-chosen look: the HUD Stage-2 deconstruct (from the picked candidate), the
-menu still + video (`--edit`-anchored to the mockup), and the logotype. (The core asset set — hero model, ground texture, skybox,
-sfx — is prompted from the game IDEA, not the picked image, and mostly
-survives a style change, so it does NOT wait: launch it up front with
-placeholders, re-rolling only the few that don't survive if the look shifts.)
-Everything else that does NOT depend on the look
-keeps moving at full speed IN PARALLEL — the scaffold and boot wiring, the
-core gameplay / network loop, the controller, and the gameplay-LOGIC subagent
-modules (world, quests, enemies, items — their structure comes from the
-contract, not the picture). The wait is therefore never idle: a slow-to-answer
-user still gets a walkable first version, and the instant they say yes the
-style pipeline launches against the frame they approved. (A user who vanishes
-entirely leaves the LOOK pending, not the game — the deliberate trade for
-never committing a style behind their back.)
+`--size 2560x1440 --quality high --no-wait`, enqueued FIRST of all art —
+ONE image, no candidate variants unless the user asks; its URL goes into
+the style-brief comment.
+
+**Describe the concept in words while it renders.** Lay it out in chat —
+the playable moment (the verb), what threatens the player, what they chase,
+how the space reads, and the brief's palette / materials / light /
+references — so the user is weighing a stated direction, not guessing at a
+picture.
+
+**The moment the mockup lands, the style chain fires — then the user sees
+the frame.** In this order, no waiting between the steps: decide the HUD
+lane as art director and record the `HUD lane:` line in DESIGN.md
+(`$genex-game-director` §5 owns the criteria), enqueue the style-dependent
+chain `--no-wait` — the HUD Stage-2 deconstruct (from the mockup), the menu
+still (`--edit`-anchored to it), and the logotype — and THEN show the frame:
+pick it up with `genex wait <id> --open` (or generate with `--open`) so it
+opens in the user's browser AND prints the link, and paste the URL as a
+clickable link — a URL is invisible in a terminal, and "do you like it?"
+with no picture in front of the user is the #1 way this checkpoint fails.
+
+**Ask keep-or-change with your question tool — as INFORMATION, never a
+gate.** The one that shows clickable options; a short numbered list in chat
+only where there is none. ONE question — "this is roughly how the game and
+its HUD will look — keep this direction, or change something?" — with
+concrete keep / change options. The chain is already running while they
+read it: silence means the concept stands; nothing except the menu VIDEO
+ever waits for the answer. The user still gets a real say — a "change" at
+any time loops the concept with their notes at image prices (below). The
+menu video (the one expensive item) fires at the FIRST of: the user's yes ·
+the next `genex preview` after the menu still landed · style work being the
+only work left — and never while a user objection is open
+(`$genex-ai-menu` owns the trigger). (The core asset set — hero model,
+ground texture, skybox, sfx — is prompted from the game IDEA, not the
+image, and mostly survives a style change: launch it up front with
+placeholders. Everything style-independent — scaffold, boot wiring, the
+core loop, the gameplay-LOGIC subagent modules — keeps moving at full speed
+in parallel throughout.)
 
 **Change reopens the loop, same shape.** If the user picks "change" — or
 comes back with notes immediately or an hour later — re-run Stage 1 (the
-concept mockup itself) with their exact notes (`--candidates 2–3` gives them
-options to choose from), open + link the new frame, and ask again the same
-structured way. Carry every note forward so each round compounds; if two
-rounds don't converge, offer 2–3 distinct directions instead of re-rolling
-blind. Each frame the user approves becomes the working style, and the
-style-dependent pipeline stays gated on the latest yes (strictly CHEAPER than
-it used to be: one image carries scene + HUD, there is no separate concept to
-redo). When the style actually changes after downstream art already ran,
-re-anchor it: the menu still is re-edited (`--edit`) against the new mockup
-and its video re-run once from the new still (`$genex-ai-menu` — a
-user-driven style change re-opens its one-video rule), and the HUD deconstruct
-(Stage 2 onward, `$genex-ai-hud`) restarts from the new mockup. Style-neutral
-assets (most textures, sfx, models) usually survive — judge each in one line.
-The same "open it + paste the link" rule covers every image the user weighs
-in on — the menu still, the HUD mockup candidates.
+concept mockup itself) with their exact notes, open + link the new frame,
+ask again the same structured way, and re-run the cheap chain from the new
+frame (image-priced — that is the design: the correction lane is cheap
+because the expensive item waited). Carry every note forward so each round
+compounds; if two rounds don't converge, offer 2–3 distinct directions
+(that's the one moment `--candidates` earns its place) instead of
+re-rolling blind. Each standing frame is the working style. When the style
+changes after downstream art already ran, re-anchor it: the menu still is
+re-edited (`--edit`) against the new mockup and its video re-run once from
+the new still (`$genex-ai-menu` — a user-driven style change re-opens its
+one-video rule), and the HUD deconstruct (Stage 2 onward, `$genex-ai-hud`)
+restarts from the new mockup. Style-neutral assets (most textures, sfx,
+models) usually survive — judge each in one line. The same "open it + paste
+the link" rule covers every image the user weighs in on — the menu still,
+the HUD mockup.
 
 **The concept anchors STYLE, not truth.** Palette, materials, light, and
 register come from the frame; CONTENT comes from the game contract. This
@@ -165,13 +161,16 @@ rule explicitly does not apply to this one message):
 ```
 UI plan
 • Screens: <list with tiers — loader / menu / pause (Esc) / win/lose / …>
-• Style: <4–5 named hues> · fonts <display> / <body>
+• Style: <4–5 named hues> · fonts <display> / <body> (from $genex-ai-menu's
+  genre table, or a one-line reason)
 • References: <2–3 AAA games — one line on what's borrowed>
 • Menu: <archetype + button treatment, one-line reason from the brief>
-• Concept (HUD mockup): <generation id — 2 candidates> — awaiting your keep / change
-• Queued ON YOUR YES (style-dependent): HUD sheet (Stage 2, from the picked
-  mockup) · menu still → video <or "no menu: reason"> · logotype <or
-  "skipped: reason">
+• HUD lane: <sprites (…) | CSS (…, one-line justification)> — recorded in DESIGN.md
+• Concept (HUD mockup): <generation id> — shown for keep / change
+  (informational — the chain below is already queued; silence = it stands)
+• Queued on concept landing: HUD sheet (Stage 2) · menu still · logotype
+  <or "skipped: reason">; menu VIDEO waits for: your yes / the next preview
+  after the still lands / style work being all that's left <or "no menu: reason">
 • Building now (style-independent): <core loop · logic modules already moving>
 • Deferred from mockup: <widgets the image invented but the game lacks — or "none">
 ```
@@ -190,8 +189,9 @@ A message missing any line means the gate did not run — go back and run it.
   every game), and the generated **logotype** — one `--transparent` wordmark
   in the brief's display register (`$genex-ai-menu`'s logotype step), default
   YES for every game with a menu; skipping it needs a one-line stated reason.
-  Enqueue this chain the instant the user approves the concept
-  (`--no-wait`) — it is style-dependent, so it waits on the yes — then
+  Enqueue this chain the instant the concept mockup LANDS (`--no-wait`) —
+  the keep/change answer never gates it; only the menu VIDEO waits, for its
+  event triple (`$genex-ai-menu`) — then
   keep building, pick results up with `npx genex wait <id>`, swap them in as
   they land. **Tier 2 must never block a playable v0 — but the game is NOT
   DONE until its Tier-2 assets have landed and been wired in** (the only
@@ -200,7 +200,9 @@ A message missing any line means the gate did not run — go back and run it.
   Run `npx genex wait` on every enqueued ID before any publish and before
   the final handoff of a session — never park landed assets for "later".
   Shipping the placeholder CSS HUD as the final HUD is a failure, not a
-  tier choice.
+  tier choice — the ONE exception is a DESIGN.md-recorded `HUD lane: CSS`
+  decision (`$genex-game-director` §5), where the CSS build, finished to
+  its brief, IS the production HUD.
 - **Tier 3 — offer, don't build.** Video layers over the HUD, 9-slice panel
   sprites, animated menu sprites. Offer in one line
   after the player has seen Tier 1+2 working; build on request.
@@ -522,15 +524,21 @@ architecture and consume the shared style brief.
 - Hard-cut phase swaps, a menu whose elements just appear, numbers that
   teleport.
 - A silent menu; a bare "Loading…" over black.
-- Style-dependent art fanned out before the user approved the concept — the
-  concept confirmation is REQUIRED and gates the look-dependent work (HUD
-  Stage 2, menu still/video, logotype, style-matched assets); OR the whole
-  build stalled waiting on that yes, when concept-INDEPENDENT work (scaffold,
-  core loop, logic subagents) must keep moving in parallel while it is pending.
+- The style chain parked behind the keep/change question — the HUD Stage-2
+  sheet, menu still, and logotype enqueue the moment the mockup LANDS, and
+  silence means the concept stands; OR the menu VIDEO fired while a user
+  objection was still open (its event triple is the only wait in the lane);
+  OR the whole build stalled on the concept at all, when concept-INDEPENDENT
+  work (scaffold, core loop, logic subagents) must keep moving in parallel
+  throughout.
 - A CSS-cut corner (`clip-path`/`mask`) that shears its own content — clipped
   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