@playcanvas/web-components 0.1.10 → 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.9/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.9"></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/components/camera-component.d.ts

@@ -18,6 +18,7 @@ declare class CameraComponentElement extends ComponentElement {
     private _fov;
     private _frustumCulling;
     private _gamma;
+    private _horizontalFov;
     private _nearClip;
     private _orthographic;
     private _orthoHeight;
@@ -38,6 +39,7 @@ declare class CameraComponentElement extends ComponentElement {
         fov: number;
         frustumCulling: boolean;
         gammaCorrection: number;
+        horizontalFov: boolean;
         nearClip: number;
         orthographic: boolean;
         orthoHeight: number;
@@ -154,6 +156,17 @@ declare class CameraComponentElement extends ComponentElement {
      * @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.

package/dist/pwc.cjs

@@ -15,11 +15,11 @@ class AsyncElement extends HTMLElement {
     }
     get closestApp() {
         var _a;
-        return (_a = this.parentElement) === null || _a === void 0 ? void 0 : _a.closest('pc-app');
+        return (_a = this.parentElement) === null || _a === undefined ? undefined : _a.closest('pc-app');
     }
     get closestEntity() {
         var _a;
-        return (_a = this.parentElement) === null || _a === void 0 ? void 0 : _a.closest('pc-entity');
+        return (_a = this.parentElement) === null || _a === undefined ? undefined : _a.closest('pc-entity');
     }
     /**
      * Called when the element is fully initialized and ready.
@@ -742,7 +742,7 @@ class EntityElement extends AsyncElement {
         if (!this.entity)
             return;
         const closestEntity = this.closestEntity;
-        if (closestEntity === null || closestEntity === void 0 ? void 0 : closestEntity.entity) {
+        if (closestEntity === null || closestEntity === undefined ? undefined : closestEntity.entity) {
             closestEntity.entity.addChild(this.entity);
         }
         else {
@@ -964,7 +964,7 @@ class EntityElement extends AsyncElement {
     }
     hasListeners(type) {
         var _a;
-        return Boolean((_a = this._listeners[type]) === null || _a === void 0 ? void 0 : _a.length);
+        return Boolean((_a = this._listeners[type]) === null || _a === undefined ? undefined : _a.length);
     }
 }
 customElements.define('pc-entity', EntityElement);
@@ -1013,7 +1013,7 @@ class AssetElement extends HTMLElement {
         // If no type is specified, try to infer it from the file extension.
         if (!type) {
             const ext = src.split('.').pop();
-            type = (_a = extToType.get(ext || '')) !== null && _a !== void 0 ? _a : null;
+            type = (_a = extToType.get(ext || '')) !== null && _a !== undefined ? _a : null;
         }
         if (!type) {
             console.warn(`Unsupported asset type: ${src}`);
@@ -1047,7 +1047,7 @@ class AssetElement extends HTMLElement {
     }
     static get(id) {
         const assetElement = document.querySelector(`pc-asset[id="${id}"]`);
-        return assetElement === null || assetElement === void 0 ? void 0 : assetElement.asset;
+        return assetElement === null || assetElement === undefined ? undefined : assetElement.asset;
     }
     static get observedAttributes() {
         return ['preload'];
@@ -1094,7 +1094,7 @@ class ComponentElement extends AsyncElement {
     initComponent() { }
     async connectedCallback() {
         var _a;
-        await ((_a = this.closestApp) === null || _a === void 0 ? void 0 : _a.ready());
+        await ((_a = this.closestApp) === null || _a === undefined ? undefined : _a.ready());
         await this.addComponent();
         this.initComponent();
         this._onReady();
@@ -1190,6 +1190,7 @@ class CameraComponentElement extends ComponentElement {
         this._fov = 45;
         this._frustumCulling = true;
         this._gamma = 'srgb';
+        this._horizontalFov = false;
         this._nearClip = 0.1;
         this._orthographic = false;
         this._orthoHeight = 10;
@@ -1210,6 +1211,7 @@ class CameraComponentElement extends ComponentElement {
             fov: this._fov,
             frustumCulling: this._frustumCulling,
             gammaCorrection: this._gamma === 'srgb' ? playcanvas.GAMMA_SRGB : playcanvas.GAMMA_NONE,
+            horizontalFov: this._horizontalFov,
             nearClip: this._nearClip,
             orthographic: this._orthographic,
             orthoHeight: this._orthoHeight,
@@ -1221,7 +1223,7 @@ class CameraComponentElement extends ComponentElement {
     }
     get xrAvailable() {
         var _a;
-        const xrManager = (_a = this.component) === null || _a === void 0 ? void 0 : _a.system.app.xr;
+        const xrManager = (_a = this.component) === null || _a === undefined ? undefined : _a.system.app.xr;
         return xrManager && xrManager.supported && xrManager.isAvailable(playcanvas.XRTYPE_VR);
     }
     startXr(type, space) {
@@ -1416,6 +1418,24 @@ class CameraComponentElement extends ComponentElement {
     get gamma() {
         return this._gamma;
     }
+    /**
+     * 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) {
+        this._horizontalFov = value;
+        if (this.component) {
+            this.component.horizontalFov = value;
+        }
+    }
+    /**
+     * 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() {
+        return this._horizontalFov;
+    }
     /**
      * Sets the near clip distance of the camera.
      * @param value - The near clip distance.
@@ -1526,7 +1546,7 @@ class CameraComponentElement extends ComponentElement {
         var _a;
         this._tonemap = value;
         if (this.component) {
-            this.component.toneMapping = (_a = tonemaps.get(value)) !== null && _a !== void 0 ? _a : playcanvas.TONEMAP_NONE;
+            this.component.toneMapping = (_a = tonemaps.get(value)) !== null && _a !== undefined ? _a : playcanvas.TONEMAP_NONE;
         }
     }
     /**
@@ -1549,6 +1569,7 @@ class CameraComponentElement extends ComponentElement {
             'fov',
             'frustum-culling',
             'gamma',
+            'horizontal-fov',
             'near-clip',
             'orthographic',
             'ortho-height',
@@ -1591,6 +1612,9 @@ class CameraComponentElement extends ComponentElement {
             case 'gamma':
                 this.gamma = newValue;
                 break;
+            case 'horizontal-fov':
+                this.horizontalFov = this.hasAttribute('horizontal-fov');
+                break;
             case 'near-clip':
                 this.nearClip = parseFloat(newValue);
                 break;
@@ -2292,7 +2316,7 @@ class LightComponentElement extends ComponentElement {
         var _a;
         this._shadowType = value;
         if (this.component) {
-            this.component.shadowType = (_a = shadowTypes.get(value)) !== null && _a !== void 0 ? _a : playcanvas.SHADOW_PCF3_32F;
+            this.component.shadowType = (_a = shadowTypes.get(value)) !== null && _a !== undefined ? _a : playcanvas.SHADOW_PCF3_32F;
         }
     }
     /**
@@ -2498,7 +2522,7 @@ class MaterialElement extends HTMLElement {
     }
     static get(id) {
         const materialElement = document.querySelector(`pc-material[id="${id}"]`);
-        return materialElement === null || materialElement === void 0 ? void 0 : materialElement.material;
+        return materialElement === null || materialElement === undefined ? undefined : materialElement.material;
     }
     static get observedAttributes() {
         return ['diffuse', 'diffuse-map', 'metalness-map', 'normal-map', 'roughness-map'];
@@ -3110,7 +3134,7 @@ class ScriptComponentElement extends ComponentElement {
     disconnectedCallback() {
         var _a;
         this.observer.disconnect();
-        (_a = super.disconnectedCallback) === null || _a === void 0 ? void 0 : _a.call(this);
+        (_a = super.disconnectedCallback) === null || _a === undefined ? undefined : _a.call(this);
     }
     /**
      * Gets the script component.
@@ -3424,7 +3448,7 @@ class SoundSlotElement extends AsyncElement {
     }
     async connectedCallback() {
         var _a;
-        await ((_a = this.soundElement) === null || _a === void 0 ? void 0 : _a.ready());
+        await ((_a = this.soundElement) === null || _a === undefined ? undefined : _a.ready());
         const options = {
             autoPlay: this._autoPlay,
             loop: this._loop,
@@ -3460,7 +3484,7 @@ class SoundSlotElement extends AsyncElement {
         var _a;
         this._asset = value;
         if (this.soundSlot) {
-            const id = (_a = AssetElement.get(value)) === null || _a === void 0 ? void 0 : _a.id;
+            const id = (_a = AssetElement.get(value)) === null || _a === undefined ? undefined : _a.id;
             if (id) {
                 this.soundSlot.asset = id;
             }
@@ -3687,8 +3711,8 @@ class ModelElement extends AsyncElement {
     async _loadModel() {
         var _a;
         this._unloadModel();
-        const appElement = await ((_a = this.closestApp) === null || _a === void 0 ? void 0 : _a.ready());
-        const app = appElement === null || appElement === void 0 ? void 0 : appElement.app;
+        const appElement = await ((_a = this.closestApp) === null || _a === undefined ? undefined : _a.ready());
+        const app = appElement === null || appElement === undefined ? undefined : appElement.app;
         const asset = AssetElement.get(this._asset);
         if (!asset) {
             return;
@@ -3705,7 +3729,7 @@ class ModelElement extends AsyncElement {
     }
     _unloadModel() {
         var _a;
-        (_a = this._entity) === null || _a === void 0 ? void 0 : _a.destroy();
+        (_a = this._entity) === null || _a === undefined ? undefined : _a.destroy();
         this._entity = null;
     }
     /**
@@ -3773,7 +3797,7 @@ class SceneElement extends AsyncElement {
     }
     async connectedCallback() {
         var _a;
-        await ((_a = this.closestApp) === null || _a === void 0 ? void 0 : _a.ready());
+        await ((_a = this.closestApp) === null || _a === undefined ? undefined : _a.ready());
         this.scene = this.closestApp.app.scene;
         this.updateSceneSettings();
         this._onReady();
@@ -3947,8 +3971,8 @@ class SkyElement extends AsyncElement {
     }
     async _loadSkybox() {
         var _a;
-        const appElement = await ((_a = this.closestApp) === null || _a === void 0 ? void 0 : _a.ready());
-        const app = appElement === null || appElement === void 0 ? void 0 : appElement.app;
+        const appElement = await ((_a = this.closestApp) === null || _a === undefined ? undefined : _a.ready());
+        const app = appElement === null || appElement === undefined ? undefined : appElement.app;
         if (!app) {
             return;
         }
@@ -3971,10 +3995,10 @@ class SkyElement extends AsyncElement {
         var _a, _b;
         if (!this._scene)
             return;
-        (_a = this._scene.skybox) === null || _a === void 0 ? void 0 : _a.destroy();
+        (_a = this._scene.skybox) === null || _a === undefined ? undefined : _a.destroy();
         // @ts-ignore
         this._scene.skybox = null;
-        (_b = this._scene.envAtlas) === null || _b === void 0 ? void 0 : _b.destroy();
+        (_b = this._scene.envAtlas) === null || _b === undefined ? undefined : _b.destroy();
         // @ts-ignore
         this._scene.envAtlas = null;
         this._scene = null;