@playcanvas/web-components 0.18.0 → 0.19.0

package/src/app.ts

@@ -66,6 +66,7 @@ import {
 
 import type { AssetElement } from './asset';
 import { AsyncElement } from './async-element';
+import { SYNTHESIZED_EVENTS } from './entity-base';
 import type { EntityBaseElement } from './entity-base';
 import type { EntityOwnerElement } from './entity-owner';
 import { LoadingBar } from './loading-bar';
@@ -73,9 +74,6 @@ import type { MaterialElement } from './material';
 import { parseBool, parseEnum, parseNumber } from './parse';
 import type { WasmElement } from './wasm';
 
-/** The pointer event types the application synthesizes on `<pc-entity>` elements via picking. */
-const pointerEventTypes = ['pointermove', 'pointerdown', 'pointerup', 'pointerenter', 'pointerleave'] as const;
-
 /**
  * The event types whose listeners make an element a hover target. Hover resolution walks past
  * elements listening for none of them, so a silent element never swallows an ancestor's
@@ -83,6 +81,48 @@ const pointerEventTypes = ['pointermove', 'pointerdown', 'pointerup', 'pointeren
  */
 const hoverEventTypes = ['pointerenter', 'pointerleave', 'pointermove'] as const;
 
+/**
+ * The canvas listeners each synthesized event type is driven by. Enter and leave are derived
+ * from move picks. A click is concluded from the down/up pair, with pointercancel discarding a
+ * press the browser takes back (for example a touch that becomes a scroll).
+ */
+const canvasEventsFor: Record<(typeof SYNTHESIZED_EVENTS)[number], readonly string[]> = {
+    pointermove: ['pointermove'],
+    pointerenter: ['pointermove'],
+    pointerleave: ['pointermove'],
+    pointerdown: ['pointerdown'],
+    pointerup: ['pointerup'],
+    click: ['pointerdown', 'pointerup', 'pointercancel']
+};
+
+/**
+ * How long after a click a further click on the same target still raises the click count that
+ * `detail` carries, approximating the platform's double-click time.
+ */
+const CLICK_CHAIN_MS = 500;
+
+/**
+ * Finds the nearest common inclusive ancestor of two picked nodes - the node a click belongs to
+ * when the press and the release picked different geometry, exactly as the DOM assigns a click
+ * whose down and up have different targets.
+ *
+ * @param a - The node the press picked, or `null`.
+ * @param b - The node the release picked, or `null`.
+ * @returns The nearest common inclusive ancestor, or `null` when there is none.
+ */
+const commonAncestor = (a: GraphNode | null, b: GraphNode | null): GraphNode | null => {
+    const ancestors = new Set<GraphNode>();
+    for (let node = a; node !== null; node = node.parent) {
+        ancestors.add(node);
+    }
+    for (let node = b; node !== null; node = node.parent) {
+        if (ancestors.has(node)) {
+            return node;
+        }
+    }
+    return null;
+};
+
 /**
  * Gives `pc-app` the sizing contract of a replaced element (`<video>`, `<img>`): a block-level
  * box that the page's CSS sizes, defaulting to the canvas's own 300x150 intrinsic size, with the
@@ -182,14 +222,6 @@ class AppElement extends AsyncElement {
 
     private _picker: Picker | null = null;
 
-    private _hasPointerListeners: Record<string, boolean> = {
-        pointerenter: false,
-        pointerleave: false,
-        pointerdown: false,
-        pointerup: false,
-        pointermove: false
-    };
-
     private _hoveredEntity: EntityBaseElement | null = null;
 
     // Identifies the newest in-flight hover pick, so out-of-order results can be discarded
@@ -198,9 +230,28 @@ class AppElement extends AsyncElement {
     private _pointerHandlers: Record<string, EventListener | null> = {
         pointermove: null,
         pointerdown: null,
-        pointerup: null
+        pointerup: null,
+        pointercancel: null
     };
 
+    /**
+     * The pick of each pointer's primary-button press, keyed by pointerId and kept while a click
+     * may still conclude it. The promise is stored rather than its result, so a release can
+     * await a press pick that has not resolved yet. Entries are removed by the matching
+     * pointerup or pointercancel, and only ever stored while some element listens for click -
+     * which is also what keeps those two canvas listeners attached.
+     */
+    private _downPicks = new Map<number, Promise<GraphNode | null>>();
+
+    /** Whether any element in the tree listens for click. Maintained by _syncCanvasListeners. */
+    private _clickListened = false;
+
+    /**
+     * The previous click's target, time and count, for chaining successive clicks into the
+     * click count that `detail` carries. `null` until a click has fired.
+     */
+    private _lastClick: { element: EntityBaseElement; time: number; count: number } | null = null;
+
     private _app: AppBase | null = null;
 
     private _loadProgress = 0;
@@ -241,12 +292,12 @@ class AppElement extends AsyncElement {
     constructor() {
         super();
 
-        // Track pointer listeners being added to and removed from descendant entities.
-        // Registered once here rather than on every boot - the handlers no-op while there is no
-        // canvas, and a re-booted element must not stack a second set.
-        pointerEventTypes.forEach((type) => {
-            this.addEventListener(`${type}:connect`, () => this._onPointerListenerAdded(type));
-            this.addEventListener(`${type}:disconnect`, () => this._onPointerListenerRemoved(type));
+        // Track listeners for the synthesized events being added to and removed from descendant
+        // entities. Registered once here rather than on every boot - the sync no-ops while there
+        // is no canvas, and a re-booted element must not stack a second set.
+        SYNTHESIZED_EVENTS.forEach((type) => {
+            this.addEventListener(`${type}:connect`, () => this._syncCanvasListeners());
+            this.addEventListener(`${type}:disconnect`, () => this._syncCanvasListeners());
         });
     }
 
@@ -609,18 +660,14 @@ class AppElement extends AsyncElement {
         this._pointerHandlers.pointermove = listener(this._onPointerMove);
         this._pointerHandlers.pointerdown = listener(this._onPointerDown);
         this._pointerHandlers.pointerup = listener(this._onPointerUp);
+        this._pointerHandlers.pointercancel = (event: Event) => {
+            this._downPicks.delete((event as PointerEvent).pointerId);
+        };
 
-        // Attach canvas handlers for listeners registered before this boot (e.g. handlers
-        // created from onpointer* attributes when their elements were first upgraded, or
+        // Attach canvas listeners for element listeners registered before this boot (e.g.
+        // handlers created from inline attributes when their elements were first upgraded, or
         // listeners carried over from before a re-boot)
-        pointerEventTypes.forEach((type) => {
-            const anyListeners = Array.from(
-                this.querySelectorAll<EntityBaseElement>('pc-entity, pc-model, pc-node')
-            ).some((entity) => entity._hasListeners(type));
-            if (anyListeners) {
-                this._onPointerListenerAdded(type);
-            }
-        });
+        this._syncCanvasListeners();
     }
 
     private _pickerDestroy() {
@@ -637,15 +684,12 @@ class AppElement extends AsyncElement {
         this._pointerHandlers = {
             pointermove: null,
             pointerdown: null,
-            pointerup: null
-        };
-        this._hasPointerListeners = {
-            pointerenter: false,
-            pointerleave: false,
-            pointerdown: false,
-            pointerup: false,
-            pointermove: false
+            pointerup: null,
+            pointercancel: null
         };
+        this._downPicks.clear();
+        this._clickListened = false;
+        this._lastClick = null;
     }
 
     /**
@@ -871,7 +915,17 @@ class AppElement extends AsyncElement {
     private async _onPointerDown(event: PointerEvent) {
         if (!this._picker || !this.app) return;
 
-        const node = await this._pickNode(event);
+        const pick = this._pickNode(event);
+
+        // A click concludes on the matching pointerup, which needs to know what the press
+        // picked. Primary button only - the only button a click can conclude from - and only
+        // while click is listened for, since it is the click mapping that keeps the pointerup
+        // and pointercancel listeners attached to clean the entry up again.
+        if (this._clickListened && event.button === 0) {
+            this._downPicks.set(event.pointerId, pick);
+        }
+
+        const node = await pick;
         if (!this._picker) return; // the element disconnected while the pick was in flight
 
         const entityElement = this._elementWithListener(node, 'pointerdown');
@@ -883,6 +937,11 @@ class AppElement extends AsyncElement {
     private async _onPointerUp(event: PointerEvent) {
         if (!this._picker || !this.app) return;
 
+        // The press pick this release may conclude as a click. Claimed synchronously, so the
+        // entry is gone before any other event for this pointer can be handled.
+        const downPick = this._downPicks.get(event.pointerId);
+        this._downPicks.delete(event.pointerId);
+
         const node = await this._pickNode(event);
         if (!this._picker) return; // the element disconnected while the pick was in flight
 
@@ -890,47 +949,63 @@ class AppElement extends AsyncElement {
         if (entityElement) {
             entityElement.dispatchEvent(new PointerEvent('pointerup', event));
         }
-    }
 
-    private _onPointerListenerAdded(type: string) {
-        if (!this._hasPointerListeners[type] && this._canvas) {
-            this._hasPointerListeners[type] = true;
-
-            // For enter/leave events, we need the move handler
-            const handler =
-                type === 'pointerenter' || type === 'pointerleave'
-                    ? this._pointerHandlers.pointermove
-                    : this._pointerHandlers[type];
-
-            if (handler) {
-                this._canvas.addEventListener(
-                    type === 'pointerenter' || type === 'pointerleave' ? 'pointermove' : type,
-                    handler
-                );
-            }
+        // A click fires where the DOM fires it: at the nearest common inclusive ancestor of
+        // what the press and the release picked, for the primary button only. The press pick
+        // may still be in flight - a quick tap resolves in pick order, not event order.
+        if (!downPick || event.button !== 0) return;
+        const downNode = await downPick;
+        if (!this._picker) return;
+
+        const clickElement = this._elementWithListener(commonAncestor(downNode, node), 'click');
+        if (clickElement) {
+            const click = new PointerEvent('click', event);
+
+            // The init above copied pointerup's `detail`, which the Pointer Events spec fixes
+            // at 0 - but click is exempt: its detail is the click count, chained here as the
+            // platform chains it (same target, within the double-click window). Overridden
+            // with defineProperty because an event instance used as an init dict cannot have
+            // single fields replaced.
+            const time = performance.now();
+            const last = this._lastClick;
+            const count =
+                last && last.element === clickElement && time - last.time <= CLICK_CHAIN_MS ? last.count + 1 : 1;
+            this._lastClick = { element: clickElement, time, count };
+            Object.defineProperty(click, 'detail', { value: count });
+
+            clickElement.dispatchEvent(click);
         }
     }
 
-    private _onPointerListenerRemoved(type: string) {
-        const hasListeners = Array.from(
-            this.querySelectorAll<EntityBaseElement>('pc-entity, pc-model, pc-node')
-        ).some((entity) => entity._hasListeners(type));
-
-        if (!hasListeners && this._canvas) {
-            this._hasPointerListeners[type] = false;
-
-            const handler =
-                type === 'pointerenter' || type === 'pointerleave'
-                    ? this._pointerHandlers.pointermove
-                    : this._pointerHandlers[type];
+    /**
+     * Attaches exactly the canvas listeners the tree's current element listeners need, and
+     * detaches the rest. Recomputed whenever a listener connects or disconnects anywhere under
+     * this element: several synthesized types can need the same canvas listener (enter, leave
+     * and move all ride the move pick; click rides the down/up pair), so one type's removal
+     * must not detach a listener another type still uses. Re-attaching an attached listener is
+     * a no-op by EventTarget semantics, so no attach state is kept.
+     */
+    private _syncCanvasListeners() {
+        const canvas = this._canvas;
+        if (!canvas) return; // not booted yet: _pickerCreate syncs once the handlers exist
 
-            if (handler) {
-                this._canvas.removeEventListener(
-                    type === 'pointerenter' || type === 'pointerleave' ? 'pointermove' : type,
-                    handler
-                );
+        const elements = Array.from(this.querySelectorAll<EntityBaseElement>('pc-entity, pc-model, pc-node'));
+        const needed = new Set<string>();
+        for (const type of SYNTHESIZED_EVENTS) {
+            if (elements.some((element) => element._hasListeners(type))) {
+                canvasEventsFor[type].forEach((canvasType) => needed.add(canvasType));
             }
         }
+        this._clickListened = elements.some((element) => element._hasListeners('click'));
+
+        Object.entries(this._pointerHandlers).forEach(([canvasType, handler]) => {
+            if (!handler) return;
+            if (needed.has(canvasType)) {
+                canvas.addEventListener(canvasType, handler);
+            } else {
+                canvas.removeEventListener(canvasType, handler);
+            }
+        });
     }
 
     /**

package/src/components/anim-clip.ts

@@ -25,8 +25,6 @@ import { AnimComponentElement } from './anim-component';
  * @elementSummary The `<pc-anim-clip>` element declares one named animation clip on its parent
  * `<pc-anim>`, taken from the `asset` it names or, without one, from the enclosing `<pc-model>`'s
  * own animations. Must be a direct child of `<pc-anim>`.
- *
- * @category Components
  */
 class AnimClipElement extends AsyncElement {
     /**

package/src/entity-base.ts

@@ -4,18 +4,29 @@ import type { AppElement } from './app';
 import { AsyncElement } from './async-element';
 
 /**
- * The attribute names of the inline `onpointer*` event handlers, shared by every element that
- * fronts an engine entity. Spread into `observedAttributes` by subclasses.
+ * The event types the containing `<pc-app>` synthesizes on entity-fronting elements via picking:
+ * the `pointer*` events, plus `click` — which concludes a primary-button press and release, and
+ * is delivered as a `PointerEvent` exactly as modern browsers deliver native clicks.
  * @internal
  */
-export const POINTER_ATTRIBUTES = [
-    'onpointerenter',
-    'onpointerleave',
-    'onpointerdown',
-    'onpointerup',
-    'onpointermove'
+export const SYNTHESIZED_EVENTS = [
+    'pointerenter',
+    'pointerleave',
+    'pointerdown',
+    'pointerup',
+    'pointermove',
+    'click'
 ] as const;
 
+const SYNTHESIZED_EVENT_SET: ReadonlySet<string> = new Set(SYNTHESIZED_EVENTS);
+
+/**
+ * The attribute names of the inline event handlers (`onpointerdown`, `onclick`, ...), shared by
+ * every element that fronts an engine entity. Spread into `observedAttributes` by subclasses.
+ * @internal
+ */
+export const EVENT_ATTRIBUTES = SYNTHESIZED_EVENTS.map((type) => `on${type}`);
+
 /**
  * The base class for elements that front an engine {@link Entity}: `<pc-entity>` and
  * `<pc-model>`, which create one, and `<pc-node>`, which binds to one inside a model's
@@ -34,12 +45,13 @@ class EntityBaseElement extends AsyncElement {
     protected _appElement: AppElement | null = null;
 
     /**
-     * The pointer event listeners for the entity.
+     * The event listeners registered on the element, by type.
      */
     private _listeners: Record<string, EventListener[]> = {};
 
     /**
-     * The event types for which an inline `onpointer*` attribute is currently present.
+     * The event types for which an inline handler attribute (`onpointerdown`, `onclick`, ...)
+     * is currently present.
      */
     private _inlineHandlerTypes = new Set<string>();
 
@@ -75,7 +87,7 @@ class EntityBaseElement extends AsyncElement {
     }
 
     /**
-     * Tracks whether an inline `onpointer*` attribute is present. The browser itself compiles and
+     * Tracks whether an inline handler attribute is present. The browser itself compiles and
      * runs these attributes — they are standard `GlobalEventHandlers`, so setting one replaces
      * the previous handler and removing it removes the handler, exactly like `onclick` on any
      * HTML element. But because they bypass {@link EventTarget.addEventListener}, the connect/disconnect
@@ -105,7 +117,7 @@ class EntityBaseElement extends AsyncElement {
         }
         this._listeners[type].push(listener);
         super.addEventListener(type, listener, options);
-        if (type.startsWith('pointer')) {
+        if (SYNTHESIZED_EVENT_SET.has(type)) {
             this.dispatchEvent(new CustomEvent(`${type}:connect`, { bubbles: true }));
         }
     }
@@ -115,15 +127,15 @@ class EntityBaseElement extends AsyncElement {
             this._listeners[type] = this._listeners[type].filter((l) => l !== listener);
         }
         super.removeEventListener(type, listener, options);
-        if (type.startsWith('pointer')) {
+        if (SYNTHESIZED_EVENT_SET.has(type)) {
             this.dispatchEvent(new CustomEvent(`${type}:disconnect`, { bubbles: true }));
         }
     }
 
     /**
      * Whether the element has a listener for an event type, registered either with
-     * {@link EventTarget.addEventListener} or with the matching inline `onpointer*` attribute. Read by the
-     * containing `<pc-app>` element to gate pointer event synthesis.
+     * {@link EventTarget.addEventListener} or with the matching inline handler attribute. Read by the
+     * containing `<pc-app>` element to gate event synthesis.
      *
      * @param type - The event type.
      * @returns Whether a listener is registered.

package/src/entity.ts

@@ -1,6 +1,6 @@
 import { Vec3 } from 'playcanvas';
 
-import { POINTER_ATTRIBUTES } from './entity-base';
+import { EVENT_ATTRIBUTES } from './entity-base';
 import { buildDescendantEntities, EntityOwnerElement } from './entity-owner';
 import { parseBool, parseTags, parseVec3 } from './parse';
 
@@ -12,8 +12,8 @@ import { parseBool, parseTags, parseVec3 } from './parse';
  *
  * The pointer events below are dispatched by the containing `<pc-app>` element when the pointer
  * intersects this entity's geometry. They are only generated while the entity has a listener for
- * them, registered either with {@link EventTarget.addEventListener} or with the matching inline `onpointer*`
- * attribute.
+ * them, registered either with {@link EventTarget.addEventListener} or with the matching inline
+ * attribute (`onpointerdown`, `onclick`, ...).
  *
  * @elementSummary The `<pc-entity>` element creates an entity: a named, transformable node of the
  * scene hierarchy, and the host for component elements such as `<pc-camera>`, `<pc-light>` and
@@ -33,11 +33,17 @@ import { parseBool, parseTags, parseVec3 } from './parse';
  * entity.
  * @attribute {string} onpointerup - Script to run when a pointer button is released over the
  * entity.
+ * @attribute {string} onclick - Script to run when the entity is clicked: a primary pointer
+ * button pressed and then released over it.
  * @fires {PointerEvent} pointerenter - Fired when the pointer moves onto the entity.
  * @fires {PointerEvent} pointerleave - Fired when the pointer moves off the entity.
  * @fires {PointerEvent} pointermove - Fired when the pointer moves over the entity.
  * @fires {PointerEvent} pointerdown - Fired when a pointer button is pressed over the entity.
  * @fires {PointerEvent} pointerup - Fired when a pointer button is released over the entity.
+ * @fires {PointerEvent} click - Fired when a primary pointer button is pressed and then released
+ * over the entity. A press and release that picked different entities fires on their nearest
+ * common ancestor instead, as in the DOM. `detail` carries the click count, so a double click
+ * arrives as a click whose `detail` is 2.
  */
 class EntityElement extends EntityOwnerElement {
     connectedCallback() {
@@ -77,7 +83,7 @@ class EntityElement extends EntityOwnerElement {
     }
 
     static get observedAttributes() {
-        return ['enabled', 'name', 'position', 'rotation', 'scale', 'tags', ...POINTER_ATTRIBUTES];
+        return ['enabled', 'name', 'position', 'rotation', 'scale', 'tags', ...EVENT_ATTRIBUTES];
     }
 
     attributeChangedCallback(name: string, _oldValue: string | null, newValue: string | null) {
@@ -105,6 +111,7 @@ class EntityElement extends EntityOwnerElement {
             case 'onpointerdown':
             case 'onpointerup':
             case 'onpointermove':
+            case 'onclick':
                 this._updateInlineHandler(name, newValue);
                 break;
         }

package/src/model.ts

@@ -2,7 +2,7 @@ import type { ContainerResource, Entity, EventHandle } from 'playcanvas';
 import { Vec3 } from 'playcanvas';
 
 import { useAsset } from './asset';
-import { POINTER_ATTRIBUTES } from './entity-base';
+import { EVENT_ATTRIBUTES } from './entity-base';
 import { buildDescendantEntities, EntityOwnerElement } from './entity-owner';
 import { parseBool, parseTags, parseVec3 } from './parse';
 
@@ -143,11 +143,17 @@ const formatHierarchy = (root: HierarchyNode, counts: ReadonlyMap<string, number
  * model.
  * @attribute {string} onpointerup - Script to run when a pointer button is released over the
  * model.
+ * @attribute {string} onclick - Script to run when the model is clicked: a primary pointer
+ * button pressed and then released over it.
  * @fires {PointerEvent} pointerenter - Fired when the pointer moves onto the model.
  * @fires {PointerEvent} pointerleave - Fired when the pointer moves off the model.
  * @fires {PointerEvent} pointermove - Fired when the pointer moves over the model.
  * @fires {PointerEvent} pointerdown - Fired when a pointer button is pressed over the model.
  * @fires {PointerEvent} pointerup - Fired when a pointer button is released over the model.
+ * @fires {PointerEvent} click - Fired when a primary pointer button is pressed and then released
+ * over the model. A press and release that picked different entities fires on their nearest
+ * common ancestor instead, as in the DOM. `detail` carries the click count, so a double click
+ * arrives as a click whose `detail` is 2.
  * @fires {Event} load - Fired each time a container asset finishes instantiating, including
  * re-instantiation after `asset` changes. Does not bubble — listen on this element, or use a
  * capture-phase listener on an ancestor.
@@ -435,7 +441,7 @@ class ModelElement extends EntityOwnerElement {
     }
 
     static get observedAttributes() {
-        return ['asset', 'enabled', 'name', 'position', 'rotation', 'scale', 'tags', ...POINTER_ATTRIBUTES];
+        return ['asset', 'enabled', 'name', 'position', 'rotation', 'scale', 'tags', ...EVENT_ATTRIBUTES];
     }
 
     attributeChangedCallback(name: string, _oldValue: string | null, newValue: string | null) {
@@ -466,6 +472,7 @@ class ModelElement extends EntityOwnerElement {
             case 'onpointerdown':
             case 'onpointerup':
             case 'onpointermove':
+            case 'onclick':
                 this._updateInlineHandler(name, newValue);
                 break;
         }

package/src/node.ts

@@ -2,7 +2,7 @@ import type { Entity, EventHandle, GraphNode, Material, MeshInstance, Quat, Rend
 import { Vec3 } from 'playcanvas';
 
 import { ComponentElement } from './components/component';
-import { EntityBaseElement, POINTER_ATTRIBUTES } from './entity-base';
+import { EntityBaseElement, EVENT_ATTRIBUTES } from './entity-base';
 import { buildDescendantEntities } from './entity-owner';
 import type { EntityOwnerElement } from './entity-owner';
 import { MaterialElement } from './material';
@@ -193,11 +193,17 @@ const levenshtein = (a: string, b: string): number => {
  * node.
  * @attribute {string} onpointerup - Script to run when a pointer button is released over the
  * node.
+ * @attribute {string} onclick - Script to run when the node is clicked: a primary pointer
+ * button pressed and then released over it.
  * @fires {PointerEvent} pointerenter - Fired when the pointer moves onto the node.
  * @fires {PointerEvent} pointerleave - Fired when the pointer moves off the node.
  * @fires {PointerEvent} pointermove - Fired when the pointer moves over the node.
  * @fires {PointerEvent} pointerdown - Fired when a pointer button is pressed over the node.
  * @fires {PointerEvent} pointerup - Fired when a pointer button is released over the node.
+ * @fires {PointerEvent} click - Fired when a primary pointer button is pressed and then released
+ * over the node. A press and release that picked different entities fires on their nearest
+ * common ancestor instead, as in the DOM. `detail` carries the click count, so a double click
+ * arrives as a click whose `detail` is 2.
  */
 class NodeElement extends EntityBaseElement {
     private _name = '';
@@ -933,7 +939,7 @@ class NodeElement extends EntityBaseElement {
             'rotation',
             'scale',
             'tags',
-            ...POINTER_ATTRIBUTES
+            ...EVENT_ATTRIBUTES
         ];
     }
 
@@ -982,6 +988,7 @@ class NodeElement extends EntityBaseElement {
             case 'onpointerdown':
             case 'onpointerup':
             case 'onpointermove':
+            case 'onclick':
                 this._updateInlineHandler(name, newValue);
                 break;
         }

package/src/scene.ts

@@ -11,9 +11,15 @@ import { parseColor, parseEnum, parseNumber, parseVec3 } from './parse';
  * {@link HTMLElement} interface.
  *
  * @elementSummary The `<pc-scene>` element holds the entity hierarchy the application renders,
- * along with the scene-wide fog and gravity settings. Must be a direct child of `<pc-app>`.
+ * along with the scene-wide fog, exposure and gravity settings. Must be a direct child of
+ * `<pc-app>`.
  */
 class SceneElement extends AsyncElement {
+    /**
+     * The exposure of the scene.
+     */
+    private _exposure = 1;
+
     /**
      * The fog type of the scene.
      */
@@ -96,6 +102,8 @@ class SceneElement extends AsyncElement {
 
     private _updateSceneSettings() {
         if (this._scene) {
+            this._scene.exposure = this._exposure;
+
             this._scene.fog.type = this._fog;
             this._scene.fog.color = this._fogColor;
             this._scene.fog.density = this._fogDensity;
@@ -117,6 +125,26 @@ class SceneElement extends AsyncElement {
         this.closestApp?.app?.systems.rigidbody?.gravity.copy(value);
     }
 
+    /**
+     * Sets the exposure of the scene, which tweaks the overall brightness of the rendered image.
+     * Ignored if the scene is using physical units. Defaults to 1.
+     * @param value - The exposure.
+     */
+    set exposure(value: number) {
+        this._exposure = value;
+        if (this.scene) {
+            this.scene.exposure = value;
+        }
+    }
+
+    /**
+     * Gets the exposure of the scene.
+     * @returns The exposure.
+     */
+    get exposure() {
+        return this._exposure;
+    }
+
     /**
      * Sets the fog type of the scene. Can be `none`, `linear`, `exp` or `exp2`. Defaults to
      * `none`.
@@ -233,11 +261,14 @@ class SceneElement extends AsyncElement {
     }
 
     static get observedAttributes() {
-        return ['fog', 'fog-color', 'fog-density', 'fog-start', 'fog-end', 'gravity'];
+        return ['exposure', 'fog', 'fog-color', 'fog-density', 'fog-start', 'fog-end', 'gravity'];
     }
 
     attributeChangedCallback(name: string, _oldValue: string | null, newValue: string | null) {
         switch (name) {
+            case 'exposure':
+                this.exposure = parseNumber(newValue, 1, name);
+                break;
             case 'fog':
                 this.fog = parseEnum(newValue, ['none', 'linear', 'exp', 'exp2'], 'none', name);
                 break;