@playcanvas/web-components 0.10.1 → 0.11.0

package/dist/pwc.mjs

@@ -1,4 +1,4 @@
-import { basisInitialize, WasmModule, Vec3, Color, Vec4, Quat, Vec2, createGraphicsDevice, AppOptions, Keyboard, Mouse, ElementInput, AnimComponentSystem, AnimationComponentSystem, AudioListenerComponentSystem, ButtonComponentSystem, CameraComponentSystem, CollisionComponentSystem, ElementComponentSystem, GSplatComponentSystem, JointComponentSystem, LayoutChildComponentSystem, LayoutGroupComponentSystem, LightComponentSystem, ModelComponentSystem, ParticleSystemComponentSystem, RenderComponentSystem, RigidBodyComponentSystem, ScreenComponentSystem, ScriptComponentSystem, ScrollbarComponentSystem, ScrollViewComponentSystem, SoundComponentSystem, SpriteComponentSystem, ZoneComponentSystem, AnimClipHandler, AnimationHandler, AnimStateGraphHandler, AudioHandler, BinaryHandler, CssHandler, ContainerHandler, CubemapHandler, FolderHandler, FontHandler, GSplatHandler, HierarchyHandler, HtmlHandler, JsonHandler, MaterialHandler, ModelHandler, RenderHandler, ScriptHandler, SceneHandler, ShaderHandler, SpriteHandler, TemplateHandler, TextHandler, TextureAtlasHandler, TextureHandler, SoundManager, Lightmapper, BatchManager, XrManager, AppBase, FILLMODE_FILL_WINDOW, RESOLUTION_AUTO, Picker, MeshInstance, Entity, Asset, SPRITE_RENDERMODE_SIMPLE, SPRITE_RENDERMODE_SLICED, SPRITE_RENDERMODE_TILED, BUTTON_TRANSITION_MODE_TINT, BUTTON_TRANSITION_MODE_SPRITE_CHANGE, PROJECTION_ORTHOGRAPHIC, PROJECTION_PERSPECTIVE, GAMMA_SRGB, GAMMA_NONE, XRTYPE_VR, TONEMAP_NONE, TONEMAP_LINEAR, TONEMAP_FILMIC, TONEMAP_HEJL, TONEMAP_ACES, TONEMAP_ACES2, TONEMAP_NEUTRAL, ORIENTATION_HORIZONTAL, FITTING_NONE, FITTING_STRETCH, FITTING_SHRINK, FITTING_BOTH, ORIENTATION_VERTICAL, SHADOW_PCF3_32F, SHADOW_PCF1_16F, SHADOW_PCF1_32F, SHADOW_PCF3_16F, SHADOW_PCF5_16F, SHADOW_PCF5_32F, SHADOW_VSM_16F, SHADOW_VSM_32F, SHADOW_PCSS_32F, StandardMaterial, BLEND_NONE, CULLFACE_BACK, FRESNEL_SCHLICK, SPECOCC_AO, BLEND_NORMAL, BLEND_ADDITIVE, BLEND_ADDITIVEALPHA, BLEND_PREMULTIPLIED, BLEND_MULTIPLICATIVE, BLEND_MULTIPLICATIVE2X, BLEND_SCREEN, BLEND_MIN, BLEND_MAX, BLEND_SUBTRACTIVE, CULLFACE_NONE, CULLFACE_FRONT, CULLFACE_FRONTANDBACK, FRESNEL_NONE, SPECOCC_NONE, SPECOCC_GLOSSDEPENDENT, SCALEMODE_BLEND, SCALEMODE_NONE, SCROLL_MODE_BOUNCE, SCROLLBAR_VISIBILITY_SHOW_WHEN_REQUIRED, SCROLLBAR_VISIBILITY_SHOW_ALWAYS, SCROLL_MODE_CLAMP, SCROLL_MODE_INFINITE, EnvLighting, LAYERID_SKYBOX } from 'playcanvas';
+import { basisInitialize, WasmModule, Vec3, Color, Vec4, Quat, Vec2, createGraphicsDevice, AppOptions, Keyboard, Mouse, ElementInput, AnimComponentSystem, AnimationComponentSystem, AudioListenerComponentSystem, ButtonComponentSystem, CameraComponentSystem, CollisionComponentSystem, ElementComponentSystem, GSplatComponentSystem, JointComponentSystem, LayoutChildComponentSystem, LayoutGroupComponentSystem, LightComponentSystem, ModelComponentSystem, ParticleSystemComponentSystem, RenderComponentSystem, RigidBodyComponentSystem, ScreenComponentSystem, ScriptComponentSystem, ScrollbarComponentSystem, ScrollViewComponentSystem, SoundComponentSystem, SpriteComponentSystem, ZoneComponentSystem, AnimClipHandler, AnimationHandler, AnimStateGraphHandler, AudioHandler, BinaryHandler, CssHandler, ContainerHandler, CubemapHandler, FolderHandler, FontHandler, GSplatHandler, HierarchyHandler, HtmlHandler, JsonHandler, MaterialHandler, ModelHandler, RenderHandler, ScriptHandler, SceneHandler, ShaderHandler, SpriteHandler, TemplateHandler, TextHandler, TextureAtlasHandler, TextureHandler, SoundManager, Lightmapper, BatchManager, XrManager, AppBase, FILLMODE_FILL_WINDOW, RESOLUTION_AUTO, Picker, MeshInstance, Entity, Asset, SPRITE_RENDERMODE_SIMPLE, SPRITE_RENDERMODE_SLICED, SPRITE_RENDERMODE_TILED, BUTTON_TRANSITION_MODE_TINT, BUTTON_TRANSITION_MODE_SPRITE_CHANGE, TONEMAP_NONE, PROJECTION_PERSPECTIVE, GAMMA_SRGB, GAMMA_NONE, XRTYPE_VR, TONEMAP_LINEAR, TONEMAP_FILMIC, TONEMAP_HEJL, TONEMAP_ACES, TONEMAP_ACES2, TONEMAP_NEUTRAL, PROJECTION_ORTHOGRAPHIC, ORIENTATION_HORIZONTAL, FITTING_NONE, FITTING_STRETCH, FITTING_SHRINK, FITTING_BOTH, ORIENTATION_VERTICAL, SHADOW_PCF3_32F, SHADOW_PCF1_16F, SHADOW_PCF1_32F, SHADOW_PCF3_16F, SHADOW_PCF5_16F, SHADOW_PCF5_32F, SHADOW_VSM_16F, SHADOW_VSM_32F, SHADOW_PCSS_32F, StandardMaterial, BLEND_NONE, CULLFACE_BACK, FRESNEL_SCHLICK, SPECOCC_AO, BLEND_NORMAL, BLEND_ADDITIVE, BLEND_ADDITIVEALPHA, BLEND_PREMULTIPLIED, BLEND_MULTIPLICATIVE, BLEND_MULTIPLICATIVE2X, BLEND_SCREEN, BLEND_MIN, BLEND_MAX, BLEND_SUBTRACTIVE, CULLFACE_NONE, CULLFACE_FRONT, CULLFACE_FRONTANDBACK, FRESNEL_NONE, SPECOCC_NONE, SPECOCC_GLOSSDEPENDENT, SCALEMODE_NONE, SCALEMODE_BLEND, SCROLL_MODE_BOUNCE, SCROLLBAR_VISIBILITY_SHOW_WHEN_REQUIRED, SCROLLBAR_VISIBILITY_SHOW_ALWAYS, SCROLL_MODE_CLAMP, SCROLL_MODE_INFINITE, EnvLighting, LAYERID_SKYBOX } from 'playcanvas';
 
 /**
  * Base class for all PlayCanvas Web Components that initialize asynchronously.
@@ -487,7 +487,9 @@ const parseColor = (value, defaultValue, attribute) => {
  * 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.
@@ -675,12 +677,24 @@ class AppElement extends AsyncElement {
     _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,
@@ -748,15 +762,19 @@ class AppElement extends AsyncElement {
             null: ['null']
         };
         const deviceTypes = backendToDeviceTypes[this._backend] || [];
+        this._optionsLocked = true;
         const device = await 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 AppOptions();
         createOptions.graphicsDevice = device;
         createOptions.keyboard = new Keyboard(window);
@@ -883,12 +901,15 @@ class AppElement extends AsyncElement {
         });
     }
     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;
@@ -954,6 +975,74 @@ class AppElement extends AsyncElement {
             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.
@@ -999,17 +1088,9 @@ class AppElement extends AsyncElement {
         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')) {
@@ -1029,26 +1110,22 @@ class AppElement extends AsyncElement {
     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));
         }
     }
@@ -1078,28 +1155,43 @@ class AppElement extends AsyncElement {
         }
     }
     /**
-     * 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() {
@@ -1107,10 +1199,11 @@ class AppElement extends AsyncElement {
     }
     /**
      * 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;
     }
     /**
@@ -1121,18 +1214,20 @@ class AppElement extends AsyncElement {
         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.
@@ -1142,24 +1237,6 @@ class AppElement extends AsyncElement {
     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
@@ -1184,21 +1261,45 @@ class AppElement extends AsyncElement {
         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) {
@@ -1211,17 +1312,17 @@ class AppElement extends AsyncElement {
             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;
         }
     }
@@ -1290,6 +1391,11 @@ class EntityElement extends AsyncElement {
      */
     _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()`
@@ -1319,6 +1425,27 @@ class EntityElement extends AsyncElement {
         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)
@@ -1361,22 +1488,11 @@ class EntityElement extends AsyncElement {
         }
     }
     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.
@@ -2523,6 +2639,10 @@ class ButtonComponentElement extends ComponentElement {
 }
 customElements.define('pc-button', ButtonComponentElement);
 
+const projections = new Map([
+    ['perspective', PROJECTION_PERSPECTIVE],
+    ['orthographic', PROJECTION_ORTHOGRAPHIC]
+]);
 const tonemaps = new Map([
     ['none', TONEMAP_NONE],
     ['linear', TONEMAP_LINEAR],
@@ -2553,7 +2673,7 @@ class CameraComponentElement extends ComponentElement {
     _gamma = 'srgb';
     _horizontalFov = false;
     _nearClip = 0.1;
-    _orthographic = false;
+    _projection = 'perspective';
     _orthoHeight = 10;
     _priority = 0;
     _rect = new Vec4(0, 0, 1, 1);
@@ -2577,12 +2697,12 @@ class CameraComponentElement extends ComponentElement {
             gammaCorrection: this._gamma === 'srgb' ? GAMMA_SRGB : GAMMA_NONE,
             horizontalFov: this._horizontalFov,
             nearClip: this._nearClip,
-            projection: this._orthographic ? PROJECTION_ORTHOGRAPHIC : PROJECTION_PERSPECTIVE,
+            projection: projections.get(this._projection) ?? PROJECTION_PERSPECTIVE,
             orthoHeight: this._orthoHeight,
             priority: this._priority,
             rect: this._rect,
             scissorRect: this._scissorRect,
-            toneMapping: tonemaps.get(this._tonemap)
+            toneMapping: tonemaps.get(this._tonemap) ?? TONEMAP_NONE
         };
     }
     get xrAvailable() {
@@ -2824,23 +2944,6 @@ class CameraComponentElement extends ComponentElement {
     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 ? PROJECTION_ORTHOGRAPHIC : 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.
@@ -2875,6 +2978,23 @@ class CameraComponentElement extends ComponentElement {
     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) ?? 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.
@@ -2941,9 +3061,9 @@ class CameraComponentElement extends ComponentElement {
             'gamma',
             'horizontal-fov',
             'near-clip',
-            'orthographic',
             'ortho-height',
             'priority',
+            'projection',
             'rect',
             'scissor-rect',
             'tonemap'
@@ -2988,15 +3108,15 @@ class CameraComponentElement extends ComponentElement {
             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 Vec4(0, 0, 1, 1), name);
                 break;
@@ -7414,6 +7534,14 @@ class RigidBodyComponentElement extends ComponentElement {
 }
 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', SCALEMODE_NONE],
+    ['blend', 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.
@@ -7427,7 +7555,7 @@ class ScreenComponentElement extends ComponentElement {
     _resolution = new Vec2(640, 320);
     _referenceResolution = new Vec2(640, 320);
     _priority = 0;
-    _blend = false;
+    _scaleMode = 'none';
     _scaleBlend = 0.5;
     /** @ignore */
     constructor() {
@@ -7439,7 +7567,7 @@ class ScreenComponentElement extends ComponentElement {
             referenceResolution: this._referenceResolution,
             resolution: this._resolution,
             scaleBlend: this._scaleBlend,
-            scaleMode: this._blend ? SCALEMODE_BLEND : SCALEMODE_NONE,
+            scaleMode: scaleModes.get(this._scaleMode) ?? SCALEMODE_NONE,
             screenSpace: this._screenSpace
         };
     }
@@ -7477,23 +7605,44 @@ class ScreenComponentElement extends ComponentElement {
     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 ? SCALEMODE_BLEND : SCALEMODE_NONE;
+            this.component.scaleMode = scaleModes.get(value) ?? 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;
@@ -7507,12 +7656,12 @@ class ScreenComponentElement extends ComponentElement {
     static get observedAttributes() {
         return [
             ...super.observedAttributes,
-            'blend',
             'screen-space',
             'resolution',
             'reference-resolution',
             'priority',
-            'scale-blend'
+            'scale-blend',
+            'scale-mode'
         ];
     }
     attributeChangedCallback(name, _oldValue, newValue) {
@@ -7530,8 +7679,8 @@ class ScreenComponentElement extends ComponentElement {
             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);
@@ -7754,7 +7903,8 @@ class ScrollViewComponentElement extends ComponentElement {
         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) {
@@ -7764,14 +7914,15 @@ class ScrollViewComponentElement extends ComponentElement {
         }
     }
     /**
-     * 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) {
@@ -7781,7 +7932,7 @@ class ScrollViewComponentElement extends ComponentElement {
         }
     }
     /**
-     * Gets whether vertical scrolling is enabled.
+     * Gets whether scrolling along the vertical axis is enabled.
      * @returns Whether vertical scrolling is enabled.
      */
     get vertical() {
@@ -9771,7 +9922,7 @@ class SkyElement extends AsyncElement {
     _center = new Vec3(0, 0.01, 0);
     _intensity = 1;
     _rotation = new Vec3();
-    _level = 0;
+    _mipLevel = 0;
     _lighting = false;
     _scale = new Vec3(100, 100, 100);
     _type = 'infinite';
@@ -9805,7 +9956,7 @@ class SkyElement extends AsyncElement {
         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();
@@ -9897,23 +10048,6 @@ class SkyElement extends AsyncElement {
     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.
@@ -9928,6 +10062,24 @@ class SkyElement extends AsyncElement {
     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.
@@ -9984,7 +10136,7 @@ class SkyElement extends AsyncElement {
         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) {
@@ -9997,12 +10149,12 @@ class SkyElement extends AsyncElement {
             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, Vec3.ZERO, name);
                 break;