@volter/editor-model-play 0.5.196 → 0.5.198

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/editor-model-play",
-  "version": "0.5.196",
+  "version": "0.5.198",
   "author": "Volter AI, Inc.",
   "license": "AGPL-3.0-only",
   "type": "module",
@@ -28,7 +28,7 @@
     ]
   },
   "dependencies": {
-    "@volter/editor-sdk": "0.5.196"
+    "@volter/editor-sdk": "0.5.198"
   },
   "peerDependencies": {
     "react": "^19.0.0",

package/src/play-script.ts

@@ -160,17 +160,41 @@ export interface ModelPlayContext {
   autoplay(bot: ModelPlayAutoplayController | Readonly<Record<string, ModelPlayAutoplayController>> | null): void;
   /**
    * Set the action an object's armature plays, as Blender's `animation_data.action` does: any
-   * action in the file that animates that armature's bones, by name. `object` is the armature, its
-   * skinned mesh, or an object above or below them, or its name. Each armature starts a run playing
-   * the action the file assigns it. Setting another crossfades over `fade` seconds (0.2), loops
-   * unless `loop: false` (which holds the last frame), and plays at `speed`; setting the action
-   * already playing does nothing, so a script may set it every update from the character's state.
-   * `null` fades it out. Actions run on the game's clock. Each change is an `action` entry in the
-   * play log; a name the armature lacks is `action-unknown` once and returns false.
+   * action in the file, by name. `object` is the armature, its skinned mesh, or an object above or
+   * below them, or its name. Each armature starts a run playing the action the file assigns it.
+   * Setting another crossfades over `fade` seconds (0.2), repeats unless `loop: false` (which
+   * holds the last frame), and plays at `speed`; setting the action already playing does nothing,
+   * so a script may set it every update from the character's state. `null` fades it out. Each
+   * change is an `action` entry in the play log; a name the file lacks is `action-unknown` once
+   * and returns false.
+   *
+   * The armature plays as Blender plays it: its NLA tracks, then this action over them, then its
+   * bone constraints, all as the file sets them (and as the Timeline shows them).
    *
    *     play.setAction('Hero', moving ? 'Run' : 'Idle');
    */
   setAction(object: THREE.Object3D | string, action: string | null, options?: ModelPlayActionOptions): boolean;
+  /**
+   * Set one of the armature's NLA tracks, by name: the `action` it plays from now (a track the
+   * file lacks is made, over the file's), its `influence` (0 to 1, reached over `fade`), or
+   * `mute`. `null` gives the track back to the file. As in Blender, an action changes only the
+   * bones it keys: an action keyed on the upper body, on a track over a running action, is an
+   * upper body that aims while the legs run. Influences set every update blend poses between
+   * authored ones (aim up, level and down by the aim's angle).
+   *
+   *     play.setTrack('Hero', 'Aim', { action: 'Aim_Upper' });
+   *     play.setTrack('Hero', 'AimUp', { action: 'Aim_Up_Upper', influence: Math.max(0, pitch) });
+   */
+  setTrack(object: THREE.Object3D | string, track: string, options: ModelPlayTrackOptions | null): boolean;
+  /**
+   * Set one bone constraint the file gives the armature, by bone and constraint name: its
+   * `influence`, or the `target` object it aims at. A constraint aims at the game's copy of its
+   * file target, so moving that object in the game moves the aim with no call at all. A game
+   * plays Damped Track; another type is refused with the reason.
+   *
+   *     play.setConstraint('Hero', 'Head', 'Look', { influence: alert ? 1 : 0 });
+   */
+  setConstraint(object: THREE.Object3D | string, bone: string, constraint: string, options: ModelPlayConstraintOptions): boolean;
   /** The actions an object's armature can play, by name (empty without an armature). */
   actions(object: THREE.Object3D | string): readonly string[];
 }
@@ -179,10 +203,23 @@ export interface ModelPlayActionOptions {
   readonly loop?: boolean;
   readonly fade?: number;
   readonly speed?: number;
-  /** Start again from the first frame when this clip is already playing. */
+  /** Start again from the first frame when this action is already playing. */
   readonly restart?: boolean;
 }
 
+export interface ModelPlayTrackOptions extends ModelPlayActionOptions {
+  /** The action the track plays from now; absent, what the file gives it. */
+  readonly action?: string;
+  readonly influence?: number;
+  readonly mute?: boolean;
+}
+
+export interface ModelPlayConstraintOptions {
+  readonly influence?: number;
+  /** The object it aims at (or its name) instead of the file's target. */
+  readonly target?: THREE.Object3D | string | null;
+}
+
 /** What the bot is handed before each `update` it drives. */
 export interface ModelPlayAutoplayInput {
   /** The behaviour driving (`play autoplay on <behaviour>`), for a controller shared by several. */
@@ -387,6 +424,23 @@ export function runPlayScript(options: {
   options.container.style.opacity = '0';
   /** One script's context: its log, tint, opacity and bot do nothing once that script is gone
    *  (replaced, failed, or the run stopped), so a stale timer cannot reach a later one. */
+  /** The object an animation call names, and the document's animation; `action-unknown` once
+   *  per object and name when either is missing. */
+  const animated = (alive: Script, object: THREE.Object3D | string, what: string | null, call: string) => {
+    const name = typeof object === 'string' ? object : object.name;
+    const unknown = (why: string): false => {
+      const key = `${name}\u0000${call}\u0000${what}`;
+      if (!alive.unknown.has(key)) { alive.unknown.add(key); run.append('play', 'action-unknown', { object: name, call, action: what, why }); }
+      return false;
+    };
+    if (!alive.value) return { ok: false as const };
+    const target = typeof object === 'string' ? root.getObjectByName(object) ?? null : object;
+    if (!target) return { ok: unknown('the model has no such object') };
+    if (!options_.animation) return { ok: unknown('this document lends no animation') };
+    return { ok: true as const, target, animation: options_.animation, unknown };
+  };
+  /** What each NLA track was last set to, so the log says a change once. */
+  const tracks = new Map<string, string>();
   const contextFor = (alive: Script): ModelPlayContext => ({
     root,
     find(name) {
@@ -413,27 +467,50 @@ export function runPlayScript(options: {
       if (alive.value) alive.bot = behaviors;
     },
     setAction(object, action, options) {
-      if (!alive.value) return false;
-      const name = typeof object === 'string' ? object : object.name;
-      const target = typeof object === 'string' ? root.getObjectByName(object) ?? null : object;
-      const unknown = (why: string): false => {
-        const key = `${name}\u0000${action}`;
-        if (!alive.unknown.has(key)) { alive.unknown.add(key); run.append('play', 'action-unknown', { object: name, action, why }); }
-        return false;
-      };
-      if (!target) return unknown('the model has no such object');
-      if (!options_.animation) return unknown('this document lends no animation');
-      const before = options_.animation.playing(target);
+      const found = animated(alive, object, action, 'setAction');
+      if (!found.ok) return false;
+      const { target, animation } = found;
+      const before = animation.playing(target);
       if (action === null) {
-        options_.animation.stop(target, options?.fade);
+        animation.stop(target, options?.fade);
         if (before !== null) run.append('play', 'action', { object: target.name, action: null, from: before });
         return true;
       }
-      const answer = options_.animation.play(target, action, options);
-      if (!answer.ok) return unknown(answer.why);
+      const answer = animation.play(target, action, options);
+      if (!answer.ok) return found.unknown(answer.why);
       if (before !== action || options?.restart) run.append('play', 'action', { armature: answer.armature, action, from: before });
       return true;
     },
+    setTrack(object, track, options) {
+      const found = animated(alive, object, track, 'setTrack');
+      if (!found.ok) return false;
+      const answer = found.animation.track(found.target, track, options);
+      if (!answer.ok) return found.unknown(answer.why);
+      // Influences change every update; the log keeps what the track plays and whether it is muted.
+      const key = `${answer.armature}${track}`;
+      const now = options === null ? 'file' : JSON.stringify([options.action ?? null, options.mute ?? false]);
+      if (tracks.get(key) !== now) {
+        tracks.set(key, now);
+        run.append('play', 'track', { armature: answer.armature, track, ...(options === null ? { file: true } : { action: options.action ?? null, mute: options.mute ?? false }) });
+      }
+      return true;
+    },
+    setConstraint(object, bone, constraint, options) {
+      const found = animated(alive, object, `${bone}/${constraint}`, 'setConstraint');
+      if (!found.ok) return false;
+      let aim: THREE.Object3D | null | undefined = undefined;
+      if (typeof options.target === 'string') {
+        aim = root.getObjectByName(options.target) ?? null;
+        if (!aim) return found.unknown(`the model has no object "${options.target}" to aim at`);
+      } else aim = options.target;
+      const answer = found.animation.constraint(found.target, bone, constraint, {
+        ...(options.influence === undefined ? {} : { influence: options.influence }),
+        ...(aim === undefined ? {} : { target: aim }),
+      });
+      if (!answer.ok) return found.unknown(answer.why);
+      if (aim !== undefined) run.append('play', 'constraint', { armature: answer.armature, bone, constraint, target: aim?.name ?? null });
+      return true;
+    },
     actions(object) {
       const target = typeof object === 'string' ? root.getObjectByName(object) ?? null : object;
       return target && options_.animation ? options_.animation.clips(target) : [];