@playcanvas/web-components 0.1.9 → 0.1.11

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2024 PlayCanvas
+Copyright (c) 2011-2025 PlayCanvas
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -5,6 +5,8 @@
 [![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)
 
+| [Examples](https://playcanvas.github.io/web-components/examples) | [API Reference](https://api.playcanvas.com/modules/EngineWebComponents.html) | [Forum](https://forum.playcanvas.com/) | [Discord](https://discord.gg/RSaMRzg) |
+
 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
@@ -32,24 +34,53 @@ See PlayCanvas Web Components in action here: https://playcanvas.github.io/web-c
 
 ## Usage 🚧
 
-If you are using a bundler (e.g. Rollup), you can install PlayCanvas Web Components and the PlayCanvas Engine using NPM:
+### Installing from NPM
+
+PlayCanvas Web Components is available as a package on [NPM](https://www.npmjs.com/package/@playcanvas/web-components). 
+You can install it (and the PlayCanvas Engine) as follows:
 
 ```bash
 npm install playcanvas @playcanvas/web-components --save-dev
 ```
 
-Or you can include it directly in your HTML file from a CDN.
+Next, in your HTML file, you will need an import map because the web components need to be able to find the PlayCanvas Engine (which is an external dependency):
+
+```html
+<script type="importmap">
+    {
+        "imports": {
+            "playcanvas": "/node_modules/playcanvas/build/playcanvas.mjs"
+        }
+    }
+</script>
+```
+
+You can then import the components as follows:
+
+```html
+<script type="module" src="/node_modules/@playcanvas/web-components/dist/pwc.mjs"></script>
+```
+
+You can now incorporate any of the PlayCanvas Web Components elements into your HTML!
+
+### Using a CDN
 
-ES Modules:
+Instead of loading the library from a local package, you can instead opt to load it from a CDN (such as jsDelivr). In this case, you would update the import map:
 
 ```html
-<script type="module" src="https://cdn.jsdelivr.net/npm/@playcanvas/web-components@0.1.5/dist/pwc.mjs"></script>
+<script type="importmap">
+    {
+        "imports": {
+            "playcanvas": "https://cdn.jsdelivr.net/npm/playcanvas@2.3.3/build/playcanvas.mjs"
+        }
+    }
+</script>
 ```
 
-UMD:
+And the components would now be imported as follows:
 
 ```html
-<script src="https://cdn.jsdelivr.net/npm/@playcanvas/web-components@0.1.5"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@playcanvas/web-components@0.1.10/dist/pwc.mjs"></script>
 ```
 
 ## Tag Reference 📖
@@ -114,6 +145,7 @@ The `pc-camera` tag is used to define a camera component. It must be a direct ch
 | `flip-faces` | Boolean attribute. Controls whether the camera flips faces. If unspecified, faces are not flipped. |
 | `fov` | The field of view of the camera. If unspecified, `45` is used. |
 | `frustum-culling` | Boolean attribute. Controls whether the camera uses frustum culling. If unspecified, frustum culling is used. |
+| `horizontal-fov` | Valueless attribute. If present, the camera uses a horizontal field of view. If unspecified, the camera uses a vertical field of view. |
 | `near-clip` | The near clipping plane of the camera. If unspecified, `0.1` is used. |
 | `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. |

package/dist/app.d.ts

@@ -14,6 +14,10 @@ declare class AppElement extends AsyncElement {
     private _stencil;
     private _highResolution;
     private _hierarchyReady;
+    private _picker;
+    private _hasPointerListeners;
+    private _hoveredEntity;
+    private _pointerHandlers;
     /**
      * The PlayCanvas application instance.
      */
@@ -27,6 +31,13 @@ declare class AppElement extends AsyncElement {
     connectedCallback(): Promise<void>;
     disconnectedCallback(): void;
     _onWindowResize(): void;
+    _pickerCreate(): void;
+    _pickerDestroy(): void;
+    _onPointerMove(event: PointerEvent): void;
+    _onPointerDown(event: PointerEvent): void;
+    _onPointerUp(event: PointerEvent): void;
+    _onPointerListenerAdded(type: string): void;
+    _onPointerListenerRemoved(type: string): void;
     /**
      * Sets the alpha flag.
      * @param value - The alpha flag.

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

@@ -17,12 +17,15 @@ declare class CameraComponentElement extends ComponentElement {
     private _flipFaces;
     private _fov;
     private _frustumCulling;
+    private _gamma;
+    private _horizontalFov;
     private _nearClip;
     private _orthographic;
     private _orthoHeight;
     private _priority;
     private _rect;
     private _scissorRect;
+    private _tonemap;
     /** @ignore */
     constructor();
     getInitialComponentData(): {
@@ -35,12 +38,15 @@ declare class CameraComponentElement extends ComponentElement {
         flipFaces: boolean;
         fov: number;
         frustumCulling: boolean;
+        gammaCorrection: number;
+        horizontalFov: boolean;
         nearClip: number;
         orthographic: boolean;
         orthoHeight: number;
         priority: number;
         rect: Vec4;
         scissorRect: Vec4;
+        toneMapping: number | undefined;
     };
     get xrAvailable(): boolean | null | undefined;
     startXr(type: 'immersive-ar' | 'immersive-vr', space: 'bounded-floor' | 'local' | 'local-floor' | 'unbounded' | 'viewer'): void;
@@ -140,6 +146,27 @@ declare class CameraComponentElement extends ComponentElement {
      * @returns The frustum culling.
      */
     get frustumCulling(): boolean;
+    /**
+     * Sets the gamma correction of the camera.
+     * @param value - The gamma correction.
+     */
+    set gamma(value: 'none' | 'srgb');
+    /**
+     * Gets the gamma correction of the camera.
+     * @returns The gamma correction.
+     */
+    get gamma(): 'none' | 'srgb';
+    /**
+     * Sets whether the camera's field of view (fov) is horizontal or vertical. Defaults to false
+     * (meaning it is vertical be default).
+     * @param value - Whether the camera's field of view is horizontal.
+     */
+    set horizontalFov(value: boolean);
+    /**
+     * Gets whether the camera's field of view (fov) is horizontal or vertical.
+     * @returns Whether the camera's field of view is horizontal.
+     */
+    get horizontalFov(): boolean;
     /**
      * Sets the near clip distance of the camera.
      * @param value - The near clip distance.
@@ -200,6 +227,16 @@ declare class CameraComponentElement extends ComponentElement {
      * @returns The scissor rect.
      */
     get scissorRect(): Vec4;
+    /**
+     * Sets the tone mapping of the camera.
+     * @param value - The tone mapping.
+     */
+    set tonemap(value: 'none' | 'linear' | 'filmic' | 'hejl' | 'aces' | 'aces2' | 'neutral');
+    /**
+     * Gets the tone mapping of the camera.
+     * @returns The tone mapping.
+     */
+    get tonemap(): 'none' | 'linear' | 'filmic' | 'hejl' | 'aces' | 'aces2' | 'neutral';
     static get observedAttributes(): string[];
     attributeChangedCallback(name: string, _oldValue: string, newValue: string): void;
 }

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

@@ -17,8 +17,11 @@ declare class LightComponentElement extends ComponentElement {
     private _range;
     private _shadowBias;
     private _shadowDistance;
+    private _shadowIntensity;
     private _shadowResolution;
+    private _shadowType;
     private _type;
+    private _vsmBias;
     /** @ignore */
     constructor();
     getInitialComponentData(): {
@@ -31,8 +34,11 @@ declare class LightComponentElement extends ComponentElement {
         range: number;
         shadowBias: number;
         shadowDistance: number;
+        shadowIntensity: number;
         shadowResolution: number;
+        shadowType: number | undefined;
         type: string;
+        vsmBias: number;
     };
     /**
      * Gets the light component.
@@ -129,6 +135,16 @@ declare class LightComponentElement extends ComponentElement {
      * @returns The shadow distance.
      */
     get shadowDistance(): number;
+    /**
+     * Sets the shadow intensity of the light.
+     * @param value - The shadow intensity.
+     */
+    set shadowIntensity(value: number);
+    /**
+     * Gets the shadow intensity of the light.
+     * @returns The shadow intensity.
+     */
+    get shadowIntensity(): number;
     /**
      * Sets the shadow resolution of the light.
      * @param value - The shadow resolution.
@@ -139,6 +155,26 @@ declare class LightComponentElement extends ComponentElement {
      * @returns The shadow resolution.
      */
     get shadowResolution(): number;
+    /**
+     * Sets the shadow type of the light.
+     * @param value - The shadow type. Can be:
+     *
+     * - `pcf1-16f` - 1-tap percentage-closer filtered shadow map with 16-bit depth.
+     * - `pcf1-32f` - 1-tap percentage-closer filtered shadow map with 32-bit depth.
+     * - `pcf3-16f` - 3-tap percentage-closer filtered shadow map with 16-bit depth.
+     * - `pcf3-32f` - 3-tap percentage-closer filtered shadow map with 32-bit depth.
+     * - `pcf5-16f` - 5-tap percentage-closer filtered shadow map with 16-bit depth.
+     * - `pcf5-32f` - 5-tap percentage-closer filtered shadow map with 32-bit depth.
+     * - `vsm-16f` - Variance shadow map with 16-bit depth.
+     * - `vsm-32f` - Variance shadow map with 32-bit depth.
+     * - `pcss-32f` - Percentage-closer soft shadow with 32-bit depth.
+     */
+    set shadowType(value: 'pcf1-16f' | 'pcf1-32f' | 'pcf3-16f' | 'pcf3-32f' | 'pcf5-16f' | 'pcf5-32f' | 'vsm-16f' | 'vsm-32f' | 'pcss-32f');
+    /**
+     * Gets the shadow type of the light.
+     * @returns The shadow type.
+     */
+    get shadowType(): "pcf1-16f" | "pcf1-32f" | "pcf3-16f" | "pcf3-32f" | "pcf5-16f" | "pcf5-32f" | "vsm-16f" | "vsm-32f" | "pcss-32f";
     /**
      * Sets the type of the light.
      * @param value - The type.
@@ -149,6 +185,16 @@ declare class LightComponentElement extends ComponentElement {
      * @returns The type.
      */
     get type(): string;
+    /**
+     * Sets the VSM bias of the light.
+     * @param value - The VSM bias.
+     */
+    set vsmBias(value: number);
+    /**
+     * Gets the VSM bias of the light.
+     * @returns The VSM bias.
+     */
+    get vsmBias(): number;
     static get observedAttributes(): string[];
     attributeChangedCallback(name: string, _oldValue: string, newValue: string): void;
 }

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

@@ -18,7 +18,7 @@ declare class SoundComponentElement extends ComponentElement {
     /** @ignore */
     constructor();
     getInitialComponentData(): {
-        distanceModel: "exponential" | "inverse" | "linear";
+        distanceModel: "linear" | "exponential" | "inverse";
         maxDistance: number;
         pitch: number;
         positional: boolean;

package/dist/entity.d.ts

@@ -30,6 +30,10 @@ declare class EntityElement extends AsyncElement {
      * The tags of the entity.
      */
     private _tags;
+    /**
+     * The pointer event listeners for the entity.
+     */
+    private _listeners;
     /**
      * The PlayCanvas entity instance.
      */
@@ -100,5 +104,8 @@ declare class EntityElement extends AsyncElement {
     get tags(): string[];
     static get observedAttributes(): string[];
     attributeChangedCallback(name: string, _oldValue: string, newValue: string): void;
+    addEventListener(type: string, listener: EventListener, options?: boolean | AddEventListenerOptions): void;
+    removeEventListener(type: string, listener: EventListener, options?: boolean | EventListenerOptions): void;
+    hasListeners(type: string): boolean;
 }
 export { EntityElement };

package/dist/fog.d.ts

@@ -0,0 +1,28 @@
+import { Color } from 'playcanvas';
+/**
+ * The FogElement interface provides properties and methods for manipulating
+ * `<pc-fog>` elements. The FogElement interface also inherits the properties and
+ * methods of the {@link HTMLElement} interface.
+ */
+declare class FogElement extends HTMLElement {
+    private _color;
+    private _density;
+    private _end;
+    private _start;
+    private _type;
+    private dispatchFogUpdate;
+    set color(value: Color);
+    get color(): Color;
+    set density(value: number);
+    get density(): number;
+    set end(value: number);
+    get end(): number;
+    set start(value: number);
+    get start(): number;
+    set type(value: 'linear' | 'exp' | 'exp2');
+    get type(): 'linear' | 'exp' | 'exp2';
+    static get observedAttributes(): string[];
+    attributeChangedCallback(name: string, _oldValue: string, newValue: string): void;
+    constructor();
+}
+export { FogElement };