@playcanvas/web-components 0.13.0 → 0.13.1

package/dist/pwc.js

@@ -1252,21 +1252,63 @@
             }
             return null;
         }
-        // New helper to convert CSS coordinates to canvas (picker) coordinates
-        _getPickerCoordinates(event) {
-            // Get the canvas' bounding rectangle in CSS pixels.
-            const canvasRect = this._canvas.getBoundingClientRect();
-            // Compute scale factors based on canvas actual resolution vs. its CSS display size.
-            const scaleX = this._canvas.width / canvasRect.width;
-            const scaleY = this._canvas.height / canvasRect.height;
-            // Convert the client coordinates accordingly.
-            const x = (event.clientX - canvasRect.left) * scaleX;
-            const y = (event.clientY - canvasRect.top) * scaleY;
-            return { x, y };
+        /**
+         * Converts a pointer event's client coordinates into drawing-buffer coordinates - the space
+         * the pick buffer and the camera viewports are laid out in. When the canvas has no CSS box
+         * to map through (jsdom; a hidden canvas receives no pointer events in a browser), the
+         * client coordinates are passed through unmapped and `mapped` is false, so callers know the
+         * coordinates correspond to no real geometry.
+         *
+         * @param event - The pointer event to convert.
+         * @param canvas - The canvas the event was dispatched on.
+         * @returns The buffer-space coordinates, and whether they were actually mapped.
+         */
+        _getPickerCoordinates(event, canvas) {
+            const canvasRect = canvas.getBoundingClientRect();
+            if (canvasRect.width === 0 || canvasRect.height === 0) {
+                return { x: event.clientX, y: event.clientY, mapped: false };
+            }
+            const scaleX = canvas.width / canvasRect.width;
+            const scaleY = canvas.height / canvasRect.height;
+            return {
+                x: (event.clientX - canvasRect.left) * scaleX,
+                y: (event.clientY - canvasRect.top) * scaleY,
+                mapped: true
+            };
+        }
+        /**
+         * Whether a camera's viewport contains the point. A camera renders into its normalized
+         * `rect`, whose origin is the bottom-left of the canvas while buffer coordinates run from
+         * the top-left - so the vertical test flips, as the engine's ElementInput flips it for UI
+         * input. The right and bottom edges are exclusive: a viewport rasterizes the half-open
+         * pixel range [left, right) x [top, bottom), so a coordinate on a shared edge belongs to
+         * the viewport whose first pixel it is - never to the one it just left, whose pick buffer
+         * holds nothing there.
+         *
+         * @param camera - The camera to test.
+         * @param x - The x coordinate, in buffer space.
+         * @param y - The y coordinate, in buffer space.
+         * @param canvas - The canvas the coordinates are relative to.
+         * @returns Whether the camera's viewport contains the point.
+         */
+        _cameraContains(camera, x, y, canvas) {
+            const rect = camera.rect;
+            const left = rect.x * canvas.width;
+            const bottom = (1 - rect.y) * canvas.height;
+            const top = bottom - rect.w * canvas.height;
+            return x >= left && x < left + rect.z * canvas.width && y >= top && y < bottom;
         }
         /**
          * Picks the scene under the pointer and returns the graph node that was hit, or `null`.
          *
+         * The camera is resolved the way the engine's ElementInput resolves it for UI input:
+         * enabled cameras are tried topmost-first (they render in ascending `priority` order),
+         * skipping cameras that render to a texture and cameras whose viewport `rect` does not
+         * contain the pointer. A camera that picks nothing ends the search if it clears the color
+         * buffer - its background visually owns the pixel - and otherwise cedes to the cameras
+         * beneath it, so an overlay camera only intercepts picks where it actually drew something.
+         * The pick buffer is prepared per camera, so each camera picks from its own layers.
+         *
          * 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
@@ -1276,16 +1318,40 @@
          * @returns The graph node under the pointer, or `null` if nothing was hit.
          */
         async _pickNode(event) {
-            const camera = this.app.root.findComponent('camera');
-            if (!camera)
-                return null;
-            const { x, y } = this._getPickerCoordinates(event);
-            this._picker.prepare(camera, this.app.scene);
-            const selection = await this._picker.getSelectionAsync(x, y);
-            if (selection.length === 0)
+            const app = this.app;
+            const picker = this._picker;
+            const canvas = this._canvas;
+            if (!app || !picker || !canvas)
                 return null;
-            const item = selection[0];
-            return item instanceof playcanvas.MeshInstance ? item.node : item.entity;
+            const { x, y, mapped } = this._getPickerCoordinates(event, canvas);
+            // Walked from the end: the array is sorted by ascending priority, so the last camera
+            // renders last and sits on top. Read through .at() because a pick handler may remove
+            // cameras while an earlier iteration's read back is in flight.
+            const cameras = app.systems.camera?.cameras ?? [];
+            for (let i = cameras.length - 1; i >= 0; i--) {
+                const camera = cameras.at(i);
+                // A camera rendering to a texture is not on the canvas.
+                if (!camera || camera.renderTarget)
+                    continue;
+                // Coordinates that could not be mapped cannot be tested for containment.
+                if (mapped && !this._cameraContains(camera, x, y, canvas))
+                    continue;
+                picker.prepare(camera, app.scene);
+                const selection = await picker.getSelectionAsync(x, y);
+                // The element may have disconnected while the read back was in flight.
+                if (!this._picker || !this.app)
+                    return null;
+                if (selection.length > 0) {
+                    const item = selection[0];
+                    return item instanceof playcanvas.MeshInstance ? item.node : item.entity;
+                }
+                // Nothing hit. A camera that clears the color buffer paints its background over
+                // everything beneath it, so the miss is final; one that does not is an overlay
+                // that the cameras beneath show through, so they get their turn.
+                if (camera.clearColorBuffer)
+                    return null;
+            }
+            return null;
         }
         async _onPointerMove(event) {
             if (!this._picker || !this.app)
@@ -2229,6 +2295,10 @@
      * immediately unless `lazy`. A `pc-asset` must be a direct child of `pc-app` — elements placed
      * elsewhere, or with an unsupported asset type, never become ready.
      *
+     * A `lazy` asset loads on first use: the first time any element resolves it by `id` — a model,
+     * a material map, a sky, a script `asset:` reference — or when the `lazy` attribute is removed,
+     * whichever comes first. Until then it stays registered and unloaded.
+     *
      * For `texture` and `textureatlas` assets, the texture options (`address-u`, `address-v`,
      * `min-filter`, `mag-filter`, `anisotropy`, `mipmaps`, `srgb`, `flip-y`) apply when the texture is
      * created and — like `lazy` — are observed: changing one updates a texture that has already
@@ -2428,7 +2498,9 @@
             if (type === 'sprite') {
                 data = data ?? {};
                 // Resolve the referenced texture atlas to its (numeric) asset id. The atlas must be
-                // declared before the sprite so its asset already exists in the registry.
+                // declared before the sprite so its asset already exists in the registry. Resolved
+                // with get, not useAsset: creation-time wiring is not a use, and the engine's
+                // sprite handler loads the atlas when the sprite itself loads.
                 const atlas = this.getAttribute('atlas') ?? data.textureAtlasAsset;
                 if (typeof atlas === 'string') {
                     const atlasAsset = AssetElement.get(atlas);
@@ -2589,13 +2661,18 @@
             return this._flipY;
         }
         /**
-         * Sets whether the asset should be loaded lazily.
+         * Sets whether the asset should be loaded lazily. A lazy asset is registered without being
+         * loaded; it loads on first use - the first time any element resolves it by `id` - or when
+         * this flag is cleared on a registered asset, whichever comes first.
          * @param value - The lazy loading flag.
          */
         set lazy(value) {
             this._lazy = value;
             if (this.asset) {
                 this.asset.preload = !value;
+                if (!value) {
+                    this.asset.registry?.load(this.asset);
+                }
             }
         }
         /**
@@ -2779,6 +2856,26 @@
         }
     }
     customElements.define('pc-asset', AssetElement);
+    /**
+     * Resolves an asset reference for use: {@link AssetElement.get}, plus starting the load of a
+     * registered asset that has not begun one - a `lazy` asset. Every element that consumes assets
+     * resolves its references here, which is what makes `lazy` mean load on first use without any
+     * consumer having to remember the load. The load is asynchronous - callers observe the asset's
+     * `load` event for the resource.
+     *
+     * @param id - The `id` of the `<pc-asset>` element.
+     * @returns The asset, or `undefined`.
+     * @internal
+     */
+    const useAsset = (id) => {
+        const asset = AssetElement.get(id);
+        // load() ignores an asset that is already loaded or loading, so repeated resolution
+        // costs nothing.
+        if (asset) {
+            asset.registry?.load(asset);
+        }
+        return asset;
+    };
 
     /**
      * Represents a component in the PlayCanvas engine.
@@ -3062,15 +3159,15 @@
             if (imageEntity) {
                 data.imageEntity = imageEntity;
             }
-            const hoverSpriteAsset = AssetElement.get(this._hoverSpriteAsset);
+            const hoverSpriteAsset = useAsset(this._hoverSpriteAsset);
             if (hoverSpriteAsset) {
                 data.hoverSpriteAsset = hoverSpriteAsset.id;
             }
-            const pressedSpriteAsset = AssetElement.get(this._pressedSpriteAsset);
+            const pressedSpriteAsset = useAsset(this._pressedSpriteAsset);
             if (pressedSpriteAsset) {
                 data.pressedSpriteAsset = pressedSpriteAsset.id;
             }
-            const inactiveSpriteAsset = AssetElement.get(this._inactiveSpriteAsset);
+            const inactiveSpriteAsset = useAsset(this._inactiveSpriteAsset);
             if (inactiveSpriteAsset) {
                 data.inactiveSpriteAsset = inactiveSpriteAsset.id;
             }
@@ -3232,7 +3329,7 @@
          */
         set hoverSpriteAsset(value) {
             this._hoverSpriteAsset = value;
-            const asset = AssetElement.get(value);
+            const asset = useAsset(value);
             if (this.component && asset) {
                 this.component.hoverSpriteAsset = asset.id;
             }
@@ -3268,7 +3365,7 @@
          */
         set pressedSpriteAsset(value) {
             this._pressedSpriteAsset = value;
-            const asset = AssetElement.get(value);
+            const asset = useAsset(value);
             if (this.component && asset) {
                 this.component.pressedSpriteAsset = asset.id;
             }
@@ -3304,7 +3401,7 @@
          */
         set inactiveSpriteAsset(value) {
             this._inactiveSpriteAsset = value;
-            const asset = AssetElement.get(value);
+            const asset = useAsset(value);
             if (this.component && asset) {
                 this.component.inactiveSpriteAsset = asset.id;
             }
@@ -4162,15 +4259,15 @@
             };
             // Asset references are resolved from `<pc-asset>` element ids to engine asset ids. They are
             // only included when they resolve, so image/group elements (with no font) don't error.
-            const fontAsset = AssetElement.get(this._fontAsset);
+            const fontAsset = useAsset(this._fontAsset);
             if (fontAsset) {
                 data.fontAsset = fontAsset.id;
             }
-            const spriteAsset = AssetElement.get(this._spriteAsset);
+            const spriteAsset = useAsset(this._spriteAsset);
             if (spriteAsset) {
                 data.spriteAsset = spriteAsset.id;
             }
-            const textureAsset = AssetElement.get(this._textureAsset);
+            const textureAsset = useAsset(this._textureAsset);
             if (textureAsset) {
                 data.textureAsset = textureAsset.id;
             }
@@ -4284,7 +4381,7 @@
          */
         set fontAsset(value) {
             this._fontAsset = value;
-            const asset = AssetElement.get(value);
+            const asset = useAsset(value);
             if (this.component && asset) {
                 this.component.fontAsset = asset.id;
             }
@@ -4439,7 +4536,7 @@
          */
         set spriteAsset(value) {
             this._spriteAsset = value;
-            const asset = AssetElement.get(value);
+            const asset = useAsset(value);
             if (this.component && asset) {
                 this.component.spriteAsset = asset.id;
             }
@@ -4491,7 +4588,7 @@
          */
         set textureAsset(value) {
             this._textureAsset = value;
-            const asset = AssetElement.get(value);
+            const asset = useAsset(value);
             if (this.component && asset) {
                 this.component.textureAsset = asset.id;
             }
@@ -5726,13 +5823,14 @@
             super('particlesystem');
         }
         getInitialComponentData() {
-            const asset = AssetElement.get(this._asset);
-            if (!asset) {
+            const asset = useAsset(this._asset);
+            // A lazy config has no resource yet - _loadAsset applies it once the load completes
+            if (!asset || !asset.resource) {
                 return {};
             }
             if (asset.resource.colorMapAsset) {
                 const id = asset.resource.colorMapAsset;
-                const colorMapAsset = AssetElement.get(id)?.id;
+                const colorMapAsset = useAsset(id)?.id;
                 if (colorMapAsset) {
                     asset.resource.colorMapAsset = colorMapAsset;
                 }
@@ -5758,9 +5856,8 @@
             }
         }
         async _loadAsset() {
-            const appElement = await this.closestApp?.ready();
-            const app = appElement?.app;
-            const asset = AssetElement.get(this._asset);
+            await this.closestApp?.ready();
+            const asset = useAsset(this._asset);
             if (!asset) {
                 return;
             }
@@ -5771,7 +5868,6 @@
                 asset.once('load', () => {
                     this.applyConfig(asset.resource);
                 });
-                app.assets.load(asset);
             }
         }
         /**
@@ -6187,7 +6283,7 @@
                 this._scheduleUpdate();
                 return;
             }
-            const asset = AssetElement.get(id);
+            const asset = useAsset(id);
             if (!asset)
                 return;
             if (asset.loaded) {
@@ -9288,7 +9384,7 @@
      * @returns The asset, or `raw`.
      */
     const assetConversion = (rest, raw) => {
-        const asset = AssetElement.get(rest);
+        const asset = useAsset(rest);
         if (asset) {
             return asset;
         }
@@ -10108,7 +10204,7 @@
         set asset(value) {
             this._asset = value;
             if (this.soundSlot) {
-                const id = AssetElement.get(value)?.id;
+                const id = useAsset(value)?.id;
                 if (id) {
                     this.soundSlot.asset = id;
                 }
@@ -10315,7 +10411,7 @@
         }
         getInitialComponentData() {
             return {
-                asset: AssetElement.get(this._asset),
+                asset: useAsset(this._asset),
                 castShadows: this._castShadows,
                 lodBaseDistance: this._lodBaseDistance,
                 lodMultiplier: this._lodMultiplier,
@@ -10336,7 +10432,7 @@
          */
         set asset(value) {
             this._asset = value;
-            const asset = AssetElement.get(value);
+            const asset = useAsset(value);
             if (this.component && asset) {
                 this.component.asset = asset;
             }
@@ -10614,8 +10710,7 @@
             if (generation !== this._loadGeneration) {
                 return;
             }
-            const app = appElement.app;
-            const asset = AssetElement.get(this._asset);
+            const asset = useAsset(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
@@ -10651,7 +10746,6 @@
                     }));
                     this._onReady();
                 });
-                app.assets.load(asset);
             }
         }
         _unloadModel() {
@@ -11616,7 +11710,7 @@
                 return;
             }
             this._appElement = appElement;
-            const asset = AssetElement.get(this._asset);
+            const asset = useAsset(this._asset);
             if (!asset) {
                 return;
             }
@@ -11635,7 +11729,6 @@
                     }
                     this._generateSkybox(asset);
                 });
-                app.assets.load(asset);
             }
         }
         _unloadSkybox() {