@genex-ai/cli-demo 0.95.0-dev.271 → 0.96.0-dev.272

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@genex-ai/cli-demo",
-  "version": "0.95.0-dev.271",
+  "version": "0.96.0-dev.272",
   "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

@@ -266,6 +266,210 @@ export function buildClipMap(
   return map;
 }
 
+// ---------------------------------------------------------------------------
+// Upper-body layering
+// ---------------------------------------------------------------------------
+//
+// This is how an attack lands while the character is still running. Without it
+// every one-shot is full-body and freezes the legs — a moving character slides
+// across the ground in a static pose for the clip's whole length.
+//
+// three.js has NO bone mask. The only mechanism that works is filtering a
+// clip's `tracks` down to one region and playing the result as an ordinary
+// action on the SAME mixer. Three facts from the three.js source shape
+// everything below; each one is a day lost if rediscovered the hard way:
+//
+// 1. `PropertyMixer.accumulate` NORMALIZES. Two normal-mode actions at weight 1
+//    on a shared bone give a 50/50 slerp, not "last one wins". The layer needs
+//    an elevated weight to actually override — see UPPER_LAYER_WEIGHT.
+// 2. NEVER `crossFadeFrom` between the base and a layer. `apply()` mixes every
+//    bone toward its ORIGINAL BIND POSE at `1 - cumulativeWeight`, so fading the
+//    full-body base out drags the torso toward T-pose. The base stays at weight
+//    1 forever; only the layer fades.
+// 3. No additive blending. `AnimationUtils.makeClipAdditive` MUTATES the clip in
+//    place, and a character loader shares clip objects between every character
+//    built on the same rig — one additive conversion would corrupt the roster.
+
+/**
+ * Weight of an upper-body layer over the full-body base.
+ *
+ * `accumulate` normalizes, so the layer's share is `w / (1 + w)`: 4 -> 80%
+ * (visibly limp — the run still bleeds through the swing), 12 -> 92%, 19 -> 95%.
+ * 12 reads as an override while leaving just enough base for the torso to keep
+ * breathing with the gait. Raise it if a swing looks half-hearted.
+ */
+const UPPER_LAYER_WEIGHT = 12;
+/** Crossfade for an upper-body layer, seconds. */
+const UPPER_FADE_DURATION = 0.12;
+
+/** Bones that must NOT end up inside an upper-body mask (verification). */
+const LEG_PATTERN = /upleg|upperleg|thigh|shin|calf|knee|ankle|foot|toe|leg/i;
+/** Bones whose presence identifies the spine subtree (never a leg). */
+const TORSO_PATTERN = /head|neck|skull|hand|wrist|palm|finger|thumb|shoulder|clavicle|arm/i;
+
+/** The result of {@link deriveUpperBody} — a bone-name set plus its provenance. */
+export interface UpperBodyMask {
+  /** Bone names belonging to the upper body (spine subtree, hips excluded). */
+  readonly names: ReadonlySet<string>;
+  /** The root/pelvis bone the mask was derived from. Never in `names`. */
+  readonly rootBone: string;
+  /** Total bones on the skeleton (for logging / sanity). */
+  readonly boneCount: number;
+}
+
+function collectBones(model: THREE.Object3D): THREE.Object3D[] {
+  // Prefer the real skeleton: it is the authoritative joint list, and a rig can
+  // carry helper Object3Ds (attachment sockets, the Armature node) that are not
+  // joints at all.
+  let bones: THREE.Object3D[] | null = null;
+  model.traverse((object) => {
+    if (bones) return;
+    const skinned = object as THREE.SkinnedMesh;
+    if (skinned.isSkinnedMesh && skinned.skeleton?.bones?.length) {
+      bones = [...skinned.skeleton.bones];
+    }
+  });
+  if (bones) return bones;
+  const found: THREE.Object3D[] = [];
+  model.traverse((object) => {
+    if ((object as THREE.Bone).isBone) found.push(object);
+  });
+  return found;
+}
+
+function subtreeNames(root: THREE.Object3D, within: Set<THREE.Object3D>): Set<string> {
+  const out = new Set<string>();
+  const stack = [root];
+  while (stack.length > 0) {
+    const node = stack.pop()!;
+    if (!within.has(node)) continue;
+    out.add(node.name);
+    for (const child of node.children) stack.push(child);
+  }
+  return out;
+}
+
+/**
+ * Derive the upper-body bone set of a humanoid rig, or null when the skeleton
+ * does not look like one.
+ *
+ * STRUCTURAL, not name-driven, on purpose: generated rigs use Mixamo-ish bone
+ * names but can INVERT the spine convention — on one shipped rig the hips'
+ * child is `Spine02` and the bone actually called `Spine` is the TOPMOST one,
+ * carrying the shoulders and neck. Anything keying off "Spine" vs "Spine1"
+ * picks the wrong end. So: walk the pelvis' children, keep the subtree that
+ * owns the head/arms, and reject the ones that own the feet.
+ *
+ * Returns null (never a guess) when any check fails — every caller degrades to
+ * full-body playback, which is merely worse-looking rather than broken.
+ */
+export function deriveUpperBody(model: THREE.Object3D): UpperBodyMask | null {
+  const bones = collectBones(model);
+  if (bones.length < 6) return null;
+  const boneSet = new Set(bones);
+
+  // Root = the bone whose parent is not itself a bone (the Armature/scene node).
+  // Several can qualify on odd exports; the one with the most descendants wins.
+  const roots = bones.filter((bone) => !bone.parent || !boneSet.has(bone.parent));
+  if (roots.length === 0) return null;
+  let root = roots[0]!;
+  if (roots.length > 1) {
+    let best = -1;
+    for (const candidate of roots) {
+      const size = subtreeNames(candidate, boneSet).size;
+      if (size > best) {
+        best = size;
+        root = candidate;
+      }
+    }
+  }
+
+  // Score the pelvis' children: the spine subtree owns head/arms and no legs.
+  let spine: THREE.Object3D | null = null;
+  let spineSize = 0;
+  for (const child of root.children) {
+    if (!boneSet.has(child)) continue;
+    const names = subtreeNames(child, boneSet);
+    let hasLeg = false;
+    let hasTorso = false;
+    for (const name of names) {
+      if (LEG_PATTERN.test(name)) hasLeg = true;
+      else if (TORSO_PATTERN.test(name)) hasTorso = true;
+    }
+    if (hasLeg || !hasTorso) continue;
+    if (names.size > spineSize) {
+      spine = child;
+      spineSize = names.size;
+    }
+  }
+  if (!spine) return null;
+
+  const names = subtreeNames(spine, boneSet);
+
+  // Verify before trusting it. A mask that quietly swallowed a leg would make
+  // the character slide with frozen feet — worse than never layering at all.
+  if (names.size === 0 || names.size >= bones.length) return null;
+  for (const name of names) if (LEG_PATTERN.test(name)) return null;
+  const legOutside = bones.some((bone) => !names.has(bone.name) && LEG_PATTERN.test(bone.name));
+  if (!legOutside) return null;
+  const ratio = names.size / bones.length;
+  if (ratio < 0.2 || ratio > 0.9) return null;
+
+  return { names, rootBone: root.name, boneCount: bones.length };
+}
+
+/**
+ * Copy of `clip` keeping only the tracks that address a bone in `mask`.
+ *
+ * NEVER mutates the source: a character loader shares clip objects across every
+ * character on the same rig, so an in-place edit here would silently change
+ * what the others play.
+ */
+export function filterClipToBones(
+  clip: THREE.AnimationClip,
+  mask: ReadonlySet<string>,
+  name: string,
+): THREE.AnimationClip | null {
+  const tracks = clip.tracks.filter((track) => {
+    const parsed = THREE.PropertyBinding.parseTrackName(track.name);
+    return parsed.nodeName !== undefined && mask.has(parsed.nodeName);
+  });
+  if (tracks.length === 0) return null;
+  // Duration is copied, not recomputed: a track set that happens to end early
+  // must still occupy the clip's full length or the one-shot fires "finished"
+  // ahead of the visual.
+  return new THREE.AnimationClip(name, clip.duration, tracks.map((track) => track.clone()));
+}
+
+/** Logged once per session, not once per character. */
+let upperBodyReported = false;
+
+export interface PlayUpperBodyOptions {
+  /** Fade-in seconds for the layer. Default 0.12. */
+  fadeIn?: number;
+  /** Playback speed. Default 1. */
+  timeScale?: number;
+  /** Layer weight; the layer's share of a shared bone is `w / (1 + w)`. Default 12. */
+  weight?: number;
+  /**
+   * Hold the clamped final frame instead of fading back to the carry stance.
+   * This is how a wind-up tell stays drawn back on the torso — indefinitely —
+   * while the legs keep running underneath. Release with `clearUpperBody()`.
+   */
+  clamp?: boolean;
+  /** Fired when the clip finishes (skipped if a newer layer clip replaces it). */
+  onDone?: () => void;
+}
+
+export interface HoldUpperBodyOptions {
+  /** Fade-in seconds for the stance. Default 0.12. */
+  fadeIn?: number;
+  /** Playback speed. Default 1. */
+  timeScale?: number;
+  /** Layer weight; the stance's share of a shared bone is `w / (1 + w)`. Default 12. */
+  weight?: number;
+}
+
 // ---------------------------------------------------------------------------
 // Playback constants (upstream demo values)
 // ---------------------------------------------------------------------------
@@ -363,6 +567,25 @@ export class CharacterAnimations {
   // locomotion states (any installed pack clip: Punch_*, Sword_*, Sitting_*…).
   #clipsByName = new Map<string, THREE.AnimationClip>();
   #missingOneShotWarnings = new Set<string>();
+  // Upper-body layering. `#upperMask` is derived lazily on first use and cached
+  // as `null` when this rig cannot be split, so a rejected skeleton is probed
+  // exactly once.
+  #upperMask: UpperBodyMask | null = null;
+  #upperMaskResolved = false;
+  #upperClips = new Map<string, THREE.AnimationClip>();
+  #upperAction: THREE.AnimationAction | null = null;
+  // The SOURCE clip name, not the filtered action's (`X__upper`): callers ask
+  // "is my cast still playing?" about the clip they requested.
+  #upperName: string | null = null;
+  #upperHoldPose = false;
+  #upperOnDone: (() => void) | undefined;
+  #upperHoldAction: THREE.AnimationAction | null = null;
+  #upperHoldName: string | null = null;
+  #upperHoldWeight = UPPER_LAYER_WEIGHT;
+  // Set when playUpperBody could not layer and ran the clip FULL-BODY instead.
+  // clearUpperBody() has to release it through the one-shot path it actually
+  // took, or a clamped fallback pose strands the character forever.
+  #upperFellBack: string | null = null;
   #oneShotAction: THREE.AnimationAction | null = null;
   #locomotionOneShotAction: THREE.AnimationAction | null = null;
   #oneShotOnDone: (() => void) | undefined;
@@ -485,6 +708,25 @@ export class CharacterAnimations {
     };
 
     this.#onFinished = (event) => {
+      // Upper-body layer one-shot finished: fade the layer out and let the
+      // carry stance (if any) come back. The base never moved, so there is
+      // nothing to recover — that is the whole point of layering.
+      if (this.#upperAction && event.action === this.#upperAction) {
+        const done = this.#upperOnDone;
+        this.#upperOnDone = undefined;
+        if (this.#upperHoldPose) {
+          // clamp:true — the drawn-back pose stays on the torso until an
+          // explicit clearUpperBody() (the charge release, a death, a respawn).
+          done?.();
+          return;
+        }
+        this.#upperAction.fadeOut(UPPER_FADE_DURATION);
+        this.#upperAction = null;
+        this.#upperName = null;
+        this.#restoreUpperHold();
+        done?.();
+        return;
+      }
       // One-shot (punch/gesture) finished.
       if (this.#oneShotAction && event.action === this.#oneShotAction) {
         const finished = this.#oneShotAction;
@@ -506,6 +748,10 @@ export class CharacterAnimations {
         this.#oneShotOnDone = undefined;
         this.#canPlayNext = true;
         this.#recoverFromOneShot(finished);
+        this.#upperFellBack = null;
+        // A full-body one-shot owns every bone, so any carry stance stepped
+        // aside for it; give the weapon back now that the body is free.
+        this.#restoreUpperHold();
         done?.();
         return;
       }
@@ -707,6 +953,10 @@ export class CharacterAnimations {
 
     this.#oneShotAction = action;
     this.#oneShotOnDone = options.onDone;
+    // A full-body one-shot owns every bone. `accumulate` normalizes, so leaving
+    // a carry stance at layer weight would average it INTO the one-shot and
+    // half-cancel it. The stance steps aside and is restored on 'finished'.
+    this.#upperHoldAction?.fadeOut(UPPER_FADE_DURATION);
     // Freeze the locomotion transition until the one-shot's 'finished' event
     // reopens it; marking the one-shot as the "current" action makes
     // #applyTransition a no-op meanwhile.
@@ -743,6 +993,258 @@ export class CharacterAnimations {
     if (finished) this.#recoverFromOneShot(finished);
   }
 
+  /**
+   * Can this rig be split into an upper body at all?
+   *
+   * Ask BEFORE designing around layering: a rig that fails the structural
+   * checks in {@link deriveUpperBody} makes every `playUpperBody` return false,
+   * and the game should fall back to full-body one-shots rather than silently
+   * dropping its attacks. Derives the mask on first call and caches it.
+   */
+  get canLayerUpperBody(): boolean {
+    return this.#resolveUpperMask() !== null;
+  }
+
+  /** Is a layered upper-body clip playing (or holding a clamped pose)? */
+  get upperBodyActive(): boolean {
+    return this.#upperAction !== null;
+  }
+
+  /** Source clip name of the active upper-body layer, or null. */
+  get currentUpperBodyName(): string | null {
+    return this.#upperName;
+  }
+
+  /** Source clip name of the held carry stance, or null. */
+  get currentUpperHoldName(): string | null {
+    return this.#upperHoldName;
+  }
+
+  /**
+   * Is the held carry stance still LOOPING?
+   *
+   * Exposed because the filtered upper-body actions are cached per clip name
+   * and shared, so a clip played as a clamped one-shot leaves its action
+   * clamped for the stance that also uses it. That is invisible from the
+   * outside — the pose simply stops moving — and it needs to be assertable.
+   */
+  get upperHoldLooping(): boolean {
+    const hold = this.#upperHoldAction;
+    return hold ? hold.loop === THREE.LoopRepeat && !hold.clampWhenFinished : false;
+  }
+
+  /**
+   * Play a clip on the torso/arms/head only, over whatever the legs are doing.
+   * This is how an attack lands while the character is still running.
+   *
+   * ALWAYS PLAYS THE CLIP. On a rig this mask cannot split it falls back to a
+   * full-body {@link playOneShot} — legs frozen, which is how every one-shot
+   * behaved before layering existed. So `true` means "the clip is playing",
+   * NOT "the clip is layered"; read {@link upperBodyActive} if you need to
+   * know which. It returns false only for the same reason `playOneShot` does:
+   * the clip is not installed.
+   *
+   * You therefore do not need to write a fallback, and should not have to
+   * remember to. {@link clearUpperBody} releases either form.
+   *
+   * @example
+   * anims.playUpperBody("Sword_Slash");     // layers if it can, plays regardless
+   */
+  playUpperBody(clipName: string, options: PlayUpperBodyOptions = {}): boolean {
+    if (this.#disposed) return false;
+    this.#upperFellBack = null;
+    const action = this.#upperActionFor(clipName);
+    if (!action) {
+      // NOT A SILENT NO-OP. A rig this mask cannot split must still PLAY the
+      // clip — full-body, legs frozen, exactly as `playOneShot` always did.
+      // Returning false and leaving nothing playing would trade a visible ugly
+      // failure for an invisible one, and the caller who forgets the fallback
+      // ships a game whose attacks have no animation at all. (Measured on the
+      // game this came from: two of its three call sites checked the return
+      // value and one did not.)
+      //
+      // The clip simply not being installed is a different thing and still
+      // returns false — same contract as `playOneShot`, which the clip-missing
+      // branch of `#upperActionFor` has already warned about.
+      if (!this.#clipsByName.has(clipName)) return false;
+      const played = this.playOneShot(clipName, {
+        fadeIn: options.fadeIn,
+        timeScale: options.timeScale,
+        clamp: options.clamp,
+        onDone: options.onDone,
+      });
+      if (played) this.#upperFellBack = clipName;
+      return played;
+    }
+
+    const previous = this.#upperAction;
+    this.#upperAction = action;
+    this.#upperName = clipName;
+    this.#upperOnDone = options.onDone;
+    // The stance and the swing fight over the same bones, and `accumulate`
+    // normalizes — leaving both at layer weight would average them into a
+    // half-swing. The stance steps aside and comes back on "finished".
+    this.#upperHoldAction?.fadeOut(UPPER_FADE_DURATION);
+    if (previous && previous !== action) previous.fadeOut(UPPER_FADE_DURATION);
+
+    action.enabled = true;
+    action.setLoop(THREE.LoopOnce, 1);
+    action.clampWhenFinished = true;
+    this.#upperHoldPose = options.clamp ?? false;
+    action.timeScale = options.timeScale ?? 1;
+    action.weight = options.weight ?? UPPER_LAYER_WEIGHT;
+    action.reset();
+    action.fadeIn(options.fadeIn ?? UPPER_FADE_DURATION);
+    action.play();
+    return true;
+  }
+
+  /**
+   * Hold a LOOPING clip on the upper body indefinitely — the weapon carry
+   * stance (sword held low, bow at the hip) that rides on top of the stock
+   * unarmed locomotion.
+   *
+   * This is what makes a weapon affordable: an immutable controller pack owns
+   * `walk.forward` / `run.forward` and cannot be replaced, but nothing stops a
+   * stance from posing the torso above those legs. Release it on weapon swap
+   * with {@link releaseUpperHold}.
+   *
+   * UNLIKE {@link playUpperBody}, THIS HAS NO FULL-BODY FALLBACK and returns
+   * false on a rig the mask cannot split. That asymmetry is deliberate: a
+   * one-shot played full-body is merely uglier, but a persistent stance played
+   * full-body would REPLACE locomotion outright — the character would stop
+   * walking for as long as the weapon is drawn. Carrying no stance is the
+   * correct degradation; there is nothing to fall back to.
+   */
+  holdUpperBody(clipName: string, options: HoldUpperBodyOptions = {}): boolean {
+    if (this.#disposed) return false;
+    if (this.#upperHoldName === clipName) return true;
+    const action = this.#upperActionFor(clipName);
+    if (!action) return false;
+
+    this.#upperHoldAction?.fadeOut(options.fadeIn ?? UPPER_FADE_DURATION);
+    this.#upperHoldWeight = options.weight ?? UPPER_LAYER_WEIGHT;
+    this.#upperHoldAction = action;
+    this.#upperHoldName = clipName;
+    action.enabled = true;
+    action.setLoop(THREE.LoopRepeat, Infinity);
+    action.clampWhenFinished = false;
+    action.timeScale = options.timeScale ?? 1;
+    action.weight = this.#upperHoldWeight;
+    action.reset();
+    // A swing owns the torso right now; the stance waits its turn rather than
+    // averaging itself into the attack.
+    if (this.#upperAction) action.setEffectiveWeight(0);
+    else action.fadeIn(options.fadeIn ?? UPPER_FADE_DURATION);
+    action.play();
+    return true;
+  }
+
+  /** Drop the held carry stance (weapon stowed / swapped). No-op when none. */
+  releaseUpperHold(fadeOut = UPPER_FADE_DURATION): void {
+    if (this.#disposed || !this.#upperHoldAction) return;
+    this.#upperHoldAction.fadeOut(fadeOut);
+    this.#upperHoldAction = null;
+    this.#upperHoldName = null;
+  }
+
+  /** Cancel a layered one-shot NOW (interrupt, death, respawn) and let the
+   *  stance — if any — take the torso back. Safe when nothing is playing.
+   *
+   *  Releases a FULL-BODY fallback too (see `playUpperBody`), so a caller that
+   *  never learns whether the rig could be split still gets a clean release —
+   *  otherwise a `clamp: true` fallback would hold its final frame forever. */
+  clearUpperBody(fadeOut = UPPER_FADE_DURATION): void {
+    if (this.#upperFellBack !== null) {
+      if (this.currentOneShotName === this.#upperFellBack) this.clearOneShot();
+      this.#upperFellBack = null;
+      return;
+    }
+    if (this.#cancelUpperOneShot(fadeOut)) this.#restoreUpperHold();
+  }
+
+  /** Drop the stance AND any layered one-shot — the full "back to unarmed". */
+  clearUpperLayers(): void {
+    this.clearUpperBody();
+    this.releaseUpperHold();
+  }
+
+  #resolveUpperMask(): UpperBodyMask | null {
+    if (!this.#upperMaskResolved) {
+      this.#upperMaskResolved = true;
+      this.#upperMask = deriveUpperBody(this.#model);
+      if (!upperBodyReported) {
+        upperBodyReported = true;
+        console.info(
+          this.#upperMask
+            ? `[character-animations] upper-body layer: ${this.#upperMask.names.size}/${this.#upperMask.boneCount} bones above "${this.#upperMask.rootBone}"`
+            : "[character-animations] this rig cannot be split into an upper body — layered actions fall back to full-body playback.",
+        );
+      }
+    }
+    return this.#upperMask;
+  }
+
+  /** Filtered action for `clipName`, or null when unsplittable / not installed. */
+  #upperActionFor(clipName: string): THREE.AnimationAction | null {
+    const mask = this.#resolveUpperMask();
+    if (!mask) return null;
+    let filtered = this.#upperClips.get(clipName);
+    if (!filtered) {
+      const source = this.#clipsByName.get(clipName);
+      if (!source) {
+        if (!this.#missingOneShotWarnings.has(clipName)) {
+          this.#missingOneShotWarnings.add(clipName);
+          console.warn(
+            `[character-animations] upper-body clip "${clipName}" is not installed; playUpperBody() returned false.`,
+          );
+        }
+        return null;
+      }
+      const built = filterClipToBones(source, mask.names, `${clipName}__upper`);
+      if (!built) return null;
+      filtered = built;
+      this.#upperClips.set(clipName, filtered);
+    }
+    return this.mixer.clipAction(filtered);
+  }
+
+  /** Fade out the layered one-shot without touching the stance.
+   *  Returns true when something was actually cancelled. */
+  #cancelUpperOneShot(fadeOut: number): boolean {
+    if (this.#disposed || !this.#upperAction) return false;
+    this.#upperAction.fadeOut(fadeOut);
+    this.#upperAction = null;
+    this.#upperName = null;
+    this.#upperHoldPose = false;
+    this.#upperOnDone = undefined;
+    return true;
+  }
+
+  /**
+   * Fade the carry stance back in after a layered one-shot released the torso.
+   *
+   * THE LOOP HAS TO BE RESTORED EXPLICITLY. `#upperActionFor` caches one filtered
+   * clip per name and hands back the SAME `AnimationAction` every time, and
+   * `playUpperBody` mutates that shared action to LoopOnce + clampWhenFinished.
+   * So a clip used as both a held stance and a clamped one-shot comes back from
+   * the one-shot permanently clamped: the carry pose plays once and freezes.
+   *
+   * Unreachable until one clip does both jobs — and reachable the moment a
+   * sneak stance moves onto the same clip as a blade carry. Restoring both
+   * flags here is correct regardless of who happens to collide.
+   */
+  #restoreUpperHold(): void {
+    const hold = this.#upperHoldAction;
+    if (!hold) return;
+    hold.enabled = true;
+    hold.weight = this.#upperHoldWeight;
+    hold.setLoop(THREE.LoopRepeat, Infinity);
+    hold.clampWhenFinished = false;
+    hold.fadeIn(UPPER_FADE_DURATION);
+    hold.play();
+  }
+
   /** 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:
@@ -761,6 +1263,12 @@ export class CharacterAnimations {
       this.mixer.uncacheClip(action.getClip());
     }
     this.#actions.clear();
+    // Filtered upper-body clips are OURS (built by filterClipToBones, never
+    // shared with the loader), so they are ours to uncache.
+    for (const clip of this.#upperClips.values()) this.mixer.uncacheClip(clip);
+    this.#upperClips.clear();
+    this.#upperAction = null;
+    this.#upperHoldAction = null;
     this.#locomotionOneShotAction = null;
   }
 

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

@@ -342,8 +342,12 @@ export class CharacterController {
   private readonly capsuleRadius: number;
   private readonly useCustomForward: boolean;
   private readonly gravityDirLerpSpeed: number;
-  private readonly maxWalkVel: number;
-  private readonly maxRunVel: number;
+  private maxWalkVel: number;
+  private maxRunVel: number;
+  /** The constructed speeds, so `setSpeedScale` always scales from the preset
+   *  rather than compounding off whatever the last call left behind. */
+  private readonly baseWalkVel: number;
+  private readonly baseRunVel: number;
   private readonly accDeltaTime: number;
   private readonly decDeltaTime: number;
   private readonly rejectVelFactor: number;
@@ -570,6 +574,8 @@ export class CharacterController {
     this.gravityDirLerpSpeed = options.gravityDirLerpSpeed ?? 6;
     this.maxWalkVel = options.maxWalkVel ?? 2;
     this.maxRunVel = options.maxRunVel ?? 5;
+    this.baseWalkVel = this.maxWalkVel;
+    this.baseRunVel = this.maxRunVel;
     this.accDeltaTime = options.accDeltaTime ?? 0.2;
     this.decDeltaTime = options.decDeltaTime ?? 0.2;
     this.rejectVelFactor = options.rejectVelFactor ?? 1;
@@ -899,11 +905,33 @@ export class CharacterController {
     if (movement.crouch !== undefined) this.movementState.crouch = movement.crouch;
   }
 
+  /**
+   * Scale walk and run speed at runtime — haste and slow effects, encumbrance,
+   * a per-class or per-difficulty pace, wading through mud.
+   *
+   * Always relative to the CONSTRUCTED speeds, so repeated calls do not compound
+   * and `setSpeedScale(1)` is an exact reset. Non-finite or non-positive values
+   * are ignored rather than freezing the character in place.
+   *
+   * This drives the real target velocity, so the animation controller's
+   * playback-rate matching follows it for free — a hasted character's legs
+   * speed up with them instead of skating.
+   */
+  setSpeedScale(scale: number): void {
+    const s = Number.isFinite(scale) && scale > 0 ? scale : 1;
+    this.maxWalkVel = this.baseWalkVel * s;
+    this.maxRunVel = this.baseRunVel * s;
+  }
+
   /**
    * 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.
+   *
+   * THIS IS ALSO HOW YOU DASH. See the dash recipe in the character-controller
+   * skill's `references/tuning-and-presets.md`: an impulse applied above the
+   * centre of mass is TORQUE, and it pitches a moving character over backwards.
    */
   setActionMotion(motion: CharacterActionMotion | null): void {
     if (motion === null) {

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

@@ -87,6 +87,12 @@ Open or link all three real candidate images, then wait for the user's choice.
 Do not treat a text description, task ID, filename, or your own preference as
 approval. Continue with the selected candidate only:
 
+The candidate images are permanent and already paid for. Reuse them as game art
+instead of generating new pictures of the same character: a character-select or
+roster portrait, a party or inventory panel, a dialogue bust, a versus card, a
+death screen. They are full-body neutral A-pose renders on a plain backdrop, so
+they crop well to a portrait and read as one set across the cast.
+
 ```bash
 npx genex character preview <concept-id> --candidate <1|2|3> --user-approved
 ```

package/templates/skills/genex-game-director/references/routing-map.md

@@ -35,6 +35,8 @@ copy demo architecture.
 | --- | --- |
 | shot composition, chase/side/orbit rigs, camera handoffs, projection ownership, pointer look, mouse-aimed action, mouse-look, the screen-direction contract for hand-rolled steering/pan/look input signs, floating origins | `$genex-threejs-camera-direction` |
 | on-foot player movement: walk/run/jump/crouch, third-person character, slopes, stairs, moving platforms, the player's body loader, directional locomotion, transitions, action motion | `$genex-threejs-character-controller` |
+| **attacking, casting, aiming or reloading WHILE moving** — any action the legs must keep running under; a weapon carry stance over stock locomotion; a wind-up the character holds while walking | `$genex-threejs-character-controller` (`references/animations.md`, upper-body layering) |
+| dash, dodge, roll, blink, backstep, a lunging attack — any burst that moves the character itself | `$genex-threejs-character-controller` (`references/tuning-and-presets.md`, dash recipe) |
 | the game's own generated character—the player's body wherever a human body appears—or Meshy animation coverage beyond the stock pack: reference-informed A-pose concepts, exact action IDs, same-rig adapter | `$genex-ai-character` + `$genex-threejs-character-controller` |
 | a character/enemy needs motion the catalog lacks—a signature move, boss telegraph, death, full 8-way set, or the player's footage; free plan before spend | `$genex-ai-character` motion section + `references/motion-generation.md` |
 | remote player bodies in multiplayer—never hand-built primitives: the game's generated character when it has one, otherwise the player's `p.avatarUrl` VRM | `$genex-threejs-multiplayer` + `$genex-threejs-character-controller` |

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

@@ -281,8 +281,17 @@ 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.
+genre hints, `playOneShot` options, **upper-body layering** (attack, cast or
+shoot while the legs keep running — `playUpperBody` / `holdUpperBody`),
+overrides, foot IK, and remote-player animation.
+
+## Dash, dodge, roll
+
+Any burst that moves the character itself: read the dash recipe in
+[references/tuning-and-presets.md](references/tuning-and-presets.md). The short
+version is that it uses `setActionMotion` and **never** `applyImpulse` — the
+controller's movement impulse is applied above the centre of mass to make the
+run lean, so it is a torque, and it pitches a *moving* character over backwards.
 
 For Meshy characters, do not repair hands, arms, or legs at runtime. Meshy limb
 rotations play unchanged. Never freeze hand tracks or apply post-mixer arm,
@@ -371,7 +380,36 @@ players; their bodies don't have to.
 
 The loader shares one parsed base across every remote (N remotes ≈ 1 body of
 GPU memory) and `remote.dispose()` detaches the clone without touching those
-shared resources. Move it with the interpolator from
+shared resources.
+
+**Tinting a clone (team colours, per-player robes) has two traps, and both are
+silent.** Clones share MATERIALS, not just geometry, so `mesh.material.color.set()`
+on one repaints every player on both teams. And the fix has its own trap:
+
+```ts
+model.traverse((o) => {
+  const mesh = o as THREE.Mesh;
+  if (!mesh.isMesh) return;
+  const src = mesh.material;
+  const list = Array.isArray(src) ? src : [src];
+  const tinted = list.map((m) => {
+    const c = (m as THREE.MeshStandardMaterial).clone();  // clone = safe to mutate
+    c.color.lerp(teamColor, 0.42);                        // lerp, don't replace
+    return c;
+  });
+  // UNWRAP. `.map()` returns an array whatever went in, and an array material
+  // sends three down its multi-material path — one draw call per
+  // `geometry.groups` entry. A single-material body has NO groups, so the loop
+  // body never runs: the mesh is in the scene, visible, lit, in frustum, and
+  // draws NOTHING. `renderer.info.render.calls === 0` with everything else
+  // looking correct is the only signature of this bug.
+  mesh.material = Array.isArray(src) ? tinted : tinted[0]!;
+});
+```
+
+`controllers/character/first-person.ts` does the same array-aware clone for a
+different reason — copy its shape if you need to save and restore the original.
+Dispose the CLONED materials when the player leaves; never the shared textures. Move it with the interpolator from
 `$genex-threejs-multiplayer`, and **never** create a rigid body, a
 `CharacterController`, or any physics for it. Simulating remote players'
 physics locally guarantees divergence — every client would compute a different

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

@@ -270,9 +270,12 @@ addEventListener("pointerdown", () => {
 `options`: `fadeIn` (default 0.1 s), `timeScale`, `clamp` (hold the final pose —
 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:
+**Every one-shot is FULL-BODY**, so it freezes the legs — a moving character
+SLIDES across the ground in a frozen pose for the clip's whole length. For a
+swing, a cast or a shot that should land WHILE the character keeps running, use
+`playUpperBody` instead (next section). For everything that genuinely should
+stop the legs — a dodge roll, a death, a knockdown — a one-shot is correct, and
+two rules keep the freeze 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
@@ -339,6 +342,94 @@ 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.
 
+## Upper-body layering — attack while moving
+
+`playUpperBody(clipName, options)` plays a clip on the torso, arms and head only,
+over whatever the legs are already doing. This is how a swing lands while the
+character is still running, and how a weapon carry stance rides on top of stock
+unarmed locomotion.
+
+```ts
+// Layers when the rig allows it, plays FULL-BODY when it does not. Either way
+// the clip plays — you do not write the fallback.
+anims.playUpperBody("Sword_Slash");
+
+// A carry stance that persists under walk/run until the weapon is stowed:
+anims.holdUpperBody("blade_carry");
+anims.releaseUpperHold();          // on stow / swap
+
+// A wind-up the character holds while still walking:
+anims.playUpperBody("Draw_Bow", { clamp: true });
+anims.clearUpperBody();            // on release / cancel — releases either form
+```
+
+**`playUpperBody` never silently does nothing.** On a rig the mask cannot split
+it falls back to a full-body `playOneShot` — legs frozen, which is how every
+one-shot behaved before layering existed. `true` therefore means "the clip is
+playing", not "the clip is layered"; read `anims.upperBodyActive` if you need to
+know which. It returns false only when the clip is not installed, the same
+reason `playOneShot` does.
+
+`anims.canLayerUpperBody` tells you up front whether this rig can split, which
+is worth knowing when you are DESIGNING around layering (a combat system built
+on attack-while-running plays very differently if every swing roots the
+character). It is not something you have to check before each call.
+
+**`holdUpperBody` has no fallback and does return false on an unsplittable
+rig** — deliberately. A one-shot played full-body is merely uglier, but a
+persistent carry stance played full-body would replace locomotion outright and
+the character would stop walking for as long as the weapon is drawn. No stance
+is the correct degradation.
+
+Why the stance matters: an immutable controller pack owns `walk.forward` and
+`run.forward` and cannot be replaced, but nothing stops a stance from posing the
+torso above those legs. That is what makes a visible weapon affordable without
+regenerating a whole armed locomotion set.
+
+### Three facts that shape the whole thing
+
+three.js has **no bone mask**. The only mechanism that works is filtering a
+clip's tracks to one region and playing the result as an ordinary action on the
+SAME mixer. Each of these costs a day if rediscovered the hard way:
+
+1. **`PropertyMixer.accumulate` NORMALIZES.** Two normal-mode actions at weight 1
+   on a shared bone give a 50/50 slerp, not "last one wins". The layer's share is
+   `w / (1 + w)` — so weight 4 is 80% (visibly limp; the run bleeds through the
+   swing), 12 is 92%, 19 is 95%. The default 12 reads as an override while
+   leaving the torso enough base to keep breathing with the gait. Raise it via
+   `{ weight }` if a swing looks half-hearted.
+2. **Never `crossFadeFrom` between the base and a layer.** `apply()` mixes every
+   bone toward its ORIGINAL BIND POSE at `1 - cumulativeWeight`, so fading the
+   full-body base out drags the torso toward T-pose. The base stays at weight 1
+   forever; only the layer fades.
+3. **No additive blending.** `AnimationUtils.makeClipAdditive` MUTATES the clip
+   in place, and the character loader shares clip objects between every character
+   on the same rig — one additive conversion corrupts the whole roster.
+
+### The mask is derived structurally, never by name
+
+`deriveUpperBody(model)` walks the pelvis' children and keeps the subtree that
+owns the head and arms and no legs. It does NOT key off bone names, because
+generated rigs use Mixamo-ish names but can INVERT the spine convention — on one
+shipped rig the hips' child is `Spine02` and the bone actually called `Spine` is
+the TOPMOST one, carrying the shoulders and neck. Anything matching "Spine" vs
+"Spine1" picks the wrong end and masks the legs instead of the torso.
+
+It then VERIFIES before trusting the result — no leg bone inside the mask, at
+least one leg bone outside it, and a sane size ratio — and returns null rather
+than a guess. A mask that quietly swallowed a leg would make the character slide
+with frozen feet, which is worse than never layering at all.
+
+### Gotcha: one clip used as both a stance and a one-shot
+
+Filtered actions are cached per clip name, so `playUpperBody` and
+`holdUpperBody` on the SAME clip name share one `AnimationAction` — and
+`playUpperBody` mutates it to `LoopOnce` + `clampWhenFinished`. The controller
+restores the loop flags when the stance comes back, so this works; it is called
+out because the failure mode is invisible from the outside (the carry pose plays
+once and freezes for the rest of the match) and it only appears once a game
+reuses one clip for both jobs.
+
 ## Binding arbitrary clip names on a compatible rig
 
 `buildClipMap(clips, overrides?)` resolves each state in priority order:

package/templates/skills/genex-threejs-character-controller/references/tuning-and-presets.md

@@ -69,7 +69,7 @@ tip-overs mean the `autoBalance*` pair is too soft.
 | "crouch should be hold, not toggle" | `crouchMode: "hold"` (default `"toggle"` — C flips it) |
 | "no control in the air" | raise `airDragFactor` (default 0.1) |
 | "falls too fast at terminal velocity" | `fallingMaxVel` (default 20 m/s) |
-| "leans too much when running" | lower `moveImpulsePointOffset` (default 0.5; 0 = no lean) |
+| "leans too much when running" | lower `moveImpulsePointOffset` (default 0.5; 0 = no lean). That same offset is why a dash must never use an impulse — see the dash recipe below |
 | "wobbles / tips over" | raise `autoBalanceSpringK` + `autoBalanceDampingC` |
 | "turns to face direction too slowly" | raise `autoBalanceSpringOnY` |
 | "grounded flag flickers on stairs / ledges" | raise `rayHitForgiveness` (default 0.28) |
@@ -103,3 +103,75 @@ capsule is a heavier body at the same density.
   `applyCounterJumpImp`, `applyCounterMoveImp`) defaults to physically-honest
   and already handles moving/rotating platforms; only touch these for
   deliberate arcade effects.
+
+## Dash, dodge, roll — burst movement
+
+**Never use `applyImpulse` / `applyImpulseAtPoint` on the character body.**
+
+The controller applies its normal movement impulse ABOVE the centre of mass, at
+`moveImpulsePointOffset` (default 0.5), because that offset is what produces the
+run lean. An impulse applied off-centre is a force AND a torque. When the
+character is standing still the torque is small; when they are already moving it
+adds to the existing lean and the character pitches over backwards.
+
+Measured on a real dash: **60.3° of backward lean while moving, 0° from a
+standing start.** That "only breaks when I'm running" signature is the tell, and
+it sends you hunting the animation instead of the impulse.
+
+Use `setActionMotion`, which drives `setLinvel` — velocity, no torque — while
+Rapier keeps gravity, slopes and collisions:
+
+```ts
+// ONE number is yours: how far a dash should carry the character, in metres.
+// Everything else derives from it and from the controller's OWN run speed, so
+// a dash stays in proportion when you retune movement and you are never
+// copying somebody else's game feel. (A dash that reads as a burst is roughly
+// 2-3x run speed; below ~2x it reads as a sprint, above ~4x as a teleport.)
+const DASH_DISTANCE = 5;                       // metres — YOUR game lives here
+const RUN_SPEED = preset.options.maxRunVel ?? 5;
+const DASH_SPEED = RUN_SPEED * 2.8;
+const DASH_TIME = DASH_DISTANCE / DASH_SPEED;
+const EXIT_SPEED = RUN_SPEED;                  // see endDash
+
+function startDash(): void {
+  dashLeft = DASH_TIME;
+  // Freeze the direction at the moment of the press: a dash that keeps
+  // steering is a strafe, not a dash.
+  dashDir.copy(worldMoveDir.lengthSq() > 0 ? worldMoveDir : bodyForward).normalize();
+  anims.playUpperBody("Dodge_Right");   // a dodge is full-body; see below
+}
+
+function driveDash(dt: number): void {
+  // RE-PROJECT EVERY STEP. setActionMotion takes a BODY-LOCAL velocity, and the
+  // body rotates during the dash — a direction captured once in local space
+  // curves the dash into an arc.
+  local.copy(dashDir).applyQuaternion(bodyQuat.clone().invert());
+  controller.setActionMotion({ x: local.x * DASH_SPEED, z: local.z * DASH_SPEED });
+  dashLeft -= dt;
+  if (dashLeft <= 0) endDash();
+}
+
+function endDash(): void {
+  controller.setActionMotion(null);
+  // Clamp the exit velocity to normal run speed. Handing the full burst speed
+  // straight back to the controller makes it brake hard, and the brake is an
+  // impulse at the same offset — which re-creates the lean you just avoided.
+  // Measured: 19.8° of hand-off lean before the clamp, 4.6° after.
+  const v = body.linvel();
+  const planar = Math.hypot(v.x, v.z);
+  if (planar > EXIT_SPEED) {
+    const k = EXIT_SPEED / planar;
+    body.setLinvel({ x: v.x * k, y: v.y, z: v.z * k }, true);
+  }
+}
+```
+
+Two more things that are not optional:
+
+- **Suppress steering input for the duration.** Feed the controller no movement
+  while `dashLeft > 0`, or its own movement impulse fights the action motion —
+  and that impulse is the torque you are avoiding.
+- **A dodge is full-body; an attack is not.** A dodge SHOULD stop the legs doing
+  their own thing, so `playOneShot` (or `playUpperBody`, which falls back to it
+  on a rig it cannot split) is right. A swing that happens *while* running wants
+  the upper-body layer instead — see `references/animations.md`.

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

@@ -98,6 +98,13 @@ function play(rig: CreatureRig, name: keyof CreatureRig["actions"], fade = 0.18)
 // instance (THREE.AnimationUtils / SkeletonUtils.clone for shared GLBs).
 ```
 
+**An attacking enemy should keep moving.** A rigged creature
+(`npx genex creature`) is a humanoid on the same controller, so its swing can
+land while it advances — `anims.playUpperBody("<attack clip>")` layers the
+attack over whatever the legs are doing instead of freezing them mid-stride.
+See `$genex-threejs-character-controller` (`references/animations.md`). An
+enemy that stops dead to attack reads as a turn-based unit, not a threat.
+
 ## The mechanical floor — ALL enemies, rigged or not
 
 ### 1. A collider — the player never walks through a body

package/templates/skills/genex-threejs-multiplayer/references/genre-recipes.md

@@ -184,7 +184,9 @@ SKILL.md is the assignment story, verbatim. Everything else is Recipe 1/2 mechan
   round-robin balance, late joiners to the short side, the map in `shared` survives host
   migration. Do not re-derive teams anywhere else, and never read `mm.matchmaking.teams` (empty
   on `open`).
-- **Everything team-flavored READS the map:** tint/skin by `teams[id]`, spawn each player on their
+- **Everything team-flavored READS the map:** tint/skin by `teams[id]` (the tint recipe is in
+  `$genex-threejs-character-controller` — clones share MATERIALS, so the naive version repaints
+  both teams, and the naive fix draws zero calls), spawn each player on their
   team's side (respawn via `me.snap`), gate friendly fire in the hit-test — skip targets where
   `teams[target] === teams[me]` before applying damage — and frame the HUD ("your team" vs
   "enemy") from your own entry. A player not yet in the map renders neutral and takes no damage;