@playcanvas/web-components 0.1.5 → 0.1.6

package/README.md

@@ -1,6 +1,34 @@
 # PlayCanvas Web Components
 
-Unleash the power of PlayCanvas in your HTML. PlayCanvas Web Components allows you to write PlayCanvas scenes using only HTML, enabling a clear and concise structure, and making it easier than ever to integrate with other web technologies. Just add tags for entities, components, and assets, and watch your 3D scene come to life!
+[![NPM Version](https://img.shields.io/npm/v/@playcanvas/web-components.svg)](https://www.npmjs.com/package/@playcanvas/web-components)
+[![NPM Downloads](https://img.shields.io/npm/dw/@playcanvas/web-components)](https://npmtrends.com/@playcanvas/web-components)
+[![License](https://img.shields.io/npm/l/@playcanvas/web-components.svg)](https://github.com/playcanvas/web-components/blob/main/LICENSE)
+[![GitHub Actions Build Status](https://github.com/playcanvas/web-components/actions/workflows/deploy.yml/badge.svg)](https://github.com/playcanvas/web-components/actions/workflows/deploy.yml)
+
+PlayCanvas Web Components are a set of custom HTML elements for building 3D interactive web apps. Using the declarative nature of HTML makes it both easy and fun to incorporate 3D into your website.
+
+```html
+<!-- A lit sphere -->
+<pc-app>
+    <pc-scene>
+        <pc-entity name="camera" position="0,0,3">
+            <pc-camera></pc-camera>
+        </pc-entity>
+        <pc-entity name="light" rotation="45,45,0">
+            <pc-light></pc-light>
+        </pc-entity>
+        <pc-entity name="ball">
+            <pc-render type="sphere"></pc-render>
+        </pc-entity>
+    </pc-scene>
+</pc-app>
+```
+
+## Examples
+
+[![image](https://github.com/user-attachments/assets/4b708711-4ac1-4908-a254-cf89c2e206ce)](https://playcanvas.github.io/web-components/examples)
+
+See PlayCanvas Web Components in action here: https://playcanvas.github.io/web-components/examples
 
 ## Usage 🚧
 
@@ -15,13 +43,13 @@ Or you can include it directly in your HTML file from a CDN.
 ES Modules:
 
 ```html
-<script type="module" src="https://cdn.jsdelivr.net/npm/@playcanvas/web-components@0.1.4/dist/pwc.mjs"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@playcanvas/web-components@0.1.5/dist/pwc.mjs"></script>
 ```
 
 UMD:
 
 ```html
-<script src="https://cdn.jsdelivr.net/npm/@playcanvas/web-components@0.1.4"></script>
+<script src="https://cdn.jsdelivr.net/npm/@playcanvas/web-components@0.1.5"></script>
 ```
 
 ## Tag Reference 📖
@@ -54,7 +82,11 @@ The `pc-app` tag is the root element for your PlayCanvas application. It is used
 
 | Attribute | Description |
 | --- | --- |
-| `high-resolution` | Valueless attribute. If present, enables high-resolution mode. |
+| `alpha` | Boolean attribute. Determines whether the application allocates an alpha channel in the frame buffer. Defaults to `true`. |
+| `antialias` | Boolean attribute. Determines whether the application uses anti-aliasing. Defaults to `true`. |
+| `depth` | Boolean attribute. Determines whether the application allocates a depth buffer. Defaults to `true`. |
+| `high-resolution` | Boolean attribute. Determines whether the application renders using physical resolution or CSS resolution. Defaults to `true`. |
+| `stencil` | Boolean attribute. Determines whether the application allocates a stencil buffer. Defaults to `true`. |
 
 ### pc-asset
 
@@ -272,8 +304,12 @@ The `pc-sounds` tag is used to define a sound component. It must be a direct chi
 
 | Attribute | Description |
 | --- | --- |
+| `distance-model` | The distance model of the sound. Can be `exponential`, `inverse` or `linear`. If not specified, `linear` is used. |
 | `pitch` | The pitch of the sound. If not specified, `1` is used. |
+| `max-distance` | The maximum distance from the listener at which audio falloff stops. If not specified, `10000` is used. |
 | `positional` | Valueless attribute. If present, the sound is positional. |
+| `ref-distance` | The distance from the listener at which the volume will be at full volume. If not specified, `1` is used. |
+| `roll-off-factor` | The factor used in the falloff equation. If not specified, `1` is used. |
 | `volume` | The volume of the sound. If not specified, `1` is used. |
 
 ### pc-splat
@@ -284,45 +320,3 @@ The `pc-splat` tag is used to define a splat component. It must be a direct chil
 | --- | --- |
 | `asset` | A string that should match the `id` of a `pc-asset` tag that has a type of `gsplat`. |
 | `enabled` | Enabled state of the splat component. If not specified, `true` is used. |
-
-## Example 
-
-Below is a basic example of how to use PlayCanvas Web Components to create a simple 3D scene (a humble sphere):
-
-```html
-<!DOCTYPE html>
-<html lang="en">
-    <head>
-        <meta charset="UTF-8">
-        <meta name="viewport" content="width=device-width, initial-scale=1.0">
-        <title>PlayCanvas Web Components - Sphere</title>
-        <script type="importmap">
-            {
-                "imports": {
-                    "playcanvas": "https://esm.run/playcanvas@2.2.2"
-                }
-            }
-        </script>
-        <script type="module" src="https://cdn.jsdelivr.net/npm/@playcanvas/web-components@0.1.4/dist/pwc.mjs"></script>
-        <link rel="stylesheet" href="styles.css">
-    </head>
-    <body>
-        <pc-app>
-            <pc-scene>
-                <!-- Camera -->
-                <pc-entity name="camera" position="0,0,3">
-                    <pc-camera clear-color="#8099e6"></pc-camera>
-                </pc-entity>
-                <!-- Light -->
-                <pc-entity name="light" rotation="45,0,0">
-                    <pc-light></pc-light>
-                </pc-entity>
-                <!-- Sphere -->
-                <pc-entity name="sphere">
-                    <pc-render type="sphere"></pc-render>
-                </pc-entity>
-            </pc-scene>
-        </pc-app>
-    </body>
-</html>
-```

package/dist/app.d.ts

@@ -8,6 +8,10 @@ declare class AppElement extends AsyncElement {
      * The canvas element.
      */
     private _canvas;
+    private _alpha;
+    private _antialias;
+    private _depth;
+    private _stencil;
     private _highResolution;
     /**
      * The PlayCanvas application instance.
@@ -20,6 +24,36 @@ declare class AppElement extends AsyncElement {
     connectedCallback(): Promise<void>;
     disconnectedCallback(): void;
     _onWindowResize(): void;
+    /**
+     * Sets the alpha flag.
+     * @param value - The alpha flag.
+     */
+    set alpha(value: boolean);
+    /**
+     * Gets the alpha flag.
+     * @returns The alpha flag.
+     */
+    get alpha(): boolean;
+    /**
+     * Sets the antialias flag.
+     * @param value - The antialias flag.
+     */
+    set antialias(value: boolean);
+    /**
+     * Gets the antialias flag.
+     * @returns The antialias flag.
+     */
+    get antialias(): boolean;
+    /**
+     * Sets the depth flag.
+     * @param value - The depth flag.
+     */
+    set depth(value: boolean);
+    /**
+     * Gets the depth flag.
+     * @returns The depth flag.
+     */
+    get depth(): boolean;
     /**
      * 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.
@@ -31,7 +65,17 @@ declare class AppElement extends AsyncElement {
      * @returns The high resolution flag.
      */
     get highResolution(): boolean;
+    /**
+     * Sets the stencil flag.
+     * @param value - The stencil flag.
+     */
+    set stencil(value: boolean);
+    /**
+     * Gets the stencil flag.
+     * @returns The stencil flag.
+     */
+    get stencil(): boolean;
     static get observedAttributes(): string[];
-    attributeChangedCallback(name: string, _oldValue: string, _newValue: string): void;
+    attributeChangedCallback(name: string, _oldValue: string, newValue: string): void;
 }
 export { AppElement };

package/dist/components/sound-component.d.ts

@@ -6,13 +6,21 @@ import { ComponentElement } from './component';
  * @category Components
  */
 declare class SoundComponentElement extends ComponentElement {
+    private _distanceModel;
+    private _maxDistance;
     private _pitch;
     private _positional;
+    private _refDistance;
+    private _rollOffFactor;
     private _volume;
     constructor();
     getInitialComponentData(): {
+        distanceModel: "exponential" | "inverse" | "linear";
+        maxDistance: number;
         pitch: number;
         positional: boolean;
+        refDistance: number;
+        rollOffFactor: number;
         volume: number;
     };
     /**
@@ -20,6 +28,26 @@ declare class SoundComponentElement extends ComponentElement {
      * @returns The sound component.
      */
     get component(): 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');
+    /**
+     * 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';
+    /**
+     * Sets the maximum distance from the listener at which audio falloff stops.
+     * @param value - The max distance.
+     */
+    set maxDistance(value: number);
+    /**
+     * Gets the maximum distance from the listener at which audio falloff stops.
+     * @returns The max distance.
+     */
+    get maxDistance(): number;
     /**
      * Sets the pitch of the sound.
      * @param value - The pitch.
@@ -40,6 +68,26 @@ declare class SoundComponentElement extends ComponentElement {
      * @returns The positional flag.
      */
     get positional(): boolean;
+    /**
+     * 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);
+    /**
+     * Gets the reference distance for reducing volume as the sound source moves further from the listener.
+     * @returns The ref distance.
+     */
+    get refDistance(): number;
+    /**
+     * Sets the factor used in the falloff equation. Defaults to 1.
+     * @param value - The roll-off factor.
+     */
+    set rollOffFactor(value: number);
+    /**
+     * Gets the factor used in the falloff equation.
+     * @returns The roll-off factor.
+     */
+    get rollOffFactor(): number;
     /**
      * Sets the volume of the sound.
      * @param value - The volume.

package/dist/pwc.cjs

@@ -47,14 +47,23 @@ class ModuleElement extends HTMLElement {
         const glue = this.getAttribute('glue');
         const wasm = this.getAttribute('wasm');
         const fallback = this.getAttribute('fallback');
-        playcanvas.WasmModule.setConfig(name, {
-            glueUrl: glue,
-            wasmUrl: wasm,
-            fallbackUrl: fallback
-        });
-        await new Promise((resolve) => {
-            playcanvas.WasmModule.getInstance(name, () => resolve());
-        });
+        if (name === 'Basis') {
+            playcanvas.basisInitialize({
+                glueUrl: glue,
+                wasmUrl: wasm,
+                fallbackUrl: fallback
+            });
+        }
+        else {
+            playcanvas.WasmModule.setConfig(name, {
+                glueUrl: glue,
+                wasmUrl: wasm,
+                fallbackUrl: fallback
+            });
+            await new Promise((resolve) => {
+                playcanvas.WasmModule.getInstance(name, () => resolve());
+            });
+        }
     }
     getLoadPromise() {
         return this.loadPromise;
@@ -75,6 +84,10 @@ class AppElement extends AsyncElement {
          * The canvas element.
          */
         this._canvas = null;
+        this._alpha = true;
+        this._antialias = true;
+        this._depth = true;
+        this._stencil = true;
         this._highResolution = false;
         /**
          * The PlayCanvas application instance.
@@ -94,11 +107,15 @@ class AppElement extends AsyncElement {
         // Initialize the PlayCanvas application
         this.app = new playcanvas.Application(this._canvas, {
             graphicsDeviceOptions: {
-                devicePixelRatio: this._highResolution ? window.devicePixelRatio : 1
+                alpha: this._alpha,
+                antialias: this._antialias,
+                depth: this._depth,
+                stencil: this._stencil
             },
             keyboard: new playcanvas.Keyboard(window),
             mouse: new playcanvas.Mouse(this._canvas)
         });
+        this.app.graphicsDevice.maxPixelRatio = this._highResolution ? window.devicePixelRatio : 1;
         this.app.setCanvasFillMode(playcanvas.FILLMODE_FILL_WINDOW);
         this.app.setCanvasResolution(playcanvas.RESOLUTION_AUTO);
         // Get all pc-asset elements that are direct children of the pc-app element
@@ -143,6 +160,48 @@ class AppElement extends AsyncElement {
             this.app.resizeCanvas();
         }
     }
+    /**
+     * Sets the alpha flag.
+     * @param value - The alpha flag.
+     */
+    set alpha(value) {
+        this._alpha = value;
+    }
+    /**
+     * Gets the alpha flag.
+     * @returns The alpha flag.
+     */
+    get alpha() {
+        return this._alpha;
+    }
+    /**
+     * Sets the antialias flag.
+     * @param value - The antialias flag.
+     */
+    set antialias(value) {
+        this._antialias = value;
+    }
+    /**
+     * Gets the antialias flag.
+     * @returns The antialias flag.
+     */
+    get antialias() {
+        return this._antialias;
+    }
+    /**
+     * Sets the depth flag.
+     * @param value - The depth flag.
+     */
+    set depth(value) {
+        this._depth = value;
+    }
+    /**
+     * Gets the depth flag.
+     * @returns The depth flag.
+     */
+    get depth() {
+        return this._depth;
+    }
     /**
      * 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.
@@ -161,13 +220,39 @@ class AppElement extends AsyncElement {
     get highResolution() {
         return this._highResolution;
     }
+    /**
+     * Sets the stencil flag.
+     * @param value - The stencil flag.
+     */
+    set stencil(value) {
+        this._stencil = value;
+    }
+    /**
+     * Gets the stencil flag.
+     * @returns The stencil flag.
+     */
+    get stencil() {
+        return this._stencil;
+    }
     static get observedAttributes() {
-        return ['high-resolution'];
+        return ['alpha', 'antialias', 'depth', 'stencil', 'high-resolution'];
     }
-    attributeChangedCallback(name, _oldValue, _newValue) {
+    attributeChangedCallback(name, _oldValue, newValue) {
         switch (name) {
+            case 'alpha':
+                this.alpha = newValue !== 'false';
+                break;
+            case 'antialias':
+                this.antialias = newValue !== 'false';
+                break;
+            case 'depth':
+                this.depth = newValue !== 'false';
+                break;
             case 'high-resolution':
-                this.highResolution = this.hasAttribute(name);
+                this.highResolution = newValue !== 'false';
+                break;
+            case 'stencil':
+                this.stencil = newValue !== 'false';
                 break;
         }
     }
@@ -2245,6 +2330,9 @@ class ScreenComponentElement extends ComponentElement {
 }
 customElements.define('pc-screen', ScreenComponentElement);
 
+const tmpV2 = new playcanvas.Vec2();
+const tmpV3 = new playcanvas.Vec3();
+const tmpV4 = new playcanvas.Vec4();
 /**
  * Represents a script component in the PlayCanvas engine.
  *
@@ -2276,7 +2364,22 @@ class ScriptComponentElement extends ComponentElement {
         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 playcanvas.Vec2) {
+                    script[key] = tmpV2.set(value[0], value[1]);
+                    continue;
+                }
+                if (Array.isArray(value) && script[key] instanceof playcanvas.Vec3) {
+                    script[key] = tmpV3.set(value[0], value[1], value[2]);
+                    continue;
+                }
+                if (Array.isArray(value) && script[key] instanceof playcanvas.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);
@@ -2440,14 +2543,22 @@ customElements.define('pc-script', ScriptElement);
 class SoundComponentElement extends ComponentElement {
     constructor() {
         super('sound');
+        this._distanceModel = 'linear';
+        this._maxDistance = 10000;
         this._pitch = 1;
         this._positional = false;
+        this._refDistance = 1;
+        this._rollOffFactor = 1;
         this._volume = 1;
     }
     getInitialComponentData() {
         return {
+            distanceModel: this._distanceModel,
+            maxDistance: this._maxDistance,
             pitch: this._pitch,
             positional: this._positional,
+            refDistance: this._refDistance,
+            rollOffFactor: this._rollOffFactor,
             volume: this._volume
         };
     }
@@ -2458,6 +2569,40 @@ class SoundComponentElement extends ComponentElement {
     get component() {
         return super.component;
     }
+    /**
+     * 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) {
+        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() {
+        return this._distanceModel;
+    }
+    /**
+     * Sets the maximum distance from the listener at which audio falloff stops.
+     * @param value - The max distance.
+     */
+    set maxDistance(value) {
+        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.
@@ -2492,6 +2637,40 @@ class SoundComponentElement extends ComponentElement {
     get positional() {
         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) {
+        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) {
+        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.
@@ -2510,17 +2689,38 @@ class SoundComponentElement extends ComponentElement {
         return this._volume;
     }
     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, _oldValue, newValue) {
         super.attributeChangedCallback(name, _oldValue, newValue);
         switch (name) {
+            case 'distance-model':
+                this.distanceModel = newValue;
+                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;