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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@genex-ai/cli-demo",
-  "version": "0.53.0-dev.121",
+  "version": "0.54.0-dev.123",
   "description": "Set up your ~/.claude workspace, authorize, create a game project, generate AI assets, and publish (genex CLI).",
   "type": "module",
   "bin": {
@@ -41,6 +41,7 @@
   },
   "devDependencies": {
     "@dimforge/rapier3d-compat": "^0.19.3",
+    "@genex/meshy-animation-catalog": "workspace:*",
     "@genex-ai/multiplayer": "workspace:*",
     "@pixiv/three-vrm": "^3.5.4",
     "@types/pngjs": "^6.0.5",

package/templates/controllers/character/animation-packs.ts

@@ -1,26 +1,11 @@
 // SPDX-License-Identifier: MIT
-// One-call animation loading for the character controller (Genex AG-775):
-// the bundled core library (./assets/animation-library.glb, 12 locomotion +
-// crouch + hit/death clips) PLUS every animation pack installed by
-// `genex controller anims <tags|clips…>` (./assets/anims/<Clip>.glb, listed in
-// ./assets/anims/manifest.json). Everything is retargeted onto the given VRM —
-// the per-file rig auto-detect in vrm-retarget.ts handles both the UE-style
-// UAL Pro rig and the older Rigify DEF-* rig — and returned as one flat clip
-// array ready for `new CharacterAnimations(scene, clips)`.
-//
-//   const { scene, vrm } = await loadVrm("./assets/avatar.vrm");
-//   const clips = await loadCharacterClips(vrm);
-//   const anims = new CharacterAnimations(scene, clips);
-//
-// Games that never ran `genex controller anims` just get the core clips (the
-// manifest fetch 404s and is ignored). Packs added later are picked up on the
-// next page load — no code change.
+// One-call loading for the proven VRM + UAL lane. Meshy-native characters load
+// their exact-rig clips from meshy/meshy-loader.ts and never enter this retargeter.
 import type * as THREE from "three";
 import { GLTFLoader } from "three/addons/loaders/GLTFLoader.js";
 import type { VRM } from "@pixiv/three-vrm";
 import { retargetClips } from "./vrm/vrm-retarget.ts";
 
-/** Shape of ./assets/anims/manifest.json (written by `genex controller anims`). */
 interface AnimsManifest {
   schema: number;
   clips: string[];
@@ -31,11 +16,7 @@ export interface LoadCharacterClipsOptions {
   base?: string;
 }
 
-/**
- * Load + retarget every animation the game has: the bundled core library and
- * all installed pack clips. Missing pack files are skipped with a console
- * warning (the game still runs on the clips that loaded).
- */
+/** Load the bundled UAL core and every optional UAL pack onto a VRM avatar. */
 export async function loadCharacterClips(
   vrm: VRM,
   options: LoadCharacterClipsOptions = {},
@@ -65,6 +46,5 @@ export async function loadCharacterClips(
       if (pack !== null) clips.push(...retargetClips(vrm, pack.scene, pack.animations));
     }
   }
-
   return clips;
 }

package/templates/controllers/character/character-animations.ts

@@ -69,6 +69,33 @@ export interface CharacterStateSnapshot {
   readonly crouchActive?: boolean;
 }
 
+export type LocomotionDirection =
+  | "forward"
+  | "forward-right"
+  | "right"
+  | "backward-right"
+  | "backward"
+  | "backward-left"
+  | "left"
+  | "forward-left";
+
+export interface AdvancedCharacterStateSnapshot extends CharacterStateSnapshot {
+  readonly inputDir: THREE.Vector3;
+  readonly relativeVelOnPlane: THREE.Vector3;
+  readonly bodyXAxis: THREE.Vector3;
+  readonly bodyZAxis: THREE.Vector3;
+  readonly moveSpeed: number;
+  readonly lockForward: boolean;
+}
+
+export interface LocomotionProfile {
+  /** Explicit semantic slot → stable clip id. Unavailable slots use declared fallbacks. */
+  slots: Readonly<Record<string, string>>;
+  nominalSpeed?: Partial<Record<"walk" | "run" | "crouch", number>>;
+  playbackRate?: { min: number; max: number };
+  directionHysteresisDegrees?: number;
+}
+
 /** Snapshot plus the previous frame's ground flag (derived internally by CharacterAnimations). */
 export interface AnimationStateContext extends CharacterStateSnapshot {
   readonly wasOnGround: boolean;
@@ -103,7 +130,7 @@ export function resolveAnimationState(ctx: AnimationStateContext): CharacterAnim
 }
 
 // ---------------------------------------------------------------------------
-// Clip lookup (NEW — alias-based fuzzy binding so UAL, Mixamo-named, or arbitrary rigs work)
+// Clip lookup (alias-based fuzzy naming for clips already compatible with the active rig)
 // ---------------------------------------------------------------------------
 
 /** Resolved clip NAME per state; null = unbound (procedural fallback may take over). */
@@ -160,7 +187,7 @@ const CLIP_SEARCH: Record<CharacterAnimationState, ClipSearchSpec> = {
  *
  * Per state, first match wins: explicit override (exact, then case-insensitive) → UAL exact
  * names → UAL 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
+ * clip name wins, so `Walk_Loop` beats `Walk_Bwd_Loop` and a generic `walking` beats
  * `walking_backwards`). Afterwards LOOP-state holes are chained (RUN↔WALK, JUMP_IDLE↔JUMP_FALL)
  * so partially-animated rigs still move; one-shot states (JUMP_START/JUMP_LAND) stay null when
  * unbound so the previous loop keeps playing (upstream behavior) instead of clamping a loop clip.
@@ -233,7 +260,7 @@ export function buildClipMap(
   if (map.JUMP_FALL === null) map.JUMP_FALL = map.JUMP_IDLE;
   if (map.JUMP_IDLE === null) map.JUMP_IDLE = map.JUMP_FALL;
   // Crouch degrades to the standing loops on rigs without crouch clips (old
-  // 46-clip libraries, Mixamo exports) — wrong pose beats a frozen T-pose.
+  // 46-clip libraries and same-rig catalog exports) — wrong pose beats a frozen T-pose.
   if (map.CROUCH_IDLE === null) map.CROUCH_IDLE = map.IDLE;
   if (map.CROUCH_MOVE === null) map.CROUCH_MOVE = map.WALK ?? map.CROUCH_IDLE;
   return map;
@@ -283,6 +310,8 @@ export interface CharacterAnimationsOptions {
    * "none": do nothing when unbound (model stays static).
    */
   fallback?: "auto" | "procedural" | "none";
+  /** Optional controller-aware directional locomotion profile. */
+  locomotionProfile?: LocomotionProfile;
 }
 
 /** Options for {@link CharacterAnimations.playOneShot}. */
@@ -323,6 +352,7 @@ export class CharacterAnimations {
   // locomotion states (any installed pack clip: Punch_*, Sword_*, Sitting_*…).
   #clipsByName = new Map<string, THREE.AnimationClip>();
   #oneShotAction: THREE.AnimationAction | null = null;
+  #locomotionOneShotAction: THREE.AnimationAction | null = null;
   #oneShotOnDone: (() => void) | undefined;
   // When true, the active one-shot holds its final pose on finish (clamp:true —
   // e.g. Death01) instead of crossfading back to locomotion.
@@ -348,12 +378,17 @@ export class CharacterAnimations {
 
   #disposed = false;
   #onFinished: (event: { action: THREE.AnimationAction }) => void;
+  #locomotionProfile: LocomotionProfile | undefined;
+  #desiredMotionName: string | null;
+  #lastDirection: LocomotionDirection = "forward";
+  #lastSpeedBand: "walk" | "run" | "crouch" = "walk";
+  #previousMoving = false;
 
   /**
    * @param model root Object3D of the character visual (mixer root; also the transform target
    *              for the procedural fallback).
    * @param clips animation clips (e.g. `gltf.animations` from the bundled animation library, a
-   *              Mixamo export, or `[]` — an empty array triggers the procedural fallback
+   *              source-biped export, or `[]` — an empty array triggers the procedural fallback
    *              under the default `"auto"` mode).
    */
   constructor(
@@ -365,6 +400,7 @@ export class CharacterAnimations {
     this.#clipMap = buildClipMap(clips, options.clipMap);
     this.#resolver = options.resolver ?? resolveAnimationState;
     this.#onChange = options.onChange;
+    this.#locomotionProfile = options.locomotionProfile;
     this.mixer = new THREE.AnimationMixer(model);
     for (const clip of clips) this.#clipsByName.set(clip.name, clip);
 
@@ -375,6 +411,10 @@ export class CharacterAnimations {
       const name = this.#clipMap[state];
       if (name !== null) boundNames.add(name);
     }
+    for (const name of Object.values(this.#locomotionProfile?.slots ?? {})) {
+      if (this.#clipsByName.has(name)) boundNames.add(name);
+      else console.warn(`[CharacterAnimations] locomotion slot clip "${name}" is not installed.`);
+    }
     for (const clip of clips) {
       if (boundNames.has(clip.name) && !this.#actions.has(clip.name)) {
         this.#actions.set(clip.name, this.mixer.clipAction(clip));
@@ -390,7 +430,9 @@ export class CharacterAnimations {
     this.#basePositionY = model.position.y;
     this.#baseRotationX = model.rotation.x;
 
-    this.#prevActionName = this.#clipMap.IDLE;
+    this.#desiredMotionName =
+      this.#resolveProfileSlot("idle.default") ?? this.#clipMap.IDLE;
+    this.#prevActionName = this.#desiredMotionName;
     if (this.#prevActionName !== null) {
       // NEW vs upstream: start the idle clip immediately (upstream stayed in bind pose
       // until the first state change).
@@ -432,6 +474,11 @@ export class CharacterAnimations {
         done?.();
         return;
       }
+      if (this.#locomotionOneShotAction && event.action === this.#locomotionOneShotAction) {
+        this.#locomotionOneShotAction = null;
+        this.#canPlayNext = true;
+        return;
+      }
       const clipName = event.action.getClip().name;
       if (
         !this.#canPlayNext &&
@@ -453,6 +500,11 @@ export class CharacterAnimations {
     return this.#clipMap;
   }
 
+  /** Clip currently posing the locomotion layer (stable id for advanced profiles). */
+  get activeClipName(): string | null {
+    return this.#prevActionName;
+  }
+
   /**
    * True while a {@link playOneShot} clip is playing (or holding its final
    * pose with `holdPose`). Feed `() => !anims.oneShotActive` to foot IK's
@@ -496,13 +548,30 @@ export class CharacterAnimations {
     // equivalent of upstream's effect re-running on canPlayNext changes: after a one-shot
     // (Jump_Start/Jump_Land) finishes and unlocks, the pending loop clip must still fade in
     // even though the state did not change again. Internal guards make this a no-op otherwise.
+    this.#desiredMotionName = this.#resolveLocomotionClip(snapshot, next) ?? this.#clipMap[next];
+    // A full-jump profile clip may outlast a very short physics hop. Release
+    // its one-shot lock as soon as the controller lands so idle/walk can
+    // crossfade immediately instead of waiting for the authored clip to end.
+    if (this.#locomotionOneShotAction && ctx.isOnGround && next !== "JUMP_START") {
+      this.#locomotionOneShotAction = null;
+      this.#canPlayNext = true;
+    }
+    const movingNow = ctx.isMoving && ctx.isOnGround;
+    if (this.#locomotionProfile && movingNow !== this.#previousMoving && !this.oneShotActive) {
+      const transition = movingNow
+        ? this.#resolveProfileSlot(`start.${this.#lastSpeedBand}.${this.#lastDirection}`)
+        : this.#resolveProfileSlot(`stop.${this.#lastSpeedBand}.${this.#lastDirection}`);
+      if (transition) this.playOneShot(transition, { fadeIn: ONE_SHOT_FADE_DURATION });
+    }
     this.#applyTransition();
+    this.#updateLocomotionRate(snapshot, next);
     if (stateChanged) {
       // Context copy: the live ctx object is reused every frame.
       this.#onChange?.(next, { ...ctx });
     }
 
     this.#previousIsOnGround = snapshot.isOnGround;
+    this.#previousMoving = movingNow;
     this.#initialized = true;
 
     this.#releaseStuckLocks();
@@ -594,6 +663,7 @@ export class CharacterAnimations {
       this.mixer.uncacheClip(action.getClip());
     }
     this.#actions.clear();
+    this.#locomotionOneShotAction = null;
   }
 
   /**
@@ -605,7 +675,7 @@ export class CharacterAnimations {
    * no bound loop (procedural fallback / previous clip keeps the rig posed).
    */
   #recoverFromOneShot(finished: THREE.AnimationAction): void {
-    const name = this.#clipMap[this.#state];
+    const name = this.#desiredMotionName;
     const loopAction = name !== null ? this.#actions.get(name) : undefined;
     if (!loopAction) {
       this.#prevActionName = null;
@@ -627,7 +697,7 @@ export class CharacterAnimations {
    * effect re-running on both state and canPlayNext changes.
    */
   #applyTransition(): void {
-    const nextName = this.#clipMap[this.#state];
+    const nextName = this.#desiredMotionName;
     // Unbound state: keep the previous action playing (upstream's `if (!nextAction) return`);
     // on a fully rig-less model the procedural fallback drives the transform instead.
     if (nextName === null) return;
@@ -647,8 +717,20 @@ export class CharacterAnimations {
 
       // One-shot detection is by CLIP NAME, not state, so a shared clip inherits
       // one-shot behavior exactly like upstream's name-keyed actions.
-      if (nextName === this.#clipMap.JUMP_START || nextName === this.#clipMap.JUMP_LAND) {
+      const profileJumpStart =
+        this.#state === "JUMP_START" && nextName === this.#resolveProfileSlot("jump.start");
+      const profileJumpLand =
+        this.#state === "JUMP_LAND" &&
+        nextName === this.#resolveProfileSlot("jump.land") &&
+        nextName !== this.#resolveProfileSlot("idle.default");
+      if (
+        nextName === this.#clipMap.JUMP_START ||
+        nextName === this.#clipMap.JUMP_LAND ||
+        profileJumpStart ||
+        profileJumpLand
+      ) {
         this.#canPlayNext = false;
+        this.#locomotionOneShotAction = nextAction;
         nextAction.timeScale = ONE_SHOT_TIME_SCALE;
         nextAction.reset();
         if (prevAction) {
@@ -722,4 +804,111 @@ export class CharacterAnimations {
     this.#model.position.y = this.#basePositionY + this.#bobOffset;
     this.#model.rotation.x = this.#baseRotationX + this.#leanOffset;
   }
+
+  #resolveProfileSlot(slot: string): string | null {
+    const name = this.#locomotionProfile?.slots[slot];
+    return name && this.#clipsByName.has(name) ? name : null;
+  }
+
+  #resolveLocomotionClip(
+    snapshot: CharacterStateSnapshot,
+    state: CharacterAnimationState,
+  ): string | null {
+    if (!this.#locomotionProfile) return null;
+    if (state === "IDLE") return this.#resolveProfileSlot("idle.default");
+    if (state === "CROUCH_IDLE") {
+      return this.#resolveProfileSlot("crouch.idle") ?? this.#resolveProfileSlot("idle.default");
+    }
+    const jumpSlot: Partial<Record<CharacterAnimationState, string>> = {
+      JUMP_START: "jump.start",
+      JUMP_IDLE: "jump.rise",
+      JUMP_FALL: "jump.fall",
+      JUMP_LAND: "jump.land",
+    };
+    const airborne = jumpSlot[state];
+    if (airborne) return this.#resolveProfileSlot(airborne);
+    if (state !== "WALK" && state !== "RUN" && state !== "CROUCH_MOVE") return null;
+    if (!isAdvancedSnapshot(snapshot)) return null;
+
+    const band = state === "RUN" ? "run" : state === "CROUCH_MOVE" ? "crouch" : "walk";
+    const direction = snapshot.lockForward ? this.#resolveDirection(snapshot) : "forward";
+    this.#lastDirection = direction;
+    this.#lastSpeedBand = band;
+    const candidates = directionFallbacks(band, direction);
+    for (const slot of candidates) {
+      const clip = this.#resolveProfileSlot(slot);
+      if (clip) return clip;
+    }
+    return null;
+  }
+
+  #resolveDirection(snapshot: AdvancedCharacterStateSnapshot): LocomotionDirection {
+    const x = snapshot.inputDir.dot(snapshot.bodyXAxis);
+    const z = snapshot.inputDir.dot(snapshot.bodyZAxis);
+    if (x * x + z * z < 1e-6) return this.#lastDirection;
+    const angle = Math.atan2(x, z);
+    const directions: readonly LocomotionDirection[] = [
+      "forward",
+      "forward-right",
+      "right",
+      "backward-right",
+      "backward",
+      "backward-left",
+      "left",
+      "forward-left",
+    ];
+    const candidate = directions[(Math.round(angle / (Math.PI / 4)) + 8) % 8]!;
+    const previousAngle = directions.indexOf(this.#lastDirection) * (Math.PI / 4);
+    const normalizedAngle = angle < 0 ? angle + Math.PI * 2 : angle;
+    const delta = Math.abs(Math.atan2(Math.sin(normalizedAngle - previousAngle), Math.cos(normalizedAngle - previousAngle)));
+    const threshold = THREE.MathUtils.degToRad(
+      22.5 + (this.#locomotionProfile?.directionHysteresisDegrees ?? 7.5),
+    );
+    return delta <= threshold ? this.#lastDirection : candidate;
+  }
+
+  #updateLocomotionRate(
+    snapshot: CharacterStateSnapshot,
+    state: CharacterAnimationState,
+  ): void {
+    if (!this.#locomotionProfile || !isAdvancedSnapshot(snapshot) || this.oneShotActive) return;
+    const band = state === "RUN" ? "run" : state === "CROUCH_MOVE" ? "crouch" : state === "WALK" ? "walk" : null;
+    if (!band || !this.#prevActionName) return;
+    const nominal = this.#locomotionProfile.nominalSpeed?.[band];
+    if (!nominal || nominal <= 0) return;
+    const limits = this.#locomotionProfile.playbackRate ?? { min: 0.75, max: 1.35 };
+    const rate = THREE.MathUtils.clamp(snapshot.moveSpeed / nominal, limits.min, limits.max);
+    this.#actions.get(this.#prevActionName)?.setEffectiveTimeScale(rate);
+  }
+}
+
+function isAdvancedSnapshot(
+  snapshot: CharacterStateSnapshot,
+): snapshot is AdvancedCharacterStateSnapshot {
+  const value = snapshot as Partial<AdvancedCharacterStateSnapshot>;
+  return (
+    typeof value.moveSpeed === "number" &&
+    typeof value.lockForward === "boolean" &&
+    value.inputDir instanceof THREE.Vector3 &&
+    value.relativeVelOnPlane instanceof THREE.Vector3 &&
+    value.bodyXAxis instanceof THREE.Vector3 &&
+    value.bodyZAxis instanceof THREE.Vector3
+  );
+}
+
+function directionFallbacks(
+  band: "walk" | "run" | "crouch",
+  direction: LocomotionDirection,
+): string[] {
+  const exact = `${band}.${direction}`;
+  const cardinal = direction.includes("backward")
+    ? `${band}.backward`
+    : direction.includes("right")
+      ? `${band}.right`
+      : direction.includes("left")
+        ? `${band}.left`
+        : `${band}.forward`;
+  const ownForward = `${band}.forward`;
+  const walkEquivalent = `walk.${direction}`;
+  return [...new Set([exact, cardinal, ownForward, walkEquivalent, "walk.forward"])];
 }

package/templates/controllers/character/character-controller.ts

@@ -53,6 +53,14 @@ export type MovementInput = {
   crouch?: boolean;
 };
 
+/** Local planar velocity for a collision-aware authored root action (m/s). */
+export interface CharacterActionMotion {
+  /** Right/left velocity along the character's local X axis. */
+  x: number;
+  /** Forward/back velocity along the character's local Z axis. */
+  z: number;
+}
+
 /** Read-only view of the merged movement state (returned by the `input` getter). */
 export type ReadonlyMovementInput = Readonly<Omit<MovementInput, "joystick">> & {
   readonly joystick?: Readonly<{ x: number; y: number }>;
@@ -433,6 +441,9 @@ export class CharacterController {
   private readonly movingDirCrossAxis = new THREE.Vector3();
   private readonly wantToMoveVel = new THREE.Vector3();
   private readonly rejectVel = new THREE.Vector3();
+  private readonly actionLocalVelocity = new THREE.Vector2();
+  private readonly actionWorldVelocity = new THREE.Vector3();
+  private actionMotionEnabled = false;
 
   // ── jump ──
   private _isOnGround = false;
@@ -771,6 +782,10 @@ export class CharacterController {
   get lockForward(): boolean {
     return this.isLockForward;
   }
+  /** True while an authored trajectory, rather than player input, owns planar velocity. */
+  get actionMotionActive(): boolean {
+    return this.actionMotionEnabled;
+  }
   /** Per-step rotation of the platform under the character (identity when off-platform). Live quaternion. */
   get turnOnYQuat(): THREE.Quaternion {
     return this._turnOnYQuat;
@@ -803,6 +818,26 @@ export class CharacterController {
     if (movement.crouch !== undefined) this.movementState.crouch = movement.crouch;
   }
 
+  /**
+   * Give an authored action collision-aware planar motion without moving the visual root.
+   * Call with a fresh local velocity before each physics step; call with `null` to return
+   * authority to normal ECCTRL input. Vertical velocity, gravity, slopes, and collisions
+   * remain owned by the dynamic Rapier body.
+   */
+  setActionMotion(motion: CharacterActionMotion | null): void {
+    if (motion === null) {
+      this.actionMotionEnabled = false;
+      this.actionLocalVelocity.set(0, 0);
+      return;
+    }
+    if (!Number.isFinite(motion.x) || !Number.isFinite(motion.z)) {
+      throw new Error("Character action motion must be finite");
+    }
+    this.actionMotionEnabled = true;
+    this.actionLocalVelocity.set(motion.x, motion.z);
+    this._body.wakeUp();
+  }
+
   /**
    * Programmatic crouch request (e.g. an on-screen crouch button:
    * `btnCrouch.onPress = () => character.setCrouch(!character.crouchActive)`).
@@ -944,6 +979,7 @@ export class CharacterController {
       jump ||
       this.movementState.crouch ||
       crouch !== crouchWasActive ||
+      this.actionMotionEnabled ||
       Math.abs(joystick.x) > 1e-4 ||
       Math.abs(joystick.y) > 1e-4;
 
@@ -967,7 +1003,7 @@ export class CharacterController {
     // movement use current-frame input.
     this.updateForwardDirection();
     this.setInputDirection({ forward, backward, rightward, leftward, joystick });
-    const hasMoveInput = this._inputDir.lengthSq() > 0;
+    const hasMoveInput = this._inputDir.lengthSq() > 0 && !this.actionMotionEnabled;
 
     // Update character auto balance
     // (NOTE: consumes LAST step's isZeroGravity — refreshed below; upstream parity)
@@ -1039,6 +1075,8 @@ export class CharacterController {
       }
     }
 
+    if (this.actionMotionEnabled) this.applyActionMotion();
+
     // Update debug indicators
     if (this.debugEnabled) this.updateDebugger();
   }
@@ -1195,6 +1233,23 @@ export class CharacterController {
     this._body.applyTorqueImpulse(torque.multiplyScalar(fpsCorr), false);
   }
 
+  /** Replace only relative planar velocity; the dynamic body still resolves contacts. */
+  private applyActionMotion(): void {
+    const liveVelocity = this._body.linvel();
+    this.actionWorldVelocity
+      .copy(this.characterXAxis)
+      .multiplyScalar(this.actionLocalVelocity.x)
+      .addScaledVector(this.characterZAxis, this.actionLocalVelocity.y)
+      .projectOnPlane(this.referenceUpAxis)
+      // Read the LIVE vertical component after float/jump impulses above; using
+      // the cached start-of-step velocity here would erase those physics effects.
+      .addScaledVector(this.referenceUpAxis, this.referenceUpAxis.dot(liveVelocity));
+    if (this.isOnMovingObject && this.followPlatform) {
+      this.actionWorldVelocity.add(this.movingObjectVelocityOnPlane);
+    }
+    this._body.setLinvel(this.actionWorldVelocity, true);
+  }
+
   /**
    * Ground-query collider filter (upstream l.539-542; userData key renamed
    * `ecctrl` -> `controller`).

package/templates/controllers/character/meshy/meshy-loader.ts

@@ -0,0 +1,137 @@
+// SPDX-License-Identifier: MIT
+import * as THREE from "three";
+import { GLTFLoader } from "three/addons/loaders/GLTFLoader.js";
+import type { LocomotionProfile } from "../character-animations.ts";
+
+export type MeshyMotionPolicy =
+  | "controller-loop"
+  | "anchored-action"
+  | "planar-root-action"
+  | "choreography";
+
+export interface MeshyCharacterManifest {
+  schema: 1;
+  characterId: string;
+  revision: number;
+  manifestVersion: number;
+  rig: "meshy-biped";
+  model: {
+    url: string;
+    heightMeters: number | null;
+    skeletonSignature: string;
+  };
+  clips: Array<{
+    actionId: number;
+    key: string;
+    name: string;
+    url: string;
+    duration: number | null;
+    loop: boolean;
+    motionPolicy: MeshyMotionPolicy;
+    rootMotionValidated: boolean;
+    controllerSlots: string[];
+    nominalSpeed: number | null;
+    trajectoryUrl: string | null;
+    requirements: Record<string, unknown>;
+    skeletonSignature: string;
+  }>;
+  locomotion: {
+    slots: Record<string, string>;
+    fallbacks: Record<string, string>;
+    nominalSpeed?: Partial<Record<"walk" | "run" | "crouch", number>>;
+    playbackRate: { min: number; max: number };
+  };
+}
+
+export interface MeshyCharacter {
+  kind: "meshy-native";
+  scene: THREE.Group;
+  clips: THREE.AnimationClip[];
+  manifest: MeshyCharacterManifest;
+  rigSignature: string;
+  locomotionProfile: LocomotionProfile;
+  update(delta: number): void;
+  dispose(): void;
+}
+
+function validateManifest(value: unknown): MeshyCharacterManifest {
+  const manifest = value as Partial<MeshyCharacterManifest> | null;
+  if (
+    !manifest ||
+    manifest.schema !== 1 ||
+    manifest.rig !== "meshy-biped" ||
+    !manifest.model?.url ||
+    !manifest.model.skeletonSignature ||
+    !Array.isArray(manifest.clips) ||
+    !manifest.locomotion?.slots
+  ) {
+    throw new Error("[meshy-character] invalid character manifest");
+  }
+  return manifest as MeshyCharacterManifest;
+}
+
+function compatibleTracks(model: THREE.Object3D, clips: THREE.AnimationClip[]): THREE.AnimationClip[] {
+  return clips.filter((clip) => clip.tracks.every((track) => {
+    const parsed = THREE.PropertyBinding.parseTrackName(track.name);
+    return parsed.nodeName !== undefined && model.getObjectByName(parsed.nodeName) !== undefined;
+  }));
+}
+
+export async function loadMeshyCharacter(manifestUrl: string): Promise<MeshyCharacter> {
+  const response = await fetch(manifestUrl);
+  if (!response.ok) throw new Error(`[meshy-character] ${manifestUrl} returned HTTP ${response.status}`);
+  const manifest = validateManifest(await response.json());
+  const loader = new GLTFLoader();
+  const base = await loader.loadAsync(manifest.model.url);
+  const clips: THREE.AnimationClip[] = [...base.animations];
+  const loaded = await Promise.all(manifest.clips.map(async (entry) => {
+    if (entry.skeletonSignature !== manifest.model.skeletonSignature) {
+      console.warn(`[meshy-character] ${entry.key} belongs to another rig revision — skipped.`);
+      return null;
+    }
+    try {
+      return { entry, gltf: await loader.loadAsync(entry.url) };
+    } catch {
+      console.warn(`[meshy-character] ${entry.key} failed to load — skipped.`);
+      return null;
+    }
+  }));
+  for (const item of loaded) {
+    if (!item) continue;
+    const compatible = compatibleTracks(base.scene, item.gltf.animations);
+    if (compatible.length !== item.gltf.animations.length) {
+      console.warn(`[meshy-character] ${item.entry.key} has tracks missing from the active rig — skipped.`);
+      continue;
+    }
+    if (compatible.length === 1) compatible[0]!.name = item.entry.key;
+    clips.push(...compatible);
+  }
+  const slots = { ...manifest.locomotion.slots };
+  for (const [slot, fallback] of Object.entries(manifest.locomotion.fallbacks)) {
+    if (!slots[slot] && slots[fallback]) slots[slot] = slots[fallback];
+  }
+  return {
+    kind: "meshy-native",
+    scene: base.scene,
+    clips,
+    manifest,
+    rigSignature: manifest.model.skeletonSignature,
+    locomotionProfile: {
+      slots,
+      nominalSpeed: manifest.locomotion.nominalSpeed,
+      playbackRate: manifest.locomotion.playbackRate,
+    },
+    update() {
+      // Native GLTF rigs do not need VRM's normalized-bone maintenance pass.
+    },
+    dispose() {
+      base.scene.traverse((object) => {
+        if (!(object instanceof THREE.Mesh)) return;
+        object.geometry.dispose();
+        const materials = Array.isArray(object.material) ? object.material : [object.material];
+        for (const material of materials) material.dispose();
+      });
+      base.scene.removeFromParent();
+    },
+  };
+}