@ikijs/engine 0.1.0 → 0.1.1

package/README.md

@@ -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;

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;

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() {