@playcanvas/web-components 0.10.0 → 0.11.0

package/src/parse.ts

@@ -113,21 +113,23 @@ export const parseColor = <T extends Color | null>(value: string | null, default
  * 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.
  */
 export const parseEnum = <T extends string>(
     value: string | null,
-    valid: readonly T[] | ReadonlyMap<T, number>,
+    valid: readonly T[] | ReadonlyMap<T, unknown>,
     defaultValue: T,
     attribute: string
 ): T => {
     if (value === null) {
         return defaultValue;
     }
-    const names = Array.isArray(valid) ? valid : [...(valid as ReadonlyMap<T, number>).keys()];
+    const names: readonly T[] = Array.isArray(valid) ? valid : [...valid.keys()];
     if (names.includes(value as T)) {
         return value as T;
     }

package/src/scene.ts

@@ -1,6 +1,5 @@
 import { Color, Scene, Vec3 } from 'playcanvas';
 
-import { AppElement } from './app';
 import { AsyncElement } from './async-element';
 import { parseColor, parseEnum, parseNumber, parseVec3 } from './parse';
 
@@ -44,36 +43,68 @@ class SceneElement extends AsyncElement {
     private _scene: Scene | null = null;
 
     /**
-     * The PlayCanvas scene instance. Available once the element is ready — await
+     * The PlayCanvas scene instance. `null` until the element is ready — await
      * {@link whenReady} or the element's `ready()` promise before accessing it.
-     * @returns The scene instance.
+     * @returns The scene instance, or `null`.
      */
-    get scene(): Scene {
-        return this._scene!;
+    get scene(): Scene | null {
+        return this._scene;
     }
 
     async connectedCallback() {
-        await this.closestApp?.ready();
+        const appElement = this.closestApp;
+        if (!appElement) {
+            console.warn('pc-scene must be a descendant of pc-app - scene settings not applied');
+            return;
+        }
+
+        await appElement.ready();
+
+        // The element may have been removed or re-parented while waiting for the app. Matches the
+        // guard in AssetElement and MaterialElement, but compares closestApp rather than
+        // parentElement because pc-scene resolves its app by ancestor rather than direct child.
+        // Without this, a scene re-parented mid-await would take its Scene from the app it started
+        // under while _applyGravity resolved the app it ended up under, splitting the two.
+        if (!this.isConnected || this.closestApp !== appElement) {
+            return;
+        }
 
-        this._scene = this.closestApp!.app!.scene;
+        // The application is gone if the tree was torn down while we awaited readiness. There is
+        // nothing to configure and nothing the author can act on, so this stays silent.
+        const app = appElement.app;
+        if (!app) {
+            return;
+        }
+
+        this._scene = app.scene;
         this.updateSceneSettings();
 
         this._onReady();
     }
 
     updateSceneSettings() {
-        if (this.scene) {
-            this.scene.fog.type = this._fog;
-            this.scene.fog.color = this._fogColor;
-            this.scene.fog.density = this._fogDensity;
-            this.scene.fog.start = this._fogStart;
-            this.scene.fog.end = this._fogEnd;
-
-            const appElement = this.parentElement as AppElement;
-            appElement.app!.systems.rigidbody!.gravity.copy(this._gravity);
+        if (this._scene) {
+            this._scene.fog.type = this._fog;
+            this._scene.fog.color = this._fogColor;
+            this._scene.fog.density = this._fogDensity;
+            this._scene.fog.start = this._fogStart;
+            this._scene.fog.end = this._fogEnd;
+
+            this._applyGravity(this._gravity);
         }
     }
 
+    /**
+     * Applies gravity to the rigid body system. Resolved through `closestApp` rather than
+     * `parentElement` so that a `<pc-scene>` nested inside a wrapper element behaves the same as
+     * a direct child, matching how `connectedCallback` resolves the application.
+     *
+     * @param value - The gravity to apply.
+     */
+    private _applyGravity(value: Vec3) {
+        this.closestApp?.app?.systems.rigidbody?.gravity.copy(value);
+    }
+
     /**
      * Sets the fog type of the scene. Can be `none`, `linear`, `exp` or `exp2`. Defaults to
      * `none`.
@@ -176,9 +207,8 @@ class SceneElement extends AsyncElement {
      */
     set gravity(value: Vec3) {
         this._gravity = value;
-        if (this.scene) {
-            const appElement = this.parentElement as AppElement;
-            appElement.app!.systems.rigidbody!.gravity.copy(value);
+        if (this._scene) {
+            this._applyGravity(value);
         }
     }
 

package/src/sky.ts

@@ -19,7 +19,7 @@ class SkyElement extends AsyncElement {
 
     private _rotation = new Vec3();
 
-    private _level = 0;
+    private _mipLevel = 0;
 
     private _lighting = false;
 
@@ -65,7 +65,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;
     }
 
     private async _loadSkybox() {
@@ -170,25 +170,6 @@ class SkyElement extends AsyncElement {
         return this._intensity;
     }
 
-    /**
-     * Sets the mip level of the skybox.
-     * @param value - The mip level.
-     */
-    set level(value: number) {
-        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.
@@ -205,6 +186,26 @@ class SkyElement extends AsyncElement {
         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: number) {
+        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.
@@ -267,7 +268,7 @@ class SkyElement extends AsyncElement {
     }
 
     static get observedAttributes() {
-        return ['asset', 'center', 'intensity', 'level', 'lighting', 'rotation', 'scale', 'type'];
+        return ['asset', 'center', 'intensity', 'lighting', 'mip-level', 'rotation', 'scale', 'type'];
     }
 
     attributeChangedCallback(name: string, _oldValue: string | null, newValue: string | null) {
@@ -281,12 +282,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;