@volter/editor-blender 0.1.135 → 0.1.136

package/contributions/blender-play-skin.ts

@@ -1,236 +1,168 @@
 /**
- * ANIMATION IN PLAY: the same skin and clips the Timeline plays (`blender-runtime-skin.ts`), bound
- * to Play's detached copy and driven by the game.
+ * ANIMATION IN A GAME: actions played on the skeletons of the game's copy of the model.
  *
- * Play runs a game on a copy of the model (`BlenderRuntimeView.detach`). Until this module the copy
- * was built without its skins, so every rigged character was a frozen mesh in a game while the same
- * character played in Movie. Nothing here is a second animation system: the rigs are bound by
- * `bindRig` and the clips built by `clipTracks`, the Timeline's own code, over the copy's graph.
+ * The copy binds its own skins (`BlenderRuntimeView.detach` keeps each skinned mesh's weights and
+ * the frame's armatures, and its view's `skeletons` builds and binds them exactly as the editing
+ * view does), so nothing here binds or reads a rig. What a game plays is Blender's: each armature
+ * starts on the action the file assigns it (`animation_data.action`), and a script sets another by
+ * name (`play.setAction`), as Blender's own assignment does. Any action in the file may be set; one
+ * that animates none of an armature's bones refuses, with the reason, once.
  *
- * WHAT A GAME PLAYS is any action that animates an armature's bones, assigned or not, so a file can
- * hold a clip library (Idle, Run, Attack, Die side by side) and a game chooses among them by name.
- * Each armature has its own `THREE.AnimationMixer`; a play crossfades from what played before.
+ * A CLIP IS BAKED ONCE PER ACTION, through the clip door, the first time it is wanted. The copy's
+ * frame is the frame it was detached from, so its revisions hold for the run. Until a bake lands
+ * the armature keeps what it showed before (at first, the pose Blender exported).
  *
- * THE GAME'S CLOCK DRIVES IT: the runner advances the mixers by the `dt` each `update` is handed
- * (`@volter/editor-model-play`'s `play-script.ts`), so pause, step, speed and Restart hold for
- * animation exactly as they do for the script. Nothing advances on the page's own time.
+ * LAYERS, BLENDS AND LOOK-AT: each armature has a layered mixer (`blender-play-mixer.ts`), so a
+ * game plays actions on parts of a body, at weights, and turns a bone toward what only it knows.
  *
- * READ ONCE PER PLAY: the rig and every clip are read from the engine when Play starts (`rna_rig`
- * walks every vertex of every rigged mesh, a clip bakes every bone per frame), never per frame.
+ * THE GAME'S CLOCK DRIVES IT: the runner advances the mixers by each update's `dt`
+ * (`@volter/editor-model-play`'s `play-script.ts`), so pause, step, speed and Restart hold for
+ * animation exactly as they do for the script.
  */
-import type { BlenderActionClip, BlenderRig } from '@volter/blender-engine/browser/rna';
+import type { BlenderActionClip } from '@volter/blender-engine/browser/rna';
+import type { BlenderRuntimeView } from '@volter/blender-engine/browser/three/blender-runtime-view';
+import type { ArmatureRig } from '@volter/blender-engine/browser/three/blender-runtime-skeleton';
 import * as THREE from 'three';
-import { blenderActionClip, blenderArmatureActions, blenderRig } from '../host/blender-runtime-host';
-import { bindRig, clipTracks, type BoundRig, type SkinPresentation } from './blender-runtime-skin';
-
-/** What Play reads from the engine: the rigs, every armature's action names, and the assigned
- *  actions baked. Any other action is baked the first time a game sets it (`bake`). */
-export interface PlayClipLibrary {
-  readonly rig: BlenderRig | null;
-  /** Armature name -> the actions that can play on it. */
-  readonly names: ReadonlyMap<string, readonly string[]>;
-  /** Armature name -> the action assigned to it in the file (`animation_data.action`), which it
-   *  plays from the start of a run, as Blender would. */
-  readonly assigned: ReadonlyMap<string, string>;
-  /** Armature name -> its baked clips by action name (the assigned ones at first). */
-  readonly clips: ReadonlyMap<string, ReadonlyMap<string, BlenderActionClip>>;
-  /** Bake one more action for an armature; null, with the reason in `warnings`, when it cannot play. */
-  bake(armature: string, action: string): Promise<BlenderActionClip | null>;
-  readonly warnings: string[];
-}
+import { clipTracks } from './blender-runtime-skin';
+import { LayeredMixer, type LayerOptions, type LookAtOptions } from './blender-play-mixer';
 
-/** Read the rigs and the assigned clips a game starts with. Empty when the file has no armature. */
-export async function readPlayClipLibrary(): Promise<PlayClipLibrary> {
-  const warnings: string[] = [];
-  const [rig, listing] = await Promise.all([blenderRig(), blenderArmatureActions()]);
-  const names = new Map<string, readonly string[]>();
-  const assigned = new Map<string, string>();
-  const clips = new Map<string, Map<string, BlenderActionClip>>();
-  const bake = async (armature: string, action: string): Promise<BlenderActionClip | null> => {
-    try {
-      const clip = await blenderActionClip({ object: armature, action });
-      if (clip?.reason) warnings.push(`${armature} / ${action}: ${clip.reason}`);
-      if (clip?.tracks.length && clip.clipStart !== undefined && clip.clipEnd !== undefined) return clip;
-    } catch (error) {
-      warnings.push(`${armature} / ${action} could not be read: ${error instanceof Error ? error.message : String(error)}`);
-    }
-    return null;
-  };
-  await Promise.all((listing?.armatures ?? []).map(async ({ armature, actions, current }) => {
-    names.set(armature, actions);
-    if (!current) return;
-    assigned.set(armature, current);
-    const clip = await bake(armature, current);
-    if (clip) clips.set(armature, new Map([[current, clip]]));
-  }));
-  return { rig, names, assigned, clips, bake, warnings };
-}
+export type PlayAnimateOptions = LayerOptions;
 
-export interface PlayAnimateOptions {
-  /** Repeat until something else plays (default true). */
-  readonly loop?: boolean;
-  /** Seconds to crossfade from what this armature played before (default 0.2). */
-  readonly fade?: number;
-  /** Playback rate, 1 is the clip's own speed. */
-  readonly speed?: number;
-  /** Start again from the first frame when this clip is already playing (default false). */
-  readonly restart?: boolean;
-}
+type Answer = { ok: true; armature: string } | { ok: false; why: string };
 
-/** The game's door to its characters' clips (`ModelPlayContext.animate`). */
+/** The game's door to its characters' actions (`ModelPlayContext.setAction`, `blend`, `lookAt`). */
 export interface PlayAnimation {
-  /** The clips an object can play: its own armature's, or the armature its rigged mesh is bound to. */
+  /** The actions in the file, which an object's armature may be set to play. */
   clips(object: THREE.Object3D): readonly string[];
-  /** Play a clip on an object's armature; the reason when it cannot. */
-  play(object: THREE.Object3D, clip: string, options?: PlayAnimateOptions): { ok: true; armature: string } | { ok: false; why: string };
-  /** Fade out whatever the object's armature plays. */
-  stop(object: THREE.Object3D, fade?: number): void;
-  /** The clip the object's armature plays now, or null. */
-  playing(object: THREE.Object3D): string | null;
-  /** Advance every mixer by one update's `dt` (the game's clock). */
+  /** Play one action on a layer of an object's armature; the reason when it cannot. */
+  play(object: THREE.Object3D, clip: string, options?: PlayAnimateOptions): Answer;
+  /** Set a layer's actions at weights. */
+  blend(object: THREE.Object3D, weights: Readonly<Record<string, number>>, options?: PlayAnimateOptions): Answer;
+  /** Fade out what a layer plays. */
+  stop(object: THREE.Object3D, fade?: number, layer?: string): void;
+  /** The action that weighs most on a layer, as last set, or null. */
+  playing(object: THREE.Object3D, layer?: string): string | null;
+  /** Turn one of an object's bones toward a point (or object) every update, until `null`. */
+  lookAt(object: THREE.Object3D, bone: string, target: THREE.Vector3 | THREE.Object3D | null, options?: LookAtOptions): Answer;
   update(dt: number): void;
   readonly warnings: readonly string[];
   dispose(): void;
 }
 
 interface Armature {
-  readonly name: string;
-  readonly object: THREE.Object3D;
-  readonly mixer: THREE.AnimationMixer;
-  /** Every action that can play on it, baked or not. */
-  readonly names: readonly string[];
-  readonly bones: ReadonlyMap<string, THREE.Bone>;
+  readonly rig: ArmatureRig;
+  readonly mixer: LayeredMixer;
   readonly clips: Map<string, THREE.AnimationClip>;
-  /** Bakes in flight, by action name. */
-  readonly baking: Map<string, Promise<void>>;
-  /** Actions whose bake gave nothing to play: asked once, never re-baked every update. */
-  readonly failed: Set<string>;
-  current: { readonly name: string; readonly action: THREE.AnimationAction } | null;
-  /** The action most recently set, which a bake in flight starts when it lands. */
-  wanted: { readonly name: string; readonly options: PlayAnimateOptions } | null;
+  readonly baking: Set<string>;
+  /** Actions with nothing this armature can play: asked once, never re-baked every update. */
+  readonly failed: Map<string, string>;
 }
 
-/** Bind the library's rigs and clips to Play's copy. */
-export function bindPlayAnimation(presentation: SkinPresentation, library: PlayClipLibrary): PlayAnimation {
-  const warnings = [...library.warnings];
-  const rigs: BoundRig[] = [];
-  for (const rig of library.rig?.rigs ?? []) {
-    if (!rig.object || !rig.armature || !rig.skinIndexBase64 || !rig.skinWeightBase64) {
-      if (rig.reason) warnings.push(rig.reason);
-      continue;
-    }
-    const bound = bindRig(presentation, rig, library.rig!.frame, warnings);
-    if (bound) rigs.push(bound);
-  }
+/** The copy's animation. `bake` reads one action of one armature through the clip door. */
+export function playAnimation(view: BlenderRuntimeView, bake: (armature: string, action: string) => Promise<BlenderActionClip | null>): PlayAnimation {
+  const warnings: string[] = [];
+  const facts = view.animationFacts();
+  const actions = Object.keys(facts.actions);
   const armatures = new Map<string, Armature>();
-  /** A mesh's presented object → the armature its skin is bound to. */
-  const meshArmature = new Map<THREE.Object3D, string>();
-  for (const rig of rigs) meshArmature.set(rig.mesh, rig.armature);
-  const toClip = (action: string, clip: BlenderActionClip, bones: ReadonlyMap<string, THREE.Bone>): THREE.AnimationClip | null => {
-    const tracks = clipTracks(clip, bones, warnings);
-    if (!tracks.length) return null;
-    return new THREE.AnimationClip(action, clip.duration ?? (clip.clipEnd! - clip.clipStart!) / clip.fps, tracks);
+  let disposed = false;
+
+  const refuse = (armature: Armature, clip: string, why: string): void => {
+    armature.failed.set(clip, why);
+    warnings.push(`${armature.rig.armature} / ${clip}: ${why}`);
   };
-  for (const [name, actions] of library.names) {
-    const object = presentation.objectForBlenderName(name);
-    if (!object || !actions.length) continue;
-    const bones = new Map<string, THREE.Bone>();
-    for (const rig of rigs) if (rig.armature === name) for (const bone of rig.bones) bones.set(bone.name, bone);
-    if (!bones.size) { warnings.push(`${name} has actions but no skinned mesh is bound to it, so they would move nothing.`); continue; }
-    const clips = new Map<string, THREE.AnimationClip>();
-    for (const [action, clip] of library.clips.get(name) ?? []) {
-      const built = toClip(action, clip, bones);
-      if (built) clips.set(action, built);
-    }
-    armatures.set(name, { name, object, mixer: new THREE.AnimationMixer(object), names: actions, bones, clips, baking: new Map(), failed: new Set(), current: null, wanted: null });
+
+  /** The clip the mixer asks for: baked, or baked now (once) and given on a later update. */
+  const clipFor = (armature: Armature, clip: string): THREE.AnimationClip | null => {
+    const held = armature.clips.get(clip);
+    if (held || disposed || armature.failed.has(clip) || armature.baking.has(clip)) return held ?? null;
+    armature.baking.add(clip);
+    void bake(armature.rig.armature, clip).then((baked) => {
+      armature.baking.delete(clip);
+      const tracks = baked && baked.clipStart !== undefined && baked.clipEnd !== undefined
+        ? clipTracks(baked, armature.rig.bones, warnings) : [];
+      if (!baked || !tracks.length) {
+        refuse(armature, clip, baked?.reason ?? `it animates none of ${armature.rig.armature}'s bones`);
+        return;
+      }
+      const duration = baked.duration ?? (baked.clipEnd! - baked.clipStart!) / baked.fps;
+      armature.clips.set(clip, new THREE.AnimationClip(clip, duration, tracks));
+    }, (error: unknown) => {
+      armature.baking.delete(clip);
+      refuse(armature, clip, `it could not be read: ${error instanceof Error ? error.message : String(error)}`);
+    });
+    return null;
+  };
+
+  for (const rig of view.skeletons.rigs()) {
+    const armature: Armature = {
+      rig, clips: new Map(), baking: new Set(), failed: new Map(),
+      mixer: new LayeredMixer(rig.object, rig.bones, (clip) => clipFor(armature, clip)),
+    };
+    armatures.set(rig.armature, armature);
   }
-  const objectArmature = new Map<THREE.Object3D, Armature>();
-  for (const armature of armatures.values()) objectArmature.set(armature.object, armature);
-  // EACH ARMATURE PLAYS ITS ASSIGNED ACTION from the first update, as Blender's viewport does.
+
+  // EACH ARMATURE STARTS ON ITS ASSIGNED ACTION, as Blender's viewport plays it.
   for (const armature of armatures.values()) {
-    const name = library.assigned.get(armature.name);
-    const source = name ? armature.clips.get(name) : undefined;
-    if (!name || !source) continue;
-    const action = armature.mixer.clipAction(source);
-    action.setLoop(THREE.LoopRepeat, Number.POSITIVE_INFINITY);
-    action.play();
-    armature.current = { name, action };
+    const assigned = facts.armatures[armature.rig.armature]?.action;
+    if (assigned) armature.mixer.set(assigned, { fade: 0 });
   }
-  /** The armature that animates `object`: itself, the one its skin is bound to, or the nearest
-   *  armature among its ancestors and descendants (a character's root empty holds its armature). */
+
+  /** The armature that animates `object`: its own, the one its skin is bound to, or the nearest
+   *  armature among its ancestors and descendants (a character's root holds its armature). */
+  const own = (candidate: THREE.Object3D): Armature | null => {
+    for (const armature of armatures.values()) if (armature.rig.object === candidate) return armature;
+    const skin = (candidate as THREE.Mesh).geometry?.userData['blenderSkin'] as { armature: string } | undefined;
+    return skin ? armatures.get(skin.armature) ?? null : null;
+  };
   const armatureOf = (object: THREE.Object3D): Armature | null => {
-    const own = objectArmature.get(object) ?? armatures.get(meshArmature.get(object) ?? '');
-    if (own) return own;
-    for (let parent = object.parent; parent; parent = parent.parent) {
-      const found = objectArmature.get(parent);
+    for (let at: THREE.Object3D | null = object; at; at = at.parent) {
+      const found = own(at);
       if (found) return found;
     }
     let found: Armature | null = null;
-    object.traverse((child) => { if (!found) found = objectArmature.get(child) ?? armatures.get(meshArmature.get(child) ?? '') ?? null; });
+    object.traverse((child) => { if (!found) found = own(child); });
     return found;
   };
-  let disposed = false;
-  /** Crossfade an armature to a baked action. */
-  const start = (armature: Armature, clip: string, options: PlayAnimateOptions): void => {
-    const source = armature.clips.get(clip)!;
-    const fade = Math.max(0, options.fade ?? 0.2);
-    const action = armature.mixer.clipAction(source);
-    action.setLoop(options.loop === false ? THREE.LoopOnce : THREE.LoopRepeat, Number.POSITIVE_INFINITY);
-    action.clampWhenFinished = options.loop === false;
-    action.setEffectiveTimeScale(options.speed ?? 1);
-    if (armature.current?.name === clip) {
-      if (options.restart) action.reset().play();
-      return;
+
+  /** The armature, after checking every action named is one it can play. */
+  const resolve = (object: THREE.Object3D, clips: readonly string[]): Armature | { why: string } => {
+    const armature = armatureOf(object);
+    if (!armature) return { why: `${object.name || 'this object'} has no armature` };
+    for (const clip of clips) {
+      if (!(clip in facts.actions)) return { why: `the file has no action "${clip}"` };
+      const failed = armature.failed.get(clip);
+      if (failed) return { why: failed };
     }
-    action.reset().setEffectiveWeight(1).play();
-    if (armature.current && fade > 0) armature.current.action.crossFadeTo(action, fade, false);
-    else armature.current?.action.stop();
-    armature.current = { name: clip, action };
+    return armature;
   };
+  const answer = (armature: Armature, refused: string | null): Answer =>
+    refused ? { ok: false, why: refused } : { ok: true, armature: armature.rig.armature };
+
   return {
     warnings,
-    clips: (object) => [...(armatureOf(object)?.names ?? [])],
+    clips: (object) => (armatureOf(object) ? actions : []),
     play(object, clip, options = {}) {
-      const armature = armatureOf(object);
-      if (!armature) return { ok: false, why: `${object.name || 'this object'} has no armature with actions` };
-      if (!armature.names.includes(clip)) return { ok: false, why: `${armature.name} has no action "${clip}"; it has ${armature.names.join(', ')}` };
-      if (armature.failed.has(clip)) return { ok: false, why: `${armature.name}'s action "${clip}" has nothing this armature can play (see the console)` };
-      armature.wanted = { name: clip, options };
-      if (!armature.clips.has(clip)) {
-        // FIRST USE: baked now, and started when it lands if it is still the one wanted.
-        if (!armature.baking.has(clip))
-          armature.baking.set(clip, library.bake(armature.name, clip).then((baked) => {
-            armature.baking.delete(clip);
-            const built = baked ? toClip(clip, baked, armature.bones) : null;
-            if (built) armature.clips.set(clip, built);
-            else {
-              armature.failed.add(clip);
-              if (armature.wanted?.name === clip) armature.wanted = null;
-            }
-            if (built && !disposed && armature.wanted?.name === clip) start(armature, clip, armature.wanted.options);
-          }));
-        return { ok: true, armature: armature.name };
-      }
-      start(armature, clip, options);
-      return { ok: true, armature: armature.name };
+      const armature = resolve(object, [clip]);
+      return 'why' in armature ? { ok: false, why: armature.why } : answer(armature, armature.mixer.set(clip, options));
     },
-    stop(object, fade = 0.2) {
-      const armature = armatureOf(object);
-      if (armature) armature.wanted = null;
-      if (!armature?.current) return;
-      if (fade > 0) armature.current.action.fadeOut(fade); else armature.current.action.stop();
-      armature.current = null;
+    blend(object, weights, options = {}) {
+      const armature = resolve(object, Object.keys(weights));
+      return 'why' in armature ? { ok: false, why: armature.why } : answer(armature, armature.mixer.blend(weights, options));
+    },
+    stop(object, fade = 0.2, layer) {
+      armatureOf(object)?.mixer.stop({ fade, ...(layer ? { layer } : {}) });
     },
-    // What was last set, so a script that sets the same action every update while it bakes asks once.
-    playing: (object) => {
+    // What was last set, so a script setting the same action every update while it bakes asks once.
+    playing: (object, layer) => armatureOf(object)?.mixer.playing(layer) ?? null,
+    lookAt(object, bone, target, options = {}) {
       const armature = armatureOf(object);
-      return armature?.wanted?.name ?? armature?.current?.name ?? null;
+      if (!armature) return { ok: false, why: `${object.name || 'this object'} has no armature` };
+      return answer(armature, armature.mixer.lookAt(bone, target, options));
     },
     update(dt) { for (const armature of armatures.values()) armature.mixer.update(dt); },
     dispose() {
       disposed = true;
-      for (const armature of armatures.values()) armature.mixer.stopAllAction();
-      for (const rig of rigs) rig.skeleton.dispose();
+      for (const armature of armatures.values()) armature.mixer.dispose();
     },
   };
 }