@genex-ai/cli-demo 0.85.0-dev.216 → 0.86.0-dev.217

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@genex-ai/cli-demo",
-  "version": "0.85.0-dev.216",
+  "version": "0.86.0-dev.217",
   "description": "Set up your project's agent workspace (.claude/.codex/.cursor in the game folder), authorize, create a game project, generate AI assets, and publish (genex CLI).",
   "type": "module",
   "bin": {

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

@@ -324,6 +324,17 @@ export interface PlayOneShotOptions {
   clamp?: boolean;
   /** Fired when the clip finishes (skipped if a newer one-shot interrupts it). */
   onDone?: () => void;
+  /**
+   * Movement cancels this one-shot. Every one-shot is FULL-BODY (there is no
+   * upper-body layering), so it freezes the legs — a moving character SLIDES
+   * across the ground in a static pose for the clip's whole length (a 2.9s hit
+   * reaction, a 2.7s cast). With `interruptible: true`, grounded movement
+   * intent releases the clip via {@link CharacterAnimations.clearOneShot} and
+   * locomotion takes over immediately. Use it for reactions and gestures a
+   * player can walk out of; leave it off for poses that must hold to their end
+   * (a death/knockdown). Default false.
+   */
+  interruptible?: boolean;
 }
 
 type MutableAnimationStateContext = {
@@ -358,6 +369,9 @@ export class CharacterAnimations {
   // When true, the active one-shot holds its final pose on finish (clamp:true —
   // e.g. Death01) instead of crossfading back to locomotion.
   #oneShotHoldPose = false;
+  // When true, grounded movement intent cancels the active one-shot (see
+  // PlayOneShotOptions.interruptible).
+  #oneShotInterruptible = false;
 
   #state: CharacterAnimationState = "IDLE";
   #prevActionName: string | null;
@@ -398,7 +412,27 @@ export class CharacterAnimations {
     options: CharacterAnimationsOptions = {}
   ) {
     this.#model = model;
-    this.#clipMap = buildClipMap(clips, options.clipMap);
+    // Seed the fuzzy name-matched map from the locomotion profile's own slots
+    // (explicit options.clipMap still wins). Simple boolean snapshots (remote
+    // players, bots) never reach the profile's directional resolver and fall
+    // through to this map — without the seed they bind DIFFERENT clips than the
+    // local player ("Running" vs the profile's run.forward), so the same
+    // movement renders as two different gaits on two screens. Jump states are
+    // deliberately NOT seeded: jump.full would one-shot-clamp as a loop.
+    const slots = options.locomotionProfile?.slots ?? {};
+    const profileSeed: Partial<Record<CharacterAnimationState, string>> = {};
+    const seedPairs: ReadonlyArray<[CharacterAnimationState, string]> = [
+      ["IDLE", "idle.default"],
+      ["WALK", "walk.forward"],
+      ["RUN", "run.forward"],
+      ["CROUCH_IDLE", "crouch.idle"],
+      ["CROUCH_MOVE", "crouch.forward"],
+    ];
+    for (const [state, slot] of seedPairs) {
+      const clip = slots[slot];
+      if (clip) profileSeed[state] = clip;
+    }
+    this.#clipMap = buildClipMap(clips, { ...profileSeed, ...options.clipMap });
     this.#resolver = options.resolver ?? resolveAnimationState;
     this.#onChange = options.onChange;
     this.#locomotionProfile = options.locomotionProfile;
@@ -542,6 +576,13 @@ export class CharacterAnimations {
     // Optional in the snapshot (older five-boolean remote-player objects).
     ctx.crouchActive = snapshot.crouchActive ?? false;
 
+    // Grounded movement cancels an interruptible one-shot — otherwise the
+    // frozen full-body pose slides across the ground for the clip's whole
+    // length. clearOneShot crossfades locomotion back in with no T-pose frame.
+    if (this.#oneShotAction && this.#oneShotInterruptible && ctx.isMoving && ctx.isOnGround) {
+      this.clearOneShot();
+    }
+
     const next = this.#resolver(ctx);
     const stateChanged = next !== this.#state;
     if (stateChanged) this.#state = next;
@@ -550,6 +591,19 @@ export class CharacterAnimations {
     // (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];
+    // Rigs whose airborne slots fall back to the SAME clip as jump.start (every
+    // Meshy rig: jump.rise/jump.fall → jump.full) never re-enter #applyTransition
+    // while airborne — the name never changes — so once the one-shot finishes the
+    // character hangs FROZEN in the jump's final frame for the rest of the fall
+    // (long drops, knockback launches). Once the held action has finished
+    // (paused+clamped), retarget sustained airtime at the idle loop so the limbs
+    // keep animating while descending.
+    if ((next === "JUMP_IDLE" || next === "JUMP_FALL") && this.#desiredMotionName !== null) {
+      const held = this.#actions.get(this.#desiredMotionName);
+      if (held && held.paused) {
+        this.#desiredMotionName = this.#resolveProfileSlot("idle.default") ?? this.#clipMap.IDLE;
+      }
+    }
     // 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.
@@ -643,6 +697,7 @@ export class CharacterAnimations {
     // finish and the rig snaps to bind pose for a frame — the T-pose flash.
     action.clampWhenFinished = true;
     this.#oneShotHoldPose = options.clamp ?? false;
+    this.#oneShotInterruptible = options.interruptible ?? false;
     action.timeScale = options.timeScale ?? 1;
     action.reset();
     if (current && current !== action) {
@@ -660,6 +715,42 @@ export class CharacterAnimations {
     return true;
   }
 
+  /**
+   * Cancel a one-shot and hand control back to locomotion NOW. The case that
+   * REQUIRES it: a `clamp:true` one-shot (death/knockdown, a held wind-up)
+   * holds its final frame and keeps the locomotion lock closed FOREVER by
+   * design — so a respawn or an aborted action must explicitly release it, or
+   * the rig keeps the clamped pose while the body moves around. Safe to call
+   * at any time; a no-op when nothing is held.
+   *
+   * Call it on TRANSITIONS (respawn, revive, action aborted) — never per
+   * frame, or it cancels every in-flight reaction clip.
+   *
+   * @example
+   * // on respawn, before teleporting the body:
+   * anims.clearOneShot();
+   */
+  clearOneShot(): void {
+    if (this.#disposed) return;
+    const finished = this.#oneShotAction;
+    this.#oneShotAction = null;
+    this.#oneShotOnDone = undefined;
+    this.#oneShotHoldPose = false;
+    this.#oneShotInterruptible = false;
+    this.#canPlayNext = true;
+    // Crossfade the current state's loop in FROM the held pose — same path the
+    // "finished" handler uses, so there is no unposed/T-pose frame.
+    if (finished) this.#recoverFromOneShot(finished);
+  }
+
+  /** Clip name of the currently-playing (or clamped-held) one-shot, or null.
+   *  Lets a caller cancel a SPECIFIC one-shot (e.g. a held charge wind-up)
+   *  without clobbering whatever replaced it:
+   *  `if (anims.currentOneShotName === WINDUP_CLIP) anims.clearOneShot();` */
+  get currentOneShotName(): string | null {
+    return this.#oneShotAction?.getClip().name ?? null;
+  }
+
   /** Stop all actions, uncache clips, remove the mixer's 'finished' listener. */
   dispose(): void {
     if (this.#disposed) return;
@@ -766,9 +857,23 @@ export class CharacterAnimations {
   #releaseStuckLocks(): void {
     const prevActionName = this.#prevActionName;
     if (prevActionName === null) return;
+    // Match BOTH bindings a jump one-shot can have: the fuzzy clipMap names and
+    // the profile slots. On profile rigs the clipMap entries are usually null
+    // (no clip is literally named "jump_start"), which made this escape hatch
+    // dead code — a stuck jump lock could never self-release. The jump.land
+    // slot is ignored when it falls back to idle.default (same guard
+    // #applyTransition uses), or an idle prevAction would spuriously match.
+    const startName = this.#clipMap.JUMP_START ?? this.#resolveProfileSlot("jump.start");
+    const profileLand = this.#resolveProfileSlot("jump.land");
+    const landName =
+      this.#clipMap.JUMP_LAND ??
+      (profileLand !== this.#resolveProfileSlot("idle.default") ? profileLand : null);
+    // A manual playOneShot() lock is NOT ours to release — even when its clip
+    // happens to share a name with the jump binding (clearOneShot owns that).
+    if (this.#oneShotAction) return;
     if (
       !this.#canPlayNext &&
-      prevActionName === this.#clipMap.JUMP_START &&
+      prevActionName === startName &&
       this.#state !== "JUMP_IDLE" &&
       this.#state !== "JUMP_START"
     ) {
@@ -776,7 +881,7 @@ export class CharacterAnimations {
     }
     if (
       !this.#canPlayNext &&
-      prevActionName === this.#clipMap.JUMP_LAND &&
+      prevActionName === landName &&
       this.#state !== "IDLE" &&
       this.#state !== "JUMP_LAND"
     ) {
@@ -878,13 +983,19 @@ export class CharacterAnimations {
     snapshot: CharacterStateSnapshot,
     state: CharacterAnimationState,
   ): void {
-    if (!this.#locomotionProfile || !isAdvancedSnapshot(snapshot) || this.oneShotActive) return;
+    // Gate on a numeric moveSpeed rather than the full advanced snapshot:
+    // remote players and bots drive with simple boolean snapshots plus an
+    // estimated speed (position deltas / their own velocity), and without this
+    // they play locomotion at a flat 1.0 while the local player's clips
+    // speed-match — visibly different gaits for the same movement.
+    const speed = (snapshot as Partial<AdvancedCharacterStateSnapshot>).moveSpeed;
+    if (!this.#locomotionProfile || typeof speed !== "number" || 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);
+    const rate = THREE.MathUtils.clamp(speed / nominal, limits.min, limits.max);
     this.#actions.get(this.#prevActionName)?.setEffectiveTimeScale(rate);
   }
 }

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

@@ -257,7 +257,34 @@ addEventListener("pointerdown", () => {
 ```
 
 `options`: `fadeIn` (default 0.1 s), `timeScale`, `clamp` (hold the final pose —
-for deaths), `onDone`.
+for deaths), `interruptible` (grounded movement cancels the clip), `onDone`.
+
+**Every one-shot is FULL-BODY** (there is no upper-body layering), so it freezes
+the legs — a moving character SLIDES across the ground in a frozen pose for the
+clip's whole length. Two rules keep that from ever being visible:
+
+- **Reactions and gestures a player can walk out of get `interruptible: true`**
+  (hit flinches, casts, taunts, celebrations). Movement intent releases the clip
+  and locomotion takes over the same frame. A 2.9 s hit reaction without it
+  locks the player's animation for 2.9 s *per hit taken*.
+- **`clamp: true` holds the lock FOREVER by design** — nothing releases it
+  automatically, not even the clip ending. Every clamped one-shot needs a
+  guaranteed paired release: call `anims.clearOneShot()` on the transition out
+  (respawn, revive, action aborted). Audit every early-return on the path
+  between "clamped one-shot started" and "the replacing clip plays" — an abort
+  branch that skips the replacement strands the pose and the character slides
+  around locked until something else clears it.
+
+`anims.clearOneShot()` cancels the active one-shot and crossfades locomotion
+back in with no T-pose frame; it is safe to call when nothing is held. Call it
+on TRANSITIONS only — per-frame calls cancel every in-flight reaction clip. To
+cancel one SPECIFIC one-shot without clobbering whatever replaced it, check
+`anims.currentOneShotName` first:
+
+```ts
+// abort a held charge wind-up, but never a death pose that replaced it:
+if (anims.currentOneShotName === WINDUP_CLIP) anims.clearOneShot();
+```
 
 The 12 core clips are always available; everything else comes from
 `npx genex controller anims <selectors…>` — selectors are **tags** (install a

package/templates/skills/genex-threejs-multiplayer/SKILL.md

@@ -658,6 +658,25 @@ Corollary: **cap top speeds against the network, not just the physics** — an o
 crossing time should stay above ~2× the smoothing delay (~0.25 s), or receivers are reacting to
 history no matter how correct the code is.
 
+**Packed animation-flag bitfields are the sneakiest violation.** Smoothing lerps EVERY numeric
+field — there is no integer exemption — and a lerped bitfield decodes to garbage: with
+`moving=1, running=2, grounded=8`, walking is `f=9` and running is `f=11`, and the interpolation
+passes through `10`, where `10 & moving === 0` — the sprinting opponent renders as *standing
+still*. Worse, the exponential ease approaches an increasing target from below, so truncation
+reads `target - 1` for the whole approach (~1.5 s median before RUN appears; at a vsync-locked
+frame rate it can stick one ULP below the target *forever*). A field-verified failure: a
+playtester swore he was running while his opponent's screen showed him walking — both were right.
+Always drive remote animation from `stateRaw`:
+
+```js
+avatar.updateFromFlags(p.stateRaw.f ?? 0, dt);   // flags are DISCRETE — never p.state.f
+```
+
+**Reaction one-shots on remotes fire on EDGES, never per frame.** If you replay a remote's
+death/hit pose from their published `out`/`hp` state, track the previous value and act only on
+the transition — a per-frame `reset()`/`playDown()` restarts or cancels every in-flight reaction
+clip (and re-writing ghost/material flags 60×/s is pure churn).
+
 ## Shared objects (the ball, the NPC) — use `objects`, never `shared`
 
 A ball belongs to no player. Put it on `objects`: exactly one client owns it at a time (the SDK +