@ikijs/engine 0.1.0 → 0.2.0

package/dist/index.mjs

@@ -417,6 +417,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`
@@ -444,8 +448,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 ?? [];
@@ -657,8 +674,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() {
@@ -1016,6 +1049,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;
 }
@@ -1089,6 +1124,7 @@ var IdleMotion = class {
     this.sink(StandardParameter.EyeballY, this.gazeCurrentY);
     this.sink(StandardParameter.AngleX, this.swayX());
     this.sink(StandardParameter.AngleY, this.swayY());
+    this.sink(StandardParameter.AngleZ, this.swayZ());
   }
   // ---------------------------------------------------------------------------
   // Private helpers
@@ -1101,6 +1137,7 @@ var IdleMotion = class {
     this.sink(StandardParameter.EyeballY, 0);
     this.sink(StandardParameter.AngleX, 0);
     this.sink(StandardParameter.AngleY, 0);
+    this.sink(StandardParameter.AngleZ, 0);
   }
   /** Returns the current eye-open value (0..1) and advances blink state. */
   advanceBlink() {
@@ -1132,6 +1169,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) {