@playcanvas/web-components 0.11.1 → 0.12.0

package/src/async-element.ts

@@ -1,5 +1,5 @@
 import type { AppElement } from './app';
-import type { EntityElement } from './entity';
+import type { EntityBaseElement } from './entity-base';
 
 /**
  * Base class for all PlayCanvas Web Components that initialize asynchronously.
@@ -33,12 +33,13 @@ class AsyncElement extends HTMLElement {
     }
 
     /**
-     * The nearest ancestor `<pc-entity>` element, or `null` if this element has no `<pc-entity>`
-     * ancestor. The search starts at the parent, so an element never resolves to itself.
-     * @returns The closest entity element, or `null`.
+     * The nearest ancestor element that fronts an entity — `<pc-entity>` or `<pc-node>` — or
+     * `null` if this element has no such ancestor. The search starts at the parent, so an element
+     * never resolves to itself.
+     * @returns The closest entity-fronting element, or `null`.
      */
-    get closestEntity(): EntityElement | null {
-        return (this.parentElement?.closest('pc-entity') as EntityElement | null) ?? null;
+    get closestEntity(): EntityBaseElement | null {
+        return (this.parentElement?.closest('pc-entity, pc-node') as EntityBaseElement | null) ?? null;
     }
 
     /**

package/src/components/collision-component.ts

@@ -11,6 +11,12 @@ import { ComponentElement } from './component';
  * The CollisionComponentElement interface also inherits the properties and methods of the
  * {@link HTMLElement} interface.
  *
+ * For `type="mesh"`, the collision geometry defaults to the host entity's own render component
+ * (its render asset) — a collider matching the visible mesh, which is what a mesh collider on a
+ * glTF node means. The default resolves each time the component applies, so a `pc-node` that
+ * 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.
+ *
  * @category Components
  */
 class CollisionComponentElement extends ComponentElement {
@@ -48,6 +54,34 @@ class CollisionComponentElement extends ComponentElement {
         };
     }
 
+    protected initComponent() {
+        this._applyMeshGeometryDefault();
+    }
+
+    /**
+     * Defaults a mesh collider's geometry to the host entity's own render component. The
+     * engine's mesh collider only works with explicitly supplied geometry, and the element has
+     * 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.
+     */
+    private _applyMeshGeometryDefault() {
+        const component = this.component;
+        if (!component || this._type !== 'mesh' || component.renderAsset !== null) {
+            return;
+        }
+
+        const asset = component.entity.render?.asset ?? null;
+        if (asset === null) {
+            console.warn(
+                `pc-collision type="mesh" on '${component.entity.name}' found no asset-backed render component to take geometry from - collider has no shape`
+            );
+            return;
+        }
+        component.renderAsset = asset;
+    }
+
     /**
      * Gets the underlying PlayCanvas collision component.
      * @returns The collision component.
@@ -137,6 +171,7 @@ class CollisionComponentElement extends ComponentElement {
         this._type = value;
         if (this.component) {
             this.component.type = value;
+            this._applyMeshGeometryDefault();
         }
     }
 

package/src/components/component.ts

@@ -2,6 +2,7 @@ import type { Component } from 'playcanvas';
 
 import type { AppElement } from '../app';
 import { AsyncElement } from '../async-element';
+import type { EntityBaseElement } from '../entity-base';
 import { parseBool } from '../parse';
 
 /**
@@ -18,6 +19,18 @@ class ComponentElement extends AsyncElement {
 
     private _appElement: AppElement | null = null;
 
+    /**
+     * The element hosting this component, held so the host's readiness cycles can be observed
+     * even after `closestEntity` would no longer resolve (during teardown).
+     */
+    private _hostElement: EntityBaseElement | null = null;
+
+    /**
+     * The listener re-applying this component when the host's readiness cycles. Held for
+     * removal on disconnect.
+     */
+    private _hostReadyListener: EventListener | null = null;
+
     /**
      * Incremented on every connect and disconnect. connectedCallback captures the value on entry
      * and abandons itself wherever it resumes from an await if the value has moved on — so a
@@ -49,6 +62,44 @@ class ComponentElement extends AsyncElement {
         return {};
     }
 
+    /**
+     * Creates the component on the host's current entity, removing it first from a previous
+     * entity that is still alive (a retargeted `<pc-node>` moves its decorations with it). When
+     * the entity already has a component of this type — a glTF node arriving with its authored
+     * `render` component, say — warns and leaves `component` null. The element-level warning is
+     * load-bearing: the engine's own duplicate-addComponent warning is Debug-stripped from
+     * production builds, which would otherwise leave a silent null.
+     */
+    private _applyComponent() {
+        const entity = this._hostElement?.entity ?? null;
+        if (this._component && this._component.entity === entity) {
+            return;
+        }
+
+        // A retarget leaves the previous component on a still-live entity - remove it so the
+        // decoration follows the element, or vanishes with a dissolved binding. A destroyed
+        // entity took its components with it.
+        const previous = this._component;
+        if (previous?.entity && previous.entity.c[this._componentName] === previous) {
+            previous.entity.removeComponent(this._componentName);
+        }
+        this._component = null;
+
+        if (!entity) {
+            return;
+        }
+
+        if (entity.c[this._componentName]) {
+            const label = this.id ? ` '${this.id}'` : '';
+            console.warn(
+                `${this.tagName.toLowerCase()}${label} - '${entity.name}' already has a '${this._componentName}' component - component not added`
+            );
+            return;
+        }
+
+        this._component = entity.addComponent(this._componentName, this.getInitialComponentData());
+    }
+
     private async _addComponent() {
         const generation = this._connectionGeneration;
 
@@ -71,9 +122,42 @@ class ComponentElement extends AsyncElement {
             return;
         }
 
-        // Add the component to the entity
-        const data = this.getInitialComponentData();
-        this._component = entityElement.entity!.addComponent(this._componentName, data);
+        this._hostElement = entityElement;
+        this._applyComponent();
+
+        // Re-apply when the host's readiness cycles without this element disconnecting: a
+        // `<pc-node>` rebinding after its model reloads or retargets, or a re-created entity.
+        // The 'ready' event bubbles, so events from descendants pass through this host - only
+        // the host's own cycles count. Readiness is cycled here too, so decorations one level
+        // down re-apply the same way.
+        this._hostReadyListener = (event: Event) => {
+            if (event.target !== this._hostElement) {
+                return;
+            }
+            if (generation !== this._connectionGeneration) {
+                return;
+            }
+            this._hostCycled();
+        };
+        entityElement.addEventListener('ready', this._hostReadyListener);
+    }
+
+    /**
+     * Re-evaluates this component against the host's current entity: applied to a new entity,
+     * moved from a still-live old one, or removed when the host no longer fronts an entity at
+     * all. Readiness follows - it cycles with a re-application and stays unresolved while the
+     * host is unbound. Called by the host-ready listener, and directly by a `<pc-node>`
+     * dissolving its binding: the one transition that fires no ready event to ride.
+     *
+     * @internal
+     */
+    _hostCycled() {
+        this._resetReady();
+        this._applyComponent();
+        if (this._hostElement?.entity) {
+            this.initComponent();
+            this._onReady();
+        }
     }
 
     /**
@@ -111,6 +195,12 @@ class ComponentElement extends AsyncElement {
         // Invalidate any connectedCallback still suspended on an await
         this._connectionGeneration++;
 
+        if (this._hostElement && this._hostReadyListener) {
+            this._hostElement.removeEventListener('ready', this._hostReadyListener);
+        }
+        this._hostElement = null;
+        this._hostReadyListener = null;
+
         // Remove the component when the element is disconnected. Skip this when the owning
         // application has already been destroyed — removing a <pc-app> disconnects it before
         // its children, taking the component systems with it.

package/src/entity-base.ts

@@ -0,0 +1,136 @@
+import type { Entity } from 'playcanvas';
+
+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.
+ * @ignore
+ */
+const POINTER_ATTRIBUTES = [
+    'onpointerenter',
+    'onpointerleave',
+    'onpointerdown',
+    'onpointerup',
+    'onpointermove'
+] as const;
+
+/**
+ * The base class for elements that front an engine {@link Entity}: `<pc-entity>`, which creates
+ * one, and `<pc-node>`, which binds to one inside a model's instantiated hierarchy. It carries
+ * what both need — the `entity` contract, registration with the owning application (which joins
+ * picked scene nodes back to elements by identity, never by name), and the pointer listener
+ * bookkeeping that lets the application lazily attach its canvas handlers.
+ */
+class EntityBaseElement extends AsyncElement {
+    protected _entity: Entity | null = null;
+
+    /**
+     * The application element this entity is registered with, cached at registration time so the
+     * entity can be unregistered even once this element has left the DOM.
+     */
+    protected _appElement: AppElement | null = null;
+
+    /**
+     * The pointer event listeners for the entity.
+     */
+    private _listeners: Record<string, EventListener[]> = {};
+
+    /**
+     * The event types for which an inline `onpointer*` attribute is currently present.
+     */
+    private _inlineHandlerTypes = new Set<string>();
+
+    /**
+     * The PlayCanvas entity instance. `null` until the element is ready, and again once the
+     * entity is gone — await {@link whenReady} or the element's `ready()` promise before
+     * accessing it.
+     * @returns The entity instance, or `null`.
+     */
+    get entity(): Entity | null {
+        return this._entity;
+    }
+
+    /**
+     * Registers `entity` as this element's backing entity with the owning application, which
+     * joins engine nodes back to elements by identity (never by name).
+     *
+     * @param entity - The entity to register.
+     */
+    protected _registerEntity(entity: Entity) {
+        this._appElement = this.closestApp;
+        this._appElement?._registerEntityElement(entity, this);
+    }
+
+    /**
+     * Removes the registration for `entity`.
+     *
+     * @param entity - The entity to unregister.
+     */
+    protected _unregisterEntity(entity: Entity) {
+        this._appElement?._unregisterEntityElement(entity);
+        this._appElement = null;
+    }
+
+    /**
+     * Tracks whether an inline `onpointer*` 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 addEventListener}, the connect/disconnect
+     * bookkeeping that lets the application lazily attach its canvas pointer handlers must be
+     * kept in sync here.
+     *
+     * @param name - The attribute name (e.g. 'onpointerdown').
+     * @param value - The attribute value, or `null` when the attribute has been removed.
+     */
+    protected _updateInlineHandler(name: string, value: string | null) {
+        const type = name.substring(2);
+        const had = this._inlineHandlerTypes.has(type);
+        const has = value !== null;
+
+        if (has && !had) {
+            this._inlineHandlerTypes.add(type);
+            this.dispatchEvent(new CustomEvent(`${type}:connect`, { bubbles: true }));
+        } else if (!has && had) {
+            this._inlineHandlerTypes.delete(type);
+            this.dispatchEvent(new CustomEvent(`${type}:disconnect`, { bubbles: true }));
+        }
+    }
+
+    addEventListener(type: string, listener: EventListener, options?: boolean | AddEventListenerOptions) {
+        if (!this._listeners[type]) {
+            this._listeners[type] = [];
+        }
+        this._listeners[type].push(listener);
+        super.addEventListener(type, listener, options);
+        if (type.startsWith('pointer')) {
+            this.dispatchEvent(new CustomEvent(`${type}:connect`, { bubbles: true }));
+        }
+    }
+
+    removeEventListener(type: string, listener: EventListener, options?: boolean | EventListenerOptions) {
+        if (this._listeners[type]) {
+            this._listeners[type] = this._listeners[type].filter((l) => l !== listener);
+        }
+        super.removeEventListener(type, listener, options);
+        if (type.startsWith('pointer')) {
+            this.dispatchEvent(new CustomEvent(`${type}:disconnect`, { bubbles: true }));
+        }
+    }
+
+    /**
+     * Whether the element has a listener for an event type, registered either with
+     * {@link addEventListener} or with the matching inline `onpointer*` attribute. Read by the
+     * containing `<pc-app>` element to gate pointer event synthesis.
+     *
+     * @param type - The event type.
+     * @returns Whether a listener is registered.
+     * @internal
+     */
+    _hasListeners(type: string): boolean {
+        return Boolean(this._listeners[type]?.length) || this._inlineHandlerTypes.has(type);
+    }
+}
+
+export { EntityBaseElement, POINTER_ATTRIBUTES };

package/src/entity.ts

@@ -1,8 +1,7 @@
 import type { AppBase } from 'playcanvas';
 import { Entity, Vec3 } from 'playcanvas';
 
-import type { AppElement } from './app';
-import { AsyncElement } from './async-element';
+import { EntityBaseElement, POINTER_ATTRIBUTES } from './entity-base';
 import { parseBool, parseTags, parseVec3 } from './parse';
 
 /**
@@ -29,7 +28,7 @@ import { parseBool, parseTags, parseVec3 } from './parse';
  * @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.
  */
-class EntityElement extends AsyncElement {
+class EntityElement extends EntityBaseElement {
     /**
      * Whether the entity is enabled.
      */
@@ -60,39 +59,11 @@ class EntityElement extends AsyncElement {
      */
     private _tags: string[] = [];
 
-    /**
-     * The pointer event listeners for the entity.
-     */
-    private _listeners: Record<string, EventListener[]> = {};
-
-    /**
-     * The event types for which an inline `onpointer*` attribute is currently present.
-     */
-    private _inlineHandlerTypes = new Set<string>();
-
     /**
      * Whether the hierarchy has been built for this entity.
      */
     private _built = false;
 
-    private _entity: Entity | null = null;
-
-    /**
-     * The application element this entity is registered with, cached at creation time so the
-     * entity can be unregistered even once this element has left the DOM.
-     */
-    private _appElement: AppElement | null = null;
-
-    /**
-     * The PlayCanvas entity instance. `null` until the element is ready, and again once it has
-     * been removed from the document — await {@link whenReady} or the element's `ready()`
-     * promise before accessing it.
-     * @returns The entity instance, or `null`.
-     */
-    get entity(): Entity | null {
-        return this._entity;
-    }
-
     /**
      * Creates the backing entity. Called by the containing `<pc-app>` element during its boot
      * sweep, and on connection for elements inserted while the application is already running.
@@ -124,13 +95,11 @@ class EntityElement extends AsyncElement {
             entity.tags.add(this._tags);
         }
 
-        // Register with the owning application, which joins engine nodes back to elements by
-        // identity (never by name), and hook the entity's destruction. The engine fires 'destroy'
-        // for every entity in a destroyed subtree, so the element learns of its entity's death no
-        // matter who causes it: this element, an ancestor, the whole application, or a user
-        // script calling entity.destroy().
-        this._appElement = this.closestApp;
-        this._appElement?._registerEntityElement(entity, this);
+        // Register with the owning application and hook the entity's destruction. The engine
+        // fires 'destroy' for every entity in a destroyed subtree, so the element learns of its
+        // entity's death no matter who causes it: this element, an ancestor, the whole
+        // application, or a user script calling entity.destroy().
+        this._registerEntity(entity);
         entity.once('destroy', this._onEntityDestroy, this);
     }
 
@@ -144,27 +113,35 @@ class EntityElement extends AsyncElement {
      * @param entity - The entity that was destroyed.
      */
     private _onEntityDestroy(entity: Entity) {
-        this._appElement?._unregisterEntityElement(entity);
-        this._appElement = null;
+        this._unregisterEntity(entity);
         this._entity = null;
         this._built = false;
         this._resetReady();
     }
 
     /**
-     * Parents the backing entity: under the entity of the nearest ancestor `<pc-entity>` when
-     * there is one, and under the application root otherwise. Called by the containing `<pc-app>`
-     * element once a sweep has created every entity, so a parent's existence never depends on
-     * document order.
+     * Parents the backing entity: under the entity of the nearest ancestor `<pc-entity>` or
+     * `<pc-node>` when there is one, and under the application root otherwise. Called by the
+     * containing `<pc-app>` element once a sweep has created every entity, so a parent's
+     * existence never depends on document order.
      *
      * @param app - The application whose root adopts parentless entities.
      * @internal
      */
     _buildHierarchy(app: AppBase) {
         if (!this.entity || this._built) return;
-        this._built = true;
 
         const closestEntity = this.closestEntity;
+
+        // A host element without an entity is an unresolved `<pc-node>`: building now would
+        // mis-anchor this entity to the application root while the host is still resolving.
+        // Stay unbuilt - the host drives this subtree itself once it binds.
+        if (closestEntity && !closestEntity.entity) {
+            return;
+        }
+
+        this._built = true;
+
         if (closestEntity?.entity) {
             closestEntity.entity.addChild(this.entity);
         } else {
@@ -328,45 +305,8 @@ class EntityElement extends AsyncElement {
         return this._tags;
     }
 
-    /**
-     * Tracks whether an inline `onpointer*` 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 addEventListener}, the connect/disconnect
-     * bookkeeping that lets the application lazily attach its canvas pointer handlers must be
-     * kept in sync here.
-     *
-     * @param name - The attribute name (e.g. 'onpointerdown').
-     * @param value - The attribute value, or `null` when the attribute has been removed.
-     */
-    private _updateInlineHandler(name: string, value: string | null) {
-        const type = name.substring(2);
-        const had = this._inlineHandlerTypes.has(type);
-        const has = value !== null;
-
-        if (has && !had) {
-            this._inlineHandlerTypes.add(type);
-            this.dispatchEvent(new CustomEvent(`${type}:connect`, { bubbles: true }));
-        } else if (!has && had) {
-            this._inlineHandlerTypes.delete(type);
-            this.dispatchEvent(new CustomEvent(`${type}:disconnect`, { bubbles: true }));
-        }
-    }
-
     static get observedAttributes() {
-        return [
-            'enabled',
-            'name',
-            'position',
-            'rotation',
-            'scale',
-            'tags',
-            'onpointerenter',
-            'onpointerleave',
-            'onpointerdown',
-            'onpointerup',
-            'onpointermove'
-        ];
+        return ['enabled', 'name', 'position', 'rotation', 'scale', 'tags', ...POINTER_ATTRIBUTES];
     }
 
     attributeChangedCallback(name: string, _oldValue: string | null, newValue: string | null) {
@@ -398,40 +338,6 @@ class EntityElement extends AsyncElement {
                 break;
         }
     }
-
-    addEventListener(type: string, listener: EventListener, options?: boolean | AddEventListenerOptions) {
-        if (!this._listeners[type]) {
-            this._listeners[type] = [];
-        }
-        this._listeners[type].push(listener);
-        super.addEventListener(type, listener, options);
-        if (type.startsWith('pointer')) {
-            this.dispatchEvent(new CustomEvent(`${type}:connect`, { bubbles: true }));
-        }
-    }
-
-    removeEventListener(type: string, listener: EventListener, options?: boolean | EventListenerOptions) {
-        if (this._listeners[type]) {
-            this._listeners[type] = this._listeners[type].filter((l) => l !== listener);
-        }
-        super.removeEventListener(type, listener, options);
-        if (type.startsWith('pointer')) {
-            this.dispatchEvent(new CustomEvent(`${type}:disconnect`, { bubbles: true }));
-        }
-    }
-
-    /**
-     * Whether the element has a listener for an event type, registered either with
-     * {@link addEventListener} or with the matching inline `onpointer*` attribute. Read by the
-     * containing `<pc-app>` element to gate pointer event synthesis.
-     *
-     * @param type - The event type.
-     * @returns Whether a listener is registered.
-     * @internal
-     */
-    _hasListeners(type: string): boolean {
-        return Boolean(this._listeners[type]?.length) || this._inlineHandlerTypes.has(type);
-    }
 }
 
 customElements.define('pc-entity', EntityElement);

package/src/index.ts

@@ -35,8 +35,10 @@ import { ScriptElement } from './components/script';
 import { SoundComponentElement } from './components/sound-component';
 import { SoundSlotElement } from './components/sound-slot';
 import { GSplatComponentElement } from './components/gsplat-component';
+import { EntityBaseElement } from './entity-base';
 import { MaterialElement } from './material';
 import { ModelElement } from './model';
+import { NodeElement } from './node';
 import { SceneElement } from './scene';
 import { SkyElement } from './sky';
 
@@ -69,6 +71,7 @@ declare global {
         'pc-material': MaterialElement;
         'pc-model': ModelElement;
         'pc-module': ModuleElement;
+        'pc-node': NodeElement;
         'pc-particles': ParticleSystemComponentElement;
         'pc-render': RenderComponentElement;
         'pc-rigidbody': RigidBodyComponentElement;
@@ -110,8 +113,10 @@ export {
     SoundComponentElement,
     SoundSlotElement,
     GSplatComponentElement,
+    EntityBaseElement,
     MaterialElement,
     ModelElement,
+    NodeElement,
     SceneElement,
     SkyElement,
     whenReady

package/src/material.ts

@@ -542,12 +542,12 @@ class MaterialElement extends HTMLElement {
 
     /**
      * @param slot - The material property to write.
-     * @param texture - The loaded texture.
+     * @param texture - The loaded texture, applied with its sampler state untouched - anisotropy
+     * and friends belong to the `pc-asset`'s texture options.
      */
     private _applyMap(slot: TextureSlot, texture: Texture) {
         if (!this.material) return;
         this.material[slot] = texture;
-        texture.anisotropy = 4;
         this._scheduleUpdate();
     }