@genex-ai/cli-demo 0.53.0-dev.121 → 0.54.0-dev.122

package/templates/controllers/character/motion-actions.ts

@@ -0,0 +1,135 @@
+// SPDX-License-Identifier: MIT
+import type { CharacterAnimations } from "./character-animations.ts";
+import type { CharacterActionMotion } from "./character-controller.ts";
+
+export type MotionTrajectorySample = readonly [time: number, x: number, y: number, z: number];
+
+export interface MotionTrajectory {
+  schema: 1;
+  clip: string;
+  samples: MotionTrajectorySample[];
+}
+
+export interface MotionActionController {
+  setActionMotion(motion: CharacterActionMotion | null): void;
+}
+
+export async function loadMotionTrajectory(url: string): Promise<MotionTrajectory> {
+  const response = await fetch(url);
+  if (!response.ok) throw new Error(`[motion-action] ${url} returned HTTP ${response.status}`);
+  const value = await response.json() as Partial<MotionTrajectory>;
+  if (value.schema !== 1 || !value.clip || !Array.isArray(value.samples) || value.samples.length < 1) {
+    throw new Error(`[motion-action] invalid trajectory ${url}`);
+  }
+  const samples = value.samples as MotionTrajectorySample[];
+  let previous = -Infinity;
+  for (const sample of samples) {
+    if (
+      sample.length !== 4 ||
+      sample.some((item) => !Number.isFinite(item)) ||
+      sample[0] < previous
+    ) {
+      throw new Error(`[motion-action] invalid trajectory sample in ${url}`);
+    }
+    previous = sample[0];
+  }
+  return { schema: 1, clip: value.clip, samples };
+}
+
+/**
+ * Samples an extracted GLB root curve into ECCTRL's dynamic Rapier body.
+ * The animation GLB stays in-place; only this driver can advance the capsule.
+ */
+export class MotionActionDriver {
+  #controller: MotionActionController;
+  #animations: CharacterAnimations;
+  #trajectory: MotionTrajectory | null = null;
+  #elapsed = 0;
+  #onDone: (() => void) | undefined;
+
+  constructor(controller: MotionActionController, animations: CharacterAnimations) {
+    this.#controller = controller;
+    this.#animations = animations;
+  }
+
+  get active(): boolean {
+    return this.#trajectory !== null;
+  }
+
+  play(trajectory: MotionTrajectory, onDone?: () => void): boolean {
+    this.cancel();
+    if (!this.#animations.playOneShot(trajectory.clip)) return false;
+    this.#trajectory = trajectory;
+    this.#elapsed = 0;
+    this.#onDone = onDone;
+    return true;
+  }
+
+  /** Call once in the fixed-step callback immediately before controller.update(). */
+  update(dt: number): void {
+    const trajectory = this.#trajectory;
+    if (!trajectory || !(dt > 0)) return;
+    const duration = trajectory.samples.at(-1)?.[0] ?? 0;
+    // Release on the callback AFTER the final interval was applied. Clearing
+    // immediately after setActionMotion would erase that velocity before the
+    // caller's following controller.update().
+    if (this.#elapsed >= duration) {
+      this.#finish();
+      return;
+    }
+    const nextTime = Math.min(this.#elapsed + dt, duration);
+    const from = sampleTrajectory(trajectory.samples, this.#elapsed);
+    const to = sampleTrajectory(trajectory.samples, nextTime);
+    const sampleDt = nextTime - this.#elapsed;
+    if (sampleDt > 0) {
+      this.#controller.setActionMotion({
+        x: (to[1] - from[1]) / sampleDt,
+        z: (to[3] - from[3]) / sampleDt,
+      });
+    }
+    this.#elapsed = nextTime;
+  }
+
+  cancel(): void {
+    if (!this.#trajectory) return;
+    this.#controller.setActionMotion(null);
+    this.#trajectory = null;
+    this.#elapsed = 0;
+    this.#onDone = undefined;
+  }
+
+  #finish(): void {
+    const done = this.#onDone;
+    this.#controller.setActionMotion(null);
+    this.#trajectory = null;
+    this.#elapsed = 0;
+    this.#onDone = undefined;
+    done?.();
+  }
+}
+
+export function sampleTrajectory(
+  samples: readonly MotionTrajectorySample[],
+  time: number,
+): MotionTrajectorySample {
+  if (samples.length === 0) return [0, 0, 0, 0];
+  if (time <= samples[0]![0]) return samples[0]!;
+  const last = samples.at(-1)!;
+  if (time >= last[0]) return last;
+  let high = samples.length - 1;
+  let low = 0;
+  while (high - low > 1) {
+    const middle = Math.floor((low + high) / 2);
+    if (samples[middle]![0] <= time) low = middle;
+    else high = middle;
+  }
+  const a = samples[low]!;
+  const b = samples[high]!;
+  const alpha = (time - a[0]) / Math.max(b[0] - a[0], Number.EPSILON);
+  return [
+    time,
+    a[1] + (b[1] - a[1]) * alpha,
+    a[2] + (b[2] - a[2]) * alpha,
+    a[3] + (b[3] - a[3]) * alpha,
+  ];
+}

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

@@ -4,14 +4,14 @@
 // 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):
+// official three-vrm humanoid retargeting example (@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
 // height ratio. Because vrm-loader calls VRMUtils.rotateVRM0, VRM 0.x and 1.0
 // share this one path — no per-version flip.
 //
 // The HIPS POSITION track is kept (delta from the source rest pose, scaled by
-// the hips-height ratio, like the Mixamo recipe). Dropping it pins the hips at
+// the hips-height ratio, like the upstream recipe). Dropping it pins the hips at
 // bind height, so any pose that lowers the hips (idle stance, walk contact,
 // punches) lifts the feet off the floor instead — the UAL idle alone holds the
 // hips ~4.5 cm below rest. All other position tracks are still dropped: the
@@ -134,7 +134,7 @@ export function retargetClips(
   // (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 the map
-  // keys on. (Mixamo names are dotless, so the upstream recipe never needed this.)
+  // keys on. (Many source rigs are dotless, so the upstream example never needed this.)
   const sanitize = (name: string): string => name.replace(/\s/g, "_").replace(/[[\]./:]/g, "");
   const sourceByTrackName = new Map<string, THREE.Object3D>();
   animationRoot.traverse((o) => {
@@ -220,7 +220,7 @@ export function retargetClips(
 
       // Full bind-pose retarget: reproduce the SOURCE bone's world-space motion
       // on the TARGET bone, accounting for BOTH rigs' bind orientations, then
-      // express it in the target's local space. Unlike the simplified Mixamo
+      // express it in the target's local space. Unlike the simplified source-rig
       // recipe (source-rest only), this also uses the VRM normalized bone's bind
       // world rotation — necessary because T-pose limbs are far from identity,
       // which is what left arms pointing straight up before. Reduces to identity

package/templates/skills/genex-ai-character/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: genex-ai-character
+description: Generate a controller-ready Meshy humanoid with Genex, search the committed Meshy animation catalog by gameplay intent, add exact same-rig actions, and install the shared physics controller's Meshy-native adapter. Use when a game needs a custom playable character or motion not covered by the default VRM + UAL lane.
+---
+
+# Genex AI Character
+
+Use the existing VRM + UAL character controller by default. Use this lane when
+the game needs a custom generated humanoid or an action unavailable in UAL.
+Both lanes use the same ECCTRL-derived Rapier controller, camera, inputs,
+crossfades, transition rules, and multiplayer authority contract.
+
+## Generate a controller-ready character
+
+```bash
+npx genex character "stylized desert courier, practical layered clothing"
+```
+
+The default request uses Meshy 6 to generate and texture an A-pose humanoid,
+remeshes and rigs it, adds the validated idle/walk/run/jump controller pack,
+and stores every successful model
+and clip at permanent Genex asset URLs. It prints the complete Genex-credit
+quote before enqueueing. The Meshy API key remains server-side; never ask the
+user for one or call Meshy directly from game code.
+
+Useful options:
+
+```bash
+npx genex character "compact fantasy knight" --height 1.7 --polycount 40000
+npx genex character "retro space pilot" --animation 466 --no-wait
+npx genex wait <generation-id>
+```
+
+`--animation <id-or-query>` is repeatable. `--no-controller-pack` deliberately
+omits the default locomotion pack. `--no-wait` returns a generation id for
+`genex wait`; it does not create a second paid request.
+
+## Search first; use action IDs
+
+```bash
+npx genex animations search "rifle reload" --json
+npx genex animations search "dance" --category Action --limit 8
+npx genex animations search "walk backward" --in-place
+```
+
+Search is local and free: it reads the committed Meshy catalog and returns the
+numeric action ID, stable key, preview URL, motion policy, controller slots,
+requirements, review status, and estimated Genex cost. Use a returned action
+ID. Never invent an ID or assume an unsupported motion exists. For example,
+the current committed catalog has no skateboard action; build that mechanic
+only after search returns real coverage.
+
+Catalog entries are metadata-reviewed. Inspect the preview before choosing a
+specialty action. Only provider-declared `InPlace` loops or measured overrides
+may fill locomotion slots automatically.
+
+## Add actions and refresh the game
+
+```bash
+npx genex character animate <character-id> --action <action-id>
+npx genex character animate <character-id> --action <first-id> --action <second-id> --no-wait
+npx genex controller character --character <character-id>
+```
+
+Ambiguous text queries print ranked candidates instead of silently spending
+credits. Already-installed actions return without another debit. After an
+animation job completes, rerun `genex controller character --character <id>`
+to refresh `public/assets/meshy-character.json`; existing controller source is
+preserved unless `--force` is explicitly used.
+
+Load `$genex-threejs-character-controller` for the actual wiring. The install
+command copies the shared controller plus `character/meshy/meshy-loader.ts`.
+The manifest points at the current rigged model and compact animation-only GLBs
+in R2, and carries the skeleton signature, locomotion slots, fallbacks,
+durations, nominal speeds, trajectories, and gameplay requirements.
+
+## Compatibility and motion authority
+
+- Meshy clips play only on the exact character revision whose skeleton
+  signature matches. There is no runtime retargeting in this lane.
+- Rapier owns the player transform. Animation tracks are normalized
+  horizontally in place; never move the rendered character root separately.
+- `controller-loop` clips follow controller-local intent and measured speed.
+  The state machine crossfades idle, walk, run, jump, directional slots, and
+  explicit fallbacks exactly as it does for VRM + UAL.
+- `anchored-action` is a one-shot at the current controller pose.
+- `planar-root-action` is not enabled for physics movement until the manifest
+  says `rootMotionValidated: true`. The current catalog does not validate root
+  motion, so do not drive a roll or lunge trajectory merely from its name.
+- `choreography` needs game logic for the named prop, partner, ledge, ladder,
+  obstacle, seat, or other environment contract. A clip does not create that
+  mechanic.
+
+For multiplayer, only the owning client advances the dynamic body and publishes
+its pose plus compact animation state. Remote characters are visual-only: they
+interpolate the owner's transform and replay the matching clip progress. Never
+run a motion driver or a second physics controller for a remote player.

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 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.
+description: Add Genex's tuned ECCTRL-derived physics character controller with `npx genex controller character`: dynamic-capsule movement, follow camera, touch input, personal VRM + UAL animation, or an exact same-rig Meshy character. Use for every on-foot player or third-person movement request.
 ---
 
 # Genex Three.js Character Controller
@@ -19,15 +19,32 @@ animation retargeting, capsule auto-fit, foot IK) and the 12-clip core
 ~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` —
+default 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 —
+By default, 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
 a character controller from scratch and do not swap in a kinematic-controller
 tutorial: this one is a real dynamic body that pushes crates, rides moving
 platforms, climbs stairs and slides on too-steep slopes out of the box.
 
+Use the VRM + UAL lane above by default. When the game needs a custom generated
+humanoid or an action unavailable in UAL, load `$genex-ai-character`, search
+Meshy's library first, generate the character, and install it by character ID:
+
+```bash
+npx genex animations search "rifle reload" --json
+npx genex character "stylized sci-fi courier, practical clothing" --animation 466
+npx genex controller character --character <character-id>
+```
+
+That is a separate, **same-rig Meshy-native lane**. Its animation-only GLBs are
+accepted only when their skeleton signature matches the active character
+revision; this lane does no runtime retargeting. The shared ECCTRL-derived
+dynamic controller stays authoritative for collision, grounding, facing, and
+world translation. The animation layer poses the visual rig; it never
+translates the visual root.
+
 Because these files are game-owned, never run `genex controller character --force` over an edited
 fork as a migration strategy. Install a fresh copy elsewhere and port only the named changes.
 
@@ -42,11 +59,13 @@ fork as a migration strategy. Install a fresh copy elsewhere and port only the n
 | `character/follow-camera.ts` | `FollowCamera` | orbit/zoom chase camera with collision pullback and an opt-in pointer-lock aim mode |
 | `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/animation-packs.ts` | `loadCharacterClips` | one call loads the core library + every installed `genex controller anims` pack, retargeted onto the VRM |
+| `character/character-animations.ts` | `CharacterAnimations` | animation state machine, directional profiles, speed-matched cadence, `playOneShot`, procedural fallback |
+| `character/animation-packs.ts` | `loadCharacterClips` | loads the core + installed UAL packs and retargets them to the active VRM |
+| `character/meshy/meshy-loader.ts` | `loadMeshyCharacter` | loads a Meshy manifest, exact-signature model/clips, locomotion slots, and fallbacks |
+| `character/motion-actions.ts` | `MotionActionDriver` | applies only validated planar trajectories through the physics controller, never the visual root |
 | `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
+## Minimal wiring: personal VRM lane
 
 ```ts
 import { PhysicsWorld } from "./controllers/shared/physics-world.ts";
@@ -147,7 +166,7 @@ preset table with provenance, the density/spring scaling rule, and the
 
 ## Animations + animation packs
 
-`CharacterAnimations` resolves nine locomotion states (IDLE / WALK / RUN /
+`CharacterAnimations` resolves 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 —
@@ -155,16 +174,23 @@ 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:
+theme needs** from the 120-clip UAL catalog by tag/name. For motion UAL does
+not cover, use the separate Meshy character lane:
 
 ```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
+npx genex animations search "rifle reload" --json
+npx genex character animate <character-id> --action <action-id>
+npx genex controller character --character <character-id> # refresh the manifest
 ```
 
-Clips land in `public/assets/anims/` and `loadCharacterClips(vrm)` picks them
-up automatically — re-run with more tags any time (additive). Read
+Meshy search results include an action ID, stable key, preview, loop mode,
+motion policy, controller slots, requirements, review status, and estimated
+cost. The installed Meshy manifest supplies exact-signature clips, directional
+slots, fallbacks, and cadence data. UAL clips still land in
+`public/assets/anims/` and are additive. Read
 [references/animations.md](references/animations.md) for the tag catalog with
 genre hints, `playOneShot` options, overrides, foot IK, and remote-player
 animation.
@@ -227,6 +253,9 @@ different world.
 - 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.
+- Only the owning client runs `MotionActionDriver`. Remotes play the same
+  one-shot event while following smoothed owner-authored position/rotation;
+  their animation mixer never moves them through the world.
 - 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,10 +1,10 @@
 # Character animations
 
 `CharacterAnimations` turns the controller's live flags into crossfaded
-`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.
+`THREE.AnimationMixer` playback: core states, directional locomotion profiles,
+alias-based clip binding, one-shots, and a procedural bob/lean fallback. The
+default lane retargets UAL packs to VRM; the Meshy lane plays animation-only
+clips only on the exact matching generated rig revision.
 
 ## The bundled assets + animation packs
 
@@ -70,6 +70,100 @@ cloth). `anims.update` takes the RAW render delta — pause/slow-motion go throu
 `anims.setPaused(true)` / `anims.setTimeScale(0.5)` (fade durations stretch with
 the time scale so slow motion doesn't pop).
 
+## Same-rig Meshy specialty lane
+
+Use this lane when a game needs a custom generated humanoid or catalog depth
+that the personal-VRM library does not cover: sports, dance, tactical actions,
+prop interactions, or authored traversal. Load `$genex-ai-character`, search
+first, generate the controller-ready character, and add exact action IDs:
+
+```bash
+npx genex animations search "rifle reload" --json
+npx genex character "stylized sci-fi courier, practical clothing" --animation 466
+npx genex character animate <character-id> --action <action-id>
+npx genex controller character --character <character-id>
+```
+
+Search output exposes the numeric action ID, stable key, preview, loop mode,
+motion policy, controller slots, gameplay requirements, review status, and
+estimated cost. Use a returned ID; do not guess from a name. Search is free and
+local. Character and animation generation print a Genex-credit quote before
+enqueueing, and successful outputs are copied to permanent R2 URLs.
+
+The install command writes `public/assets/meshy-character.json`. Wire that
+manifest through the **same** physics controller and camera:
+
+```ts
+import { loadMeshyCharacter } from "./controllers/character/meshy/meshy-loader.ts";
+
+const native = await loadMeshyCharacter("./assets/meshy-character.json");
+const fit = capsuleFromModel(native.scene);
+const character = new CharacterController(physics.world, camera, {
+  ...characterPresets["default"].options,
+  ...fit,
+  position: { x: 0, y: 2, z: 0 },
+});
+character.root.add(native.scene);
+native.scene.position.y = fit.modelOffsetY;
+const anims = new CharacterAnimations(native.scene, native.clips, {
+  locomotionProfile: native.locomotionProfile,
+});
+```
+
+The loader rejects clips whose manifest skeleton signature differs from the
+current model revision or whose tracks target missing bones. This is deliberate
+same-rig playback, not runtime retargeting. After adding an action, rerun the
+controller command to refresh the manifest; existing controller source remains
+untouched unless `--force` is explicitly used.
+
+### Directional locomotion and cadence
+
+Meshy manifests can fill slots such as `idle.default`, `walk.forward`,
+`walk.backward`, `walk.left`, `walk.right`, their diagonal variants, matching
+run/crouch slots, transitions, and jump phases. Under `lockForward`, the state
+machine quantizes controller-local input into eight directions with hysteresis;
+under free-facing movement it uses forward locomotion. Playback cadence follows
+controller move speed divided by each band's authored nominal speed, clamped to
+the profile range, so ECCTRL remains authoritative while feet track velocity.
+
+### Motion policies and authored root actions
+
+Meshy results distinguish four policies:
+
+- `controller-loop` — looping locomotion; ECCTRL supplies all translation.
+- `anchored-action` — a one-shot that stays at the current controller pose.
+- `planar-root-action` — a one-shot that may carry an extracted trajectory, but
+  it remains disabled until real output is validated.
+- `choreography` — a multi-actor or constrained sequence; game code owns the
+  participants, anchors, props, and environment contract.
+
+All installed GLBs stay horizontally in-place. A planar trajectory may request
+movement only when its manifest entry says `rootMotionValidated: true`; current
+Meshy manifests publish `false`, so these actions remain anchored. Once a real
+canary validates extraction and synchronization, `MotionActionDriver` feeds the
+trajectory into `CharacterController` immediately before
+`character.update()`:
+
+```ts
+import { loadMotionTrajectory, MotionActionDriver } from "./controllers/character/motion-actions.ts";
+
+const trajectory = await loadMotionTrajectory("./assets/anims/<trajectory-file>.json");
+const motion = new MotionActionDriver(character, anims);
+motion.play(trajectory);
+
+physics.onBeforeStep(() => {
+  character.setMovement(kb.getCharacterMovement());
+  motion.update(physics.world.timestep);
+  character.update();
+});
+```
+
+Resolve the URL from `meshy-character.json`'s `trajectoryUrl` rather than
+guessing it, and refuse it unless `rootMotionValidated` is true. Fulfill every
+declared requirement (`prop`, `partner`, or `environment`) before starting an
+action. Only the owning client runs the driver; remotes play the event while
+following the owner's smoothed transform.
+
 ### Foot IK (optional)
 
 `vrm/foot-ik.ts` plants feet on uneven ground (no skating/floating on steps and
@@ -176,18 +270,21 @@ run `--list <tag>` for per-clip descriptions before wiring one-shots:
 | `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
+For legacy-library 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. All clips
-are in-place (no root motion) — the physics controller owns all translation.
+`$genex-threejs-vehicle-controllers` skill shows the seated pattern. UAL clips
+are in-place. Meshy planar actions remain anchored until their manifest
+explicitly validates the extracted trajectory; in every case the physics
+controller owns world translation.
 
-## Binding arbitrary rigs (Mixamo included)
+## Binding arbitrary clip names on a compatible rig
 
 `buildClipMap(clips, overrides?)` resolves each state in priority order:
 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`,
+matching clip name wins (so `Walk_Loop` beats `Walk_Bwd_Loop`, and `walking`
+beats `walking_backwards`). Aliases include `idle`, `walk`, `run`,
 `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
@@ -195,7 +292,9 @@ matching clip name wins (so `Walk_Loop` beats `Walk_Bwd_Loop`, and Mixamo's
 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:
+This resolves names; it does **not** make incompatible skeletons compatible.
+Only pass clips already retargeted to the VRM or authored for the exact Meshy
+rig revision. If a compatible clip name refuses to bind, pass overrides:
 
 ```ts
 const anims = new CharacterAnimations(model, gltf.animations, {
@@ -260,11 +359,12 @@ remoteAnims.update(remoteState.flags, delta);
 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 —
-load each remote through `loadVrm` + `retargetClips` just like the local one, and
-call `vrm.update(delta)` per remote each frame. Relay one-shot events (punch, hit)
-alongside the flags and call `remoteAnims.playOneShot("Hit_Chest")` on receipt.
+correctly without simulating anything. Use the same visual lane as the owner:
+`loadVrm` + retargeted UAL clips for a VRM game (and call `vrm.update(delta)`
+per remote), or `loadMeshyCharacter` for a Meshy game. Relay one-shot events (punch,
+hit, validated planar-action start) alongside the flags and call the matching
+`remoteAnims.playOneShot(...)` on receipt. Never run `MotionActionDriver` for a
+remote: its smoothed owner-authored transform is the sole movement authority.
 Full networking patterns: `$genex-threejs-multiplayer`.
 
 ## Gotchas

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

@@ -16,7 +16,8 @@ map, execution order, and acceptance gate.
 | Work needed | Load |
 | --- | --- |
 | 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, floating origins | `$genex-threejs-camera-direction` |
-| 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` |
+| 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: search, generate, rig, add exact action IDs, install the same-rig adapter | `$genex-ai-character` + `$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` |
@@ -53,6 +54,14 @@ map, execution order, and acceptance gate.
 mentions sign-in, saves, progress, per-player state, a persistent world, or
 leaderboards. Multiplayer auth (`getColyseusAuth`) comes from it too.
 
+**Character-animation routing:** use the existing VRM + UAL character
+controller by default. Use `npx genex character` when the game needs a custom
+generated humanoid or an action unavailable in UAL. Load `$genex-ai-character`,
+search Meshy actions first with `npx genex animations search "<intent>" --json`,
+and use returned action IDs; never invent IDs or move the visual root. In both
+lanes, the ECCTRL-derived character controller owns collision and world
+translation.
+
 **UI is mandatory routing:** every game has an interface — load
 `$genex-threejs-game-ui` for every NEW game and run its "Plan the UI first" gate
 (screen inventory, one shared style brief, tier decisions) right after the game
@@ -113,7 +122,8 @@ commit. Each skill has the exact Three.js loader code.
 
 | Work needed | Generate with | Skill |
 | --- | --- | --- |
-| a specific prop / item / character / vehicle as a real mesh | `npx genex model "<prompt>"` | `$genex-ai-model` |
+| a specific prop / item / non-playable static figure / vehicle body as a real mesh | `npx genex model "<prompt>"` | `$genex-ai-model` |
+| a custom generated playable humanoid with a rig and controller-ready animation pack | `npx genex character "<prompt>"` | `$genex-ai-character` |
 | 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` |