@ikijs/engine 0.1.1 → 0.3.0

package/README.md

@@ -1,9 +1,9 @@
 # @ikijs/engine
 
-WebGL2 runtime that plays a [`.iki`](../format) puppet model in the browser.
+WebGL2 runtime that plays a [`.iki`](https://github.com/zeikar/iki/tree/main/packages/format) puppet model in the browser.
 
 The engine is **host-agnostic**: it depends only on
-[`@ikijs/format`](../format) and knows nothing about any particular app. A host
+[`@ikijs/format`](https://github.com/zeikar/iki/tree/main/packages/format) and knows nothing about any particular app. A host
 drives it by setting parameters (from lip-sync, gaze, blink, expressions); the
 engine renders the result each frame.
 
@@ -38,15 +38,16 @@ clamped to the declared range; unknown ids and non-finite values are ignored.
 
 ## API
 
-| Export                                           | What it is                                                                                              |
-| ------------------------------------------------ | ------------------------------------------------------------------------------------------------------- |
-| `IkiPlayer`                                      | The renderer: `load` / `start` / `stop` / `setParameter` / `getParameter` / `getParameters` / `destroy` |
-| `IkiLoadResult`                                  | `{ failedTextures, superseded }` returned by `load()`                                                   |
-| `ParameterStore`                                 | The clamped parameter map the player drives                                                             |
-| `IdleMotion`                                     | Auto-blink / breath / gaze-drift driver                                                                 |
-| `PhysicsMotion`                                  | Spring-mass-damper secondary motion (`model.physics`)                                                   |
-| `HairChainMotion`                                | Multi-segment angular chain with gravity (`model.physicsChains`)                                        |
-| `translate` `rotate` `scale` `multiply` `toMat3` | The 2D affine helpers the engine itself uses                                                            |
+| Export                                           | What it is                                                                                                 |
+| ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------- |
+| `IkiPlayer`                                      | The renderer: `load` / `start` / `stop` / `setParameter` / `getParameter` / `getParameters` / `destroy`    |
+| `IkiLoadResult`                                  | `{ failedTextures, superseded }` returned by `load()`                                                      |
+| `ParameterStore`                                 | The clamped parameter map the player drives                                                                |
+| `IkiMotion`                                      | The three drivers below, built from a model and stepped as one; `drivenParameterIds` lists what they write |
+| `IdleMotion`                                     | Auto-blink / breath / gaze-drift driver                                                                    |
+| `PhysicsMotion`                                  | Spring-mass-damper secondary motion (`model.physics`)                                                      |
+| `HairChainMotion`                                | Multi-segment angular chain with gravity (`model.physicsChains`)                                           |
+| `translate` `rotate` `scale` `multiply` `toMat3` | The 2D affine helpers the engine itself uses                                                               |
 
 ## Motion drivers
 
@@ -56,37 +57,30 @@ per frame, and each writes through a sink you supply. That keeps them testable
 and lets a host override or omit any of them.
 
 ```ts
-import { HairChainMotion, IdleMotion, PhysicsMotion } from "@ikijs/engine";
+import { IkiMotion } from "@ikijs/engine";
 
 // The drivers read the live pose and write the next one, both through the
 // player — no host-side copy of the parameter state to keep in sync.
-const drive = (id: string, value: number) => player.setParameter(id, value);
-const read = (id: string) => player.getParameter(id);
-
-const idle = new IdleMotion(drive);
-const physics = new PhysicsMotion(
-  model.physics ?? [],
-  model.parameters,
-  read,
-  drive,
-);
-const chains = new HairChainMotion(
-  model.physicsChains ?? [],
-  model.parameters,
-  model.deformers ?? [],
-  read,
-  drive,
+const motion = new IkiMotion(
+  model,
+  (id) => player.getParameter(id),
+  (id, value) => player.setParameter(id, value),
 );
 
 const tick = (now: number) => {
-  idle.update(now);
-  physics.update(now); // reads what idle just wrote
-  chains.update(now);
+  motion.update(now); // idle, then physics (lags what idle just wrote), then chains
   requestAnimationFrame(tick);
 };
 requestAnimationFrame(tick);
 ```
 
+To stop, stop calling `update()` — the drivers leave the pose where it was,
+and `motion.drivenParameterIds` lists every parameter they wrote for a host
+that wants to restore it. The three drivers are also exported individually
+(`IdleMotion`, `PhysicsMotion`, `HairChainMotion`): the two physics drivers
+take the same `read`/`sink` pair, `IdleMotion` only the `sink`, and each is
+stepped with `update(nowMs)` in that order.
+
 Both physics drivers integrate on a fixed 1/60 s sub-step with a clamped frame
 delta, so a backgrounded tab or a long hitch cannot snap the rig.
 

package/dist/index.d.mts

@@ -189,7 +189,7 @@ interface IdleMotionOptions {
     rng?: () => number;
 }
 /**
- * Pure-logic idle-animation driver. Animates the seven "life" parameters
+ * Pure-logic idle-animation driver. Animates the eight "life" parameters
  * (eyes, breath, gaze, head sway) on an internal clock so tab-backgrounding
  * or irregular frame delivery can't produce teleports or snap-close blinks.
  *
@@ -201,6 +201,13 @@ interface IdleMotionOptions {
  * The host is responsible for scheduling; this class has no timers or rAF.
  */
 declare class IdleMotion {
+    /**
+     * Every parameter id {@link update} and `emitRestingPose` write, in write
+     * order. Published so a host (or IkiMotion) can restore them after it
+     * stops driving — keep in step with those two methods; the test suite
+     * pins this list to the actual emissions.
+     */
+    readonly drivenParameterIds: readonly string[];
     private readonly sink;
     private readonly rng;
     private clockMs;
@@ -232,6 +239,8 @@ declare class IdleMotion {
     private swayX;
     /** Vertical head sway in degrees, pure function of the internal clock. */
     private swayY;
+    /** Head roll sway in degrees, pure function of the internal clock. */
+    private swayZ;
     /** Ease gaze current toward target; pick a new target on the internal clock. */
     private advanceGaze;
 }
@@ -260,6 +269,8 @@ declare class IdleMotion {
  * updated params on its own render loop (drivers and rendering are decoupled).
  */
 declare class PhysicsMotion {
+    /** The output parameter of every rig, in rig order — what `emit` writes. */
+    readonly drivenParameterIds: readonly string[];
     private readonly rigs;
     private readonly read;
     private readonly sink;
@@ -315,6 +326,8 @@ declare class PhysicsMotion {
  * The host schedules updates; this class has no timers, rAF, DOM, or Date.now.
  */
 declare class HairChainMotion {
+    /** Every segment's output, chain by chain — what `emitSegment` writes. */
+    readonly drivenParameterIds: readonly string[];
     private readonly chainData;
     private readonly params;
     private readonly deformers;
@@ -370,4 +383,49 @@ declare class HairChainMotion {
     private emitSegment;
 }
 
-export { type Affine, HairChainMotion, IdleMotion, type IdleMotionOptions, type IkiLoadResult, IkiPlayer, ParameterStore, PhysicsMotion, multiply, rotate, scale, toMat3, translate };
+/**
+ * Bundles the three motion drivers — {@link IdleMotion}, {@link PhysicsMotion},
+ * {@link HairChainMotion} — into the one loop every host otherwise hand-builds:
+ * construct all three from the model, step them in the order physics and
+ * chains depend on, and know what they wrote.
+ *
+ * Usage:
+ *   const motion = new IkiMotion(
+ *     model,
+ *     (id) => player.getParameter(id),
+ *     (id, value) => player.setParameter(id, value),
+ *   );
+ *   // inside your rAF loop:
+ *   motion.update(performance.now());
+ *
+ * The host schedules; this class has no timers, rAF, DOM, or Date.now.
+ *
+ * Stopping is the host's too: stop calling update(). The drivers leave the
+ * pose where it was — a host that wants it back writes its own resting values
+ * to `drivenParameterIds`.
+ */
+declare class IkiMotion {
+    /**
+     * Idle ids, then rig outputs, then chain-segment outputs, deduplicated and
+     * insertion-ordered. May name ids the model lacks (the player silently
+     * drops writes to unknown ids) — intersect with the model's parameters if
+     * you mirror into your own store.
+     */
+    readonly drivenParameterIds: readonly string[];
+    private readonly idle;
+    private readonly physics;
+    private readonly chains;
+    constructor(model: IkiModel, read: (id: string) => number, sink: (id: string, value: number) => void);
+    /**
+     * Advance idle, then physics, then chains to the same wall-clock timestamp
+     * (milliseconds). Order is load-bearing: `PhysicsMotion` reads its input
+     * parameters (typically `ParamAngleX/Z`) through `read`, and the head sway
+     * idle wrote THIS frame is what the springs must lag behind; `HairChainMotion`
+     * then resolves its anchor deformer's world rotation from that same
+     * just-written pose (which may include a physics output). One timestamp for
+     * all three keeps their dt in lockstep.
+     */
+    update(nowMs: number): void;
+}
+
+export { type Affine, HairChainMotion, IdleMotion, type IdleMotionOptions, type IkiLoadResult, IkiMotion, IkiPlayer, ParameterStore, PhysicsMotion, multiply, rotate, scale, toMat3, translate };

package/dist/index.d.ts

@@ -189,7 +189,7 @@ interface IdleMotionOptions {
     rng?: () => number;
 }
 /**
- * Pure-logic idle-animation driver. Animates the seven "life" parameters
+ * Pure-logic idle-animation driver. Animates the eight "life" parameters
  * (eyes, breath, gaze, head sway) on an internal clock so tab-backgrounding
  * or irregular frame delivery can't produce teleports or snap-close blinks.
  *
@@ -201,6 +201,13 @@ interface IdleMotionOptions {
  * The host is responsible for scheduling; this class has no timers or rAF.
  */
 declare class IdleMotion {
+    /**
+     * Every parameter id {@link update} and `emitRestingPose` write, in write
+     * order. Published so a host (or IkiMotion) can restore them after it
+     * stops driving — keep in step with those two methods; the test suite
+     * pins this list to the actual emissions.
+     */
+    readonly drivenParameterIds: readonly string[];
     private readonly sink;
     private readonly rng;
     private clockMs;
@@ -232,6 +239,8 @@ declare class IdleMotion {
     private swayX;
     /** Vertical head sway in degrees, pure function of the internal clock. */
     private swayY;
+    /** Head roll sway in degrees, pure function of the internal clock. */
+    private swayZ;
     /** Ease gaze current toward target; pick a new target on the internal clock. */
     private advanceGaze;
 }
@@ -260,6 +269,8 @@ declare class IdleMotion {
  * updated params on its own render loop (drivers and rendering are decoupled).
  */
 declare class PhysicsMotion {
+    /** The output parameter of every rig, in rig order — what `emit` writes. */
+    readonly drivenParameterIds: readonly string[];
     private readonly rigs;
     private readonly read;
     private readonly sink;
@@ -315,6 +326,8 @@ declare class PhysicsMotion {
  * The host schedules updates; this class has no timers, rAF, DOM, or Date.now.
  */
 declare class HairChainMotion {
+    /** Every segment's output, chain by chain — what `emitSegment` writes. */
+    readonly drivenParameterIds: readonly string[];
     private readonly chainData;
     private readonly params;
     private readonly deformers;
@@ -370,4 +383,49 @@ declare class HairChainMotion {
     private emitSegment;
 }
 
-export { type Affine, HairChainMotion, IdleMotion, type IdleMotionOptions, type IkiLoadResult, IkiPlayer, ParameterStore, PhysicsMotion, multiply, rotate, scale, toMat3, translate };
+/**
+ * Bundles the three motion drivers — {@link IdleMotion}, {@link PhysicsMotion},
+ * {@link HairChainMotion} — into the one loop every host otherwise hand-builds:
+ * construct all three from the model, step them in the order physics and
+ * chains depend on, and know what they wrote.
+ *
+ * Usage:
+ *   const motion = new IkiMotion(
+ *     model,
+ *     (id) => player.getParameter(id),
+ *     (id, value) => player.setParameter(id, value),
+ *   );
+ *   // inside your rAF loop:
+ *   motion.update(performance.now());
+ *
+ * The host schedules; this class has no timers, rAF, DOM, or Date.now.
+ *
+ * Stopping is the host's too: stop calling update(). The drivers leave the
+ * pose where it was — a host that wants it back writes its own resting values
+ * to `drivenParameterIds`.
+ */
+declare class IkiMotion {
+    /**
+     * Idle ids, then rig outputs, then chain-segment outputs, deduplicated and
+     * insertion-ordered. May name ids the model lacks (the player silently
+     * drops writes to unknown ids) — intersect with the model's parameters if
+     * you mirror into your own store.
+     */
+    readonly drivenParameterIds: readonly string[];
+    private readonly idle;
+    private readonly physics;
+    private readonly chains;
+    constructor(model: IkiModel, read: (id: string) => number, sink: (id: string, value: number) => void);
+    /**
+     * Advance idle, then physics, then chains to the same wall-clock timestamp
+     * (milliseconds). Order is load-bearing: `PhysicsMotion` reads its input
+     * parameters (typically `ParamAngleX/Z`) through `read`, and the head sway
+     * idle wrote THIS frame is what the springs must lag behind; `HairChainMotion`
+     * then resolves its anchor deformer's world rotation from that same
+     * just-written pose (which may include a physics output). One timestamp for
+     * all three keeps their dt in lockstep.
+     */
+    update(nowMs: number): void;
+}
+
+export { type Affine, HairChainMotion, IdleMotion, type IdleMotionOptions, type IkiLoadResult, IkiMotion, IkiPlayer, ParameterStore, PhysicsMotion, multiply, rotate, scale, toMat3, translate };

package/dist/index.js

@@ -22,6 +22,7 @@ var index_exports = {};
 __export(index_exports, {
   HairChainMotion: () => HairChainMotion,
   IdleMotion: () => IdleMotion,
+  IkiMotion: () => IkiMotion,
   IkiPlayer: () => IkiPlayer,
   ParameterStore: () => ParameterStore,
   PhysicsMotion: () => PhysicsMotion,
@@ -1084,6 +1085,8 @@ var SWAY_X_AMP_B_DEG = 1.3;
 var SWAY_X_PERIOD_B_MS = 9700;
 var SWAY_Y_AMP_DEG = 1.6;
 var SWAY_Y_PERIOD_MS = 7300;
+var SWAY_Z_AMP_DEG = 1.1;
+var SWAY_Z_PERIOD_MS = 11300;
 function lerp(a, b, t) {
   return a + (b - a) * t;
 }
@@ -1096,6 +1099,22 @@ function randomInDisk(rng, radius) {
   return [r * Math.cos(theta), r * Math.sin(theta)];
 }
 var IdleMotion = class {
+  /**
+   * Every parameter id {@link update} and `emitRestingPose` write, in write
+   * order. Published so a host (or IkiMotion) can restore them after it
+   * stops driving — keep in step with those two methods; the test suite
+   * pins this list to the actual emissions.
+   */
+  drivenParameterIds = [
+    import_format.StandardParameter.EyeOpenLeft,
+    import_format.StandardParameter.EyeOpenRight,
+    import_format.StandardParameter.Breath,
+    import_format.StandardParameter.EyeballX,
+    import_format.StandardParameter.EyeballY,
+    import_format.StandardParameter.AngleX,
+    import_format.StandardParameter.AngleY,
+    import_format.StandardParameter.AngleZ
+  ];
   sink;
   rng;
   // Internal clock: advances by clamped dt, NOT by raw wall-clock jumps.
@@ -1157,6 +1176,7 @@ var IdleMotion = class {
     this.sink(import_format.StandardParameter.EyeballY, this.gazeCurrentY);
     this.sink(import_format.StandardParameter.AngleX, this.swayX());
     this.sink(import_format.StandardParameter.AngleY, this.swayY());
+    this.sink(import_format.StandardParameter.AngleZ, this.swayZ());
   }
   // ---------------------------------------------------------------------------
   // Private helpers
@@ -1169,6 +1189,7 @@ var IdleMotion = class {
     this.sink(import_format.StandardParameter.EyeballY, 0);
     this.sink(import_format.StandardParameter.AngleX, 0);
     this.sink(import_format.StandardParameter.AngleY, 0);
+    this.sink(import_format.StandardParameter.AngleZ, 0);
   }
   /** Returns the current eye-open value (0..1) and advances blink state. */
   advanceBlink() {
@@ -1200,6 +1221,10 @@ var IdleMotion = class {
   swayY() {
     return SWAY_Y_AMP_DEG * Math.sin(2 * Math.PI * this.clockMs / SWAY_Y_PERIOD_MS);
   }
+  /** Head roll sway in degrees, pure function of the internal clock. */
+  swayZ() {
+    return SWAY_Z_AMP_DEG * Math.sin(2 * Math.PI * this.clockMs / SWAY_Z_PERIOD_MS);
+  }
   /** Ease gaze current toward target; pick a new target on the internal clock. */
   advanceGaze(dt) {
     if (this.clockMs >= this.nextGazeRetargetMs) {
@@ -1222,6 +1247,8 @@ function signedNormalized(value, param) {
   return clamp((value - rest) / den, -1, 1);
 }
 var PhysicsMotion = class {
+  /** The output parameter of every rig, in rig order — what `emit` writes. */
+  drivenParameterIds;
   rigs;
   read;
   sink;
@@ -1235,6 +1262,7 @@ var PhysicsMotion = class {
     this.sink = sink;
     this.params = new Map(params.map((p) => [p.id, p]));
     this.state = rigs.map(() => ({ x: 0, v: 0 }));
+    this.drivenParameterIds = rigs.map((rig) => rig.output.parameter);
   }
   /**
    * Advance every rig to the given wall-clock timestamp (milliseconds).
@@ -1305,6 +1333,8 @@ var PhysicsMotion = class {
 var DEG2RAD = Math.PI / 180;
 var RAD2DEG = 180 / Math.PI;
 var HairChainMotion = class {
+  /** Every segment's output, chain by chain — what `emitSegment` writes. */
+  drivenParameterIds;
   chainData;
   params;
   deformers;
@@ -1325,6 +1355,9 @@ var HairChainMotion = class {
       ),
       state: chain.segments.map(() => ({ angle: 0, angularVelocity: 0 }))
     }));
+    this.drivenParameterIds = chains.flatMap(
+      (c) => c.segments.map((s) => s.output.parameter)
+    );
   }
   /**
    * Advance every chain to the given wall-clock timestamp (milliseconds).
@@ -1437,10 +1470,59 @@ var HairChainMotion = class {
     );
   }
 };
+
+// src/iki-motion.ts
+var IkiMotion = class {
+  /**
+   * Idle ids, then rig outputs, then chain-segment outputs, deduplicated and
+   * insertion-ordered. May name ids the model lacks (the player silently
+   * drops writes to unknown ids) — intersect with the model's parameters if
+   * you mirror into your own store.
+   */
+  drivenParameterIds;
+  idle;
+  physics;
+  chains;
+  constructor(model, read, sink) {
+    const rigs = model.physics ?? [];
+    const chains = model.physicsChains ?? [];
+    this.idle = new IdleMotion(sink);
+    this.physics = new PhysicsMotion(rigs, model.parameters, read, sink);
+    this.chains = new HairChainMotion(
+      chains,
+      model.parameters,
+      model.deformers ?? [],
+      read,
+      sink
+    );
+    this.drivenParameterIds = [
+      .../* @__PURE__ */ new Set([
+        ...this.idle.drivenParameterIds,
+        ...this.physics.drivenParameterIds,
+        ...this.chains.drivenParameterIds
+      ])
+    ];
+  }
+  /**
+   * Advance idle, then physics, then chains to the same wall-clock timestamp
+   * (milliseconds). Order is load-bearing: `PhysicsMotion` reads its input
+   * parameters (typically `ParamAngleX/Z`) through `read`, and the head sway
+   * idle wrote THIS frame is what the springs must lag behind; `HairChainMotion`
+   * then resolves its anchor deformer's world rotation from that same
+   * just-written pose (which may include a physics output). One timestamp for
+   * all three keeps their dt in lockstep.
+   */
+  update(nowMs) {
+    this.idle.update(nowMs);
+    this.physics.update(nowMs);
+    this.chains.update(nowMs);
+  }
+};
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   HairChainMotion,
   IdleMotion,
+  IkiMotion,
   IkiPlayer,
   ParameterStore,
   PhysicsMotion,