@ikijs/engine 0.1.0 → 0.2.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.
 
@@ -30,8 +30,11 @@ player.setParameter(StandardParameter.MouthOpen, 0.7);
 ```
 
 `load()` decodes and uploads every texture before swapping the model in, so a
-frame is never half-textured. Parameter writes are clamped to the declared
-range; unknown ids and non-finite values are ignored.
+frame is never half-textured. That swap is also why it must be awaited before
+`getParameters()`: an un-awaited `load()` leaves the parameter store empty for
+the rest of the tick, and the engine reports that case rather than let a host
+read `[]` and conclude the model declares no parameters. Parameter writes are
+clamped to the declared range; unknown ids and non-finite values are ignored.
 
 ## API
 

package/dist/index.d.mts

@@ -50,6 +50,10 @@ declare class IkiPlayer {
     private textures;
     /** Bumped by every `load` and by `destroy`; lets a stale async load bail. */
     private loadGeneration;
+    /** True from the moment `load()` is entered until it resolves or throws. */
+    private loadPending;
+    /** Latches the un-awaited-load report, so a repeat caller says it once. */
+    private warnedLoadUnfinished;
     private destroyed;
     /**
      * Engine-internal mesh buffers, keyed by the part's INDEX in `this.parts`
@@ -78,8 +82,14 @@ declare class IkiPlayer {
      * Mesh buffer allocation failure IS fatal (unlike per-texture skip) because
      * textures have an `IkiLoadResult.failedTextures` reporting surface and mesh
      * buffers have none — there is no partial-mesh concept in the format.
+     *
+     * AWAIT THIS before reading {@link getParameters}. The swap happens after
+     * texture decoding, so an un-awaited `load()` leaves the parameter store
+     * empty for the rest of the tick; `getParameters` reports that case rather
+     * than letting a host conclude the model drives nothing.
      */
     load(model: IkiModel): Promise<IkiLoadResult>;
+    private adoptModel;
     /**
      * Start the render loop. Safe to call more than once, and a no-op after
      * {@link destroy} — the program and buffers the loop draws with are gone, so
@@ -101,7 +111,17 @@ declare class IkiPlayer {
      * mirror's clamping in step with {@link ParameterStore} by hand.
      */
     getParameter(id: string): number;
-    /** The model's parameter descriptors, for building UI or host wiring. */
+    /**
+     * The model's parameter descriptors, for building UI or host wiring.
+     *
+     * Empty until the first {@link load} resolves. Reaching it through an
+     * un-awaited `load()` is the one mistake in this class that produces no
+     * error and no motion: the caller gets `[]`, concludes the model has no
+     * parameters, and drives nothing — so that case is reported instead of
+     * being indistinguishable from a model that really declares none. A
+     * reload is deliberately NOT reported: those parameters are stale rather
+     * than absent, and warning there would fire on legitimate concurrent reads.
+     */
     getParameters(): IkiParameter[];
     destroy(): void;
     private renderFrame;
@@ -212,6 +232,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;
 }

package/dist/index.d.ts

@@ -50,6 +50,10 @@ declare class IkiPlayer {
     private textures;
     /** Bumped by every `load` and by `destroy`; lets a stale async load bail. */
     private loadGeneration;
+    /** True from the moment `load()` is entered until it resolves or throws. */
+    private loadPending;
+    /** Latches the un-awaited-load report, so a repeat caller says it once. */
+    private warnedLoadUnfinished;
     private destroyed;
     /**
      * Engine-internal mesh buffers, keyed by the part's INDEX in `this.parts`
@@ -78,8 +82,14 @@ declare class IkiPlayer {
      * Mesh buffer allocation failure IS fatal (unlike per-texture skip) because
      * textures have an `IkiLoadResult.failedTextures` reporting surface and mesh
      * buffers have none — there is no partial-mesh concept in the format.
+     *
+     * AWAIT THIS before reading {@link getParameters}. The swap happens after
+     * texture decoding, so an un-awaited `load()` leaves the parameter store
+     * empty for the rest of the tick; `getParameters` reports that case rather
+     * than letting a host conclude the model drives nothing.
      */
     load(model: IkiModel): Promise<IkiLoadResult>;
+    private adoptModel;
     /**
      * Start the render loop. Safe to call more than once, and a no-op after
      * {@link destroy} — the program and buffers the loop draws with are gone, so
@@ -101,7 +111,17 @@ declare class IkiPlayer {
      * mirror's clamping in step with {@link ParameterStore} by hand.
      */
     getParameter(id: string): number;
-    /** The model's parameter descriptors, for building UI or host wiring. */
+    /**
+     * The model's parameter descriptors, for building UI or host wiring.
+     *
+     * Empty until the first {@link load} resolves. Reaching it through an
+     * un-awaited `load()` is the one mistake in this class that produces no
+     * error and no motion: the caller gets `[]`, concludes the model has no
+     * parameters, and drives nothing — so that case is reported instead of
+     * being indistinguishable from a model that really declares none. A
+     * reload is deliberately NOT reported: those parameters are stale rather
+     * than absent, and warning there would fire on legitimate concurrent reads.
+     */
     getParameters(): IkiParameter[];
     destroy(): void;
     private renderFrame;
@@ -212,6 +232,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;
 }

package/dist/index.js

@@ -452,6 +452,10 @@ var IkiPlayer = class {
   textures = [];
   /** Bumped by every `load` and by `destroy`; lets a stale async load bail. */
   loadGeneration = 0;
+  /** True from the moment `load()` is entered until it resolves or throws. */
+  loadPending = false;
+  /** Latches the un-awaited-load report, so a repeat caller says it once. */
+  warnedLoadUnfinished = false;
   destroyed = false;
   /**
    * Engine-internal mesh buffers, keyed by the part's INDEX in `this.parts`
@@ -479,8 +483,21 @@ var IkiPlayer = class {
    * Mesh buffer allocation failure IS fatal (unlike per-texture skip) because
    * textures have an `IkiLoadResult.failedTextures` reporting surface and mesh
    * buffers have none — there is no partial-mesh concept in the format.
+   *
+   * AWAIT THIS before reading {@link getParameters}. The swap happens after
+   * texture decoding, so an un-awaited `load()` leaves the parameter store
+   * empty for the rest of the tick; `getParameters` reports that case rather
+   * than letting a host conclude the model drives nothing.
    */
   async load(model) {
+    this.loadPending = true;
+    try {
+      return await this.adoptModel(model);
+    } finally {
+      this.loadPending = false;
+    }
+  }
+  async adoptModel(model) {
     const { gl } = this;
     const generation = ++this.loadGeneration;
     const sources = model.textures ?? [];
@@ -692,8 +709,24 @@ var IkiPlayer = class {
   getParameter(id) {
     return this.params.get(id);
   }
-  /** The model's parameter descriptors, for building UI or host wiring. */
+  /**
+   * The model's parameter descriptors, for building UI or host wiring.
+   *
+   * Empty until the first {@link load} resolves. Reaching it through an
+   * un-awaited `load()` is the one mistake in this class that produces no
+   * error and no motion: the caller gets `[]`, concludes the model has no
+   * parameters, and drives nothing — so that case is reported instead of
+   * being indistinguishable from a model that really declares none. A
+   * reload is deliberately NOT reported: those parameters are stale rather
+   * than absent, and warning there would fire on legitimate concurrent reads.
+   */
   getParameters() {
+    if (this.loadPending && this.model === void 0 && !this.warnedLoadUnfinished) {
+      this.warnedLoadUnfinished = true;
+      console.error(
+        "Iki: getParameters() ran before load() finished, so it returned an empty list \u2014 await load() before reading parameters."
+      );
+    }
     return this.params.list();
   }
   destroy() {
@@ -1051,6 +1084,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;
 }
@@ -1124,6 +1159,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
@@ -1136,6 +1172,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() {
@@ -1167,6 +1204,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) {