@playcanvas/web-components 0.11.0 → 0.12.0

package/src/material.ts

@@ -21,17 +21,26 @@ import {
     SPECOCC_GLOSSDEPENDENT,
     SPECOCC_NONE,
     StandardMaterial,
-    Vec2,
-    type EventHandle,
-    type Texture
+    Vec2
 } from 'playcanvas';
+import type { EventHandle, Texture } from 'playcanvas';
 
-import { AppElement } from './app';
+import type { AppElement } from './app';
 import { AssetElement } from './asset';
 import { parseBool, parseColor, parseEnum, parseNumber, parseVec2 } from './parse';
 
-type BlendType = 'none' | 'normal' | 'additive' | 'additive-alpha' | 'premultiplied' |
-    'multiplicative' | 'multiplicative-2x' | 'screen' | 'min' | 'max' | 'subtractive';
+type BlendType =
+    | 'none'
+    | 'normal'
+    | 'additive'
+    | 'additive-alpha'
+    | 'premultiplied'
+    | 'multiplicative'
+    | 'multiplicative-2x'
+    | 'screen'
+    | 'min'
+    | 'max'
+    | 'subtractive';
 
 const blendTypes = new Map<BlendType, number>([
     ['none', BLEND_NONE],
@@ -100,8 +109,8 @@ const roughnessAliases = ['roughness', 'roughness-map'];
  * The texture slots a `pc-material` can populate. Each is backed by a `pc-asset` id rather than a
  * `Texture`, so the element can be authored before the asset has loaded.
  */
-type TextureSlot = 'aoMap' | 'diffuseMap' | 'emissiveMap' | 'glossMap' | 'heightMap' |
-    'metalnessMap' | 'normalMap' | 'opacityMap';
+type TextureSlot =
+    'aoMap' | 'diffuseMap' | 'emissiveMap' | 'glossMap' | 'heightMap' | 'metalnessMap' | 'normalMap' | 'opacityMap';
 
 /**
  * The MaterialElement interface provides properties and methods for manipulating
@@ -286,7 +295,7 @@ class MaterialElement extends HTMLElement {
 
     private _useLighting = true;
 
-    // Diverges from the engine default of false - see the class docblock and createMaterial()
+    // Diverges from the engine default of false - see the class docblock and _createMaterial()
     private _useMetalness = true;
 
     private _useMetalnessSpecularColor = false;
@@ -306,10 +315,14 @@ class MaterialElement extends HTMLElement {
 
     private _glossConflictWarned = false;
 
+    /**
+     * The material. `null` until the containing application has created it — an element present
+     * at startup has its material once the application is ready.
+     */
     material: StandardMaterial | null = null;
 
     async connectedCallback() {
-        const appElement = this.parentElement?.closest('pc-app') as AppElement | null ?? null;
+        const appElement = (this.parentElement?.closest('pc-app') as AppElement | null) ?? null;
 
         // Materials must be direct children of pc-app (matches the boot query ':scope > pc-material')
         if (!appElement || this.parentElement !== appElement) {
@@ -326,11 +339,18 @@ class MaterialElement extends HTMLElement {
         // elements inserted (or re-inserted) after the app is already running
         if (!this.material) {
             if (!appElement.app) return; // pc-app is re-connecting; its own boot will create this
-            this.createMaterial();
+            this._createMaterial();
         }
     }
 
-    createMaterial() {
+    /**
+     * Creates the material from the element's cached properties. Called by the containing
+     * `<pc-app>` element during its boot sweep, and on connection for elements inserted while
+     * the application is already running.
+     *
+     * @internal
+     */
+    _createMaterial() {
         const material = new StandardMaterial();
         this.material = material;
 
@@ -464,10 +484,10 @@ class MaterialElement extends HTMLElement {
      * warning latches and reports once per episode, clearing when the clash is resolved.
      */
     private _warnGlossConflict() {
-        const quote = (names: string[]) => `'${names.join('\', \'')}'`;
+        const quote = (names: string[]) => `'${names.join("', '")}'`;
 
-        const roughness = roughnessAliases.filter(name => this.hasAttribute(name));
-        const gloss = glossConflicts.filter(name => this.hasAttribute(name));
+        const roughness = roughnessAliases.filter((name) => this.hasAttribute(name));
+        const gloss = glossConflicts.filter((name) => this.hasAttribute(name));
 
         if (roughness.length === 0 || gloss.length === 0) {
             this._glossConflictWarned = false;
@@ -477,8 +497,10 @@ class MaterialElement extends HTMLElement {
         if (this._glossConflictWarned) return;
         this._glossConflictWarned = true;
 
-        console.warn(`pc-material '${this.id}' sets both ${quote(roughness)} and ${quote(gloss)} - ` +
-            'the roughness-* attributes invert gloss, so the two families contradict each other. Use one or the other.');
+        console.warn(
+            `pc-material '${this.id}' sets both ${quote(roughness)} and ${quote(gloss)} - ` +
+                'the roughness-* attributes invert gloss, so the two families contradict each other. Use one or the other.'
+        );
     }
 
     /**
@@ -488,7 +510,7 @@ class MaterialElement extends HTMLElement {
      * @param id - The id of the `pc-asset`, or an empty string to clear the slot.
      * @param slot - The material property to write.
      */
-    setMap(id: string, slot: TextureSlot) {
+    private _setMap(id: string, slot: TextureSlot) {
         // Drop any load still pending for this slot - its texture is no longer the one we want
         this._mapHandles.get(slot)?.off();
         this._mapHandles.delete(slot);
@@ -509,20 +531,23 @@ class MaterialElement extends HTMLElement {
             return;
         }
 
-        this._mapHandles.set(slot, asset.once('load', () => {
-            this._mapHandles.delete(slot);
-            this._applyMap(slot, asset.resource as Texture);
-        }));
+        this._mapHandles.set(
+            slot,
+            asset.once('load', () => {
+                this._mapHandles.delete(slot);
+                this._applyMap(slot, asset.resource as Texture);
+            })
+        );
     }
 
     /**
      * @param slot - The material property to write.
-     * @param texture - The loaded texture.
+     * @param texture - The loaded texture, applied with its sampler state untouched - anisotropy
+     * and friends belong to the `pc-asset`'s texture options.
      */
     private _applyMap(slot: TextureSlot, texture: Texture) {
         if (!this.material) return;
         this.material[slot] = texture;
-        texture.anisotropy = 4;
         this._scheduleUpdate();
     }
 
@@ -592,7 +617,7 @@ class MaterialElement extends HTMLElement {
      */
     set aoMap(value: string) {
         this._aoMap = value;
-        this.setMap(value, 'aoMap');
+        this._setMap(value, 'aoMap');
     }
 
     /**
@@ -850,7 +875,7 @@ class MaterialElement extends HTMLElement {
      */
     set diffuseMap(value: string) {
         this._diffuseMap = value;
-        this.setMap(value, 'diffuseMap');
+        this._setMap(value, 'diffuseMap');
     }
 
     /**
@@ -1007,7 +1032,7 @@ class MaterialElement extends HTMLElement {
      */
     set emissiveMap(value: string) {
         this._emissiveMap = value;
-        this.setMap(value, 'emissiveMap');
+        this._setMap(value, 'emissiveMap');
     }
 
     /**
@@ -1205,7 +1230,7 @@ class MaterialElement extends HTMLElement {
      */
     set glossMap(value: string) {
         this._glossMap = value;
-        this.setMap(value, 'glossMap');
+        this._setMap(value, 'glossMap');
     }
 
     /**
@@ -1322,7 +1347,7 @@ class MaterialElement extends HTMLElement {
      */
     set heightMap(value: string) {
         this._heightMap = value;
-        this.setMap(value, 'heightMap');
+        this._setMap(value, 'heightMap');
     }
 
     /**
@@ -1479,7 +1504,7 @@ class MaterialElement extends HTMLElement {
      */
     set metalnessMap(value: string) {
         this._metalnessMap = value;
-        this.setMap(value, 'metalnessMap');
+        this._setMap(value, 'metalnessMap');
     }
 
     /**
@@ -1596,7 +1621,7 @@ class MaterialElement extends HTMLElement {
      */
     set normalMap(value: string) {
         this._normalMap = value;
-        this.setMap(value, 'normalMap');
+        this._setMap(value, 'normalMap');
     }
 
     /**
@@ -1694,7 +1719,7 @@ class MaterialElement extends HTMLElement {
     set occludeDirect(value: boolean) {
         this._occludeDirect = value;
         if (this.material) {
-            // @ts-ignore see createMaterial() - the engine mistypes occludeDirect as a number
+            // @ts-ignore see _createMaterial() - the engine mistypes occludeDirect as a number
             this.material.occludeDirect = value;
             this._scheduleUpdate();
         }
@@ -1796,7 +1821,7 @@ class MaterialElement extends HTMLElement {
      */
     set opacityMap(value: string) {
         this._opacityMap = value;
-        this.setMap(value, 'opacityMap');
+        this._setMap(value, 'opacityMap');
     }
 
     /**
@@ -2150,6 +2175,13 @@ class MaterialElement extends HTMLElement {
         return this._useTonemap;
     }
 
+    /**
+     * Returns the {@link StandardMaterial} created by the `<pc-material>` element with the given
+     * `id`, or `undefined` if there is no such element or its material has not been created yet.
+     *
+     * @param id - The `id` of the `<pc-material>` element.
+     * @returns The material, or `undefined`.
+     */
     static get(id: string) {
         const materialElement = document.querySelector<MaterialElement>(`pc-material[id="${id}"]`);
         return materialElement?.material;
@@ -2508,10 +2540,4 @@ class MaterialElement extends HTMLElement {
 
 customElements.define('pc-material', MaterialElement);
 
-declare global {
-    interface HTMLElementTagNameMap {
-        'pc-material': MaterialElement;
-    }
-}
-
 export { MaterialElement };

package/src/model.ts

@@ -1,4 +1,4 @@
-import { ContainerResource, Entity } from 'playcanvas';
+import type { ContainerResource, Entity, EventHandle } from 'playcanvas';
 
 import { AssetElement } from './asset';
 import { AsyncElement } from './async-element';
@@ -8,41 +8,123 @@ 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: string = '';
+    private _asset = '';
 
     private _entity: Entity | null = null;
 
+    /**
+     * Incremented on every new load and on disconnect, and captured by a load when it starts. A
+     * load that resumes from an await or a load callback abandons itself if the value has moved
+     * on, so a superseded load can neither instantiate a second entity nor parent one that has
+     * since been destroyed.
+     */
+    private _loadGeneration = 0;
+
+    /**
+     * 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.
+     * @returns The model's root entity, or `null`.
+     */
+    get entity(): Entity | null {
+        return this._entity;
+    }
+
     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._detachLoadHandlers();
         this._unloadModel();
+        this._resetReady();
+    }
+
+    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) {
-        this._entity = container.instantiateRenderEntity();
+        const generation = this._loadGeneration;
+
+        const entity = container.instantiateRenderEntity();
+        this._entity = entity;
 
         // @ts-ignore
         if (container.animations.length > 0) {
-            this._entity.addComponent('anim');
+            entity.addComponent('anim');
             // @ts-ignore
-            this._entity.anim.assignAnimation('animation', container.animations[0].resource);
+            entity.anim.assignAnimation('animation', container.animations[0].resource);
         }
 
+        // The parent's readiness re-arms when it is torn down, so these can resume in a later
+        // connection cycle. The entity is captured above and the generation re-checked, so a
+        // stale resume cannot parent an entity a newer cycle has already destroyed.
         const parentEntityElement = this.closestEntity;
         if (parentEntityElement) {
             parentEntityElement.ready().then(() => {
-                parentEntityElement.entity!.addChild(this._entity!);
+                if (generation !== this._loadGeneration) {
+                    return;
+                }
+                parentEntityElement.entity!.addChild(entity);
+                this._announceLoad();
             });
         } else {
             const appElement = this.closestApp;
             if (appElement) {
                 appElement.ready().then(() => {
-                    appElement.app!.root.addChild(this._entity!);
+                    if (generation !== this._loadGeneration) {
+                        return;
+                    }
+                    appElement.app!.root.addChild(entity);
+                    this._announceLoad();
                 });
             }
         }
@@ -51,20 +133,67 @@ class ModelElement extends AsyncElement {
     private async _loadModel() {
         this._unloadModel();
 
-        const appElement = await this.closestApp?.ready();
-        const app = appElement?.app;
+        // Supersede any load already in flight - only the newest load may instantiate
+        const generation = ++this._loadGeneration;
+        this._detachLoadHandlers();
+
+        // 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 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;
         }
 
         if (asset.loaded) {
             this._instantiate(asset.resource as ContainerResource);
         } else {
-            asset.once('load', () => {
+            // 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. Whichever of load/error fires first detaches the other.
+            this._loadHandle = asset.once('load', () => {
+                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);
         }
     }
@@ -108,10 +237,4 @@ class ModelElement extends AsyncElement {
 
 customElements.define('pc-model', ModelElement);
 
-declare global {
-    interface HTMLElementTagNameMap {
-        'pc-model': ModelElement;
-    }
-}
-
 export { ModelElement };

package/src/module.ts

@@ -43,17 +43,18 @@ class ModuleElement extends HTMLElement {
         }
     }
 
-    public getLoadPromise(): Promise<void> {
+    /**
+     * 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 load promise.
+     * @internal
+     */
+    _getLoadPromise(): Promise<void> {
         return this.loadPromise;
     }
 }
 
 customElements.define('pc-module', ModuleElement);
 
-declare global {
-    interface HTMLElementTagNameMap {
-        'pc-module': ModuleElement;
-    }
-}
-
 export { ModuleElement };