@playcanvas/web-components 0.1.4 → 0.1.6

package/src/async-element.ts

@@ -0,0 +1,45 @@
+import { AppElement } from './app';
+import { EntityElement } from './entity';
+
+/**
+ * Base class for all PlayCanvas web components that initialize asynchronously.
+ */
+class AsyncElement extends HTMLElement {
+    private _readyPromise: Promise<void>;
+
+    private _readyResolve!: () => void;
+
+    constructor() {
+        super();
+        this._readyPromise = new Promise<void>((resolve) => {
+            this._readyResolve = resolve;
+        });
+    }
+
+    get closestApp(): AppElement {
+        return this.parentElement?.closest('pc-app') as AppElement;
+    }
+
+    get closestEntity(): EntityElement {
+        return this.parentElement?.closest('pc-entity') as EntityElement;
+    }
+
+    /**
+     * Called when the element is fully initialized and ready.
+     * Subclasses should call this when they're ready.
+     */
+    protected _onReady() {
+        this._readyResolve();
+        this.dispatchEvent(new CustomEvent('ready'));
+    }
+
+    /**
+     * Returns a promise that resolves with this element when it's ready.
+     * @returns A promise that resolves with this element when it's ready.
+     */
+    ready(): Promise<this> {
+        return this._readyPromise.then(() => this);
+    }
+}
+
+export { AsyncElement };

package/src/components/camera-component.ts

@@ -1,4 +1,4 @@
-import { PROJECTION_ORTHOGRAPHIC, PROJECTION_PERSPECTIVE, CameraComponent, Color, Vec4 } from 'playcanvas';
+import { PROJECTION_ORTHOGRAPHIC, PROJECTION_PERSPECTIVE, CameraComponent, Color, Vec4, XRTYPE_VR } from 'playcanvas';
 
 import { ComponentElement } from './component';
 import { parseColor, parseVec4 } from '../utils';
@@ -66,6 +66,27 @@ class CameraComponentElement extends ComponentElement {
         };
     }
 
+    get xrAvailable() {
+        const xrManager = this.component?.system.app.xr;
+        return xrManager && xrManager.supported && xrManager.isAvailable(XRTYPE_VR);
+    }
+
+    startXr(type: 'immersive-ar' | 'immersive-vr', space: 'bounded-floor' | 'local' | 'local-floor' | 'unbounded' | 'viewer') {
+        if (this.component && this.xrAvailable) {
+            this.component.startXr(type, space, {
+                callback: (err: any) => {
+                    if (err) console.error(`WebXR Immersive VR failed to start: ${err.message}`);
+                }
+            });
+        }
+    }
+
+    endXr() {
+        if (this.component) {
+            this.component.endXr();
+        }
+    }
+
     /**
      * Gets the camera component.
      * @returns The camera component.

package/src/components/component.ts

@@ -1,14 +1,13 @@
 import { Component } from 'playcanvas';
 
-import { AppElement } from '../app';
-import { EntityElement } from '../entity';
+import { AsyncElement } from '../async-element';
 
 /**
  * Represents a component in the PlayCanvas engine.
  *
  * @category Components
  */
-class ComponentElement extends HTMLElement {
+class ComponentElement extends AsyncElement {
     private _componentName: string;
 
     private _enabled = true;
@@ -30,33 +29,23 @@ class ComponentElement extends HTMLElement {
         return {};
     }
 
-    async connectedCallback() {
-        const appElement = this.closest('pc-app') as AppElement | null;
-        if (!appElement) {
-            console.error(`${this.tagName.toLowerCase()} should be a descendant of pc-app`);
-            return;
+    async addComponent() {
+        const entityElement = this.closestEntity;
+        if (entityElement) {
+            await entityElement.ready();
+            // Add the component to the entity
+            const data = this.getInitialComponentData();
+            this._component = entityElement.entity!.addComponent(this._componentName, data);
         }
-
-        await appElement.getApplication();
-
-        this.addComponent();
     }
 
-    addComponent() {
-        // Access the parent pc-entity's 'entity' property
-        const entityElement = this.closest('pc-entity') as EntityElement | null;
-        if (!entityElement) {
-            console.error(`${this.tagName.toLowerCase()} should be a child of pc-entity`);
-            return;
-        }
+    initComponent() {}
 
-        if (entityElement && entityElement.entity) {
-            // Add the component to the entity
-            this._component = entityElement.entity.addComponent(
-                this._componentName,
-                this.getInitialComponentData()
-            );
-        }
+    async connectedCallback() {
+        await this.closestApp?.ready();
+        await this.addComponent();
+        this.initComponent();
+        this._onReady();
     }
 
     disconnectedCallback() {

package/src/components/element-component.ts

@@ -37,9 +37,7 @@ class ElementComponentElement extends ComponentElement {
         super('element');
     }
 
-    async connectedCallback() {
-        await super.connectedCallback();
-
+    initComponent() {
         this.component!._text._material.useFog = true;
     }
 
@@ -198,7 +196,20 @@ class ElementComponentElement extends ComponentElement {
     }
 
     static get observedAttributes() {
-        return [...super.observedAttributes, 'anchor', 'asset', 'auto-width', 'color', 'font-size', 'line-height', 'pivot', 'text', 'type', 'width', 'wrap-lines'];
+        return [
+            ...super.observedAttributes,
+            'anchor',
+            'asset',
+            'auto-width',
+            'color',
+            'font-size',
+            'line-height',
+            'pivot',
+            'text',
+            'type',
+            'width',
+            'wrap-lines'
+        ];
     }
 
     attributeChangedCallback(name: string, _oldValue: string, newValue: string) {

package/src/components/render-component.ts

@@ -21,16 +21,11 @@ class RenderComponentElement extends ComponentElement {
         super('render');
     }
 
-    async connectedCallback() {
-        await super.connectedCallback();
-
-        this.material = this._material;
-    }
-
     getInitialComponentData() {
         return {
             type: this._type,
             castShadows: this._castShadows,
+            material: MaterialElement.get(this._material),
             receiveShadows: this._receiveShadows
         };
     }

package/src/components/script-component.ts

@@ -1,8 +1,12 @@
-import { ScriptComponent, ScriptType } from 'playcanvas';
+import { ScriptComponent, Script, Vec2, Vec3, Vec4 } from 'playcanvas';
 
 import { ComponentElement } from './component';
 import { ScriptElement } from './script';
 
+const tmpV2 = new Vec2();
+const tmpV3 = new Vec3();
+const tmpV4 = new Vec4();
+
 // Add these interfaces at the top of the file, after the imports
 interface ScriptAttributesChangeEvent extends CustomEvent {
     detail: { attributes: any };
@@ -42,9 +46,7 @@ class ScriptComponentElement extends ComponentElement {
         this.addEventListener('scriptenablechange', this.handleScriptEnableChange.bind(this));
     }
 
-    async connectedCallback() {
-        await super.connectedCallback();
-
+    initComponent() {
         // Handle initial script elements
         this.querySelectorAll<ScriptElement>(':scope > pc-script').forEach((scriptElement) => {
             const scriptName = scriptElement.getAttribute('name');
@@ -55,11 +57,27 @@ class ScriptComponentElement extends ComponentElement {
         });
     }
 
-    private applyAttributes(script: ScriptType, attributes: string | null) {
+    private applyAttributes(script: any, attributes: string | null) {
         try {
             // Parse the attributes string into an object and set them on the script
             const attributesObject = attributes ? JSON.parse(attributes) : {};
-            Object.assign(script, attributesObject);
+            for (const key in attributesObject) {
+                const value = attributesObject[key];
+                if (Array.isArray(value) && script[key] instanceof Vec2) {
+                    script[key] = tmpV2.set(value[0], value[1]);
+                    continue;
+                }
+                if (Array.isArray(value) && script[key] instanceof Vec3) {
+                    script[key] = tmpV3.set(value[0], value[1], value[2]);
+                    continue;
+                }
+                if (Array.isArray(value) && script[key] instanceof Vec4) {
+                    script[key] = tmpV4.set(value[0], value[1], value[2], value[3]);
+                    continue;
+                }
+
+                script[key] = value;
+            }
         } catch (error) {
             console.error(`Error parsing attributes JSON string ${attributes}:`, error);
         }
@@ -87,7 +105,7 @@ class ScriptComponentElement extends ComponentElement {
         }
     }
 
-    private createScript(name: string, attributes: string | null): ScriptType | null {
+    private createScript(name: string, attributes: string | null): Script | null {
         if (!this.component) return null;
 
         this.component.on(`create:${name}`, (script) => {

package/src/components/sound-component.ts

@@ -8,10 +8,18 @@ import { ComponentElement } from './component';
  * @category Components
  */
 class SoundComponentElement extends ComponentElement {
+    private _distanceModel: 'exponential' | 'inverse' | 'linear' = 'linear';
+
+    private _maxDistance: number = 10000;
+
     private _pitch: number = 1;
 
     private _positional: boolean = false;
 
+    private _refDistance: number = 1;
+
+    private _rollOffFactor: number = 1;
+
     private _volume: number = 1;
 
     constructor() {
@@ -20,8 +28,12 @@ class SoundComponentElement extends ComponentElement {
 
     getInitialComponentData() {
         return {
+            distanceModel: this._distanceModel,
+            maxDistance: this._maxDistance,
             pitch: this._pitch,
             positional: this._positional,
+            refDistance: this._refDistance,
+            rollOffFactor: this._rollOffFactor,
             volume: this._volume
         };
     }
@@ -34,6 +46,44 @@ class SoundComponentElement extends ComponentElement {
         return super.component as SoundComponent | null;
     }
 
+    /**
+     * Sets which algorithm to use to reduce the volume of the sound as it moves away from the listener.
+     * @param value - The distance model.
+     */
+    set distanceModel(value: 'exponential' | 'inverse' | 'linear') {
+        this._distanceModel = value;
+        if (this.component) {
+            this.component.distanceModel = value;
+        }
+    }
+
+    /**
+     * Gets which algorithm to use to reduce the volume of the sound as it moves away from the listener.
+     * @returns The distance model.
+     */
+    get distanceModel(): 'exponential' | 'inverse' | 'linear' {
+        return this._distanceModel;
+    }
+
+    /**
+     * Sets the maximum distance from the listener at which audio falloff stops.
+     * @param value - The max distance.
+     */
+    set maxDistance(value: number) {
+        this._maxDistance = value;
+        if (this.component) {
+            this.component.maxDistance = value;
+        }
+    }
+
+    /**
+     * Gets the maximum distance from the listener at which audio falloff stops.
+     * @returns The max distance.
+     */
+    get maxDistance() {
+        return this._maxDistance;
+    }
+
     /**
      * Sets the pitch of the sound.
      * @param value - The pitch.
@@ -72,6 +122,44 @@ class SoundComponentElement extends ComponentElement {
         return this._positional;
     }
 
+    /**
+     * Sets the reference distance for reducing volume as the sound source moves further from the listener. Defaults to 1.
+     * @param value - The ref distance.
+     */
+    set refDistance(value: number) {
+        this._refDistance = value;
+        if (this.component) {
+            this.component.refDistance = value;
+        }
+    }
+
+    /**
+     * Gets the reference distance for reducing volume as the sound source moves further from the listener.
+     * @returns The ref distance.
+     */
+    get refDistance() {
+        return this._refDistance;
+    }
+
+    /**
+     * Sets the factor used in the falloff equation. Defaults to 1.
+     * @param value - The roll-off factor.
+     */
+    set rollOffFactor(value: number) {
+        this._rollOffFactor = value;
+        if (this.component) {
+            this.component.rollOffFactor = value;
+        }
+    }
+
+    /**
+     * Gets the factor used in the falloff equation.
+     * @returns The roll-off factor.
+     */
+    get rollOffFactor() {
+        return this._rollOffFactor;
+    }
+
     /**
      * Sets the volume of the sound.
      * @param value - The volume.
@@ -92,19 +180,40 @@ class SoundComponentElement extends ComponentElement {
     }
 
     static get observedAttributes() {
-        return [...super.observedAttributes, 'pitch', 'positional', 'volume'];
+        return [
+            ...super.observedAttributes,
+            'distance-model',
+            'max-distance',
+            'pitch',
+            'positional',
+            'ref-distance',
+            'roll-off-factor',
+            'volume'
+        ];
     }
 
     attributeChangedCallback(name: string, _oldValue: string, newValue: string) {
         super.attributeChangedCallback(name, _oldValue, newValue);
 
         switch (name) {
+            case 'distance-model':
+                this.distanceModel = newValue as 'exponential' | 'inverse' | 'linear';
+                break;
+            case 'max-distance':
+                this.maxDistance = parseFloat(newValue);
+                break;
             case 'pitch':
                 this.pitch = parseFloat(newValue);
                 break;
             case 'positional':
                 this.positional = this.hasAttribute('positional');
                 break;
+            case 'ref-distance':
+                this.refDistance = parseFloat(newValue);
+                break;
+            case 'roll-off-factor':
+                this.rollOffFactor = parseFloat(newValue);
+                break;
             case 'volume':
                 this.volume = parseFloat(newValue);
                 break;

package/src/components/sound-slot.ts

@@ -1,13 +1,13 @@
 import { SoundSlot } from 'playcanvas';
 
-import { AppElement } from '../app';
-import { SoundComponentElement } from './sound-component';
 import { AssetElement } from '../asset';
+import { AsyncElement } from '../async-element';
+import { SoundComponentElement } from './sound-component';
 
 /**
  * Represents a sound slot in the PlayCanvas engine.
  */
-class SoundSlotElement extends HTMLElement {
+class SoundSlotElement extends AsyncElement {
     private _asset: string = '';
 
     private _autoPlay: boolean = false;
@@ -32,13 +32,7 @@ class SoundSlotElement extends HTMLElement {
     soundSlot: SoundSlot | null = null;
 
     async connectedCallback() {
-        const appElement = this.closest('pc-app') as AppElement | null;
-        if (!appElement) {
-            console.error(`${this.tagName.toLowerCase()} should be a descendant of pc-app`);
-            return;
-        }
-
-        await appElement.getApplication();
+        await this.soundElement?.ready();
 
         const options = {
             autoPlay: this._autoPlay,
@@ -51,9 +45,12 @@ class SoundSlotElement extends HTMLElement {
         if (this._duration) {
             options.duration = this._duration;
         }
+
         this.soundSlot = this.soundElement!.component!.addSlot(this._name, options);
         this.asset = this._asset;
         this.soundSlot!.play();
+
+        this._onReady();
     }
 
     disconnectedCallback() {

package/src/entity.ts

@@ -1,12 +1,12 @@
 import { Entity, Vec3 } from 'playcanvas';
 
-import { AppElement } from './app';
+import { AsyncElement } from './async-element';
 import { parseVec3 } from './utils';
 
 /**
  * Represents an entity in the PlayCanvas engine.
  */
-class EntityElement extends HTMLElement {
+class EntityElement extends AsyncElement {
     /**
      * Whether the entity is enabled.
      */
@@ -37,38 +37,22 @@ class EntityElement extends HTMLElement {
      */
     private _tags: string[] = [];
 
-    private _resolveEntity!: (entity: Entity) => void;
-
-    private _entityReady = new Promise<Entity>((resolve) => {
-        this._resolveEntity = resolve;
-    });
-
     /**
      * The PlayCanvas entity instance.
      */
     entity: Entity | null = null;
 
     async connectedCallback() {
-        // Get the application
-        const appElement = this.closest('pc-app') as AppElement;
-        if (!appElement) {
-            console.warn(`${this.tagName} must be a child of pc-app`);
-            return;
-        }
+        const closestApp = this.closestApp;
+        if (!closestApp) return;
+
+        // Wait for the app to complete initialization
+        await closestApp.ready();
 
-        const app = await appElement.getApplication();
+        const app = closestApp.app!;
 
         // Create a new entity
         this.entity = new Entity(this._name, app);
-        this._resolveEntity(this.entity);
-
-        if (this.parentElement &&
-            this.parentElement.tagName.toLowerCase() === 'pc-entity') {
-            const parentEntity = await (this.parentElement as EntityElement)._entityReady;
-            parentEntity.addChild(this.entity);
-        } else {
-            app.root.addChild(this.entity);
-        }
 
         // Initialize from attributes
         const nameAttr = this.getAttribute('name');
@@ -82,6 +66,17 @@ class EntityElement extends HTMLElement {
         if (rotationAttr) this.rotation = parseVec3(rotationAttr);
         if (scaleAttr) this.scale = parseVec3(scaleAttr);
         if (tagsAttr) this.tags = tagsAttr.split(',').map(tag => tag.trim());
+
+        const closestEntity = this.closestEntity;
+        if (closestEntity) {
+            closestEntity.ready().then(() => {
+                closestEntity.entity!.addChild(this.entity!);
+                this._onReady();
+            });
+        } else {
+            app.root.addChild(this.entity);
+            this._onReady();
+        }
     }
 
     disconnectedCallback() {
@@ -95,11 +90,6 @@ class EntityElement extends HTMLElement {
             this.entity.destroy();
             this.entity = null;
         }
-
-        // Reset the promise for potential reconnection
-        this._entityReady = new Promise<Entity>((resolve) => {
-            this._resolveEntity = resolve;
-        });
     }
 
     /**

package/src/index.ts

@@ -1,6 +1,16 @@
+/**
+ * The Engine Web Components module provides a set of Web Components for the PlayCanvas Engine.
+ * While these components are normally instantiated in a declarative fashion using HTML, this
+ * reference covers the TypeScript/JavaScript API that allows these components to be created
+ * programmatically.
+ *
+ * @module EngineWebComponents
+ */
+
 /* eslint-disable import/order */
 
 // Note that order matters here (e.g. pc-entity must be defined before components)
+import { AsyncElement } from './async-element';
 import { ModuleElement } from './module';
 import { AppElement } from './app';
 import { EntityElement } from './entity';
@@ -25,6 +35,7 @@ import { SceneElement } from './scene';
 import { SkyElement } from './sky';
 
 export {
+    AsyncElement,
     ModuleElement,
     AppElement,
     EntityElement,

package/src/model.ts

@@ -1,27 +1,21 @@
-import { AppElement } from './app';
 import { AssetElement } from './asset';
-import { EntityElement } from './entity';
+import { AsyncElement } from './async-element';
 
 /**
  * Represents a model in the PlayCanvas engine.
  */
-class ModelElement extends HTMLElement {
+class ModelElement extends AsyncElement {
     private _asset: string = '';
 
     async connectedCallback() {
-        // Get the application
-        const appElement = this.closest('pc-app') as AppElement;
-        if (!appElement) {
-            console.warn(`${this.tagName} must be a child of pc-app`);
-            return;
-        }
-
-        await appElement.getApplication();
+        await this.closestApp?.ready();
 
         const asset = this.getAttribute('asset');
         if (asset) {
             this.asset = asset;
         }
+
+        this._onReady();
     }
 
     _loadModel() {
@@ -31,12 +25,23 @@ class ModelElement extends HTMLElement {
         }
         const entity = asset.resource.instantiateRenderEntity();
 
-        const parentEntityElement = this.closest('pc-entity') as EntityElement | null;
+        if (asset.resource.animations.length > 0) {
+            entity.addComponent('anim');
+            entity.anim.assignAnimation('animation', asset.resource.animations[0].resource);
+        }
+
+        const parentEntityElement = this.closestEntity;
         if (parentEntityElement) {
-            parentEntityElement.entity!.addChild(entity);
+            parentEntityElement.ready().then(() => {
+                parentEntityElement.entity!.addChild(entity);
+            });
         } else {
-            const appElement = this.closest('pc-app') as AppElement;
-            appElement.app!.root.addChild(entity);
+            const appElement = this.closestApp;
+            if (appElement) {
+                appElement.ready().then(() => {
+                    appElement.app!.root.addChild(entity);
+                });
+            }
         }
     }
 

package/src/module.ts

@@ -1,4 +1,4 @@
-import { WasmModule } from 'playcanvas';
+import { basisInitialize, WasmModule } from 'playcanvas';
 
 class ModuleElement extends HTMLElement {
     private loadPromise: Promise<void>;
@@ -14,15 +14,23 @@ class ModuleElement extends HTMLElement {
         const wasm = this.getAttribute('wasm')!;
         const fallback = this.getAttribute('fallback')!;
 
-        WasmModule.setConfig(name, {
-            glueUrl: glue,
-            wasmUrl: wasm,
-            fallbackUrl: fallback
-        });
-
-        await new Promise<void>((resolve) => {
-            WasmModule.getInstance(name, () => resolve());
-        });
+        if (name === 'Basis') {
+            basisInitialize({
+                glueUrl: glue,
+                wasmUrl: wasm,
+                fallbackUrl: fallback
+            });
+        } else {
+            WasmModule.setConfig(name, {
+                glueUrl: glue,
+                wasmUrl: wasm,
+                fallbackUrl: fallback
+            });
+
+            await new Promise<void>((resolve) => {
+                WasmModule.getInstance(name, () => resolve());
+            });
+        }
     }
 
     public getLoadPromise(): Promise<void> {