@genex-ai/cli-demo 0.37.0 → 0.38.0

package/templates/controllers/character/vrm/foot-ik.ts

@@ -68,6 +68,16 @@ export interface FootIKOptions {
    * so airborne legs keep their jump pose). Default: always active.
    */
   isActive?: () => boolean;
+  /**
+   * Gate for the terrain-relative reach (downward offsets + pelvis drop, and
+   * full plant-up). Return false while a full-body one-shot is playing
+   * (`() => !anims.oneShotActive`): those clips are choreography — a foot
+   * swinging over a lower step must not drag the pelvis down into a staircase,
+   * and a raised stance foot must not be yanked a full step up. While gated,
+   * feet are lifted only as much as needed to keep the sole out of the contact
+   * under them (anti dig-in). Default: always allowed.
+   */
+  allowReachDown?: () => boolean;
 }
 
 // three-vrm's own node type — same THREE.Object3D at runtime, but using the
@@ -96,6 +106,12 @@ const NORMAL_DAMPING = 12; // ground-normal smoothing
 const PLANTED_LIFT_MIN = 0.04; // below this lift the foot is fully planted (align at full weight)
 const PLANTED_LIFT_MAX = 0.16; // above this lift the foot is fully lifted (no align)
 const MAX_FOOT_TILT = 0.6; // clamp foot-to-slope tilt (rad)
+const PENETRATION_SLACK = 0.02; // ankle may dip this far below rest before the no-sink lift kicks in
+// Max anti-dig-in lift while reach-down is gated (one-shots). Retarget dips are
+// a few cm; a hard cap keeps a stance foot carried INTO a stair riser by the
+// choreography from being lifted a whole step ("knee to the chest") — beyond
+// the cap it stays buried, which the step itself mostly occludes.
+const GATED_LIFT_CAP = 0.12;
 const MIN_BONE_LENGTH = 1e-4;
 const IK_EPSILON = 1e-4;
 
@@ -136,6 +152,7 @@ export class FootIK {
   #pelvisDrop: boolean;
   #alignFeet: boolean;
   #isActive: (() => boolean) | undefined;
+  #allowReachDown: (() => boolean) | undefined;
   #enabled = true;
   #weight = 0;
   #restFootHeight = 0;
@@ -148,6 +165,7 @@ export class FootIK {
     this.#pelvisDrop = options.pelvisDrop ?? true;
     this.#alignFeet = options.alignFeet ?? true;
     this.#isActive = options.isActive;
+    this.#allowReachDown = options.allowReachDown;
     this.#modelRoot = vrm.scene;
 
     const h = vrm.humanoid;
@@ -157,7 +175,14 @@ export class FootIK {
       const lower = h.getNormalizedBoneNode(l);
       const foot = h.getNormalizedBoneNode(f);
       return upper && lower && foot
-        ? { upper, lower, foot, offset: 0, normal: new THREE.Vector3(0, 1, 0), animFootPos: new THREE.Vector3() }
+        ? {
+            upper,
+            lower,
+            foot,
+            offset: 0,
+            normal: new THREE.Vector3(0, 1, 0),
+            animFootPos: new THREE.Vector3(),
+          }
         : null;
     };
     const left = mk(VRMHumanBoneName.LeftUpperLeg, VRMHumanBoneName.LeftLowerLeg, VRMHumanBoneName.LeftFoot);
@@ -192,14 +217,27 @@ export class FootIK {
 
     const k = 1 - Math.exp(-this.#smoothing * dt);
     const kNormal = 1 - Math.exp(-NORMAL_DAMPING * dt);
+    const reachDown = this.#allowReachDown?.() ?? true;
 
     // 1. Sample the ground under each ANIMATED foot; smooth offset + normal.
-    //    The offset is TERRAIN-relative — the ground height under the foot vs the
-    //    body root (the VRM origin = its floor/sole level), NOT vs the animated
-    //    foot. That's the load-bearing choice: it's independent of the foot's
-    //    stride phase, so a lifted swing foot keeps its animation (no dragging /
-    //    sinking while running) while a planted foot still lands on its step, and
-    //    it self-corrects any residual capsule-float gap (feet reach true ground).
+    //    Two lift signals, merged:
+    //    - TERRAIN-relative plant: the ground height under the foot vs the body
+    //      root (the VRM origin = its floor/sole level), NOT vs the animated
+    //      foot. Stride-phase independent — a lifted swing foot keeps its
+    //      animation (no dragging/sinking while running) while a planted foot
+    //      still lands on its step, and it self-corrects any residual
+    //      capsule-float gap (feet reach true ground).
+    //    - needLift: raise the ankle ONLY as much as needed so the sole clears
+    //      the contact under it — the anti-dig-in floor for poses that dip the
+    //      animated feet below the clip's own ground (weapon recoil etc. on
+    //      differently-proportioned avatars).
+    //    With reach-down gated off (full-body one-shots), ONLY needLift
+    //    applies, capped at GATED_LIFT_CAP: choreography feet are left alone
+    //    unless they'd clip into a step, and a foot the stance carries INTO a
+    //    riser gets at most a small hop, not a knee-to-the-chest fold. The
+    //    lift-only offsets also mean min(0,offset)=0 keeps the pelvis drop
+    //    off. Smoothing eases every transition (one-shot start/end, a ray
+    //    crossing a step edge) without pops.
     for (const leg of this.#legs) {
       leg.foot.getWorldPosition(leg.animFootPos);
       const sample = active ? this.#query(leg.animFootPos) : null;
@@ -207,14 +245,30 @@ export class FootIK {
       _normalTarget.copy(
         sample !== null && typeof sample !== "number" && sample.normal ? sample.normal : UP,
       );
-      const desired =
-        groundY === null
-          ? 0
-          : THREE.MathUtils.clamp(
-              groundY + this.#soleClearance - _rootPos.y,
-              -this.#maxOffset,
-              this.#maxOffset,
-            );
+      let desired = 0;
+      if (groundY !== null) {
+        // Anti-dig-in signal: how much lift (if any) the ankle needs so the
+        // sole clears the contact under it. NEGATIVE when the foot is safely
+        // above the contact — and it must stay negative: flooring it at zero
+        // here would win every Math.max below and silently kill the downward
+        // reach (and with it the pelvis drop) for the whole planter.
+        const needLift =
+          groundY +
+          this.#soleClearance +
+          this.#restFootHeight -
+          PENETRATION_SLACK -
+          leg.animFootPos.y;
+        desired = reachDown
+          ? Math.max(
+              THREE.MathUtils.clamp(
+                groundY + this.#soleClearance - _rootPos.y,
+                -this.#maxOffset,
+                this.#maxOffset,
+              ),
+              Math.min(needLift, this.#maxOffset),
+            )
+          : THREE.MathUtils.clamp(needLift, 0, GATED_LIFT_CAP);
+      }
       leg.offset += (desired - leg.offset) * k;
       leg.normal.lerp(_normalTarget, kNormal).normalize();
     }
@@ -229,6 +283,8 @@ export class FootIK {
     }
 
     // 3. Per-leg two-bone IK to the grounded target, then flatten planted feet.
+    //    (Anti-dig-in is already folded into the smoothed offset — needLift in
+    //    step 1 — so the target needs no extra instant clamp here.)
     for (const leg of this.#legs) {
       _target.copy(leg.animFootPos);
       _target.y += leg.offset * this.#weight;

package/templates/controllers/character/vrm/vrm-retarget.ts

@@ -1,6 +1,9 @@
 // SPDX-License-Identifier: MIT
-// Retarget Quaternius Universal Animation Library clips (Blender Rigify `DEF-`
-// rig) onto a three-vrm normalized humanoid rig (Genex AG-747). Adapted from the
+// Retarget Quaternius Universal Animation Library clips onto a three-vrm
+// normalized humanoid rig (Genex AG-747/AG-775). Two source rigs are supported
+// and auto-detected: the free UAL's Blender Rigify `DEF-*` skeleton and the UAL
+// Pro's UE-mannequin-style skeleton (`pelvis`/`spine_01`/…) that the bundled
+// core library and every CDN animation pack use. Adapted from the
 // official three-vrm Mixamo retarget recipe (@pixiv/three-vrm examples, MIT):
 // rewrite each bone track into the VRM's normalized-bone local space using the
 // SOURCE rig's rest-pose world rotations, and scale the hips translation by the
@@ -56,26 +59,81 @@ const DEF_TO_VRM: Record<string, VrmBone> = {
   "DEF-toe.R": VRMHumanBoneName.RightToes,
 };
 
+// Quaternius UAL Pro (UE-mannequin-style skeleton) -> VRM humanoid bone. Bone
+// names verified against the UAL1 master GLB ("Head" really is capitalized).
+// Fingers are omitted, same policy as the DEF map.
+const UE_TO_VRM: Record<string, VrmBone> = {
+  pelvis: VRMHumanBoneName.Hips,
+  spine_01: VRMHumanBoneName.Spine,
+  spine_02: VRMHumanBoneName.Chest,
+  spine_03: VRMHumanBoneName.UpperChest,
+  neck_01: VRMHumanBoneName.Neck,
+  Head: VRMHumanBoneName.Head,
+  clavicle_l: VRMHumanBoneName.LeftShoulder,
+  upperarm_l: VRMHumanBoneName.LeftUpperArm,
+  lowerarm_l: VRMHumanBoneName.LeftLowerArm,
+  hand_l: VRMHumanBoneName.LeftHand,
+  clavicle_r: VRMHumanBoneName.RightShoulder,
+  upperarm_r: VRMHumanBoneName.RightUpperArm,
+  lowerarm_r: VRMHumanBoneName.RightLowerArm,
+  hand_r: VRMHumanBoneName.RightHand,
+  thigh_l: VRMHumanBoneName.LeftUpperLeg,
+  calf_l: VRMHumanBoneName.LeftLowerLeg,
+  foot_l: VRMHumanBoneName.LeftFoot,
+  ball_l: VRMHumanBoneName.LeftToes,
+  thigh_r: VRMHumanBoneName.RightUpperLeg,
+  calf_r: VRMHumanBoneName.RightLowerLeg,
+  foot_r: VRMHumanBoneName.RightFoot,
+  ball_r: VRMHumanBoneName.RightToes,
+};
+
+/**
+ * Pick the source-rig bone map by looking for each rig's hips bone in the
+ * scene: `DEF-hips` -> Rigify (free UAL), `pelvis` -> UE-style (UAL Pro).
+ * Returns null for unrecognized rigs.
+ */
+export function detectBoneMap(sourceRoot: THREE.Object3D): Record<string, VrmBone> | null {
+  let map: Record<string, VrmBone> | null = null;
+  sourceRoot.traverse((object) => {
+    if (map !== null) return;
+    if (object.name === "DEF-hips") map = DEF_TO_VRM;
+    else if (object.name === "pelvis") map = UE_TO_VRM;
+  });
+  return map;
+}
+
 /**
  * Retarget UAL clips onto `vrm`.
  * @param vrm           the loaded VRM (already through {@link loadVrm}).
- * @param animationRoot the animation-library GLB's scene — its `DEF-` bones in
- *                      rest pose supply the source frame the tracks are relative to.
- * @param clips         that GLB's animations (all 46 UAL clips).
+ * @param animationRoot the animation GLB's scene — its bones in rest pose
+ *                      supply the source frame the tracks are relative to.
+ * @param clips         that GLB's animations.
+ * @param boneMap       source-bone-name -> VRM humanoid bone. Defaults to
+ *                      {@link detectBoneMap} on `animationRoot` (Rigify or
+ *                      UE-style rigs bind automatically).
  * @returns new clips whose tracks target the VRM's normalized humanoid bones.
  */
 export function retargetClips(
   vrm: VRM,
   animationRoot: THREE.Object3D,
   clips: THREE.AnimationClip[],
+  boneMap?: Record<string, VrmBone>,
 ): THREE.AnimationClip[] {
+  const sourceToVrm = boneMap ?? detectBoneMap(animationRoot);
+  if (sourceToVrm === null) {
+    console.warn(
+      "[vrm-retarget] unrecognized animation rig (no DEF-hips or pelvis bone found) — returning no clips; pass an explicit boneMap to retargetClips.",
+    );
+    return [];
+  }
+
   animationRoot.updateWorldMatrix(true, true);
   vrm.scene.updateWorldMatrix(true, true);
 
   // three's GLTFLoader SANITIZES node names in animation track targets
   // (PropertyBinding strips `[].:/ ` and turns spaces into `_`), so a Rigify bone
   // "DEF-upper_arm.L" shows up in tracks as "DEF-upper_armL". Map those sanitized
-  // names back to the real bones, whose actual names carry the dots DEF_TO_VRM
+  // names back to the real bones, whose actual names carry the dots the map
   // keys on. (Mixamo names are dotless, so the upstream recipe never needed this.)
   const sanitize = (name: string): string => name.replace(/\s/g, "_").replace(/[[\]./:]/g, "");
   const sourceByTrackName = new Map<string, THREE.Object3D>();
@@ -83,9 +141,9 @@ export function retargetClips(
     if (o.name) sourceByTrackName.set(sanitize(o.name), o);
   });
   // glTF load sanitizes bone names too, so `source.name` is already dot-stripped —
-  // key the VRM-bone lookup by the sanitized DEF name, matching the track's nodeName.
-  const sanitizedDefToVrm: Record<string, VrmBone> = {};
-  for (const [def, bone] of Object.entries(DEF_TO_VRM)) sanitizedDefToVrm[sanitize(def)] = bone;
+  // key the VRM-bone lookup by the sanitized source name, matching the track's nodeName.
+  const sanitizedSourceToVrm: Record<string, VrmBone> = {};
+  for (const [src, bone] of Object.entries(sourceToVrm)) sanitizedSourceToVrm[sanitize(src)] = bone;
 
   // Reusable bind-pose quaternions. Both rigs are at rest here (nothing has
   // animated them yet), so getWorldQuaternion reads the bind pose.
@@ -99,8 +157,10 @@ export function retargetClips(
   // hips' vertical bob/crouch on the target hips as a rest-relative DELTA, so
   // the physics controller still owns the whole-body base translation while the
   // pose keeps the pelvis (and therefore the feet) at the right height.
-  const HIPS_SANITIZED = sanitize("DEF-hips");
-  const srcHips = sourceByTrackName.get(HIPS_SANITIZED) ?? null;
+  const hipsSourceName = Object.entries(sanitizedSourceToVrm).find(
+    ([, bone]) => bone === VRMHumanBoneName.Hips,
+  )?.[0];
+  const srcHips = (hipsSourceName ? sourceByTrackName.get(hipsSourceName) : undefined) ?? null;
   const tgtHips = vrm.humanoid.getNormalizedBoneNode(VRMHumanBoneName.Hips);
   const hipsSrcParentWorld = new THREE.Quaternion();
   const hipsTgtParentWorldInv = new THREE.Quaternion();
@@ -128,7 +188,7 @@ export function retargetClips(
       const nodeName = track.name.slice(0, lastDot);
       const prop = track.name.slice(lastDot + 1);
       const source = sourceByTrackName.get(nodeName);
-      const vrmBone = sanitizedDefToVrm[nodeName];
+      const vrmBone = sanitizedSourceToVrm[nodeName];
       if (!source || !vrmBone) continue;
 
       const target = vrm.humanoid.getNormalizedBoneNode(vrmBone);

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.