@playcanvas/web-components 0.1.1 → 0.1.2

package/README.md

@@ -24,7 +24,242 @@ UMD:
 <script src="https://cdn.jsdelivr.net/npm/@playcanvas/web-components@0.1.0"></script>
 ```
 
-## Example 📖
+## Tag Reference 📖
+
+Table of contents:
+
+- [pc-app](#pc-app)
+- [pc-asset](#pc-asset)
+- [pc-camera](#pc-camera)
+- [pc-collision](#pc-collision)
+- [pc-element](#pc-element)
+- [pc-entity](#pc-entity)
+- [pc-light](#pc-light)
+- [pc-listener](#pc-listener)
+- [pc-module](#pc-module)
+- [pc-render](#pc-render)
+- [pc-rigidbody](#pc-rigidbody)
+- [pc-scene](#pc-scene)
+- [pc-script](#pc-script)
+- [pc-scripts](#pc-scripts)
+- [pc-sky](#pc-sky)
+- [pc-sound](#pc-sound)
+- [pc-sounds](#pc-sounds)
+- [pc-splat](#pc-splat)
+
+### pc-app
+
+The `pc-app` tag is the root element for your PlayCanvas application. It is used to initialize the PlayCanvas application and provide a container for your scene.
+
+| Attribute | Description |
+| --- | --- |
+| `high-resolution` | Valueless attribute. If present, enables high-resolution mode. |
+
+### pc-asset
+
+The `pc-asset` tag is used to define an asset. It must be a direct child of `pc-app`.
+
+| Attribute | Description |
+| --- | --- |
+| `id` | The ID of the asset. This is used to reference the asset in scripts. |
+| `src` | The path to the asset. |
+| `preload` | Valueless attribute. If present, the asset is loaded immediately. |
+| `type` | The type of asset. If not specified, the type is inferred from the file extension. Can be: `audio`, `binary`, `css`, `container`, `gsplat`, `html`, `json`, `script`, `shader`, `text`, `texture`. |
+
+### pc-camera
+
+The `pc-camera` tag is used to define a camera component. It must be a direct child of an `pc-entity`.
+
+| Attribute | Description |
+| --- | --- |
+| `clear-color` | The background color of the camera. Can be a comma-separated list of R, G, B, and A values or a hex color code. If not specified, `1,1,1,1` is used. |
+| `far-clip` | The far clipping plane of the camera. If not specified, `1000` is used. |
+| `fov` | The field of view of the camera. If not specified, `45` is used. |
+| `near-clip` | The near clipping plane of the camera. If not specified, `0.1` is used. |
+| `orthographic` | Valueless attribute. If present, the camera uses an orthographic projection. |
+| `ortho-height` | The height of the orthographic projection. If not specified, `10` is used. |
+
+### pc-collision
+
+The `pc-collision` tag is used to define a collision component. It must be a direct child of a `pc-entity`.
+
+| Attribute | Description |
+| --- | --- |
+| `axis` | The axis of the collision component. If not specified, `1` is used (Y-axis). |
+| `convex-hull` | Valueless attribute. If present, the collision component uses a convex hull. |
+| `enabled` | Enabled state of the collision component. If not specified, `true` is used. |
+| `half-extents` | The half-extents of the collision component. Specified as a comma-separated list of X, Y, and Z values. If not specified, `0.5,0.5,0.5` is used. |
+| `height` | The height of the collision component. If not specified, `2` is used. |
+| `radius` | The radius of the collision component. If not specified, `0.5` is used. |
+| `type` | The type of collision component. Can be `box`, `capsule`, `cone`, `cylinder` or `sphere`. |
+
+### pc-element
+
+The `pc-element` tag is used to define an element component. It must be a direct child of a `pc-entity`.
+
+| Attribute | Description |
+| --- | --- |
+| `anchor` | The anchor of the element component. Specified as a comma-separated list of X, Y, Z, and W values. If not specified, `0,0,0,1` is used. |
+| `asset` | A string that should match the `id` of a `pc-asset` tag that has a type of `font`. |
+| `auto-width` | Valueless attribute. If present, the element component automatically adjusts its width. |
+| `color` | The color of the element component. Can be a comma-separated list of R, G, B, and A values or a hex color code. If not specified, `1,1,1,1` is used. |
+| `font-size` | The font size of the element component. If not specified, `16` is used. |
+| `line-height` | The line height of the element component. If not specified, `1.2` is used. |
+| `pivot` | The pivot of the element component. Specified as a comma-separated list of X and Y values. If not specified, `0.5,0.5` is used. |
+| `text` | The text of the element component. |
+| `type` | The type of element component. Can be `group`, `image` or `text`. If not specified, `group` is used. |
+| `width` | The width of the element component. If not specified, `0` is used. |
+| `wrap-lines` | Valueless attribute. If present, the element component wraps lines. |
+
+### pc-entity
+
+The `pc-entity` tag is used to define an entity. It must be a direct child of `pc-scene` or another `pc-entity`.
+
+| Attribute | Description |
+| --- | --- |
+| `enabled` | Enabled state of the entity. If not specified, `true` is used. |
+| `name` | The name of the entity. |
+| `position` | The position of the entity. Specified as a comma-separated list of X, Y, and Z values. If not specified, `0,0,0` is used. |
+| `rotation` | The rotation of the entity. Specified as a comma-separated list of X, Y, and Z Euler angles in degrees. If not specified, `0,0,0` is used. |
+| `scale` | The scale of the entity. Specified as a comma-separated list of X, Y, and Z values. If not specified, `1,1,1` is used. |
+| `tags` | A comma-separated list of tags for the entity. |
+
+### pc-light
+
+The `pc-light` tag is used to define a light component. It must be a direct child of a `pc-entity`.
+
+| Attribute | Description |
+| --- | --- |
+| `color` | The color of the light. Can be a comma-separated list of R, G, B values or a hex color code. If not specified, `1,1,1` is used. |
+| `cast-shadows` | Valueless attribute. If present, the light casts shadows. |
+| `inner-cone-angle` | The angle of the light's inner cone. If not specified, `40` is used. |
+| `intensity` | The intensity of the light. If not specified, `1` is used. |
+| `normal-offset-bias` | The bias of the light's normal offset. If not specified, `0.05` is used. |
+| `outer-cone-angle` | The angle of the light's outer cone. If not specified, `45` is used. |
+| `range` | The range of the light. If not specified, `10` is used. |
+| `shadow-bias` | The bias of the light's shadows. If not specified, `0.2` is used. |
+| `shadow-distance` | The distance at which the light's shadows are no longer rendered. If not specified, `16` is used. |
+| `type` | The type of light. Can be `directional`, `point` or `omni`. |
+
+### pc-listener
+
+The `pc-listener` tag is used to define a listener component. It must be a direct child of a `pc-entity`. It has no attributes.
+
+### pc-module
+
+The `pc-module` tag is used to define a WASM module. It must be a direct child of `pc-app`.
+
+| Attribute | Description |
+| --- | --- |
+| `name` | The name of the module. This is used to reference the module in scripts. |
+| `glue` | The path to the glue code for the module. |
+| `wasm` | The path to the WASM file for the module. |
+| `fallback` | The path to the fallback (asm.js) code for the module. |
+
+### pc-render
+
+The `pc-render` tag is used to define a render component that render a 3D primitive. It must be a direct child of a `pc-entity`.
+
+| Attribute | Description |
+| --- | --- |
+| `type` | The type of render component. Can be `box`, `capsule`, `cone`, `cylinder`, `plane` or `sphere`. |
+| `cast-shadows` | Valueless attribute. If present, the render component casts shadows. |
+| `receive-shadows` | Valueless attribute. If present, the render component receives shadows. |
+
+### pc-rigidbody
+
+The `pc-rigidbody` tag is used to define a rigidbody component. It must be a direct child of a `pc-entity`.
+
+| Attribute | Description |
+| --- | --- |
+| `angular-damping` | The angular damping of the rigidbody. If not specified, `0` is used. |
+| `angular-factor` | The angular factor of the rigidbody. Specified as a comma-separated list of X, Y, and Z values. If not specified, `1,1,1` is used. |
+| `friction` | The friction of the rigidbody. If not specified, `0.5` is used. |
+| `linear-damping` | The linear damping of the rigidbody. If not specified, `0` is used. |
+| `linear-factor` | The linear factor of the rigidbody. Specified as a comma-separated list of X, Y, and Z values. If not specified, `1,1,1` is used. |
+| `mass` | The mass of the rigidbody. If not specified, `1` is used. |
+| `restitution` | The restitution of the rigidbody. If not specified, `0` is used. |
+| `rolling-friction` | The rolling friction of the rigidbody. If not specified, `0` is used. |
+| `type` | The type of rigidbody component. Can be `static`, `kinematic` or `dynamic`. |
+
+### pc-scene
+
+The `pc-scene` tag is used to define the scene. It must be a direct child of `pc-app`.
+
+| Attribute | Description |
+| --- | --- |
+| `fog` | The type of fog to use. Can be `linear`, `exp`, or `exp2`. |
+| `fog-color` | The color of the fog. Can be a CSS color string or a hex color code. |
+| `fog-start` | The start distance of the fog. |
+| `fog-end` | The end distance of the fog. |
+| `fog-density` | The density of the fog. |
+
+### pc-script
+
+The `pc-script` tag is used to define a script. It must be a direct child of a `pc-scripts` component.
+
+| Attribute | Description |
+| --- | --- |
+| `attributes` | A JSON string of attributes for the script. |
+| `enabled` | Enabled state of the script. If not specified, `true` is used. |
+| `name` | The name of the script. |
+
+### pc-scripts
+
+The `pc-scripts` tag is used to define a scripts component. It must be a direct child of a `pc-entity`.
+
+| Attribute | Description |
+| --- | --- |
+| `enabled` | Enabled state of the scripts component. If not specified, `true` is used. |
+
+### pc-sky
+
+The `pc-sky` tag is used to define a sky component. It must be a direct child of a `pc-scene`.
+
+| Attribute | Description |
+| --- | --- |
+| `asset` | A string that should match the `id` of a `pc-asset` tag that has a type of `texture`. |
+| `intensity` | The intensity of the sky. If not specified, `1` is used. |
+| `level` | The mipmap level used to render the sky. If not specified, `0` is used (base mip level). |
+| `rotation` | The rotation of the sky. Specified as a comma-separated list of X, Y, and Z values. If not specified, `0,0,0` is used. |
+| `solid-color` | Valueless attribute. If present, the skybox itself is not rendered but is still used for environment lighting. |
+
+### pc-sound
+
+The `pc-sound` tag is used to define a sound. It must be a direct child of a `pc-sounds`.
+
+| Attribute | Description |
+| --- | --- |
+| `asset` | A string that should match the `id` of a `pc-asset` tag that has a type of `audio`. |
+| `auto-play` | Valueless attribute. If present, the sound slot plays automatically. |
+| `duration` | The duration of the sound slot. |
+| `loop` | Valueless attribute. If present, the sound slot loops. |
+| `name` | The name of the sound slot. |
+| `overlap` | Valueless attribute. If present, the sound slot overlaps. |
+| `pitch` | The pitch of the sound slot. If not specified, `1` is used. |
+| `start-time` | The start time of the sound slot. If not specified, `0` is used. |
+| `volume` | The volume of the sound slot. If not specified, `1` is used. |
+
+### pc-sounds
+
+The `pc-sounds` tag is used to define a sound component. It must be a direct child of a `pc-entity`.
+
+| Attribute | Description |
+| --- | --- |
+| `pitch` | The pitch of the sound. If not specified, `1` is used. |
+| `positional` | Valueless attribute. If present, the sound is positional. |
+| `volume` | The volume of the sound. If not specified, `1` is used. |
+
+### pc-splat
+
+The `pc-splat` tag is used to define a splat component. It must be a direct child of a `pc-entity`.
+
+| Attribute | Description |
+| --- | --- |
+| `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 spinning cube):
 

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

@@ -1,12 +1,37 @@
 import { ScriptComponent } from 'playcanvas';
 import { ComponentElement } from './component';
+interface ScriptAttributesChangeEvent extends CustomEvent {
+    detail: {
+        attributes: any;
+    };
+}
+interface ScriptEnableChangeEvent extends CustomEvent {
+    detail: {
+        enabled: boolean;
+    };
+}
+declare global {
+    interface HTMLElementEventMap {
+        'scriptattributeschange': ScriptAttributesChangeEvent;
+        'scriptenablechange': ScriptEnableChangeEvent;
+    }
+}
 /**
  * Represents a script component in the PlayCanvas engine.
  *
  * @category Components
  */
 declare class ScriptComponentElement extends ComponentElement {
+    private observer;
     constructor();
+    connectedCallback(): Promise<void>;
+    private applyAttributes;
+    private handleScriptAttributesChange;
+    private handleScriptEnableChange;
+    private createScript;
+    private destroyScript;
+    private handleMutations;
+    disconnectedCallback(): void;
     /**
      * Gets the script component.
      * @returns The script component.

package/dist/components/script.d.ts

@@ -1,4 +1,3 @@
-import { ScriptComponentElement } from './script-component';
 /**
  * Represents a script in the PlayCanvas engine.
  */
@@ -6,13 +5,20 @@ declare class ScriptElement extends HTMLElement {
     private _attributes;
     private _enabled;
     private _name;
-    private _script;
-    connectedCallback(): Promise<void>;
-    disconnectedCallback(): void;
-    refreshAttributes(): void;
-    protected get scriptsElement(): ScriptComponentElement | null;
+    /**
+     * Sets the attributes of the script.
+     * @param value - The attributes of the script.
+     */
     set scriptAttributes(value: string);
+    /**
+     * Gets the attributes of the script.
+     * @returns The attributes of the script.
+     */
     get scriptAttributes(): string;
+    /**
+     * Sets the enabled state of the script.
+     * @param value - The enabled state of the script.
+     */
     set enabled(value: boolean);
     /**
      * Gets the enabled state of the script.

package/dist/pwc.cjs

@@ -1665,6 +1665,96 @@ customElements.define('pc-rigidbody', RigidBodyComponentElement);
 class ScriptComponentElement extends ComponentElement {
     constructor() {
         super('script');
+        // Create mutation observer to watch for child script elements
+        this.observer = new MutationObserver(this.handleMutations.bind(this));
+        this.observer.observe(this, {
+            childList: true
+        });
+        // Listen for script attribute and enable changes
+        this.addEventListener('scriptattributeschange', this.handleScriptAttributesChange.bind(this));
+        this.addEventListener('scriptenablechange', this.handleScriptEnableChange.bind(this));
+    }
+    async connectedCallback() {
+        await super.connectedCallback();
+        // Handle initial script elements
+        this.querySelectorAll(':scope > pc-script').forEach((scriptElement) => {
+            const scriptName = scriptElement.getAttribute('name');
+            const attributes = scriptElement.getAttribute('attributes');
+            if (scriptName) {
+                this.createScript(scriptName, attributes);
+            }
+        });
+    }
+    applyAttributes(script, attributes) {
+        try {
+            // Parse the attributes string into an object and set them on the script
+            const attributesObject = attributes ? JSON.parse(attributes) : {};
+            Object.assign(script, attributesObject);
+        }
+        catch (error) {
+            console.error(`Error parsing attributes JSON string ${attributes}:`, error);
+        }
+    }
+    handleScriptAttributesChange(event) {
+        const scriptElement = event.target;
+        const scriptName = scriptElement.getAttribute('name');
+        if (!scriptName || !this.component)
+            return;
+        const script = this.component.get(scriptName);
+        if (script) {
+            this.applyAttributes(script, event.detail.attributes);
+        }
+    }
+    handleScriptEnableChange(event) {
+        const scriptElement = event.target;
+        const scriptName = scriptElement.getAttribute('name');
+        if (!scriptName || !this.component)
+            return;
+        const script = this.component.get(scriptName);
+        if (script) {
+            script.enabled = event.detail.enabled;
+        }
+    }
+    createScript(name, attributes) {
+        if (!this.component)
+            return null;
+        this.component.on(`create:${name}`, (script) => {
+            this.applyAttributes(script, attributes);
+        });
+        return this.component.create(name);
+    }
+    destroyScript(name) {
+        if (!this.component)
+            return;
+        this.component.destroy(name);
+    }
+    handleMutations(mutations) {
+        for (const mutation of mutations) {
+            // Handle added nodes
+            mutation.addedNodes.forEach((node) => {
+                if (node instanceof HTMLElement && node.tagName.toLowerCase() === 'pc-script') {
+                    const scriptName = node.getAttribute('name');
+                    const attributes = node.getAttribute('attributes');
+                    if (scriptName) {
+                        this.createScript(scriptName, attributes);
+                    }
+                }
+            });
+            // Handle removed nodes
+            mutation.removedNodes.forEach((node) => {
+                if (node instanceof HTMLElement && node.tagName.toLowerCase() === 'pc-script') {
+                    const scriptName = node.getAttribute('name');
+                    if (scriptName) {
+                        this.destroyScript(scriptName);
+                    }
+                }
+            });
+        }
+    }
+    disconnectedCallback() {
+        var _a;
+        this.observer.disconnect();
+        (_a = super.disconnectedCallback) === null || _a === void 0 ? void 0 : _a.call(this);
     }
     /**
      * Gets the script component.
@@ -1682,67 +1772,38 @@ customElements.define('pc-scripts', ScriptComponentElement);
 class ScriptElement extends HTMLElement {
     constructor() {
         super(...arguments);
-        this._attributes = {};
+        this._attributes = '{}';
         this._enabled = true;
         this._name = '';
-        this._script = null;
-    }
-    async connectedCallback() {
-        var _a, _b, _c;
-        const appElement = this.closest('pc-app');
-        if (!appElement) {
-            console.error(`${this.tagName.toLowerCase()} should be a descendant of pc-app`);
-            return;
-        }
-        await appElement.getApplication();
-        const scriptAttributes = this.getAttribute('attributes');
-        if (scriptAttributes) {
-            try {
-                this._attributes = JSON.parse(scriptAttributes);
-            }
-            catch (e) {
-                console.error('Failed to parse script attributes:', e);
-            }
-        }
-        // When the script is created, initialize it with the necessary attributes
-        (_a = this.scriptsElement) === null || _a === void 0 ? void 0 : _a.component.on(`create:${this._name}`, (scriptInstance) => {
-            Object.assign(scriptInstance, this._attributes);
-        });
-        this._script = (_c = (_b = this.scriptsElement) === null || _b === void 0 ? void 0 : _b.component.create(this._name, { preloading: false })) !== null && _c !== void 0 ? _c : null;
-    }
-    disconnectedCallback() {
-        var _a;
-        (_a = this.scriptsElement) === null || _a === void 0 ? void 0 : _a.component.destroy(this._name);
-    }
-    refreshAttributes() {
-        if (this._script) {
-            Object.entries(this._attributes).forEach(([name, value]) => {
-                if (this._script && name in this._script) {
-                    this._script[name] = value;
-                }
-            });
-        }
-    }
-    get scriptsElement() {
-        const scriptsElement = this.parentElement;
-        if (!(scriptsElement instanceof ScriptComponentElement)) {
-            console.warn('pc-script must be a direct child of a pc-scripts element');
-            return null;
-        }
-        return scriptsElement;
     }
+    /**
+     * Sets the attributes of the script.
+     * @param value - The attributes of the script.
+     */
     set scriptAttributes(value) {
-        this._attributes = JSON.parse(value);
-        this.refreshAttributes();
+        this._attributes = value;
+        this.dispatchEvent(new CustomEvent('scriptattributeschange', {
+            detail: { attributes: value },
+            bubbles: true
+        }));
     }
+    /**
+     * Gets the attributes of the script.
+     * @returns The attributes of the script.
+     */
     get scriptAttributes() {
-        return JSON.stringify(this._attributes);
+        return this._attributes;
     }
+    /**
+     * Sets the enabled state of the script.
+     * @param value - The enabled state of the script.
+     */
     set enabled(value) {
         this._enabled = value;
-        if (this._script) {
-            this._script.enabled = value;
-        }
+        this.dispatchEvent(new CustomEvent('scriptenablechange', {
+            detail: { enabled: value },
+            bubbles: true
+        }));
     }
     /**
      * Gets the enabled state of the script.
@@ -1879,7 +1940,7 @@ class SoundComponentElement extends ComponentElement {
         }
     }
 }
-customElements.define('pc-sound', SoundComponentElement);
+customElements.define('pc-sounds', SoundComponentElement);
 
 /**
  * Represents a sound slot in the PlayCanvas engine.
@@ -2127,7 +2188,7 @@ class SoundSlotElement extends HTMLElement {
         }
     }
 }
-customElements.define('pc-sound-slot', SoundSlotElement);
+customElements.define('pc-sound', SoundSlotElement);
 
 /**
  * Represents a model in the PlayCanvas engine.