@playcanvas/web-components 0.11.1 → 0.13.0

package/src/model.ts

@@ -8,6 +8,21 @@ import { AsyncElement } from './async-element';
  * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-model/ | `<pc-model>`} elements.
  * The ModelElement interface also inherits the properties and methods of the
  * {@link HTMLElement} interface.
+ *
+ * The element becomes ready once its container asset has loaded and the instantiated hierarchy has
+ * been added to the scene — `entity` is non-null by then. A failed load also settles readiness,
+ * with `entity` remaining `null`: readiness means the load settled, not that it succeeded — listen
+ * for `error`, or check `entity`, to tell the outcomes apart. Changing `asset` re-arms readiness
+ * and instantiates anew, so a `ready()` obtained after the change resolves against the new
+ * hierarchy. A `pc-model` outside a `pc-app`, or referencing an unknown asset id, warns and never
+ * becomes ready.
+ *
+ * @fires {Event} load - Fired each time a container asset finishes instantiating, including
+ * re-instantiation after `asset` changes. Does not bubble — listen on this element, or use a
+ * capture-phase listener on an ancestor.
+ * @fires {ErrorEvent} error - Fired when the container asset fails to load, with the engine's
+ * error in `message`. Does not bubble. The element still becomes ready — readiness means the load
+ * settled, not that it succeeded.
  */
 class ModelElement extends AsyncElement {
     private _asset = '';
@@ -23,12 +38,14 @@ class ModelElement extends AsyncElement {
     private _loadGeneration = 0;
 
     /**
-     * The pending asset-load subscription of the current load, if it is waiting for its asset.
-     * Held so that whatever supersedes the load can detach the handler from the asset, rather
-     * than leave it registered until the asset loads (or forever, if it never does).
+     * The pending asset subscriptions of the current load, if it is waiting for its asset. Held
+     * so that whatever supersedes the load can detach the handlers from the asset, rather than
+     * leave them registered until the asset settles (or forever, if it never does).
      */
     private _loadHandle: EventHandle | null = null;
 
+    private _errorHandle: EventHandle | null = null;
+
     /**
      * The root entity of the instantiated model. `null` until the container asset has loaded
      * and been instantiated, and again once the element has been removed from the document.
@@ -39,20 +56,39 @@ class ModelElement extends AsyncElement {
     }
 
     connectedCallback() {
+        // A model outside an application is inert and never becomes ready, so awaiting it hangs.
+        // Warn rather than fail silently, naming the parent it requires, as every other misplaced
+        // element does.
+        if (!this.closestApp) {
+            const label = this._asset ? ` '${this._asset}'` : '';
+            console.warn(`pc-model${label} must be a descendant of pc-app - model not created`);
+            return;
+        }
         this._loadModel();
-        this._onReady();
     }
 
     disconnectedCallback() {
         this._loadGeneration++;
-        this._detachLoadHandler();
+        this._detachLoadHandlers();
         this._unloadModel();
         this._resetReady();
     }
 
-    private _detachLoadHandler() {
+    private _detachLoadHandlers() {
         this._loadHandle?.off();
         this._loadHandle = null;
+        this._errorHandle?.off();
+        this._errorHandle = null;
+    }
+
+    /**
+     * Resolves readiness and dispatches the `load` event. Called once the instantiated hierarchy
+     * has been parented — readiness means "in the scene graph", matching `pc-entity`, so a ready
+     * model's entity always has world transforms.
+     */
+    private _announceLoad() {
+        this._onReady();
+        this.dispatchEvent(new Event('load'));
     }
 
     private _instantiate(container: ContainerResource) {
@@ -78,6 +114,7 @@ class ModelElement extends AsyncElement {
                     return;
                 }
                 parentEntityElement.entity!.addChild(entity);
+                this._announceLoad();
             });
         } else {
             const appElement = this.closestApp;
@@ -87,6 +124,7 @@ class ModelElement extends AsyncElement {
                         return;
                     }
                     appElement.app!.root.addChild(entity);
+                    this._announceLoad();
                 });
             }
         }
@@ -97,19 +135,35 @@ class ModelElement extends AsyncElement {
 
         // Supersede any load already in flight - only the newest load may instantiate
         const generation = ++this._loadGeneration;
-        this._detachLoadHandler();
+        this._detachLoadHandlers();
 
-        const appElement = await this.closestApp?.ready();
+        // Re-arm readiness so a waiter obtained after an asset change resolves against the new
+        // hierarchy. A no-op on first connection, where readiness is still pending.
+        this._resetReady();
+
+        const appElement = this.closestApp;
+        if (!appElement) {
+            // Outside pc-app; connectedCallback already warned. Reached through the asset setter.
+            return;
+        }
+
+        await appElement.ready();
 
         // The element may have been removed, or another load started, while we waited
         if (generation !== this._loadGeneration) {
             return;
         }
 
-        const app = appElement?.app;
+        const app = appElement.app;
 
         const asset = AssetElement.get(this._asset);
         if (!asset) {
+            // An empty id is a legitimate transient (the asset may be assigned later); a
+            // non-empty one that resolves to nothing is a dead end - say so rather than staying
+            // silently pending.
+            if (this._asset) {
+                console.warn(`pc-model could not find asset '${this._asset}' - model not created`);
+            }
             return;
         }
 
@@ -118,14 +172,28 @@ class ModelElement extends AsyncElement {
         } else {
             // The generation is re-checked even though a superseded handler is detached: the
             // detach relies on how the engine's event emitter treats removal, while the check
-            // holds on its own.
+            // holds on its own. Whichever of load/error fires first detaches the other.
             this._loadHandle = asset.once('load', () => {
-                this._loadHandle = null;
+                this._detachLoadHandlers();
                 if (generation !== this._loadGeneration) {
                     return;
                 }
                 this._instantiate(asset.resource as ContainerResource);
             });
+            this._errorHandle = asset.once('error', (err: string | Error) => {
+                this._detachLoadHandlers();
+                if (generation !== this._loadGeneration) {
+                    return;
+                }
+                // A failed load settles readiness with a null entity, mirroring pc-asset:
+                // readiness means the load settled, not that it succeeded.
+                this.dispatchEvent(
+                    new ErrorEvent('error', {
+                        message: err instanceof Error ? err.message : String(err)
+                    })
+                );
+                this._onReady();
+            });
             app!.assets.load(asset);
         }
     }

package/src/module.ts

@@ -1,13 +1,21 @@
 import { basisInitialize, WasmModule } from 'playcanvas';
 
+import { AsyncElement } from './async-element';
+
 /**
  * The ModuleElement interface provides properties and methods for manipulating
- * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-module/ | `<pc-module>`} elements.
- * The ModuleElement interface also inherits the properties and methods of the
- * {@link HTMLElement} interface.
+ * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-module/ | `<pc-module>`}
+ * elements. The ModuleElement interface also inherits the properties and methods of the
+ * {@link AsyncElement} interface.
+ *
+ * The attributes are read once, when the module starts loading - on the element's first
+ * connection, or earlier if a containing `<pc-app>` boots first and collects it - so changing
+ * them later has no effect. The element becomes ready once the module has loaded. WebAssembly
+ * modules configure engine-global state that never unloads, so readiness is not re-armed by
+ * removing the element, and a re-inserted element does not load again.
  *
- * Note that these attributes are read once when the element is created, so changing them later
- * has no effect.
+ * A `<pc-module>` without a `name` warns and never becomes ready; a containing `<pc-app>` still
+ * boots.
  *
  * @attribute {string} name - The name of the WebAssembly module to configure, e.g. `Basis` or
  * `Ammo`.
@@ -16,21 +24,25 @@ import { basisInitialize, WasmModule } from 'playcanvas';
  * @attribute {string} fallback - The URL of the module's asm.js fallback script, used when
  * WebAssembly is unavailable.
  */
-class ModuleElement extends HTMLElement {
-    private loadPromise: Promise<void>;
+class ModuleElement extends AsyncElement {
+    private _loadPromise: Promise<void> | null = null;
 
-    /** @ignore */
-    constructor() {
-        super();
-        this.loadPromise = this.loadModule();
+    connectedCallback() {
+        this._getLoadPromise();
     }
 
-    private async loadModule(): Promise<void> {
-        const name = this.getAttribute('name')!;
-        const glueUrl = this.getAttribute('glue')!;
-        const wasmUrl = this.getAttribute('wasm')!;
-        const fallbackUrl = this.getAttribute('fallback')!;
-        const config = { glueUrl, wasmUrl, fallbackUrl };
+    private async _loadModule(): Promise<void> {
+        const name = this.getAttribute('name');
+        if (!name) {
+            console.warn("pc-module requires a 'name' attribute - no module was configured");
+            return;
+        }
+
+        const config = {
+            glueUrl: this.getAttribute('glue') ?? undefined,
+            wasmUrl: this.getAttribute('wasm') ?? undefined,
+            fallbackUrl: this.getAttribute('fallback') ?? undefined
+        };
 
         if (name === 'Basis') {
             basisInitialize(config);
@@ -41,17 +53,24 @@ class ModuleElement extends HTMLElement {
                 WasmModule.getInstance(name, () => resolve());
             });
         }
+
+        this._onReady();
     }
 
     /**
-     * Returns the promise that settles when the module has loaded. Awaited by the containing
-     * `<pc-app>` element before it creates its graphics device.
+     * Returns the promise that settles when the module has loaded, starting the load if it has
+     * not already started - a containing `<pc-app>` boots in document order, so it may collect
+     * this element before the element's own connectedCallback has run. A missing `name` resolves
+     * the promise without configuring anything, so a misconfigured module never blocks the app.
      *
      * @returns The load promise.
      * @internal
      */
     _getLoadPromise(): Promise<void> {
-        return this.loadPromise;
+        if (!this._loadPromise) {
+            this._loadPromise = this._loadModule();
+        }
+        return this._loadPromise;
     }
 }