@playcanvas/web-components 0.1.5 → 0.1.7

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/6106ec23-30ab-4662-8370-c3b286386ce9)](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
 
@@ -73,7 +105,7 @@ The `pc-camera` tag is used to define a camera component. It must be a direct ch
 
 | 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 unspecified, `0.75,0.75,0.75,1` is used. |
+| `clear-color` | The background color of the camera. Can be a space-separated list of R, G, B, and A values or a hex color code. If unspecified, `0.75,0.75,0.75,1` is used. |
 | `clear-color-buffer` | Boolean attribute. Controls whether the camera clears the color buffer. If unspecified, the color buffer is cleared. |
 | `clear-depth-buffer` | Boolean attribute. Controls whether the camera clears the depth buffer. If unspecified, the depth buffer is cleared. |
 | `clear-stencil-buffer` | Boolean attribute. Controls whether the camera clears the stencil buffer. If unspecified, the stencil buffer is cleared. |
@@ -86,8 +118,8 @@ The `pc-camera` tag is used to define a camera component. It must be a direct ch
 | `orthographic` | Valueless attribute. If present, the camera uses an orthographic projection. If unspecified, the camera uses a perspective projection. |
 | `ortho-height` | The height of the orthographic projection. If unspecified, `10` is used. |
 | `priority` | The priority of the camera. If unspecified, `0` is used. |
-| `rect` | The viewport rectangle of the camera. Specified as a comma-separated list of X, Y, Width, and Height values. If unspecified, `0,0,1,1` is used. |
-| `scissor-rect` | The scissor rectangle of the camera. Specified as a comma-separated list of X, Y, Width, and Height values. If not specified, `0,0,1,1` is used. |
+| `rect` | The viewport rectangle of the camera. Specified as a space-separated list of X, Y, Width, and Height values. If unspecified, `0 0 1 1` is used. |
+| `scissor-rect` | The scissor rectangle of the camera. Specified as a space-separated list of X, Y, Width, and Height values. If not specified, `0 0 1 1` is used. |
 
 ### pc-collision
 
@@ -98,7 +130,7 @@ The `pc-collision` tag is used to define a collision component. It must be a dir
 | `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. |
+| `half-extents` | The half-extents of the collision component. Specified as a space-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`. |
@@ -109,13 +141,13 @@ The `pc-element` tag is used to define an element component. It must be a direct
 
 | 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. |
+| `anchor` | The anchor of the element component. Specified as a space-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. |
+| `color` | The color of the element component. Can be a space-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. |
+| `pivot` | The pivot of the element component. Specified as a space-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. |
@@ -129,10 +161,10 @@ The `pc-entity` tag is used to define an entity. It must be a direct child of `p
 | --- | --- |
 | `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. |
+| `position` | The position of the entity. Specified as a space-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 space-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 space-separated list of X, Y, and Z values. If not specified, `1 1 1` is used. |
+| `tags` | A space-separated list of tags for the entity. |
 
 ### pc-light
 
@@ -140,7 +172,7 @@ The `pc-light` tag is used to define a light component. It must be a direct chil
 
 | 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. |
+| `color` | The color of the light. Can be a space-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. |
@@ -183,10 +215,10 @@ The `pc-rigidbody` tag is used to define a rigidbody component. It must be a dir
 | 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. |
+| `angular-factor` | The angular factor of the rigidbody. Specified as a space-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. |
+| `linear-factor` | The linear factor of the rigidbody. Specified as a space-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. |
@@ -212,8 +244,8 @@ The `pc-screen` tag is used to define a screen component. It must be a direct ch
 | --- | --- |
 | `blend` | Valueless attribute. If present, the screen component blends. |
 | `priority` | The priority of the screen component. Must be an integer between `0` and `255`. If not specified, `0` is used. |
-| `reference-resolution` | The reference resolution of the screen component. Specified as a comma-separated list of Width and Height values. If not specified, `640,320` is used. |
-| `resolution` | The resolution of the screen component. Specified as a comma-separated list of Width and Height values. If not specified, `640,320` is used. |
+| `reference-resolution` | The reference resolution of the screen component. Specified as a space-separated list of Width and Height values. If not specified, `640 320` is used. |
+| `resolution` | The resolution of the screen component. Specified as a space-separated list of Width and Height values. If not specified, `640 320` is used. |
 | `scale-blend` | The scale blend of the screen component. Must be a number between `0` and `1`. If not specified, `0.5` is used. |
 | `screen-space` | Valueless attribute. If present, the screen component is in screen space. |
 
@@ -243,11 +275,11 @@ The `pc-sky` tag is used to define a sky component. It must be a direct child of
 | Attribute | Description |
 | --- | --- |
 | `asset` | A string that should match the `id` of a `pc-asset` tag that has a type of `texture`. |
-| `center` | The center of the sky. Specified as a comma-separated list of X, Y, and Z values in the range 0 to 1. If not specified, `0,0.01,0` is used. |
+| `center` | The center of the sky. Specified as a space-separated list of X, Y, and Z values in the range 0 to 1. If not specified, `0 0.01 0` is used. |
 | `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. |
-| `scale` | The scale of the sky. Specified as a comma-separated list of X, Y, and Z values. If not specified, `100,100,100` is used. |
+| `rotation` | The rotation of the sky. Specified as a space-separated list of X, Y, and Z values. If not specified, `0 0 0` is used. |
+| `scale` | The scale of the sky. Specified as a space-separated list of X, Y, and Z values. If not specified, `100 100 100` is used. |
 | `type` | The type of sky component. Can be `box`, `dome`, `infinite` or `none`. |
 
 ### pc-sound
@@ -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/colors.d.ts

@@ -0,0 +1 @@
+export declare const CSS_COLORS: Record<string, string>;

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/model.d.ts

@@ -4,8 +4,12 @@ import { AsyncElement } from './async-element';
  */
 declare class ModelElement extends AsyncElement {
     private _asset;
-    connectedCallback(): Promise<void>;
-    _loadModel(): void;
+    private _entity;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    private _instantiate;
+    private _loadModel;
+    private _unloadModel;
     /**
      * Sets the asset ID of the model.
      * @param value - The asset ID.