@playcanvas/web-components 0.10.1 → 0.11.0

package/dist/pwc.js

@@ -491,7 +491,9 @@
      * the value is invalid — the latter also logs a warning listing the valid names.
      *
      * @param value - The attribute value to parse (`null` when the attribute is absent).
-     * @param valid - The valid names: an array, or a map whose keys are the valid names.
+     * @param valid - The valid names: an array, or a map whose keys are the valid names. Only the keys
+     * are read, so the map's value type is unconstrained - engine enums are mostly numeric constants,
+     * but some (e.g. `SCALEMODE_BLEND`) are strings.
      * @param defaultValue - The value to use when the attribute is absent or invalid.
      * @param attribute - The attribute name, used in the warning message.
      * @returns The resolved enum name.
@@ -679,12 +681,24 @@
         _alpha = true;
         _backend = 'webgpu';
         _antialias = true;
-        _depth = true;
-        _stencil = true;
-        _highResolution = true;
+        _depthBuffer = true;
+        _stencilBuffer = true;
+        _maxPixelRatio = Infinity;
         _loadingBar = true;
+        /**
+         * Set once the graphics options above have been handed to `createGraphicsDevice`, after which
+         * writing any of them changes nothing. Guards the warning in {@link _warnIfBooted}, and is
+         * cleared on disconnect so a re-connected element boots from its current attributes.
+         */
+        _optionsLocked = false;
         _bar = null;
         _hierarchyReady = false;
+        /**
+         * The elements backing this application's entities, keyed by the entity itself. Registered
+         * by EntityElement at creation and removed when an entity is destroyed, this joins engine
+         * scene nodes back to their owning elements by identity - never by name.
+         */
+        _entityElements = new Map();
         _picker = null;
         _hasPointerListeners = {
             pointerenter: false,
@@ -752,15 +766,19 @@
                 null: ['null']
             };
             const deviceTypes = backendToDeviceTypes[this._backend] || [];
+            this._optionsLocked = true;
             const device = await playcanvas.createGraphicsDevice(this._canvas, {
                 // @ts-ignore - alpha needs to be documented
                 alpha: this._alpha,
                 antialias: this._antialias,
-                depth: this._depth,
+                depth: this._depthBuffer,
                 deviceTypes: deviceTypes,
-                stencil: this._stencil
+                stencil: this._stencilBuffer
             });
-            device.maxPixelRatio = this._highResolution ? window.devicePixelRatio : 1;
+            // Assigned rather than resolved to a number here: the engine caps against the live
+            // window.devicePixelRatio on every resize, so an uncapped Infinity keeps following the
+            // display when a window moves between monitors of differing density.
+            device.maxPixelRatio = this._maxPixelRatio;
             const createOptions = new playcanvas.AppOptions();
             createOptions.graphicsDevice = device;
             createOptions.keyboard = new playcanvas.Keyboard(window);
@@ -887,12 +905,15 @@
             });
         }
         disconnectedCallback() {
+            this._optionsLocked = false;
             this._pickerDestroy();
-            // Clean up the application
+            // Clean up the application. Destroying it destroys every entity, whose destroy hooks
+            // unregister them - clear() covers any entity the engine no longer reached.
             if (this._app) {
                 this._app.destroy();
                 this._app = null;
             }
+            this._entityElements.clear();
             this._loadProgress = 0;
             this._bar?.destroy();
             this._bar = null;
@@ -958,6 +979,74 @@
                 pointermove: false
             };
         }
+        /**
+         * Registers the element that created an entity. Called by EntityElement when it creates its
+         * entity.
+         *
+         * @param entity - The entity.
+         * @param element - The element that created it.
+         * @ignore
+         */
+        _registerEntityElement(entity, element) {
+            this._entityElements.set(entity, element);
+        }
+        /**
+         * Removes the registration for a destroyed entity. Called by EntityElement.
+         *
+         * @param entity - The entity.
+         * @ignore
+         */
+        _unregisterEntityElement(entity) {
+            this._entityElements.delete(entity);
+        }
+        /**
+         * Returns the `<pc-entity>` element whose backing entity is `entity`, or `null` if the
+         * entity was not created by an element of this application - for example, a node inside a
+         * model's instantiated hierarchy, or an entity created through the engine API.
+         *
+         * @param entity - The entity to look up.
+         * @returns The element backing the entity, or `null`.
+         */
+        elementFromEntity(entity) {
+            return this._entityElements.get(entity) ?? null;
+        }
+        /**
+         * Resolves the element that owns a picked node: the nearest node up the parent chain -
+         * starting with the node itself - that was created by a `<pc-entity>` of this application.
+         * A hit inside a model's instantiated hierarchy therefore resolves to the element hosting
+         * the model.
+         *
+         * @param node - The picked node, or `null`.
+         * @returns The owning element, or `null`.
+         */
+        _elementFromNode(node) {
+            while (node !== null) {
+                const element = this._entityElements.get(node);
+                if (element) {
+                    return element;
+                }
+                node = node.parent;
+            }
+            return null;
+        }
+        /**
+         * Like {@link _elementFromNode}, but skips elements without a listener for `type`, so a hit
+         * on an unlistened child still reaches a listening ancestor.
+         *
+         * @param node - The picked node, or `null`.
+         * @param type - The pointer event type a listener is required for.
+         * @returns The nearest listening element, or `null`.
+         */
+        _elementWithListener(node, type) {
+            while (node !== null) {
+                const element = this._entityElements.get(node);
+                if (element?.hasListeners(type)) {
+                    return element;
+                }
+                node = node.parent;
+            }
+            return null;
+        }
         // New helper to convert CSS coordinates to canvas (picker) coordinates
         _getPickerCoordinates(event) {
             // Get the canvas' bounding rectangle in CSS pixels.
@@ -1003,17 +1092,9 @@
             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 = null;
-            let currentNode = node;
-            while (currentNode !== null) {
-                const entityElement = this.querySelector(`pc-entity[name="${currentNode.name}"]`);
-                if (entityElement) {
-                    newHoverEntity = entityElement;
-                    break;
-                }
-                currentNode = currentNode.parent;
-            }
+            // The hovered element is the nearest one up the node's parent chain, listening or not -
+            // dispatch is gated per event type below
+            const newHoverEntity = this._elementFromNode(node);
             // Handle enter/leave events
             if (this._hoveredEntity !== newHoverEntity) {
                 if (this._hoveredEntity && this._hoveredEntity.hasListeners('pointerleave')) {
@@ -1033,26 +1114,22 @@
         async _onPointerDown(event) {
             if (!this._picker || !this.app)
                 return;
-            let currentNode = await this._pickNode(event);
+            const node = await this._pickNode(event);
             if (!this._picker)
                 return; // the element disconnected while the pick was in flight
-            while (currentNode !== null) {
-                const entityElement = this.querySelector(`pc-entity[name="${currentNode.name}"]`);
-                if (entityElement && entityElement.hasListeners('pointerdown')) {
-                    entityElement.dispatchEvent(new PointerEvent('pointerdown', event));
-                    break;
-                }
-                currentNode = currentNode.parent;
+            const entityElement = this._elementWithListener(node, 'pointerdown');
+            if (entityElement) {
+                entityElement.dispatchEvent(new PointerEvent('pointerdown', event));
             }
         }
         async _onPointerUp(event) {
             if (!this._picker || !this.app)
                 return;
             const node = await this._pickNode(event);
-            if (!node || !this._picker)
-                return;
-            const entityElement = this.querySelector(`pc-entity[name="${node.name}"]`);
-            if (entityElement && entityElement.hasListeners('pointerup')) {
+            if (!this._picker)
+                return; // the element disconnected while the pick was in flight
+            const entityElement = this._elementWithListener(node, 'pointerup');
+            if (entityElement) {
                 entityElement.dispatchEvent(new PointerEvent('pointerup', event));
             }
         }
@@ -1082,28 +1159,43 @@
             }
         }
         /**
-         * Sets the alpha flag.
+         * Warns that a graphics option was written too late to have any effect. These options are read
+         * once, when the element connects and creates its graphics device, so a later write updates
+         * only the element's own property - silently, without this.
+         *
+         * @param name - The name of the option, as its attribute.
+         */
+        _warnIfBooted(name) {
+            if (this._optionsLocked) {
+                console.warn(`Attribute '${name}' on <pc-app> is only read when the application boots, so this change has no effect. Set it before the element is connected, or remove and re-insert the element to reboot with the new value.`);
+            }
+        }
+        /**
+         * Sets whether the frame buffer has an alpha channel, which is what lets the page show through
+         * wherever the scene has not drawn. Read only when the application boots.
          * @param value - The alpha flag.
          */
         set alpha(value) {
+            this._warnIfBooted('alpha');
             this._alpha = value;
         }
         /**
-         * Gets the alpha flag.
+         * Gets whether the frame buffer has an alpha channel.
          * @returns The alpha flag.
          */
         get alpha() {
             return this._alpha;
         }
         /**
-         * Sets the antialias flag.
+         * Sets whether the frame buffer is anti-aliased. Read only when the application boots.
          * @param value - The antialias flag.
          */
         set antialias(value) {
+            this._warnIfBooted('antialias');
             this._antialias = value;
         }
         /**
-         * Gets the antialias flag.
+         * Gets whether the frame buffer is anti-aliased.
          * @returns The antialias flag.
          */
         get antialias() {
@@ -1111,10 +1203,11 @@
         }
         /**
          * Sets the graphics backend. Defaults to 'webgpu', which falls back to 'webgl2' if WebGPU
-         * is not supported by the browser.
+         * is not supported by the browser. Read only when the application boots.
          * @param value - The graphics backend ('webgpu', 'webgl2', or 'null').
          */
         set backend(value) {
+            this._warnIfBooted('backend');
             this._backend = value;
         }
         /**
@@ -1125,18 +1218,20 @@
             return this._backend;
         }
         /**
-         * Sets the depth flag.
-         * @param value - The depth flag.
+         * Sets whether the frame buffer has a depth buffer, which the renderer needs to resolve which
+         * surface is nearest the camera. Read only when the application boots.
+         * @param value - The depth buffer flag.
          */
-        set depth(value) {
-            this._depth = value;
+        set depthBuffer(value) {
+            this._warnIfBooted('depth-buffer');
+            this._depthBuffer = value;
         }
         /**
-         * Gets the depth flag.
-         * @returns The depth flag.
+         * Gets whether the frame buffer has a depth buffer.
+         * @returns The depth buffer flag.
          */
-        get depth() {
-            return this._depth;
+        get depthBuffer() {
+            return this._depthBuffer;
         }
         /**
          * Gets the hierarchy ready flag.
@@ -1146,24 +1241,6 @@
         get hierarchyReady() {
             return this._hierarchyReady;
         }
-        /**
-         * Sets the high resolution flag. When true, the application will render at the device's
-         * physical resolution. When false, the application will render at CSS resolution.
-         * @param value - The high resolution flag.
-         */
-        set highResolution(value) {
-            this._highResolution = value;
-            if (this.app) {
-                this.app.graphicsDevice.maxPixelRatio = value ? window.devicePixelRatio : 1;
-            }
-        }
-        /**
-         * Gets the high resolution flag.
-         * @returns The high resolution flag.
-         */
-        get highResolution() {
-            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
@@ -1188,21 +1265,45 @@
             return this._loadingBar;
         }
         /**
-         * Sets the stencil flag.
-         * @param value - The stencil flag.
+         * Sets the cap on the pixel ratio the application renders at. The canvas is sized by the
+         * smaller of this value and the display's own device pixel ratio, so the default of `Infinity`
+         * renders at full physical resolution, `1` renders at CSS resolution, and an intermediate
+         * value such as `2` keeps a dense display sharp without paying for every one of its pixels.
+         * Must be greater than 0. Unlike the other graphics options, this applies immediately.
+         * @param value - The maximum pixel ratio.
+         */
+        set maxPixelRatio(value) {
+            this._maxPixelRatio = value;
+            if (this.app) {
+                this.app.graphicsDevice.maxPixelRatio = value;
+                this.app.resizeCanvas();
+            }
+        }
+        /**
+         * Gets the cap on the pixel ratio the application renders at.
+         * @returns The maximum pixel ratio.
+         */
+        get maxPixelRatio() {
+            return this._maxPixelRatio;
+        }
+        /**
+         * Sets whether the frame buffer has a stencil buffer, which stencil-based effects and UI
+         * masking need. Read only when the application boots.
+         * @param value - The stencil buffer flag.
          */
-        set stencil(value) {
-            this._stencil = value;
+        set stencilBuffer(value) {
+            this._warnIfBooted('stencil-buffer');
+            this._stencilBuffer = value;
         }
         /**
-         * Gets the stencil flag.
-         * @returns The stencil flag.
+         * Gets whether the frame buffer has a stencil buffer.
+         * @returns The stencil buffer flag.
          */
-        get stencil() {
-            return this._stencil;
+        get stencilBuffer() {
+            return this._stencilBuffer;
         }
         static get observedAttributes() {
-            return ['alpha', 'antialias', 'backend', 'depth', 'stencil', 'high-resolution', 'loading-bar'];
+            return ['alpha', 'antialias', 'backend', 'depth-buffer', 'loading-bar', 'max-pixel-ratio', 'stencil-buffer'];
         }
         attributeChangedCallback(name, _oldValue, newValue) {
             switch (name) {
@@ -1215,17 +1316,17 @@
                 case 'backend':
                     this.backend = parseEnum(newValue, ['webgpu', 'webgl2', 'null'], 'webgpu', name);
                     break;
-                case 'depth':
-                    this.depth = parseBool(newValue, true);
-                    break;
-                case 'high-resolution':
-                    this.highResolution = parseBool(newValue, true);
+                case 'depth-buffer':
+                    this.depthBuffer = parseBool(newValue, true);
                     break;
                 case 'loading-bar':
                     this.loadingBar = parseBool(newValue, true);
                     break;
-                case 'stencil':
-                    this.stencil = parseBool(newValue, true);
+                case 'max-pixel-ratio':
+                    this.maxPixelRatio = parseNumber(newValue, Infinity, name);
+                    break;
+                case 'stencil-buffer':
+                    this.stencilBuffer = parseBool(newValue, true);
                     break;
             }
         }
@@ -1294,6 +1395,11 @@
          */
         _built = false;
         _entity = null;
+        /**
+         * The application element this entity is registered with, cached at creation time so the
+         * entity can be unregistered even once this element has left the DOM.
+         */
+        _appElement = null;
         /**
          * 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()`
@@ -1323,6 +1429,27 @@
             if (this._tags.length > 0) {
                 entity.tags.add(this._tags);
             }
+            // Register with the owning application, which joins engine nodes back to elements by
+            // identity (never by name), and hook the entity's destruction. The engine fires 'destroy'
+            // for every entity in a destroyed subtree, so the element learns of its entity's death no
+            // matter who causes it: this element, an ancestor, the whole application, or a user
+            // script calling entity.destroy().
+            this._appElement = this.closestApp;
+            this._appElement?._registerEntityElement(entity, this);
+            entity.once('destroy', this._onEntityDestroy, this);
+        }
+        /**
+         * Handles the destruction of the backing entity. Resets the element so a later re-insertion
+         * starts clean: `_built` must be cleared alongside `_entity`, or buildHierarchy would bail
+         * and a re-created entity would never be parented.
+         *
+         * @param entity - The entity that was destroyed.
+         */
+        _onEntityDestroy(entity) {
+            this._appElement?._unregisterEntityElement(entity);
+            this._appElement = null;
+            this._entity = null;
+            this._built = false;
         }
         buildHierarchy(app) {
             if (!this.entity || this._built)
@@ -1365,22 +1492,11 @@
             }
         }
         disconnectedCallback() {
-            if (this.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('pc-entity');
-                children.forEach((child) => {
-                    child._entity = null;
-                    child._built = false;
-                });
-                // Destroy the entity
-                this.entity.destroy();
-                this._entity = null;
-                this._built = false;
-            }
+            // Destroying the entity destroys its whole subtree, and the engine fires 'destroy' for
+            // every entity in it - so _onEntityDestroy resets this element AND every descendant
+            // element before the descendants' own disconnectedCallbacks run. Their entities are null
+            // by then, making this call a no-op for them.
+            this._entity?.destroy();
         }
         /**
          * Sets the enabled state of the entity.
@@ -2527,6 +2643,10 @@
     }
     customElements.define('pc-button', ButtonComponentElement);
 
+    const projections = new Map([
+        ['perspective', playcanvas.PROJECTION_PERSPECTIVE],
+        ['orthographic', playcanvas.PROJECTION_ORTHOGRAPHIC]
+    ]);
     const tonemaps = new Map([
         ['none', playcanvas.TONEMAP_NONE],
         ['linear', playcanvas.TONEMAP_LINEAR],
@@ -2557,7 +2677,7 @@
         _gamma = 'srgb';
         _horizontalFov = false;
         _nearClip = 0.1;
-        _orthographic = false;
+        _projection = 'perspective';
         _orthoHeight = 10;
         _priority = 0;
         _rect = new playcanvas.Vec4(0, 0, 1, 1);
@@ -2581,12 +2701,12 @@
                 gammaCorrection: this._gamma === 'srgb' ? playcanvas.GAMMA_SRGB : playcanvas.GAMMA_NONE,
                 horizontalFov: this._horizontalFov,
                 nearClip: this._nearClip,
-                projection: this._orthographic ? playcanvas.PROJECTION_ORTHOGRAPHIC : playcanvas.PROJECTION_PERSPECTIVE,
+                projection: projections.get(this._projection) ?? playcanvas.PROJECTION_PERSPECTIVE,
                 orthoHeight: this._orthoHeight,
                 priority: this._priority,
                 rect: this._rect,
                 scissorRect: this._scissorRect,
-                toneMapping: tonemaps.get(this._tonemap)
+                toneMapping: tonemaps.get(this._tonemap) ?? playcanvas.TONEMAP_NONE
             };
         }
         get xrAvailable() {
@@ -2828,23 +2948,6 @@
         get nearClip() {
             return this._nearClip;
         }
-        /**
-         * Sets the orthographic projection of the camera.
-         * @param value - The orthographic projection.
-         */
-        set orthographic(value) {
-            this._orthographic = value;
-            if (this.component) {
-                this.component.projection = value ? playcanvas.PROJECTION_ORTHOGRAPHIC : playcanvas.PROJECTION_PERSPECTIVE;
-            }
-        }
-        /**
-         * Gets the orthographic projection of the camera.
-         * @returns The orthographic projection.
-         */
-        get orthographic() {
-            return this._orthographic;
-        }
         /**
          * Sets the orthographic height of the camera.
          * @param value - The orthographic height.
@@ -2879,6 +2982,23 @@
         get priority() {
             return this._priority;
         }
+        /**
+         * Sets the projection of the camera. Use `orthoHeight` to size an orthographic projection.
+         * @param value - The projection ('perspective' or 'orthographic').
+         */
+        set projection(value) {
+            this._projection = value;
+            if (this.component) {
+                this.component.projection = projections.get(value) ?? playcanvas.PROJECTION_PERSPECTIVE;
+            }
+        }
+        /**
+         * Gets the projection of the camera.
+         * @returns The projection.
+         */
+        get projection() {
+            return this._projection;
+        }
         /**
          * Sets the rect of the camera.
          * @param value - The rect.
@@ -2945,9 +3065,9 @@
                 'gamma',
                 'horizontal-fov',
                 'near-clip',
-                'orthographic',
                 'ortho-height',
                 'priority',
+                'projection',
                 'rect',
                 'scissor-rect',
                 'tonemap'
@@ -2992,15 +3112,15 @@
                 case 'near-clip':
                     this.nearClip = parseNumber(newValue, 0.1, name);
                     break;
-                case 'orthographic':
-                    this.orthographic = parseBool(newValue, false);
-                    break;
                 case 'ortho-height':
                     this.orthoHeight = parseNumber(newValue, 10, name);
                     break;
                 case 'priority':
                     this.priority = parseNumber(newValue, 0, name);
                     break;
+                case 'projection':
+                    this.projection = parseEnum(newValue, projections, 'perspective', name);
+                    break;
                 case 'rect':
                     this.rect = parseVec4(newValue, new playcanvas.Vec4(0, 0, 1, 1), name);
                     break;
@@ -7418,6 +7538,14 @@
     }
     customElements.define('pc-rigidbody', RigidBodyComponentElement);
 
+    // The engine's SCALEMODE_* constants are the strings 'none' and 'blend', so this map happens to be
+    // an identity. It is still the right shape: it supplies parseEnum's valid-name list, it is what the
+    // manifest generator reads the enum values from, and it keeps the attribute vocabulary independent
+    // of constants the engine is free to change.
+    const scaleModes = new Map([
+        ['none', playcanvas.SCALEMODE_NONE],
+        ['blend', playcanvas.SCALEMODE_BLEND]
+    ]);
     /**
      * The ScreenComponentElement interface provides properties and methods for manipulating
      * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-screen/ | `<pc-screen>`} elements.
@@ -7431,7 +7559,7 @@
         _resolution = new playcanvas.Vec2(640, 320);
         _referenceResolution = new playcanvas.Vec2(640, 320);
         _priority = 0;
-        _blend = false;
+        _scaleMode = 'none';
         _scaleBlend = 0.5;
         /** @ignore */
         constructor() {
@@ -7443,7 +7571,7 @@
                 referenceResolution: this._referenceResolution,
                 resolution: this._resolution,
                 scaleBlend: this._scaleBlend,
-                scaleMode: this._blend ? playcanvas.SCALEMODE_BLEND : playcanvas.SCALEMODE_NONE,
+                scaleMode: scaleModes.get(this._scaleMode) ?? playcanvas.SCALEMODE_NONE,
                 screenSpace: this._screenSpace
             };
         }
@@ -7481,23 +7609,44 @@
         get resolution() {
             return this._resolution;
         }
+        /**
+         * Sets how the screen's `resolution` and `referenceResolution` are weighted against each other
+         * when `scaleMode` is `blend`, from 0 (follow the resolution) to 1 (follow the reference
+         * resolution). Ignored while `scaleMode` is `none`.
+         * @param value - The scale blend factor.
+         */
         set scaleBlend(value) {
             this._scaleBlend = value;
             if (this.component) {
                 this.component.scaleBlend = this._scaleBlend;
             }
         }
+        /**
+         * Gets how the screen's resolutions are weighted against each other.
+         * @returns The scale blend factor.
+         */
         get scaleBlend() {
             return this._scaleBlend;
         }
-        set blend(value) {
-            this._blend = value;
+        /**
+         * Sets how the screen scales its contents. `none` renders at `resolution` and ignores
+         * `referenceResolution`; `blend` scales between the two, weighted by `scaleBlend`, which is what
+         * keeps a UI laid out at one resolution usable at another. Requires `screenSpace` - the engine
+         * forces `none` on a world-space screen, which does not support scaling.
+         * @param value - The scale mode ('none' or 'blend').
+         */
+        set scaleMode(value) {
+            this._scaleMode = value;
             if (this.component) {
-                this.component.scaleMode = this._blend ? playcanvas.SCALEMODE_BLEND : playcanvas.SCALEMODE_NONE;
+                this.component.scaleMode = scaleModes.get(value) ?? playcanvas.SCALEMODE_NONE;
             }
         }
-        get blend() {
-            return this._blend;
+        /**
+         * Gets how the screen scales its contents.
+         * @returns The scale mode.
+         */
+        get scaleMode() {
+            return this._scaleMode;
         }
         set screenSpace(value) {
             this._screenSpace = value;
@@ -7511,12 +7660,12 @@
         static get observedAttributes() {
             return [
                 ...super.observedAttributes,
-                'blend',
                 'screen-space',
                 'resolution',
                 'reference-resolution',
                 'priority',
-                'scale-blend'
+                'scale-blend',
+                'scale-mode'
             ];
         }
         attributeChangedCallback(name, _oldValue, newValue) {
@@ -7534,8 +7683,8 @@
                 case 'scale-blend':
                     this.scaleBlend = parseNumber(newValue, 0.5, name);
                     break;
-                case 'blend':
-                    this.blend = parseBool(newValue, false);
+                case 'scale-mode':
+                    this.scaleMode = parseEnum(newValue, scaleModes, 'none', name);
                     break;
                 case 'screen-space':
                     this.screenSpace = parseBool(newValue, false);
@@ -7758,7 +7907,8 @@
             return super.component;
         }
         /**
-         * Sets whether horizontal scrolling is enabled.
+         * Sets whether scrolling along the horizontal axis is enabled. This is a toggle, unlike the
+         * `orientation` of a `<pc-scrollbar>`, for which `horizontal` is one of the accepted values.
          * @param value - Whether horizontal scrolling is enabled.
          */
         set horizontal(value) {
@@ -7768,14 +7918,15 @@
             }
         }
         /**
-         * Gets whether horizontal scrolling is enabled.
+         * Gets whether scrolling along the horizontal axis is enabled.
          * @returns Whether horizontal scrolling is enabled.
          */
         get horizontal() {
             return this._horizontal;
         }
         /**
-         * Sets whether vertical scrolling is enabled.
+         * Sets whether scrolling along the vertical axis is enabled. This is a toggle, unlike the
+         * `orientation` of a `<pc-scrollbar>`, for which `vertical` is one of the accepted values.
          * @param value - Whether vertical scrolling is enabled.
          */
         set vertical(value) {
@@ -7785,7 +7936,7 @@
             }
         }
         /**
-         * Gets whether vertical scrolling is enabled.
+         * Gets whether scrolling along the vertical axis is enabled.
          * @returns Whether vertical scrolling is enabled.
          */
         get vertical() {
@@ -9775,7 +9926,7 @@
         _center = new playcanvas.Vec3(0, 0.01, 0);
         _intensity = 1;
         _rotation = new playcanvas.Vec3();
-        _level = 0;
+        _mipLevel = 0;
         _lighting = false;
         _scale = new playcanvas.Vec3(100, 100, 100);
         _type = 'infinite';
@@ -9809,7 +9960,7 @@
             this._scene.sky.node.setLocalScale(this._scale);
             this._scene.sky.center = this._center;
             this._scene.skyboxIntensity = this._intensity;
-            this._scene.skyboxMip = this._level;
+            this._scene.skyboxMip = this._mipLevel;
         }
         async _loadSkybox() {
             const appElement = await this.closestApp?.ready();
@@ -9901,23 +10052,6 @@
         get intensity() {
             return this._intensity;
         }
-        /**
-         * Sets the mip level of the skybox.
-         * @param value - The mip level.
-         */
-        set level(value) {
-            this._level = value;
-            if (this._scene) {
-                this._scene.skyboxMip = this._level;
-            }
-        }
-        /**
-         * Gets the mip level of the skybox.
-         * @returns The mip level.
-         */
-        get level() {
-            return this._level;
-        }
         /**
          * Sets whether the skybox is used as a light source.
          * @param value - Whether to use lighting.
@@ -9932,6 +10066,24 @@
         get lighting() {
             return this._lighting;
         }
+        /**
+         * Sets the mip level of the skybox, where 0 is the sharpest. Raising it selects a blurrier mip,
+         * which is how a skybox is softened without blurring the texture itself.
+         * @param value - The mip level.
+         */
+        set mipLevel(value) {
+            this._mipLevel = value;
+            if (this._scene) {
+                this._scene.skyboxMip = this._mipLevel;
+            }
+        }
+        /**
+         * Gets the mip level of the skybox.
+         * @returns The mip level.
+         */
+        get mipLevel() {
+            return this._mipLevel;
+        }
         /**
          * Sets the Euler rotation of the skybox.
          * @param value - The rotation.
@@ -9988,7 +10140,7 @@
             return this._type;
         }
         static get observedAttributes() {
-            return ['asset', 'center', 'intensity', 'level', 'lighting', 'rotation', 'scale', 'type'];
+            return ['asset', 'center', 'intensity', 'lighting', 'mip-level', 'rotation', 'scale', 'type'];
         }
         attributeChangedCallback(name, _oldValue, newValue) {
             switch (name) {
@@ -10001,12 +10153,12 @@
                 case 'intensity':
                     this.intensity = parseNumber(newValue, 1, name);
                     break;
-                case 'level':
-                    this.level = parseNumber(newValue, 0, name);
-                    break;
                 case 'lighting':
                     this.lighting = parseBool(newValue, false);
                     break;
+                case 'mip-level':
+                    this.mipLevel = parseNumber(newValue, 0, name);
+                    break;
                 case 'rotation':
                     this.rotation = parseVec3(newValue, playcanvas.Vec3.ZERO, name);
                     break;