@genex-ai/cli-demo 0.37.0 → 0.38.0

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

@@ -1,37 +1,43 @@
 # Character animations
 
 `CharacterAnimations` turns the controller's live flags into crossfaded
-`THREE.AnimationMixer` playback: seven states, alias-based clip binding that
-works with the bundled library, Mixamo exports, or arbitrary rigs, and a
-procedural bob/lean fallback when a model has no usable clips at all.
+`THREE.AnimationMixer` playback: nine states, alias-based clip binding that
+works with the bundled library, installed animation packs, Mixamo exports, or
+arbitrary rigs, and a procedural bob/lean fallback when a model has no usable
+clips at all.
 
-## The bundled assets
+## The bundled assets + animation packs
 
 `npx genex controller character` sets the game up to play as a **VRM avatar**:
 
 - `public/assets/avatar.vrm` — the player's avatar (yours when signed in, else a
   bundled CC0 default). Always present; always one path.
-- `public/assets/animation-library.glb` (6.4 MB) — 46 clips on a shared
-  Quaternius rig (provenance in `src/controllers/NOTICE.md`).
+- `public/assets/animation-library.glb` (~1.3 MB) — the 12-clip core
+  (idle/walk/jog/sprint, the jump trio, crouch idle+move, hit, death, interact)
+  on a shared Quaternius rig (provenance in `src/controllers/NOTICE.md`).
+- `public/assets/anims/*.glb` — OPTIONAL per-clip packs installed by
+  `npx genex controller anims <tags|clip names…>` from the 120-clip Quaternius
+  Universal Animation Library Pro catalog (see the tag catalog below). Re-runs
+  are additive; `--reset` starts over; a `manifest.json` alongside lists what's
+  installed.
 
 VRM helpers live in `src/controllers/character/vrm/`. Install three-vrm once:
 `npm i @pixiv/three-vrm`.
 
-Load the avatar, retarget the library clips onto its humanoid rig, and auto-fit
-the capsule — all with **relative** paths so the published game works under its
-subpath:
+Load the avatar, then EVERYTHING the game has via `loadCharacterClips` — core
+library + installed packs, each retargeted onto the avatar's humanoid rig —
+all with **relative** paths so the published game works under its subpath:
 
 ```ts
-import { GLTFLoader } from "three/addons/loaders/GLTFLoader.js";
 import { loadVrm } from "./controllers/character/vrm/vrm-loader.ts";
-import { retargetClips } from "./controllers/character/vrm/vrm-retarget.ts";
+import { loadCharacterClips } from "./controllers/character/animation-packs.ts";
 import { capsuleFromModel } from "./controllers/character/vrm/capsule-fit.ts";
 import { CharacterController } from "./controllers/character/character-controller.ts";
 import { CharacterAnimations } from "./controllers/character/character-animations.ts";
 import { characterPresets } from "./controllers/character/presets.ts";
 
 const { scene, vrm } = await loadVrm("./assets/avatar.vrm");
-const lib = await new GLTFLoader().loadAsync("./assets/animation-library.glb");
+const clips = await loadCharacterClips(vrm); // core + every installed pack, retargeted
 
 // capsuleFromModel derives the collider from the avatar's bounds — no manual
 // per-avatar tuning even as heights/proportions vary across the library.
@@ -44,11 +50,13 @@ const character = new CharacterController(physics.world, camera, {
 character.root.add(scene);
 scene.position.y = fit.modelOffsetY; // root = capsule CENTER; drop the model so feet touch the floor
 
-// retargetClips maps the Quaternius rig onto the VRM's normalized humanoid rig
-// (VRM 0.x and 1.0 alike); the result feeds CharacterAnimations unchanged.
-const anims = new CharacterAnimations(scene, retargetClips(vrm, lib.scene, lib.animations));
+const anims = new CharacterAnimations(scene, clips);
 ```
 
+(Advanced: to load a single GLB by hand, `retargetClips(vrm, gltf.scene,
+gltf.animations)` from `vrm/vrm-retarget.ts` is what `loadCharacterClips` uses
+internally — it auto-detects the source rig per file.)
+
 Per render frame, **after** `physics.step(delta)`:
 
 ```ts
@@ -73,11 +81,27 @@ import { FootIK } from "./controllers/character/vrm/foot-ik.ts";
 const footIK = new FootIK(vrm, (foot) => {
   const hit = physics.world.castRay(
     new RAPIER.Ray({ x: foot.x, y: foot.y + 0.5, z: foot.z }, { x: 0, y: -1, z: 0 }),
-    1.5, true);
+    1.5, true, RAPIER.QueryFilterFlags.EXCLUDE_SENSORS,
+    undefined, undefined, character.body); // exclude the character's own capsule
   return hit ? foot.y + 0.5 - hit.timeOfImpact : null;
+}, {
+  isActive: () => character.isOnGround,          // keep the jump pose while airborne
+  allowReachDown: () => !anims.oneShotActive,    // REQUIRED with one-shots: they are
+  // choreography — without this a firing stance over a step edge drags the pelvis
+  // down into the staircase. While gated, feet are only lifted as much as needed
+  // to stay out of the step under them (anti dig-in).
 });
-// each frame, after vrm.update(delta):
-footIK.update(delta);
+```
+
+ORDER IS LOAD-BEARING — foot IK poses the VRM's *normalized* bones, which
+`vrm.update()` then copies onto the render mesh. Run it BETWEEN the two (after
+`vrm.update` it has no visible effect at all — the next frame's mixer tick
+overwrites it before the copy):
+
+```ts
+anims.update(character, delta); // 1. mixer poses the normalized rig
+footIK.update(delta);           // 2. plant the feet on that pose
+vrm.update(delta);              // 3. copy normalized -> render mesh + spring bones
 ```
 
 ## States and default clips
@@ -89,14 +113,16 @@ The pure resolver (`resolveAnimationState`) maps controller flags to one of:
 | `IDLE` | `Idle_Loop` | starts playing immediately on construction |
 | `WALK` | `Walk_Loop` | |
 | `RUN` | `Jog_Fwd_Loop` | **the default run clip**; `Sprint_Loop` also binds via alias — force it with an override if the user wants an all-out sprint look |
+| `CROUCH_IDLE` | `Crouch_Idle_Loop` | while `crouchActive`; degrades to `IDLE` on rigs without crouch clips |
+| `CROUCH_MOVE` | `Crouch_Fwd_Loop` | crouched + moving; degrades to `WALK` |
 | `JUMP_START` | `Jump_Start` | one-shot, played at 1.6× so it finishes inside the hop |
 | `JUMP_IDLE` | `Jump_Loop` | airborne, moving up |
 | `JUMP_FALL` | `Jump_Loop` | airborne, moving down (shares the clip — no restart mid-air) |
 | `JUMP_LAND` | `Jump_Land` | one-shot |
 
-## One-shot actions + the 46-clip catalog
+## One-shot actions + the 120-clip pack catalog
 
-The seven states above cover locomotion. **Every other clip** plays through
+The nine states above cover locomotion. **Every other clip** plays through
 `anims.playOneShot(clipName, options?)`: it crossfades the clip over the current
 motion, plays it once, then hands control back to the state machine. Returns
 `false` if the clip name isn't in the set you passed to the constructor.
@@ -116,31 +142,44 @@ addEventListener("pointerdown", () => {
 `options`: `fadeIn` (default 0.1 s), `timeScale`, `clamp` (hold the final pose —
 for deaths), `onDone`.
 
-Full catalog (clip → motion → reach for it when):
+The 12 core clips are always available; everything else comes from
+`npx genex controller anims <selectors…>` — selectors are **tags** (install a
+themed set) or **exact clip names** (cherry-pick), freely mixed:
 
-| Clip(s) | Motion | Use for |
+```bash
+npx genex controller anims sword pistol         # tags: a sword + shooter game
+npx genex controller anims stealth Celebration  # a tag + one exact clip
+npx genex controller anims --list               # all tags with sizes
+npx genex controller anims --list sword magic   # per-clip durations + descriptions
+```
+
+Tag catalog (tag → clips → reach for it when). Pick tags from the game's theme;
+run `--list <tag>` for per-clip descriptions before wiring one-shots:
+
+| Tag | Clips (≈size) | Use for |
 | --- | --- | --- |
-| `Punch_Jab` / `Punch_Cross` | quick / heavy punch | melee, click-to-attack (default) |
-| `Punch_Enter` | raise fists | enter a fighting stance |
-| `Hit_Chest` / `Hit_Head` | flinch | taking damage (multiplayer-friendly reactions) |
-| `Death01` | collapse | death — pair with `clamp: true` |
-| `Sword_Idle` / `Sword_Attack` / `Sword_Attack_RM` | ready / swing / swing+step | melee weapons (`_RM` = root motion, travels) |
-| `Pistol_Idle_Loop` / `Pistol_Aim_Up` / `_Neutral` / `_Down` | aim poses | shooters — pick by camera pitch |
-| `Pistol_Shoot` / `Pistol_Reload` | fire / reload | shooter actions |
-| `Spell_Simple_Enter` / `_Idle_Loop` / `_Shoot` / `_Exit` | cast cycle | magic / RPG |
-| `Roll` / `Roll_RM` | dodge roll | dodge (`_RM` travels) |
-| `Interact` / `PickUp_Table` / `Fixing_Kneeling` | reach / pick up / kneel-work | pickups, levers, crafting |
-| `Sitting_Enter` / `_Idle_Loop` / `_Talking_Loop` / `_Exit` | sit / sit-idle / chat / stand | seats, vehicles, dialogue |
-| `Dance_Loop` / `Idle_Talking_Loop` / `Idle_Torch_Loop` | dance / gesture / torch idle | emotes, NPCs, ambience |
-| `Push_Loop` / `Crouch_Idle_Loop` / `Crouch_Fwd_Loop` | push / crouch / crouch-walk | pushing, stealth |
-| `Swim_Idle_Loop` / `Swim_Fwd_Loop` | tread / swim | water |
-| `Walk_Formal_Loop` | stiff walk | override `WALK` for a formal gait |
-| `Driving_Loop` | seated at a wheel | vehicles (see `$genex-threejs-vehicle-controllers`) |
-| `A_TPose` | rest pose | reference only |
+| `core` | Idle/Walk/Jog/Sprint loops, Jump trio, Crouch idle+fwd, Hit_Chest, Death01, Interact | already bundled — never needs installing |
+| `locomotion-extra` | Jog strafe/diagonal/lean ×10, Turn90_L/R, Walk_Formal_Loop, Sprint_Enter/Exit (~1 MB) | 8-way strafe rigs, formal NPC gaits, sprint transitions |
+| `stealth` | Crouch_Enter/Exit + crouched strafe/diagonal/backward ×9 (~0.6 MB) | stealth games (the built-in crouch only needs core; these add direction variety + transitions) |
+| `crawl` | Crawl enter/exit/idle + 4 directions (~0.5 MB) | prone crawling, vents, tunnels |
+| `climb` | Climb enter/exit/idle, up/down/left/right, ClimbLedge (~0.6 MB) | ladders, walls, parkour |
+| `parkour` | BackFlip, Roll, Dodge_Left/Right (~0.3 MB) | dodges and flips |
+| `brawl` | Punch_Jab/Cross, Kick, PunchKick_Enter/Exit (~0.35 MB) | fist fighting |
+| `sword` | Sword_Enter/Exit/Idle/Attack/Attack_Standing (~0.35 MB) | melee weapons |
+| `pistol` | Pistol_Idle_Loop, Aim_Up/Neutral/Down (pick by camera pitch), Shoot, Reload (~0.3 MB) | shooters |
+| `magic` | Spell_Simple + Spell_Double enter/exit/idle/shoot cycles (~0.5 MB) | casters — Double's shoot is a channel/beam loop |
+| `damage` | Hit_Head/Shoulder_L/R/Stomach, Death02 (~0.3 MB) | directional hit reactions beyond the core pair |
+| `swim` | Swim_Idle_Loop, Swim_Fwd_Loop (~0.15 MB) | water |
+| `sit` | Sitting enter/exit + 5 idles, GroundSit set (~0.7 MB) | seats, campfires, dialogue |
+| `emote` | Celebration, Crying, Dance_Loop, Drink, talking/tired/look-around idles, Rock/Paper/Scissors (~0.7 MB) | emotes, NPCs, minigames |
+| `interact` | PickUp_Kneeling/Table, Fixing_Kneeling, Push enter/exit/loop (~0.4 MB) | pickups, levers, crafting, pushing |
+| `shop` | Counter enter/exit/idle/give/show/angry (~0.4 MB) | shopkeeper NPCs |
+| `drive` | Driving_Loop (~0.05 MB) | vehicles (see `$genex-threejs-vehicle-controllers`) |
 
 For looping poses that should **persist** (aiming, sitting, swimming) rather than
 play once, drive them through the public `anims.mixer` escape hatch instead; the
-`$genex-threejs-vehicle-controllers` skill shows the seated pattern.
+`$genex-threejs-vehicle-controllers` skill shows the seated pattern. All clips
+are in-place (no root motion) — the physics controller owns all translation.
 
 ## Binding arbitrary rigs (Mixamo included)
 
@@ -149,10 +188,12 @@ explicit override (exact, then case-insensitive) → library exact names →
 case-insensitive → each alias as a case-insensitive **substring**, shortest
 matching clip name wins (so `Walk_Loop` beats `Walk_Bwd_Loop`, and Mixamo's
 `walking` beats `walking_backwards`). Aliases include `idle`, `walk`, `run`,
-`jog`, `sprint`, `jump_start`, `takeoff`, `fall`, `land`, and a bare `jump`
-catch-all so a rig whose only airborne clip is "Jumping" still binds all four
-jump states. Unbound loop states chain (RUN↔WALK, JUMP_IDLE↔JUMP_FALL);
-unbound one-shots stay silent so the previous loop keeps playing.
+`jog`, `sprint`, `crouch_idle`, `sneak`, `jump_start`, `takeoff`, `fall`,
+`land`, and a bare `jump` catch-all so a rig whose only airborne clip is
+"Jumping" still binds all four jump states. Unbound loop states chain
+(RUN↔WALK, JUMP_IDLE↔JUMP_FALL, CROUCH_IDLE→IDLE, CROUCH_MOVE→WALK — rigs
+without crouch clips sneak in a standing pose instead of T-posing); unbound
+one-shots stay silent so the previous loop keeps playing.
 
 If a name refuses to bind, pass overrides:
 
@@ -195,9 +236,9 @@ const anims = new CharacterAnimations(placeholderMesh, []); // procedural fallba
 
 ## Remote players (multiplayer)
 
-The snapshot type is structural — **anything** with the five booleans works,
+The snapshot type is structural — **anything** with the six booleans works,
 which is exactly what remote players need. Remote players have no physics and
-no `CharacterController` (see the SKILL's multiplayer rule): sync the five
+no `CharacterController` (see the SKILL's multiplayer rule): sync the six
 flags from the owner and feed them straight in.
 
 ```ts
@@ -208,12 +249,16 @@ const flags = {
   isMoving: character.isMoving,
   runActive: character.runActive,
   jumpActive: character.jumpActive,
+  crouchActive: character.crouchActive,
 };
 
 // Receiver: one CharacterAnimations per remote model, fed the synced flags.
 remoteAnims.update(remoteState.flags, delta);
 ```
 
+`crouchActive` is additive: an older game syncing only five flags still
+resolves correctly (a missing flag reads as not-crouched).
+
 The mixer crossfades exactly as it does locally, so remote players animate
 correctly without simulating anything. In v1 every player loads the same
 `./assets/avatar.vrm` (the game owner's avatar), so remotes look like the owner —

package/templates/skills/genex-threejs-character-controller/references/tuning-and-presets.md

@@ -64,6 +64,9 @@ tip-overs mean the `autoBalance*` pair is too soft.
 | "drifts sideways through turns" | raise `rejectVelFactor` toward 1 (default 1; `ice-slide` lowers it to 0.2) |
 | "too slow / too fast" | `maxWalkVel` (default 2) / `maxRunVel` (default 5) |
 | "run should be hold, not toggle" | `enableToggleRun: false` (default true = Shift toggles) |
+| "sneaks too fast / too slow" | `crouchSpeedRatio` (default 0.45 × `maxWalkVel`) |
+| "can't fit under the obstacle when crouched" | lower `crouchCapsuleScale` (default 0.6 — the crouched capsule's cylinder half-height as a fraction of standing; the head drops by `2*(1-scale)*capsuleHalfHeight`) |
+| "crouch should be hold, not toggle" | `crouchMode: "hold"` (default `"toggle"` — C flips it) |
 | "no control in the air" | raise `airDragFactor` (default 0.1) |
 | "falls too fast at terminal velocity" | `fallingMaxVel` (default 20 m/s) |
 | "leans too much when running" | lower `moveImpulsePointOffset` (default 0.5; 0 = no lean) |

package/templates/skills/genex-threejs-multiplayer/references/host-physics.md

@@ -224,7 +224,7 @@ remote simulation:
 
 The vendored controllers expose their pose as `currPos` (a `THREE.Vector3`) and `currQuat` (a
 `THREE.Quaternion`) — **not** `.position` / `.quaternion` — plus boolean state getters. Character
-animation is driven by **five booleans**, not a single enum; publish the booleans and let remotes
+animation is driven by **six booleans**, not a single enum; publish the booleans and let remotes
 reconstruct the animation. There is **no** `rig.animState`, no `remoteAnimator.play(...)`, and no
 vehicle `wheelSpinPhase` getter.
 
@@ -235,9 +235,9 @@ const q = character.currQuat;  // THREE.Quaternion
 room.me.set({
   x: r2(p.x), y: r2(p.y), z: r2(p.z),
   q: [r2(q.x), r2(q.y), r2(q.z), r2(q.w)],   // quaternion array — never a scalar yaw
-  // character animation = 5 booleans (the CharacterController exposes each as a getter):
+  // character animation = 6 booleans (the CharacterController exposes each as a getter):
   g: character.isOnGround, f: character.isFalling, m: character.isMoving,
-  r: character.runActive,  j: character.jumpActive,
+  r: character.runActive,  j: character.jumpActive, c: character.crouchActive,
 });
 
 // Remote players: a VISUAL-ONLY avatar — NO Rapier body, NO controller instance for remotes.
@@ -248,15 +248,16 @@ remoteAvatar.group.position.set(pl.state.x, pl.state.y, pl.state.z);
 remoteAvatar.group.quaternion.fromArray(pl.state.q);
 const raw = pl.stateRaw; // discrete flags: read RAW, never smoothed
 remoteAvatar.update(
-  { isOnGround: !!raw.g, isFalling: !!raw.f, isMoving: !!raw.m, runActive: !!raw.r, jumpActive: !!raw.j },
+  { isOnGround: !!raw.g, isFalling: !!raw.f, isMoving: !!raw.m, runActive: !!raw.r, jumpActive: !!raw.j, crouchActive: !!raw.c },
   dt,
 );
 ```
 
 What to publish per controller:
 
-- **character**: `currPos` → `x/y/z`, `currQuat` → `q`, and the five booleans above
-  (`isOnGround`/`isFalling`/`isMoving`/`runActive`/`jumpActive`). Remotes rebuild the animation
+- **character**: `currPos` → `x/y/z`, `currQuat` → `q`, and the six booleans above
+  (`isOnGround`/`isFalling`/`isMoving`/`runActive`/`jumpActive`/`crouchActive` — the last is
+  additive; a peer syncing only five still animates, minus crouch). Remotes rebuild the animation
   with `avatar.update(flags, dt)` — see the `genex-threejs-character-controller` animations
   reference for the flag set (single source of truth; don't invent a `play(anim)` call).
 - **vehicle**: body `currPos` → `x/y/z` + `currQuat` → `q`. For visible steering, publish the

package/templates/skills/genex-threejs-skill-router/SKILL.md

@@ -16,7 +16,7 @@ map, execution order, and acceptance gate.
 | Work needed | Load |
 | --- | --- |
 | shot composition, chase/side/orbit rigs, camera handoffs, projection ownership, pointer look, floating origins | `$genex-threejs-camera-direction` |
-| on-foot player movement: walk/run/jump, third-person character, slopes, stairs, moving platforms, animation binding | `$genex-threejs-character-controller` |
+| on-foot player movement: walk/run/jump/crouch, third-person character, slopes, stairs, moving platforms, animation binding, extra animation packs (sword/pistol/magic/climb/swim/emotes via `genex controller anims`) | `$genex-threejs-character-controller` |
 | the player drives or flies something: cars, drones, vehicle physics, gearbox, enter/exit between character and vehicle | `$genex-threejs-vehicle-controllers` |
 | anything falls, collides, gets pushed, or needs physics: Rapier world setup, colliders for meshes and GLBs, collision events | `$genex-threejs-physics-rapier` |
 | launch and docking timelines, procedural transform phases, springs, staging, rotating-frame alignment, debris motion | `$genex-threejs-procedural-animation` |

package/templates/skills/genex-threejs-vehicle-controllers/references/enter-exit.md

@@ -109,8 +109,9 @@ a seated pilot; that is game glue on the `onHandoff` seam. The pattern: keep
 a reference to the character's visual model, re-parent it into a seat anchor
 under the vehicle's chassis object, and play the seat clips through a
 dedicated `THREE.AnimationMixer` (the locomotion state machine is idle while
-parked). The clips ship in `animation-library.glb` (installed by
-`npx genex controller character`).
+parked). The seat clips are animation-pack clips — install them once with
+`npx genex controller anims sit drive` (they land in `public/assets/anims/`
+and `loadCharacterClips` from the character controller picks them up).
 
 ```ts
 const seatMixer = new THREE.AnimationMixer(characterModel);