@playcanvas/web-components 0.16.0 → 0.18.0

package/src/components/camera-component.ts

@@ -13,6 +13,7 @@ import {
     TONEMAP_ACES,
     TONEMAP_HEJL,
     TONEMAP_NONE,
+    XRTYPE_AR,
     XRTYPE_VR
 } from 'playcanvas';
 
@@ -41,6 +42,12 @@ const tonemaps = new Map<'none' | 'linear' | 'filmic' | 'hejl' | 'aces' | 'aces2
  * The CameraComponentElement interface also inherits the properties and methods of the
  * {@link HTMLElement} interface.
  *
+ * Engine component: {@link CameraComponent} (`camera`).
+ *
+ * @elementSummary The `<pc-camera>` element renders the scene from its entity's transform, with
+ * attributes for the projection, field of view, clip planes, clear color and tonemapping. Must be a
+ * child of a `<pc-entity>`, `<pc-model>` or `<pc-node>`.
+ *
  * @category Components
  */
 class CameraComponentElement extends ComponentElement {
@@ -48,9 +55,11 @@ class CameraComponentElement extends ComponentElement {
 
     private _clearColorBuffer = true;
 
+    private _clearDepth = 1;
+
     private _clearDepthBuffer = true;
 
-    private _clearStencilBuffer = false;
+    private _clearStencilBuffer = true;
 
     private _cullFaces = true;
 
@@ -89,6 +98,7 @@ class CameraComponentElement extends ComponentElement {
         return {
             clearColor: this._clearColor,
             clearColorBuffer: this._clearColorBuffer,
+            clearDepth: this._clearDepth,
             clearDepthBuffer: this._clearDepthBuffer,
             clearStencilBuffer: this._clearStencilBuffer,
             cullFaces: this._cullFaces,
@@ -108,9 +118,33 @@ class CameraComponentElement extends ComponentElement {
         };
     }
 
-    get xrAvailable() {
+    /**
+     * Whether immersive AR is available. Independent of {@link vrAvailable}: a device can offer
+     * either mode without the other.
+     * @returns Whether immersive AR is available.
+     */
+    get arAvailable(): boolean {
+        return this._available(XRTYPE_AR);
+    }
+
+    /**
+     * Whether immersive VR is available. Independent of {@link arAvailable}: a device can offer
+     * either mode without the other.
+     * @returns Whether immersive VR is available.
+     */
+    get vrAvailable(): boolean {
+        return this._available(XRTYPE_VR);
+    }
+
+    /**
+     * Whether one XR session type is available on this device.
+     *
+     * @param type - The XR session type to test.
+     * @returns Whether that type is available.
+     */
+    private _available(type: string): boolean {
         const xrManager = this.component?.system.app.xr;
-        return xrManager && xrManager.supported && xrManager.isAvailable(XRTYPE_VR);
+        return Boolean(xrManager?.supported && xrManager.isAvailable(type));
     }
 
     /**
@@ -122,10 +156,12 @@ class CameraComponentElement extends ComponentElement {
         type: 'immersive-ar' | 'immersive-vr',
         space: 'bounded-floor' | 'local' | 'local-floor' | 'unbounded' | 'viewer'
     ) {
-        if (this.component && this.xrAvailable) {
+        // Gated on the mode being started, not on XR in general: a device that offers only
+        // one of the two would otherwise accept a session it cannot serve
+        if (this.component && this._available(type)) {
             this.component.startXr(type, space, {
                 callback: (err: any) => {
-                    if (err) console.error(`WebXR Immersive VR failed to start: ${err.message}`);
+                    if (err) console.error(`WebXR ${type} failed to start: ${err.message}`);
                 }
             });
         }
@@ -186,6 +222,25 @@ class CameraComponentElement extends ComponentElement {
         return this._clearColorBuffer;
     }
 
+    /**
+     * Sets the depth value the depth buffer is cleared to. Defaults to 1.
+     * @param value - The clear depth value.
+     */
+    set clearDepth(value: number) {
+        this._clearDepth = value;
+        if (this.component) {
+            this.component.clearDepth = value;
+        }
+    }
+
+    /**
+     * Gets the depth value the depth buffer is cleared to.
+     * @returns The clear depth value.
+     */
+    get clearDepth(): number {
+        return this._clearDepth;
+    }
+
     /**
      * Sets the clear depth buffer of the camera.
      * @param value - The clear depth buffer.
@@ -496,6 +551,7 @@ class CameraComponentElement extends ComponentElement {
             ...super.observedAttributes,
             'clear-color',
             'clear-color-buffer',
+            'clear-depth',
             'clear-depth-buffer',
             'clear-stencil-buffer',
             'cull-faces',
@@ -525,11 +581,14 @@ class CameraComponentElement extends ComponentElement {
             case 'clear-color-buffer':
                 this.clearColorBuffer = parseBool(newValue, true);
                 break;
+            case 'clear-depth':
+                this.clearDepth = parseNumber(newValue, 1, name);
+                break;
             case 'clear-depth-buffer':
                 this.clearDepthBuffer = parseBool(newValue, true);
                 break;
             case 'clear-stencil-buffer':
-                this.clearStencilBuffer = parseBool(newValue, false);
+                this.clearStencilBuffer = parseBool(newValue, true);
                 break;
             case 'cull-faces':
                 this.cullFaces = parseBool(newValue, true);

package/src/components/collision-component.ts

@@ -17,6 +17,12 @@ import { ComponentElement } from './component';
  * retargets or rebinds picks up the new node's geometry. An entity with no asset-backed render
  * component warns, and the collider has no shape.
  *
+ * Engine component: {@link CollisionComponent} (`collision`).
+ *
+ * @elementSummary The `<pc-collision>` element gives its entity a collision shape — a box, sphere,
+ * capsule, cone, cylinder or mesh — for the physics simulation to collide against. Pair it with a
+ * `<pc-rigid-body>`. Must be a child of a `<pc-entity>`, `<pc-model>` or `<pc-node>`.
+ *
  * @category Components
  */
 class CollisionComponentElement extends ComponentElement {
@@ -64,7 +70,9 @@ class CollisionComponentElement extends ComponentElement {
      * no attribute to supply it - so the host's visible geometry, the meaning a mesh collider
      * on a glTF node carries, fills the gap. Runs on every application (so a rebound `pc-node`
      * recomputes it) and on a runtime switch to `type="mesh"`; an explicitly assigned
-     * `renderAsset` is never overwritten.
+     * `renderAsset` is never overwritten. A `pc-model` host entity never carries a render
+     * component (the instantiated content beneath it does), so a mesh collider that should take
+     * an asset's geometry belongs on a bound `pc-node`.
      */
     private _applyMeshGeometryDefault() {
         const component = this.component;

package/src/components/component.ts

@@ -109,7 +109,7 @@ class ComponentElement extends AsyncElement {
             // It still becomes ready (with a null `component`), so warn rather than fail silently
             const label = this.id ? ` '${this.id}'` : '';
             console.warn(
-                `${this.tagName.toLowerCase()}${label} must be a descendant of pc-entity - component not added`
+                `${this.tagName.toLowerCase()}${label} must be a descendant of pc-entity, pc-model or pc-node - component not added`
             );
             return;
         }
@@ -214,8 +214,9 @@ class ComponentElement extends AsyncElement {
 
     /**
      * The PlayCanvas component instance. `null` until the element is ready, and also for an
-     * element that is not a descendant of a `<pc-entity>` — await {@link whenReady} or the
-     * element's `ready()` promise before accessing it.
+     * element that is not a descendant of an entity-fronting element (`<pc-entity>`,
+     * `<pc-model>` or `<pc-node>`) — await {@link whenReady} or the element's `ready()` promise
+     * before accessing it.
      * @returns The component instance, or `null`.
      */
     get component(): Component | null {

package/src/components/element-component.ts

@@ -12,6 +12,17 @@ import { ComponentElement } from './component';
  * The ElementComponentElement interface also inherits the properties and methods of the
  * {@link HTMLElement} interface.
  *
+ * Despite the name, this is not a base class or a generic wrapper: it is the engine's 2D UI
+ * component, which gives its host entity a rectangle in a `<pc-screen>` hierarchy that draws
+ * either an image, a line of text or nothing (`type="image"`, `"text"` or `"group"`). The tag
+ * spells the engine component it adds, as every component element does.
+ *
+ * Engine component: {@link ElementComponent} (`element`).
+ *
+ * @elementSummary The `<pc-element>` element gives its entity a 2D UI rectangle inside a
+ * `<pc-screen>` hierarchy, drawing an image, a line of text or nothing (`type="image"`, `"text"` or
+ * `"group"`). Must be a child of a `<pc-entity>`, `<pc-model>` or `<pc-node>`.
+ *
  * @category Components
  */
 class ElementComponentElement extends ComponentElement {

package/src/components/gsplat-component.ts

@@ -11,6 +11,12 @@ import { ComponentElement } from './component';
  * The GSplatComponentElement interface also inherits the properties and methods of the
  * {@link HTMLElement} interface.
  *
+ * Engine component: {@link GSplatComponent} (`gsplat`).
+ *
+ * @elementSummary The `<pc-gsplat>` element renders the 3D Gaussian splats of a `gsplat` asset at
+ * its entity, with attributes for shadow casting and level of detail. Must be a child of a
+ * `<pc-entity>`, `<pc-model>` or `<pc-node>`.
+ *
  * @category Components
  */
 class GSplatComponentElement extends ComponentElement {

package/src/components/joint-component.ts

@@ -5,9 +5,14 @@ import { getEntity, parseBool, parseEnum, parseNumber, parseVec2, parseVec3 } fr
 
 import { ComponentElement } from './component';
 
-type JointType = 'fixed' | 'ball' | 'hinge' | 'slider' | '6dof';
+/** The constraint types supported by the `<pc-joint>` element. */
+export type JointType = 'fixed' | 'ball' | 'hinge' | 'slider' | '6dof';
 
-type MotionMode = 'locked' | 'limited' | 'free';
+/**
+ * The motion modes for a single joint axis: fully constrained (`locked`), constrained within
+ * limits (`limited`) or unconstrained (`free`).
+ */
+export type MotionMode = 'locked' | 'limited' | 'free';
 
 /**
  * The JointComponentElement interface provides properties and methods for manipulating
@@ -22,10 +27,17 @@ type MotionMode = 'locked' | 'limited' | 'free';
  * a rigid body component; leaving `entity-b` empty constrains `entity-a` to a fixed point in world
  * space. The underlying engine component is in alpha, so its API may change.
  *
+ * @elementSummary The `<pc-joint>` element constrains two rigid bodies to each other — a hinged
+ * door, a swinging chain, a sliding drawer. Its entity's transform is the joint frame, and
+ * `entity-a` and `entity-b` name the bodies. Must be a child of a `<pc-entity>`, `<pc-model>` or
+ * `<pc-node>`.
+ *
  * @fires {CustomEvent} break - Fired when the impulse on the joint exceeds `break-impulse` and the
  * constraint breaks. A broken joint no longer constrains its bodies; calling `refreshFrames()` on
  * the underlying component re-attaches it. Bubbles and is composed.
  *
+ * Engine component: {@link JointComponent} (`joint`).
+ *
  * @category Components
  */
 class JointComponentElement extends ComponentElement {

package/src/components/{layoutchild-component.ts → layout-child-component.ts}

@@ -6,10 +6,16 @@ import { ComponentElement } from './component';
 
 /**
  * The LayoutChildComponentElement interface provides properties and methods for manipulating
- * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-layoutchild/ | `<pc-layoutchild>`} elements.
+ * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-layout-child/ | `<pc-layout-child>`} elements.
  * The LayoutChildComponentElement interface also inherits the properties and methods of the
  * {@link HTMLElement} interface.
  *
+ * Engine component: {@link LayoutChildComponent} (`layoutchild`).
+ *
+ * @elementSummary The `<pc-layout-child>` element controls how its entity is sized by the
+ * `<pc-layout-group>` above it, through minimum and maximum sizes and fit proportions. Must be a
+ * child of a `<pc-entity>`, `<pc-model>` or `<pc-node>`.
+ *
  * @category Components
  */
 class LayoutChildComponentElement extends ComponentElement {
@@ -229,6 +235,6 @@ class LayoutChildComponentElement extends ComponentElement {
     }
 }
 
-customElements.define('pc-layoutchild', LayoutChildComponentElement);
+customElements.define('pc-layout-child', LayoutChildComponentElement);
 
 export { LayoutChildComponentElement };

package/src/components/{layoutgroup-component.ts → layout-group-component.ts}

@@ -28,10 +28,16 @@ const fittings = new Map<'none' | 'stretch' | 'shrink' | 'both', number>([
 
 /**
  * The LayoutGroupComponentElement interface provides properties and methods for manipulating
- * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-layoutgroup/ | `<pc-layoutgroup>`} elements.
+ * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-layout-group/ | `<pc-layout-group>`} elements.
  * The LayoutGroupComponentElement interface also inherits the properties and methods of the
  * {@link HTMLElement} interface.
  *
+ * Engine component: {@link LayoutGroupComponent} (`layoutgroup`).
+ *
+ * @elementSummary The `<pc-layout-group>` element arranges its entity's children in a row or
+ * column, with spacing, padding, alignment and fitting. Must be a child of a `<pc-entity>`,
+ * `<pc-model>` or `<pc-node>`.
+ *
  * @category Components
  */
 class LayoutGroupComponentElement extends ComponentElement {
@@ -304,6 +310,6 @@ class LayoutGroupComponentElement extends ComponentElement {
     }
 }
 
-customElements.define('pc-layoutgroup', LayoutGroupComponentElement);
+customElements.define('pc-layout-group', LayoutGroupComponentElement);
 
 export { LayoutGroupComponentElement };

package/src/components/light-component.ts

@@ -37,9 +37,19 @@ const shadowTypes = new Map<
  * The LightComponentElement interface also inherits the properties and methods of the
  * {@link HTMLElement} interface.
  *
+ * Engine component: {@link LightComponent} (`light`).
+ *
+ * @elementSummary The `<pc-light>` element lights the scene from its entity — as a directional,
+ * omni or spot light — with attributes for color, intensity, range and shadows. Must be a child of
+ * a `<pc-entity>`, `<pc-model>` or `<pc-node>`.
+ *
  * @category Components
  */
 class LightComponentElement extends ComponentElement {
+    private _cascadeBlend = 0;
+
+    private _cascadeDistribution = 0.5;
+
     private _castShadows = false;
 
     private _color = new Color(1, 1, 1);
@@ -48,15 +58,17 @@ class LightComponentElement extends ComponentElement {
 
     private _intensity = 1;
 
-    private _normalOffsetBias = 0.05;
+    private _normalOffsetBias = 0;
+
+    private _numCascades = 1;
 
     private _outerConeAngle = 45;
 
     private _range = 10;
 
-    private _shadowBias = 0.2;
+    private _shadowBias = 0.05;
 
-    private _shadowDistance = 16;
+    private _shadowDistance = 40;
 
     private _shadowIntensity = 1;
 
@@ -75,7 +87,7 @@ class LightComponentElement extends ComponentElement {
 
     private _type: 'directional' | 'omni' | 'spot' = 'directional';
 
-    private _vsmBias = 0.01;
+    private _vsmBias = 0.0025;
 
     private _vsmBlurSize = 11;
 
@@ -94,11 +106,14 @@ class LightComponentElement extends ComponentElement {
 
     protected getInitialComponentData() {
         return {
+            cascadeBlend: this._cascadeBlend,
+            cascadeDistribution: this._cascadeDistribution,
             castShadows: this._castShadows,
             color: this._color,
             innerConeAngle: this._innerConeAngle,
             intensity: this._intensity,
             normalOffsetBias: this._normalOffsetBias,
+            numCascades: this._numCascades,
             outerConeAngle: this._outerConeAngle,
             penumbraFalloff: this._penumbraFalloff,
             penumbraSize: this._penumbraSize,
@@ -109,7 +124,7 @@ class LightComponentElement extends ComponentElement {
             shadowIntensity: this._shadowIntensity,
             shadowResolution: this._shadowResolution,
             shadowSamples: this._shadowSamples,
-            shadowType: shadowTypes.get(this._shadowType),
+            shadowType: shadowTypes.get(this._shadowType) ?? SHADOW_PCF3_32F,
             type: this._type,
             vsmBias: this._vsmBias,
             vsmBlurSize: this._vsmBlurSize
@@ -124,6 +139,51 @@ class LightComponentElement extends ComponentElement {
         return super.component as LightComponent;
     }
 
+    /**
+     * Sets the fraction of each shadow cascade that is blended into the next one, from 0 (no
+     * blending) to 1, which applies only to `directional` lights with `num-cascades` greater than
+     * 1. Defaults to 0.
+     * @param value - The cascade blend factor.
+     */
+    set cascadeBlend(value: number) {
+        this._cascadeBlend = value;
+        if (this.component) {
+            this.component.cascadeBlend = value;
+        }
+    }
+
+    /**
+     * Gets the cascade blend factor of the light, from 0 (no blending) to 1, which applies only to
+     * `directional` lights with `num-cascades` greater than 1.
+     * @returns The cascade blend factor.
+     */
+    get cascadeBlend() {
+        return this._cascadeBlend;
+    }
+
+    /**
+     * Sets the distribution of the camera frustum split between shadow cascades, from 0 (linear
+     * split) to 1 (logarithmic split, concentrating shadow resolution near the camera), which
+     * applies only to `directional` lights with `num-cascades` greater than 1. Defaults to 0.5.
+     * @param value - The cascade distribution.
+     */
+    set cascadeDistribution(value: number) {
+        this._cascadeDistribution = value;
+        if (this.component) {
+            this.component.cascadeDistribution = value;
+        }
+    }
+
+    /**
+     * Gets the cascade distribution of the light, from 0 (linear split) to 1 (logarithmic split,
+     * concentrating shadow resolution near the camera), which applies only to `directional` lights
+     * with `num-cascades` greater than 1.
+     * @returns The cascade distribution.
+     */
+    get cascadeDistribution() {
+        return this._cascadeDistribution;
+    }
+
     /**
      * Sets the cast shadows flag of the light.
      * @param value - The cast shadows flag.
@@ -219,6 +279,27 @@ class LightComponentElement extends ComponentElement {
         return this._normalOffsetBias;
     }
 
+    /**
+     * Sets the number of shadow cascades of the light, an integer from 1 (no cascades) to 4, which
+     * applies only to `directional` lights. Defaults to 1.
+     * @param value - The number of shadow cascades.
+     */
+    set numCascades(value: number) {
+        this._numCascades = value;
+        if (this.component) {
+            this.component.numCascades = value;
+        }
+    }
+
+    /**
+     * Gets the number of shadow cascades of the light, an integer from 1 (no cascades) to 4, which
+     * applies only to `directional` lights.
+     * @returns The number of shadow cascades.
+     */
+    get numCascades() {
+        return this._numCascades;
+    }
+
     /**
      * Sets the outer cone angle of the light.
      * @param value - The outer cone angle.
@@ -510,11 +591,14 @@ class LightComponentElement extends ComponentElement {
     static get observedAttributes() {
         return [
             ...super.observedAttributes,
-            'color',
+            'cascade-blend',
+            'cascade-distribution',
             'cast-shadows',
-            'intensity',
+            'color',
             'inner-cone-angle',
+            'intensity',
             'normal-offset-bias',
+            'num-cascades',
             'outer-cone-angle',
             'penumbra-falloff',
             'penumbra-size',
@@ -536,12 +620,18 @@ class LightComponentElement extends ComponentElement {
         super.attributeChangedCallback(name, _oldValue, newValue);
 
         switch (name) {
-            case 'color':
-                this.color = parseColor(newValue, Color.WHITE, name);
+            case 'cascade-blend':
+                this.cascadeBlend = parseNumber(newValue, 0, name);
+                break;
+            case 'cascade-distribution':
+                this.cascadeDistribution = parseNumber(newValue, 0.5, name);
                 break;
             case 'cast-shadows':
                 this.castShadows = parseBool(newValue, false);
                 break;
+            case 'color':
+                this.color = parseColor(newValue, Color.WHITE, name);
+                break;
             case 'inner-cone-angle':
                 this.innerConeAngle = parseNumber(newValue, 40, name);
                 break;
@@ -549,7 +639,10 @@ class LightComponentElement extends ComponentElement {
                 this.intensity = parseNumber(newValue, 1, name);
                 break;
             case 'normal-offset-bias':
-                this.normalOffsetBias = parseNumber(newValue, 0.05, name);
+                this.normalOffsetBias = parseNumber(newValue, 0, name);
+                break;
+            case 'num-cascades':
+                this.numCascades = parseNumber(newValue, 1, name);
                 break;
             case 'outer-cone-angle':
                 this.outerConeAngle = parseNumber(newValue, 45, name);
@@ -564,20 +657,20 @@ class LightComponentElement extends ComponentElement {
                 this.range = parseNumber(newValue, 10, name);
                 break;
             case 'shadow-bias':
-                this.shadowBias = parseNumber(newValue, 0.2, name);
-                break;
-            case 'shadow-distance':
-                this.shadowDistance = parseNumber(newValue, 16, name);
+                this.shadowBias = parseNumber(newValue, 0.05, name);
                 break;
             case 'shadow-blocker-samples':
                 this.shadowBlockerSamples = parseNumber(newValue, 16, name);
                 break;
-            case 'shadow-resolution':
-                this.shadowResolution = parseNumber(newValue, 1024, name);
+            case 'shadow-distance':
+                this.shadowDistance = parseNumber(newValue, 40, name);
                 break;
             case 'shadow-intensity':
                 this.shadowIntensity = parseNumber(newValue, 1, name);
                 break;
+            case 'shadow-resolution':
+                this.shadowResolution = parseNumber(newValue, 1024, name);
+                break;
             case 'shadow-samples':
                 this.shadowSamples = parseNumber(newValue, 16, name);
                 break;
@@ -588,7 +681,7 @@ class LightComponentElement extends ComponentElement {
                 this.type = parseEnum(newValue, ['directional', 'omni', 'spot'], 'directional', name);
                 break;
             case 'vsm-bias':
-                this.vsmBias = parseNumber(newValue, 0.01, name);
+                this.vsmBias = parseNumber(newValue, 0.0025, name);
                 break;
             case 'vsm-blur-size':
                 this.vsmBlurSize = parseNumber(newValue, 11, name);

package/src/components/{particlesystem-component.ts → particle-system-component.ts}

@@ -6,10 +6,16 @@ import { ComponentElement } from './component';
 
 /**
  * The ParticleSystemComponentElement interface provides properties and methods for manipulating
- * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-particles/ | `<pc-particles>`} elements.
+ * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-particle-system/ | `<pc-particle-system>`} elements.
  * The ParticleSystemComponentElement interface also inherits the properties and methods of the
  * {@link HTMLElement} interface.
  *
+ * Engine component: {@link ParticleSystemComponent} (`particlesystem`).
+ *
+ * @elementSummary The `<pc-particle-system>` element emits particles from its entity, with
+ * attributes for the emitter's shape, rate, lifetime, textures and blending. Must be a child of a
+ * `<pc-entity>`, `<pc-model>` or `<pc-node>`.
+ *
  * @category Components
  */
 class ParticleSystemComponentElement extends ComponentElement {
@@ -147,6 +153,6 @@ class ParticleSystemComponentElement extends ComponentElement {
     }
 }
 
-customElements.define('pc-particles', ParticleSystemComponentElement);
+customElements.define('pc-particle-system', ParticleSystemComponentElement);
 
 export { ParticleSystemComponentElement };

package/src/components/render-component.ts

@@ -15,6 +15,13 @@ import { ComponentElement } from './component';
  * to `box`). It does not cover the engine's `asset` render type, since there is no way to supply
  * a render asset here — use `pc-model` for glTF content instead.
  *
+ * Engine component: {@link RenderComponent} (`render`).
+ *
+ * @elementSummary The `<pc-render>` element renders one of the engine's built-in primitives at its
+ * entity — box, sphere, capsule, cone, cylinder or plane — shaded by the `<pc-material>` its
+ * `material` attribute names. For glTF content, use `<pc-model>` instead. Must be a child of a
+ * `<pc-entity>`, `<pc-model>` or `<pc-node>`.
+ *
  * @category Components
  */
 class RenderComponentElement extends ComponentElement {

package/src/components/{rigidbody-component.ts → rigid-body-component.ts}

@@ -7,10 +7,17 @@ import { ComponentElement } from './component';
 
 /**
  * The RigidBodyComponentElement interface provides properties and methods for manipulating
- * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-rigidbody/ | `<pc-rigidbody>`} elements.
+ * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-rigid-body/ | `<pc-rigid-body>`} elements.
  * The RigidBodyComponentElement interface also inherits the properties and methods of the
  * {@link HTMLElement} interface.
  *
+ * Engine component: {@link RigidBodyComponent} (`rigidbody`).
+ *
+ * @elementSummary The `<pc-rigid-body>` element hands its entity to the physics simulation, with
+ * attributes for its type, mass, friction and restitution. It needs a sibling `<pc-collision>` for
+ * its shape, and `Ammo` loaded through `<pc-wasm>`. Must be a child of a `<pc-entity>`,
+ * `<pc-model>` or `<pc-node>`.
+ *
  * @category Components
  */
 class RigidBodyComponentElement extends ComponentElement {
@@ -235,6 +242,6 @@ class RigidBodyComponentElement extends ComponentElement {
     }
 }
 
-customElements.define('pc-rigidbody', RigidBodyComponentElement);
+customElements.define('pc-rigid-body', RigidBodyComponentElement);
 
 export { RigidBodyComponentElement };

package/src/components/screen-component.ts

@@ -20,6 +20,12 @@ const scaleModes = new Map<'none' | 'blend', string>([
  * The ScreenComponentElement interface also inherits the properties and methods of the
  * {@link HTMLElement} interface.
  *
+ * Engine component: {@link ScreenComponent} (`screen`).
+ *
+ * @elementSummary The `<pc-screen>` element gives its entity a 2D space — in screen space or in the
+ * world — that a hierarchy of `<pc-element>` descendants lays out inside. Must be a child of a
+ * `<pc-entity>`, `<pc-model>` or `<pc-node>`.
+ *
  * @category Components
  */
 class ScreenComponentElement extends ComponentElement {