@playcanvas/web-components 0.1.4 → 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.0/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.0"></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
 
@@ -243,10 +275,12 @@ 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. |
 | `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. |
+| `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. |
+| `type` | The type of sky component. Can be `box`, `dome`, `infinite` or `none`. |
 
 ### pc-sound
 
@@ -270,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
@@ -282,59 +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 spinning cube):
-
-```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 - Spinning Cube</title>
-        <script type="importmap">
-            {
-                "imports": {
-                    "playcanvas": "https://esm.run/playcanvas@2.1.0"
-                }
-            }
-        </script>
-        <script type="module" src="https://cdn.jsdelivr.net/npm/@playcanvas/web-components@0.1.0/dist/pwc.mjs"></script>
-        <link rel="stylesheet" href="styles.css">
-    </head>
-    <body>
-        <pc-app>
-            <script type="module">
-                import { registerScript, Script } from 'playcanvas';
-
-                class Rotate extends Script {
-                    update(dt) {
-                        this.entity.rotate(10 * dt, 20 * dt, 30 * dt);
-                    }
-                }
-
-                registerScript(Rotate, 'rotate');
-            </script>
-            <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>
-                <!-- Cube -->
-                <pc-entity name="cube">
-                    <pc-render type="box"></pc-render>
-                    <pc-scripts>
-                        <pc-script name="rotate"></pc-script>
-                    </pc-scripts>
-                </pc-entity>
-            </pc-scene>
-        </pc-app>
-    </body>
-</html>
-```

package/dist/app.d.ts

@@ -1,14 +1,17 @@
 import { Application } from 'playcanvas';
+import { AsyncElement } from './async-element';
 /**
  * The main application element.
  */
-declare class AppElement extends HTMLElement {
+declare class AppElement extends AsyncElement {
     /**
      * The canvas element.
      */
     private _canvas;
-    private appReadyPromise;
-    private appReadyResolve;
+    private _alpha;
+    private _antialias;
+    private _depth;
+    private _stencil;
     private _highResolution;
     /**
      * The PlayCanvas application instance.
@@ -20,11 +23,59 @@ declare class AppElement extends HTMLElement {
     constructor();
     connectedCallback(): Promise<void>;
     disconnectedCallback(): void;
-    getApplication(): Promise<Application>;
     _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.
+     * @param value - The high resolution flag.
+     */
     set highResolution(value: boolean);
+    /**
+     * Gets the high resolution flag.
+     * @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/asset.d.ts

@@ -8,7 +8,6 @@ declare class AssetElement extends HTMLElement {
      * The asset that is loaded.
      */
     asset: Asset | null;
-    connectedCallback(): Promise<void>;
     disconnectedCallback(): void;
     createAsset(): void;
     destroyAsset(): void;

package/dist/async-element.d.ts

@@ -0,0 +1,23 @@
+import { AppElement } from './app';
+import { EntityElement } from './entity';
+/**
+ * Base class for all PlayCanvas web components that initialize asynchronously.
+ */
+declare class AsyncElement extends HTMLElement {
+    private _readyPromise;
+    private _readyResolve;
+    constructor();
+    get closestApp(): AppElement;
+    get closestEntity(): EntityElement;
+    /**
+     * Called when the element is fully initialized and ready.
+     * Subclasses should call this when they're ready.
+     */
+    protected _onReady(): void;
+    /**
+     * 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>;
+}
+export { AsyncElement };

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

@@ -42,6 +42,9 @@ declare class CameraComponentElement extends ComponentElement {
         rect: Vec4;
         scissorRect: Vec4;
     };
+    get xrAvailable(): boolean | null | undefined;
+    startXr(type: 'immersive-ar' | 'immersive-vr', space: 'bounded-floor' | 'local' | 'local-floor' | 'unbounded' | 'viewer'): void;
+    endXr(): void;
     /**
      * Gets the camera component.
      * @returns The camera component.

package/dist/components/component.d.ts

@@ -1,10 +1,11 @@
 import { Component } from 'playcanvas';
+import { AsyncElement } from '../async-element';
 /**
  * Represents a component in the PlayCanvas engine.
  *
  * @category Components
  */
-declare class ComponentElement extends HTMLElement {
+declare class ComponentElement extends AsyncElement {
     private _componentName;
     private _enabled;
     private _component;
@@ -14,8 +15,9 @@ declare class ComponentElement extends HTMLElement {
      */
     constructor(componentName: string);
     getInitialComponentData(): {};
+    addComponent(): Promise<void>;
+    initComponent(): void;
     connectedCallback(): Promise<void>;
-    addComponent(): void;
     disconnectedCallback(): void;
     get component(): Component | null;
     /**

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

@@ -18,7 +18,7 @@ declare class ElementComponentElement extends ComponentElement {
     private _width;
     private _wrapLines;
     constructor();
-    connectedCallback(): Promise<void>;
+    initComponent(): void;
     getInitialComponentData(): {
         anchor: Vec4;
         autoWidth: boolean;

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

@@ -1,4 +1,4 @@
-import { RenderComponent } from 'playcanvas';
+import { RenderComponent, StandardMaterial } from 'playcanvas';
 import { ComponentElement } from './component';
 /**
  * Represents a render component in the PlayCanvas engine.
@@ -11,10 +11,10 @@ declare class RenderComponentElement extends ComponentElement {
     private _receiveShadows;
     private _type;
     constructor();
-    connectedCallback(): Promise<void>;
     getInitialComponentData(): {
         type: "box" | "asset" | "capsule" | "cone" | "cylinder" | "plane" | "sphere";
         castShadows: boolean;
+        material: StandardMaterial | null | undefined;
         receiveShadows: boolean;
     };
     /**

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

@@ -24,7 +24,7 @@ declare global {
 declare class ScriptComponentElement extends ComponentElement {
     private observer;
     constructor();
-    connectedCallback(): Promise<void>;
+    initComponent(): void;
     private applyAttributes;
     private handleScriptAttributesChange;
     private handleScriptEnableChange;

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/components/sound-slot.d.ts

@@ -1,9 +1,10 @@
 import { SoundSlot } from 'playcanvas';
+import { AsyncElement } from '../async-element';
 import { SoundComponentElement } from './sound-component';
 /**
  * Represents a sound slot in the PlayCanvas engine.
  */
-declare class SoundSlotElement extends HTMLElement {
+declare class SoundSlotElement extends AsyncElement {
     private _asset;
     private _autoPlay;
     private _duration;

package/dist/entity.d.ts

@@ -1,8 +1,9 @@
 import { Entity, Vec3 } from 'playcanvas';
+import { AsyncElement } from './async-element';
 /**
  * Represents an entity in the PlayCanvas engine.
  */
-declare class EntityElement extends HTMLElement {
+declare class EntityElement extends AsyncElement {
     /**
      * Whether the entity is enabled.
      */
@@ -27,8 +28,6 @@ declare class EntityElement extends HTMLElement {
      * The tags of the entity.
      */
     private _tags;
-    private _resolveEntity;
-    private _entityReady;
     /**
      * The PlayCanvas entity instance.
      */

package/dist/index.d.ts

@@ -1,3 +1,12 @@
+/**
+ * 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
+ */
+import { AsyncElement } from './async-element';
 import { ModuleElement } from './module';
 import { AppElement } from './app';
 import { EntityElement } from './entity';
@@ -20,4 +29,4 @@ import { MaterialElement } from './material';
 import { ModelElement } from './model';
 import { SceneElement } from './scene';
 import { SkyElement } from './sky';
-export { ModuleElement, AppElement, EntityElement, AssetElement, CameraComponentElement, CollisionComponentElement, ComponentElement, ElementComponentElement, GSplatComponentElement, LightComponentElement, ListenerComponentElement, RenderComponentElement, RigidBodyComponentElement, ScreenComponentElement, ScriptComponentElement, ScriptElement, SoundComponentElement, SoundSlotElement, MaterialElement, ModelElement, SceneElement, SkyElement };
+export { AsyncElement, ModuleElement, AppElement, EntityElement, AssetElement, CameraComponentElement, CollisionComponentElement, ComponentElement, ElementComponentElement, GSplatComponentElement, LightComponentElement, ListenerComponentElement, RenderComponentElement, RigidBodyComponentElement, ScreenComponentElement, ScriptComponentElement, ScriptElement, SoundComponentElement, SoundSlotElement, MaterialElement, ModelElement, SceneElement, SkyElement };

package/dist/model.d.ts

@@ -1,7 +1,8 @@
+import { AsyncElement } from './async-element';
 /**
  * Represents a model in the PlayCanvas engine.
  */
-declare class ModelElement extends HTMLElement {
+declare class ModelElement extends AsyncElement {
     private _asset;
     connectedCallback(): Promise<void>;
     _loadModel(): void;