@genex-ai/cli-demo 0.36.0 → 0.38.0

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

@@ -1,6 +1,6 @@
 ---
 name: genex-threejs-character-controller
-description: Add a tuned physics character controller to a Genex Three.js game with `npx genex controller character` — dynamic-capsule movement (walk/run/jump, slopes, stairs, moving platforms), follow camera, keyboard + touch input, and animation binding. Use for any on-foot player or third-person movement, and whenever the user asks for ecctrl — this is that controller, ported to plain Three.js.
+description: Add a tuned physics character controller to a Genex Three.js game with `npx genex controller character` — dynamic-capsule walk/run/jump/crouch (slopes, stairs, moving platforms), follow camera, keyboard + touch input, animation binding. Animation packs (sword, pistol, magic, climb, swim, emotes…) install via `npx genex controller anims <tags>`. Use for any on-foot player or third-person movement, and whenever the user asks for ecctrl — this is that controller, ported to plain Three.js.
 ---
 
 # Genex Three.js Character Controller
@@ -14,9 +14,13 @@ npm i @dimforge/rapier3d-compat @pixiv/three-vrm   # three is already in the sca
 
 The command vendors tested, tuned controller code into the game: TypeScript
 modules into `src/controllers/` (including `character/vrm/` — VRM loading,
-animation retargeting, capsule auto-fit, foot IK) and the 46-clip
-`animation-library.glb` into `public/assets/`. It also writes the player's
-avatar to `public/assets/avatar.vrm` — **your** avatar when you're signed in,
+animation retargeting, capsule auto-fit, foot IK) and the 12-clip core
+`animation-library.glb` (idle/walk/run/jump/crouch + hit/death/interact,
+~1.3 MB) into `public/assets/`. Need more — swords, pistols, magic, climbing,
+swimming, emotes? Install exactly what the game uses with
+`npx genex controller anims <tags|clip names…>` (see Animations below). The
+command also writes the player's avatar to `public/assets/avatar.vrm` —
+**your** avatar when you're signed in,
 otherwise a bundled CC0 default (attribution in `src/controllers/NOTICE.md`).
 The character plays as that VRM. The copied files are then owned by the game —
 edit them freely; re-running skips existing files unless `--force`. Do not write
@@ -36,27 +40,28 @@ platforms, climbs stairs and slides on too-steep slopes out of the box.
 | `character/keyboard-input.ts` | `KeyboardInput` | WASD/arrows/Shift/Space/F state, no per-frame polling setup |
 | `character/touch-joystick.ts` | `TouchJoystick`, `VirtualButton` | mobile controls |
 | `character/character-animations.ts` | `CharacterAnimations` | animation state machine + fuzzy clip binding + `playOneShot` + procedural fallback |
-| `character/vrm/*` | `loadVrm`, `retargetClips`, `capsuleFromModel`, `FootIK` | load the VRM avatar, retarget the 46 UAL clips onto its humanoid rig, auto-fit the capsule, ground the feet |
+| `character/animation-packs.ts` | `loadCharacterClips` | one call loads the core library + every installed `genex controller anims` pack, retargeted onto the VRM |
+| `character/vrm/*` | `loadVrm`, `retargetClips`, `capsuleFromModel`, `FootIK` | load the VRM avatar, retarget library clips onto its humanoid rig, auto-fit the capsule, ground the feet |
 
 ## Minimal wiring
 
 ```ts
-import { GLTFLoader } from "three/addons/loaders/GLTFLoader.js";
 import { PhysicsWorld } from "./controllers/shared/physics-world.ts";
 import { CharacterController } from "./controllers/character/character-controller.ts";
 import { CharacterAnimations } from "./controllers/character/character-animations.ts";
+import { loadCharacterClips } from "./controllers/character/animation-packs.ts";
 import { characterPresets } from "./controllers/character/presets.ts";
 import { FollowCamera } from "./controllers/character/follow-camera.ts";
 import { KeyboardInput } from "./controllers/character/keyboard-input.ts";
 import { loadVrm } from "./controllers/character/vrm/vrm-loader.ts";
-import { retargetClips } from "./controllers/character/vrm/vrm-retarget.ts";
 import { capsuleFromModel } from "./controllers/character/vrm/capsule-fit.ts";
 
 const physics = await PhysicsWorld.create(); // nothing RAPIER-related may run before this resolves
 
-// Load the player's avatar + the animation library, then retarget onto the VRM.
+// Load the player's avatar, then every animation the game has (the bundled core
+// library + any packs installed by `genex controller anims`), retargeted onto the VRM.
 const { scene: avatar, vrm } = await loadVrm("./assets/avatar.vrm");
-const lib = await new GLTFLoader().loadAsync("./assets/animation-library.glb");
+const clips = await loadCharacterClips(vrm);
 
 const fit = capsuleFromModel(avatar);          // collider fits THIS avatar's bounds
 const character = new CharacterController(physics.world, camera, {
@@ -70,7 +75,7 @@ character.root.add(avatar);                     // parent the avatar under the c
 avatar.position.y = fit.modelOffsetY;           // root = capsule CENTER; drop the model so feet touch the floor
 physics.registerBody(character.body, character.root); // root now follows the body, interpolated
 
-const anims = new CharacterAnimations(avatar, retargetClips(vrm, lib.scene, lib.animations));
+const anims = new CharacterAnimations(avatar, clips);
 addEventListener("pointerdown", () => anims.playOneShot("Punch_Jab")); // punch on click
 
 const kb = new KeyboardInput();
@@ -127,17 +132,39 @@ preset table with provenance, the density/spring scaling rule, and the
 - The capsule ships with friction `-0.5` **on purpose** (grip is synthesized by
   the controller). Do not "fix" it to a positive value.
 
-## Animations
+## Animations + animation packs
 
-`CharacterAnimations` resolves seven locomotion states (IDLE / WALK / RUN /
-JUMP_START / JUMP_IDLE / JUMP_FALL / JUMP_LAND) from the controller's live flags
-and crossfades mixer actions. Every OTHER library clip — punches, sword swings,
-pistol fire, spells, sit, dance, hit reactions — plays through
-`anims.playOneShot("Punch_Jab")`, which layers over locomotion and returns to it
-when done (punch-on-click is the default). Read
-[references/animations.md](references/animations.md) for the VRM load + retarget
-wiring, the **full 46-clip catalog** with genre hints, `playOneShot` options,
-overrides, foot IK, and remote-player animation.
+`CharacterAnimations` resolves nine locomotion states (IDLE / WALK / RUN /
+CROUCH_IDLE / CROUCH_MOVE / JUMP_START / JUMP_IDLE / JUMP_FALL / JUMP_LAND)
+from the controller's live flags and crossfades mixer actions. Every OTHER
+clip — punches, sword swings, pistol fire, spells, sit, dance, hit reactions —
+plays through `anims.playOneShot("Punch_Jab")`, which layers over locomotion
+and returns to it when done (punch-on-click is the default).
+
+The bundled library carries only the 12 core clips. **Install what the game's
+theme needs** from the 120-clip catalog, by tag or exact clip name:
+
+```bash
+npx genex controller anims sword pistol        # a sword+shooter game
+npx genex controller anims stealth climb crawl # a ninja game
+npx genex controller anims --list              # browse tags; --list <tag> for per-clip details
+```
+
+Clips land in `public/assets/anims/` and `loadCharacterClips(vrm)` picks them
+up automatically — re-run with more tags any time (additive). Read
+[references/animations.md](references/animations.md) for the tag catalog with
+genre hints, `playOneShot` options, overrides, foot IK, and remote-player
+animation.
+
+## Crouch (built in)
+
+`C` toggles crouch (capsule shrinks, speed drops to `crouchSpeedRatio ×
+maxWalkVel`, CROUCH_IDLE/CROUCH_MOVE play). Standing back up is
+ceiling-checked: under a low obstacle the character STAYS crouched and pops up
+automatically once clear; jumping while crouched requests a stand instead of
+jumping. `crouchMode: "hold"` makes it hold-to-crouch;
+`character.setCrouch(bool)` and `character.crouchActive` are the programmatic
+hooks (that's also how a touch button wires in — see Mobile below).
 
 ## Mobile: TouchJoystick + VirtualButton (wire by default)
 
@@ -151,6 +178,11 @@ import { TouchJoystick, VirtualButton } from "./controllers/character/touch-joys
 
 const joy = new TouchJoystick({ wrapperStyle: { left: "20px", bottom: "20px" } }); // position is REQUIRED
 const btnJump = new VirtualButton({ label: "Jump", wrapperStyle: { right: "30px", bottom: "30px" } });
+const btnCrouch = new VirtualButton({
+  label: "Crouch",
+  wrapperStyle: { right: "100px", bottom: "30px" },
+  onPress: () => character.setCrouch(!character.crouchActive), // tap = toggle
+});
 
 physics.onBeforeStep(() => {
   character.setMovement({
@@ -178,8 +210,9 @@ players' physics locally guarantees divergence — every client would compute a
 different world.
 
 - Publish your own `currPos` + yaw on the fixed 10–20 Hz tick, not per frame.
-- To animate remotes, sync the five animation booleans and feed them to a
-  per-remote `CharacterAnimations` — see the animations reference.
+- To animate remotes, sync the six animation booleans (`isOnGround`,
+  `isFalling`, `isMoving`, `runActive`, `jumpActive`, `crouchActive`) and feed
+  them to a per-remote `CharacterAnimations` — see the animations reference.
 - Load `$genex-threejs-multiplayer` before writing any networking code; it is
   mandatory for any 2+ player game.
 

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` |
@@ -60,13 +60,12 @@ recipes (sports/ball, shooter, co-op).
 ## Real (AI-generated) assets — `npx genex` commands
 
 When the user wants a **specific, recognizable asset** (a named object, a described
-sky, a particular sound or surface) rather than something authored in code, generate
-it with an `npx genex` command (run inside the project, where the `@genex-ai/cli-demo`
-dev dependency makes `genex` resolve to the right CLI). Each drops a real file into
-`public/assets/<kind>/` so it ships with the built game — load it at runtime as
-`./assets/...` (the `public/` prefix is stripped when served; a bare `./assets/` dir
-would be dropped from the production build). Each skill has the exact Three.js
-loader code.
+sky, a particular sound, surface, image, or clip) rather than something authored in
+code, generate it with an `npx genex` command (run inside the project, where the
+`@genex-ai/cli-demo` dev dependency makes `genex` resolve to the right CLI). Each
+prints a permanent public `assets.genex.technology` URL you load straight from at
+runtime — the asset lives in Genex storage (R2), not your repo, so there's nothing to
+commit. Each skill has the exact Three.js loader code.
 
 | Work needed | Generate with | Skill |
 | --- | --- | --- |
@@ -74,6 +73,8 @@ loader code.
 | a described 360° sky / backdrop + image-based lighting | `npx genex skybox "<prompt>"` | `$genex-ai-skybox` |
 | a specific sound effect tied to an event | `npx genex sfx "<prompt>"` | `$genex-ai-sfx` |
 | a photoreal surface/material on a mesh or terrain | `npx genex texture "<prompt>" [--terrain]` | `$genex-ai-texture` |
+| a picture on a plane/sprite — poster, sign, sprite, card art, decal/sticker | `npx genex image "<prompt>" [--transparent]` | `$genex-ai-image` |
+| a video clip on a surface — in-game screen, billboard, cutscene, backdrop | `npx genex video "<prompt>" [--loop]` | `$genex-ai-video` |
 
 Prefer the **procedural** skills above for abstract/parametric/animated systems
 (geometry, materials, sky, water, VFX) — no files, infinite variation. Prefer the

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);