@playcanvas/web-components 0.10.0 → 0.10.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@playcanvas/web-components",
-  "version": "0.10.0",
+  "version": "0.10.1",
   "author": "PlayCanvas <support@playcanvas.com>",
   "homepage": "https://playcanvas.com",
   "description": "Web Components for the PlayCanvas Engine",

package/src/app.ts

@@ -69,6 +69,7 @@ import {
 import { AssetElement } from './asset';
 import { AsyncElement } from './async-element';
 import { EntityElement } from './entity';
+import { LoadingBar } from './loading-bar';
 import { MaterialElement } from './material';
 import { ModuleElement } from './module';
 import { parseBool, parseEnum } from './parse';
@@ -78,6 +79,11 @@ import { parseBool, parseEnum } from './parse';
  * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-app/ | `<pc-app>`} elements.
  * The AppElement interface also inherits the properties and methods of the
  * {@link HTMLElement} interface.
+ *
+ * @fires {ProgressEvent} progress - Fired while the application preloads its assets. `loaded` and
+ * `total` are asset counts, not bytes, and an asset that fails to load still counts as loaded.
+ * Fired at least once per boot, and the final event always has `loaded` equal to `total`. Does
+ * not bubble.
  */
 class AppElement extends AsyncElement {
     /**
@@ -97,6 +103,10 @@ class AppElement extends AsyncElement {
 
     private _highResolution = true;
 
+    private _loadingBar = true;
+
+    private _bar: LoadingBar | null = null;
+
     private _hierarchyReady = false;
 
     private _picker: Picker | null = null;
@@ -111,6 +121,9 @@ class AppElement extends AsyncElement {
 
     private _hoveredEntity: EntityElement | null = null;
 
+    // Identifies the newest in-flight hover pick, so out-of-order results can be discarded
+    private _pickToken = 0;
+
     private _pointerHandlers: { [key: string]: EventListener | null } = {
         pointermove: null,
         pointerdown: null,
@@ -119,13 +132,27 @@ class AppElement extends AsyncElement {
 
     private _app: AppBase | null = null;
 
+    private _loadProgress = 0;
+
     /**
-     * The PlayCanvas application instance. Available once the element is ready — await
-     * {@link whenReady} or the element's `ready()` promise before accessing it.
-     * @returns The application instance.
+     * The PlayCanvas application instance. `null` until the element is ready, and again once it
+     * has been removed from the document — await {@link whenReady} or the element's `ready()`
+     * promise before accessing it.
+     * @returns The application instance, or `null`.
      */
-    get app(): AppBase {
-        return this._app!;
+    get app(): AppBase | null {
+        return this._app;
+    }
+
+    /**
+     * The asset preload progress of the application, as a fraction from 0 to 1. It is 0 until
+     * preloading begins (and again once the element has been removed from the document), and 1
+     * once preloading has finished — including when there was nothing to preload. Read this to
+     * initialize a loading UI; subsequent updates arrive via the `progress` event.
+     * @returns The preload progress.
+     */
+    get loadProgress(): number {
+        return this._loadProgress;
     }
 
     /**
@@ -141,6 +168,12 @@ class AppElement extends AsyncElement {
     }
 
     async connectedCallback() {
+        // Created before the first await, so the bar is visible while modules and the graphics
+        // device are created, and exists before any disconnect could need to clean it up
+        if (this._loadingBar && !this._bar) {
+            this._bar = new LoadingBar(this);
+        }
+
         // Get all pc-module elements that are direct children of the pc-app element
         const moduleElements = this.querySelectorAll<ModuleElement>(':scope > pc-module');
 
@@ -234,11 +267,12 @@ class AppElement extends AsyncElement {
         createOptions.batchManager = BatchManager;
         createOptions.xr = XrManager;
 
-        this._app = new AppBase(this._canvas);
-        this.app.init(createOptions);
+        const app = new AppBase(this._canvas);
+        this._app = app;
+        app.init(createOptions);
 
-        this.app.setCanvasFillMode(FILLMODE_FILL_WINDOW);
-        this.app.setCanvasResolution(RESOLUTION_AUTO);
+        app.setCanvasFillMode(FILLMODE_FILL_WINDOW);
+        app.setCanvasResolution(RESOLUTION_AUTO);
 
         this._pickerCreate();
 
@@ -248,7 +282,7 @@ class AppElement extends AsyncElement {
             assetElement.createAsset();
             const asset = assetElement.asset;
             if (asset) {
-                this.app!.assets.add(asset);
+                app.assets.add(asset);
             }
         });
 
@@ -261,20 +295,46 @@ class AppElement extends AsyncElement {
         // Create all entities
         const entityElements = this.querySelectorAll<EntityElement>('pc-entity');
         Array.from(entityElements).forEach((entityElement) => {
-            entityElement.createEntity(this.app!);
+            entityElement.createEntity(app);
         });
 
         // Build hierarchy
         entityElements.forEach((entityElement) => {
-            entityElement.buildHierarchy(this.app!);
+            entityElement.buildHierarchy(app);
         });
 
         this._hierarchyReady = true;
 
+        // Forward the engine's preload lifecycle as DOM ProgressEvents on this element. The
+        // listener must be attached before preload() is called: an asset that is already loaded
+        // ticks synchronously inside it.
+        const total = app.assets.list({ preload: true }).length;
+        let loaded = 0;
+        const onPreloadProgress = () => {
+            loaded += 1;
+            this._loadProgress = loaded / total;
+            this._bar?.progress(loaded, total);
+            this.dispatchEvent(new ProgressEvent('progress', { lengthComputable: true, loaded, total }));
+        };
+        app.on('preload:progress', onPreloadProgress);
+
+        this._loadProgress = total === 0 ? 1 : 0;
+        this._bar?.progress(0, total);
+        this.dispatchEvent(new ProgressEvent('progress', { lengthComputable: true, loaded: 0, total }));
+
         // Load assets before starting the application
-        this.app.preload(() => {
+        app.preload(() => {
+            // Scope the counter to this preload pass, so a later app.preload() call by user code
+            // cannot push `loaded` past `total`
+            app.off('preload:progress', onPreloadProgress);
+            this._loadProgress = 1;
+
             // Start the application
-            this.app!.start();
+            app.start();
+
+            // Dismiss the bar only once a frame has actually rendered; ready fires before the
+            // first rAF tick
+            app.once('frameend', () => this._bar?.complete());
 
             // Handle window resize to keep the canvas responsive
             window.addEventListener('resize', this._onWindowResize);
@@ -287,10 +347,13 @@ class AppElement extends AsyncElement {
         this._pickerDestroy();
 
         // Clean up the application
-        if (this.app) {
-            this.app.destroy();
+        if (this._app) {
+            this._app.destroy();
             this._app = null;
         }
+        this._loadProgress = 0;
+        this._bar?.destroy();
+        this._bar = null;
 
         // Remove event listeners
         window.removeEventListener('resize', this._onWindowResize);
@@ -312,10 +375,18 @@ class AppElement extends AsyncElement {
         const { width, height } = this.app!.graphicsDevice;
         this._picker = new Picker(this.app!, width, height);
 
-        // Create bound handlers but don't attach them yet
-        this._pointerHandlers.pointermove = this._onPointerMove.bind(this) as EventListener;
-        this._pointerHandlers.pointerdown = this._onPointerDown.bind(this) as EventListener;
-        this._pointerHandlers.pointerup = this._onPointerUp.bind(this) as EventListener;
+        // Create bound handlers but don't attach them yet. The handlers pick asynchronously, so
+        // each is wrapped to discard the promise - a listener must not return one, and nothing
+        // awaits the result.
+        const listener = (handler: (event: PointerEvent) => Promise<void>): EventListener => {
+            return (event: Event) => {
+                handler.call(this, event as PointerEvent);
+            };
+        };
+
+        this._pointerHandlers.pointermove = listener(this._onPointerMove);
+        this._pointerHandlers.pointerdown = listener(this._onPointerDown);
+        this._pointerHandlers.pointerup = listener(this._onPointerUp);
 
         // Listen for pointer listeners being added/removed
         ['pointermove', 'pointerdown', 'pointerup', 'pointerenter', 'pointerleave'].forEach((type) => {
@@ -369,31 +440,51 @@ class AppElement extends AsyncElement {
         return { x, y };
     }
 
-    _onPointerMove(event: PointerEvent) {
-        if (!this._picker || !this.app) return;
-
+    /**
+     * Picks the scene under the pointer and returns the graph node that was hit, or `null`.
+     *
+     * The read back is asynchronous because the synchronous {@link Picker.getSelection} is not
+     * supported on WebGPU, where it returns an empty selection rather than failing - which
+     * silently disabled every `onpointer*` handler once WebGPU became the resolved backend. The
+     * async variant works on both backends and does not block the main thread on a GPU read.
+     *
+     * @param event - The pointer event to pick under.
+     * @returns The graph node under the pointer, or `null` if nothing was hit.
+     */
+    private async _pickNode(event: PointerEvent): Promise<GraphNode | null> {
         const camera = this.app!.root.findComponent('camera') as CameraComponent;
-        if (!camera) return;
+        if (!camera) return null;
 
-        // Use the helper to convert event coordinates into canvas/picker coordinates.
         const { x, y } = this._getPickerCoordinates(event);
 
-        this._picker.prepare(camera, this.app!.scene);
-        const selection = this._picker.getSelection(x, y);
+        this._picker!.prepare(camera, this.app!.scene);
+        const selection = await this._picker!.getSelectionAsync(x, y);
+        if (selection.length === 0) return null;
+
+        const item = selection[0];
+        return item instanceof MeshInstance ? item.node : (item as GSplatComponent).entity;
+    }
+
+    async _onPointerMove(event: PointerEvent) {
+        if (!this._picker || !this.app) return;
+
+        // Moves arrive faster than a pick resolves, so results can land out of order. Only the
+        // newest pick may update the hover state - an older one describes a pointer position the
+        // user has already left.
+        const token = ++this._pickToken;
+        const node = await this._pickNode(event);
+        if (token !== this._pickToken || !this._picker) return;
 
         // Get the currently hovered entity by walking up the hierarchy
         let newHoverEntity: EntityElement | null = null;
-        if (selection.length > 0) {
-            const item = selection[0];
-            let currentNode: GraphNode | null = item instanceof MeshInstance ? item.node : (item as GSplatComponent).entity;
-            while (currentNode !== null) {
-                const entityElement = this.querySelector(`pc-entity[name="${currentNode.name}"]`) as EntityElement;
-                if (entityElement) {
-                    newHoverEntity = entityElement;
-                    break;
-                }
-                currentNode = currentNode.parent;
+        let currentNode = node;
+        while (currentNode !== null) {
+            const entityElement = this.querySelector(`pc-entity[name="${currentNode.name}"]`) as EntityElement;
+            if (entityElement) {
+                newHoverEntity = entityElement;
+                break;
             }
+            currentNode = currentNode.parent;
         }
 
         // Handle enter/leave events
@@ -415,51 +506,31 @@ class AppElement extends AsyncElement {
         }
     }
 
-    _onPointerDown(event: PointerEvent) {
+    async _onPointerDown(event: PointerEvent) {
         if (!this._picker || !this.app) return;
 
-        const camera = this.app!.root.findComponent('camera') as CameraComponent;
-        if (!camera) return;
+        let currentNode = await this._pickNode(event);
+        if (!this._picker) return; // the element disconnected while the pick was in flight
 
-        // Convert the event's pointer coordinates
-        const { x, y } = this._getPickerCoordinates(event);
-
-        this._picker.prepare(camera, this.app!.scene);
-        const selection = this._picker.getSelection(x, y);
-
-        if (selection.length > 0) {
-            const item = selection[0];
-            let currentNode: GraphNode | null = item instanceof MeshInstance ? item.node : (item as GSplatComponent).entity;
-            while (currentNode !== null) {
-                const entityElement = this.querySelector(`pc-entity[name="${currentNode.name}"]`) as EntityElement;
-                if (entityElement && entityElement.hasListeners('pointerdown')) {
-                    entityElement.dispatchEvent(new PointerEvent('pointerdown', event));
-                    break;
-                }
-                currentNode = currentNode.parent;
+        while (currentNode !== null) {
+            const entityElement = this.querySelector(`pc-entity[name="${currentNode.name}"]`) as EntityElement;
+            if (entityElement && entityElement.hasListeners('pointerdown')) {
+                entityElement.dispatchEvent(new PointerEvent('pointerdown', event));
+                break;
             }
+            currentNode = currentNode.parent;
         }
     }
 
-    _onPointerUp(event: PointerEvent) {
+    async _onPointerUp(event: PointerEvent) {
         if (!this._picker || !this.app) return;
 
-        const camera = this.app!.root.findComponent('camera') as CameraComponent;
-        if (!camera) return;
-
-        // Convert CSS coordinates to picker coordinates
-        const { x, y } = this._getPickerCoordinates(event);
+        const node = await this._pickNode(event);
+        if (!node || !this._picker) return;
 
-        this._picker.prepare(camera, this.app!.scene);
-        const selection = this._picker.getSelection(x, y);
-
-        if (selection.length > 0) {
-            const item = selection[0];
-            const node = item instanceof MeshInstance ? item.node : (item as GSplatComponent).entity;
-            const entityElement = this.querySelector(`pc-entity[name="${node.name}"]`) as EntityElement;
-            if (entityElement && entityElement.hasListeners('pointerup')) {
-                entityElement.dispatchEvent(new PointerEvent('pointerup', event));
-            }
+        const entityElement = this.querySelector(`pc-entity[name="${node.name}"]`) as EntityElement;
+        if (entityElement && entityElement.hasListeners('pointerup')) {
+            entityElement.dispatchEvent(new PointerEvent('pointerup', event));
         }
     }
 
@@ -589,6 +660,31 @@ class AppElement extends AsyncElement {
         return this._highResolution;
     }
 
+    /**
+     * Sets whether the application shows its built-in loading bar while it boots and preloads its
+     * assets. Enabled by default; setting `false` removes the bar immediately, while setting
+     * `true` has no effect until the element is next connected. The bar can be themed with the
+     * CSS custom properties `--pc-loading-bar-color`, `--pc-loading-bar-background` and
+     * `--pc-loading-bar-height`.
+     * @param value - The loading bar flag.
+     */
+    set loadingBar(value: boolean) {
+        this._loadingBar = value;
+        if (!value && this._bar) {
+            this._bar.destroy();
+            this._bar = null;
+        }
+    }
+
+    /**
+     * Gets whether the application shows its built-in loading bar while it boots and preloads
+     * its assets.
+     * @returns The loading bar flag.
+     */
+    get loadingBar() {
+        return this._loadingBar;
+    }
+
     /**
      * Sets the stencil flag.
      * @param value - The stencil flag.
@@ -606,7 +702,7 @@ class AppElement extends AsyncElement {
     }
 
     static get observedAttributes() {
-        return ['alpha', 'antialias', 'backend', 'depth', 'stencil', 'high-resolution'];
+        return ['alpha', 'antialias', 'backend', 'depth', 'stencil', 'high-resolution', 'loading-bar'];
     }
 
     attributeChangedCallback(name: string, _oldValue: string | null, newValue: string | null) {
@@ -626,6 +722,9 @@ class AppElement extends AsyncElement {
             case 'high-resolution':
                 this.highResolution = parseBool(newValue, true);
                 break;
+            case 'loading-bar':
+                this.loadingBar = parseBool(newValue, true);
+                break;
             case 'stencil':
                 this.stencil = parseBool(newValue, true);
                 break;

package/src/asset.ts

@@ -99,6 +99,13 @@ const processBufferView = (
  * @attribute {number} pixels-per-unit - For a `sprite` asset, the number of pixels per world unit.
  * @attribute {'simple' | 'sliced' | 'tiled'} render-mode - For a `sprite` asset, how the sprite is
  * rendered when resized.
+ *
+ * @fires {Event} load - Fired each time the asset finishes loading, including a `lazy` asset
+ * loaded later and any subsequent reloads. Does not bubble — listen on this element, or use a
+ * capture-phase listener on an ancestor to observe every asset.
+ * @fires {ErrorEvent} error - Fired when the 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 AssetElement extends AsyncElement {
     private _lazy: boolean = false;
@@ -149,6 +156,16 @@ class AssetElement extends AsyncElement {
         this.destroyAsset();
     }
 
+    private _onAssetLoad() {
+        this.dispatchEvent(new Event('load'));
+    }
+
+    private _onAssetError(err: string | Error) {
+        this.dispatchEvent(new ErrorEvent('error', {
+            message: err instanceof Error ? err.message : String(err)
+        }));
+    }
+
     createAsset() {
         const id = this.getAttribute('id') || '';
         const src = this.getAttribute('src') || '';
@@ -186,6 +203,11 @@ class AssetElement extends AsyncElement {
         }
 
         this.asset.preload = !this._lazy;
+
+        // Forward the engine asset's load outcome as DOM events on this element, like <img>.
+        // Attached before the asset joins the registry, which is what starts a preloaded load.
+        this.asset.on('load', this._onAssetLoad, this);
+        this.asset.on('error', this._onAssetError, this);
     }
 
     /**
@@ -249,6 +271,9 @@ class AssetElement extends AsyncElement {
 
     destroyAsset() {
         if (this.asset) {
+            // A caller that keeps the Asset alive must not dispatch on a removed element
+            this.asset.off('load', this._onAssetLoad, this);
+            this.asset.off('error', this._onAssetError, this);
             // Deregister first so unload() can still notify the registry
             this.asset.registry?.remove(this.asset);
             this.asset.unload();

package/src/async-element.ts

@@ -20,12 +20,22 @@ class AsyncElement extends HTMLElement {
         });
     }
 
-    get closestApp(): AppElement {
-        return this.parentElement?.closest('pc-app') as AppElement;
+    /**
+     * The nearest ancestor `<pc-app>` element, or `null` if this element has no `<pc-app>`
+     * ancestor. The search starts at the parent, so an element never resolves to itself.
+     * @returns The closest app element, or `null`.
+     */
+    get closestApp(): AppElement | null {
+        return this.parentElement?.closest('pc-app') as AppElement | null ?? null;
     }
 
-    get closestEntity(): EntityElement {
-        return this.parentElement?.closest('pc-entity') as EntityElement;
+    /**
+     * The nearest ancestor `<pc-entity>` element, or `null` if this element has no `<pc-entity>`
+     * ancestor. The search starts at the parent, so an element never resolves to itself.
+     * @returns The closest entity element, or `null`.
+     */
+    get closestEntity(): EntityElement | null {
+        return this.parentElement?.closest('pc-entity') as EntityElement | null ?? null;
     }
 
     /**

package/src/components/component.ts

@@ -73,12 +73,13 @@ class ComponentElement extends AsyncElement {
     }
 
     /**
-     * The PlayCanvas component instance. Available once the element is ready — await
-     * {@link whenReady} or the element's `ready()` promise before accessing it.
-     * @returns The component instance.
+     * The PlayCanvas component instance. `null` until the element is ready, and also for an
+     * element that is not a descendant of a `<pc-entity>` — await {@link whenReady} or the
+     * element's `ready()` promise before accessing it.
+     * @returns The component instance, or `null`.
      */
-    get component(): Component {
-        return this._component!;
+    get component(): Component | null {
+        return this._component;
     }
 
     /**

package/src/entity.ts

@@ -76,12 +76,13 @@ class EntityElement extends AsyncElement {
     private _entity: Entity | null = null;
 
     /**
-     * The PlayCanvas entity instance. Available once the element is ready — await
-     * {@link whenReady} or the element's `ready()` promise before accessing it.
-     * @returns The entity instance.
+     * The PlayCanvas entity instance. `null` until the element is ready, and again once it has
+     * been removed from the document — await {@link whenReady} or the element's `ready()`
+     * promise before accessing it.
+     * @returns The entity instance, or `null`.
      */
-    get entity(): Entity {
-        return this._entity!;
+    get entity(): Entity | null {
+        return this._entity;
     }
 
     createEntity(app: AppBase) {
@@ -92,18 +93,20 @@ class EntityElement extends AsyncElement {
             return;
         }
 
-        // Create a new entity
-        const entity = new Entity(this.getAttribute('name') || this._name, app);
+        // Seed from the cached fields rather than re-reading the attributes. Every observed
+        // attribute is routed through its property setter by attributeChangedCallback, so the field
+        // already holds the parsed attribute value - and it also holds anything assigned through the
+        // property API before the app booted, which reading the attribute back would discard.
+        const entity = new Entity(this._name, app);
         this._entity = entity;
 
-        entity.enabled = parseBool(this.getAttribute('enabled'), true);
-        entity.setLocalPosition(parseVec3(this.getAttribute('position'), Vec3.ZERO, 'position'));
-        entity.setLocalEulerAngles(parseVec3(this.getAttribute('rotation'), Vec3.ZERO, 'rotation'));
-        entity.setLocalScale(parseVec3(this.getAttribute('scale'), Vec3.ONE, 'scale'));
+        entity.enabled = this._enabled;
+        entity.setLocalPosition(this._position);
+        entity.setLocalEulerAngles(this._rotation);
+        entity.setLocalScale(this._scale);
 
-        const tags = parseTags(this.getAttribute('tags'));
-        if (tags.length > 0) {
-            entity.tags.add(tags);
+        if (this._tags.length > 0) {
+            entity.tags.add(this._tags);
         }
     }
 
@@ -124,7 +127,15 @@ class EntityElement extends AsyncElement {
     connectedCallback() {
         // Wait for app to be ready
         const closestApp = this.closestApp;
-        if (!closestApp) return;
+        if (!closestApp) {
+            // An entity 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.
+            const name = this.getAttribute('name');
+            const label = name ? ` '${name}'` : '';
+            console.warn(`pc-entity${label} must be a descendant of pc-app - entity not created`);
+            return;
+        }
 
         // If app is already running, create entity immediately
         if (closestApp.hierarchyReady) {
@@ -146,10 +157,15 @@ class EntityElement extends AsyncElement {
 
     disconnectedCallback() {
         if (this.entity) {
-            // Notify all children that their entities are about to become invalid
-            const children = this.querySelectorAll('pc-entity');
+            // Notify all children that their entities are about to become invalid. Both fields have
+            // to be reset here, not just _entity: a descendant's own disconnectedCallback runs after
+            // this one and skips its reset behind the `if (this.entity)` guard, because we have
+            // already nulled the entity it tests. Leaving _built set would make buildHierarchy bail
+            // on re-insertion, so the descendant would get a fresh entity that is never parented.
+            const children = this.querySelectorAll<EntityElement>('pc-entity');
             children.forEach((child) => {
-                (child as EntityElement)._entity = null;
+                child._entity = null;
+                child._built = false;
             });
 
             // Destroy the entity