@playcanvas/web-components 0.15.0 → 0.17.0

package/src/entity.ts

@@ -1,36 +1,9 @@
-import type { AppBase } from 'playcanvas';
-import { Entity, Vec3 } from 'playcanvas';
+import { Vec3 } from 'playcanvas';
 
-import { EntityBaseElement, POINTER_ATTRIBUTES } from './entity-base';
+import { POINTER_ATTRIBUTES } from './entity-base';
+import { buildDescendantEntities, EntityOwnerElement } from './entity-owner';
 import { parseBool, parseTags, parseVec3 } from './parse';
 
-/**
- * Creates and parents the entities of every descendant `<pc-entity>` of `root`, in two passes so
- * that no parent's existence depends on document order. Called wherever a subtree could not build
- * itself: an element inserted into an application that is already running, and a `<pc-node>` whose
- * children waited for it to bind.
- *
- * Descendants that are not yet custom elements are skipped, because there is nothing useful to do
- * for them and reaching for `_createEntity` would throw. A subtree cloned from a `<template>`
- * arrives entirely unupgraded — template content lives in an inert document, where custom element
- * definitions are never looked up — and appending the clone upgrades its elements in tree order,
- * an element before its descendants. So a sweep from an element's own `connectedCallback` sees
- * plain `HTMLElement`s below it. Each becomes an `EntityElement` moments later and its own
- * `connectedCallback` creates and parents it, by which time the ancestor it parents under has its
- * entity — the same guarantee tree order gives this sweep.
- *
- * @param root - The element whose descendant entities to build.
- * @param app - The application to create the entities in.
- * @internal
- */
-export const buildDescendantEntities = (root: Element, app: AppBase) => {
-    const children = Array.from(root.querySelectorAll('pc-entity')).filter(
-        (child): child is EntityElement => child instanceof EntityElement
-    );
-    children.forEach((child) => child._createEntity(app));
-    children.forEach((child) => child._buildHierarchy(app));
-};
-
 /**
  * The EntityElement interface provides properties and methods for manipulating
  * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-entity/ | `<pc-entity>`} elements.
@@ -42,6 +15,12 @@ export const buildDescendantEntities = (root: Element, app: AppBase) => {
  * them, registered either with {@link addEventListener} or with the matching inline `onpointer*`
  * attribute.
  *
+ * @attribute {boolean} enabled - The enabled state of the entity.
+ * @attribute {string} name - The name of the entity.
+ * @attribute {string} position - The position of the entity.
+ * @attribute {string} rotation - The rotation of the entity.
+ * @attribute {string} scale - The scale of the entity.
+ * @attribute {string} tags - The tags of the entity.
  * @attribute {string} onpointerenter - Script to run when the pointer moves onto the entity.
  * @attribute {string} onpointerleave - Script to run when the pointer moves off the entity.
  * @attribute {string} onpointermove - Script to run when the pointer moves over the entity.
@@ -55,129 +34,7 @@ export const buildDescendantEntities = (root: Element, app: AppBase) => {
  * @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 EntityBaseElement {
-    /**
-     * Whether the entity is enabled.
-     */
-    private _enabled = true;
-
-    /**
-     * The name of the entity.
-     */
-    private _name = 'Untitled';
-
-    /**
-     * The position of the entity.
-     */
-    private _position = new Vec3();
-
-    /**
-     * The rotation of the entity.
-     */
-    private _rotation = new Vec3();
-
-    /**
-     * The scale of the entity.
-     */
-    private _scale = new Vec3(1, 1, 1);
-
-    /**
-     * The tags of the entity.
-     */
-    private _tags: string[] = [];
-
-    /**
-     * Whether the hierarchy has been built for this entity.
-     */
-    private _built = false;
-
-    /**
-     * 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.
-     *
-     * @param app - The application to create the entity in.
-     * @internal
-     */
-    _createEntity(app: AppBase) {
-        // Guard against double creation. When a subtree is inserted at runtime (e.g. cloning a
-        // `<template>`), an ancestor's connectedCallback eagerly creates descendant entities; the
-        // descendants' own connectedCallbacks would otherwise create them a second time.
-        if (this._entity) {
-            return;
-        }
-
-        // Seed from the cached fields rather than re-reading the attributes. Every observed
-        // attribute is routed through its property setter by attributeChangedCallback, so the field
-        // already holds the parsed attribute value - and it also holds anything assigned through the
-        // property API before the app booted, which reading the attribute back would discard.
-        const entity = new Entity(this._name, app);
-        this._entity = entity;
-
-        entity.enabled = this._enabled;
-        entity.setLocalPosition(this._position);
-        entity.setLocalEulerAngles(this._rotation);
-        entity.setLocalScale(this._scale);
-
-        if (this._tags.length > 0) {
-            entity.tags.add(this._tags);
-        }
-
-        // 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);
-    }
-
-    /**
-     * Handles the destruction of the backing entity. Resets the element so a later re-insertion
-     * starts clean: `_built` must be cleared alongside `_entity`, or _buildHierarchy would bail
-     * and a re-created entity would never be parented. Readiness is re-armed for the same
-     * reason — with the entity gone, a resolved ready promise would resume its awaiters against
-     * a null `entity`.
-     *
-     * @param entity - The entity that was destroyed.
-     */
-    private _onEntityDestroy(entity: Entity) {
-        this._unregisterEntity(entity);
-        this._entity = null;
-        this._built = false;
-        this._resetReady();
-    }
-
-    /**
-     * 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;
-
-        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 {
-            app.root.addChild(this.entity);
-        }
-
-        this._onReady();
-    }
-
+class EntityElement extends EntityOwnerElement {
     connectedCallback() {
         // Wait for app to be ready
         const closestApp = this.closestApp;
@@ -198,8 +55,11 @@ class EntityElement extends EntityBaseElement {
             this._createEntity(app);
             this._buildHierarchy(app);
 
-            // Handle any child entities that might exist
-            buildDescendantEntities(this, app);
+            // Handle any child entities that might exist. A build that deferred (an unresolved
+            // pc-node above) defers the whole subtree with it - the node's bind sweeps it.
+            if (this._built) {
+                buildDescendantEntities(this, app);
+            }
         }
     }
 
@@ -211,121 +71,6 @@ class EntityElement extends EntityBaseElement {
         this._entity?.destroy();
     }
 
-    /**
-     * Sets the enabled state of the entity.
-     * @param value - Whether the entity is enabled.
-     */
-    set enabled(value) {
-        this._enabled = value;
-        if (this.entity) {
-            this.entity.enabled = value;
-        }
-    }
-
-    /**
-     * Gets the enabled state of the entity.
-     * @returns Whether the entity is enabled.
-     */
-    get enabled() {
-        return this._enabled;
-    }
-
-    /**
-     * Sets the name of the entity.
-     * @param value - The name of the entity.
-     */
-    set name(value) {
-        this._name = value;
-        if (this.entity) {
-            this.entity.name = value;
-        }
-    }
-
-    /**
-     * Gets the name of the entity.
-     * @returns The name of the entity.
-     */
-    get name() {
-        return this._name;
-    }
-
-    /**
-     * Sets the position of the entity.
-     * @param value - The position of the entity.
-     */
-    set position(value) {
-        this._position = value;
-        if (this.entity) {
-            this.entity.setLocalPosition(this._position);
-        }
-    }
-
-    /**
-     * Gets the position of the entity.
-     * @returns The position of the entity.
-     */
-    get position() {
-        return this._position;
-    }
-
-    /**
-     * Sets the rotation of the entity.
-     * @param value - The rotation of the entity.
-     */
-    set rotation(value) {
-        this._rotation = value;
-        if (this.entity) {
-            this.entity.setLocalEulerAngles(this._rotation);
-        }
-    }
-
-    /**
-     * Gets the rotation of the entity.
-     * @returns The rotation of the entity.
-     */
-    get rotation() {
-        return this._rotation;
-    }
-
-    /**
-     * Sets the scale of the entity.
-     * @param value - The scale of the entity.
-     */
-    set scale(value) {
-        this._scale = value;
-        if (this.entity) {
-            this.entity.setLocalScale(this._scale);
-        }
-    }
-
-    /**
-     * Gets the scale of the entity.
-     * @returns The scale of the entity.
-     */
-    get scale() {
-        return this._scale;
-    }
-
-    /**
-     * Sets the tags of the entity.
-     * @param value - The tags of the entity.
-     */
-    set tags(value) {
-        this._tags = value;
-        if (this.entity) {
-            this.entity.tags.clear();
-            this.entity.tags.add(this._tags);
-        }
-    }
-
-    /**
-     * Gets the tags of the entity.
-     * @returns The tags of the entity.
-     */
-    get tags() {
-        return this._tags;
-    }
-
     static get observedAttributes() {
         return ['enabled', 'name', 'position', 'rotation', 'scale', 'tags', ...POINTER_ATTRIBUTES];
     }

package/src/index.ts

@@ -9,36 +9,39 @@
 
 /* eslint-disable import-x/order */
 
-// Note that order matters here (e.g. pc-entity must be defined before components)
+// Note that order matters here (e.g. pc-entity and pc-model must be defined before components)
 import { AsyncElement, whenReady } from './async-element';
-import { ModuleElement } from './module';
+import { WasmElement } from './wasm';
 import { AppElement } from './app';
 import { EntityElement } from './entity';
+import { ModelElement } from './model';
 import { AssetElement } from './asset';
-import { ListenerComponentElement } from './components/listener-component';
+import { AnimComponentElement } from './components/anim-component';
+import { AnimClipElement } from './components/anim-clip';
+import { AudioListenerComponentElement } from './components/audio-listener-component';
 import { ButtonComponentElement } from './components/button-component';
 import { CameraComponentElement } from './components/camera-component';
 import { CollisionComponentElement } from './components/collision-component';
 import { ComponentElement } from './components/component';
 import { ElementComponentElement } from './components/element-component';
 import { JointComponentElement } from './components/joint-component';
-import { LayoutChildComponentElement } from './components/layoutchild-component';
-import { LayoutGroupComponentElement } from './components/layoutgroup-component';
+import { LayoutChildComponentElement } from './components/layout-child-component';
+import { LayoutGroupComponentElement } from './components/layout-group-component';
 import { LightComponentElement } from './components/light-component';
-import { ParticleSystemComponentElement } from './components/particlesystem-component';
+import { ParticleSystemComponentElement } from './components/particle-system-component';
 import { RenderComponentElement } from './components/render-component';
-import { RigidBodyComponentElement } from './components/rigidbody-component';
+import { RigidBodyComponentElement } from './components/rigid-body-component';
 import { ScreenComponentElement } from './components/screen-component';
 import { ScrollbarComponentElement } from './components/scrollbar-component';
-import { ScrollViewComponentElement } from './components/scrollview-component';
+import { ScrollViewComponentElement } from './components/scroll-view-component';
 import { ScriptComponentElement } from './components/script-component';
-import { ScriptElement } from './components/script';
+import { ScriptInstanceElement } from './components/script-instance';
 import { SoundComponentElement } from './components/sound-component';
 import { SoundSlotElement } from './components/sound-slot';
 import { GSplatComponentElement } from './components/gsplat-component';
 import { EntityBaseElement } from './entity-base';
+import { EntityOwnerElement } from './entity-owner';
 import { MaterialElement } from './material';
-import { ModelElement } from './model';
 import { NodeElement } from './node';
 import { SceneElement } from './scene';
 import { SkyElement } from './sky';
@@ -58,6 +61,8 @@ declare global {
     }
 
     interface HTMLElementTagNameMap {
+        'pc-anim': AnimComponentElement;
+        'pc-anim-clip': AnimClipElement;
         'pc-app': AppElement;
         'pc-asset': AssetElement;
         'pc-button': ButtonComponentElement;
@@ -67,35 +72,37 @@ declare global {
         'pc-entity': EntityElement;
         'pc-gsplat': GSplatComponentElement;
         'pc-joint': JointComponentElement;
-        'pc-layoutchild': LayoutChildComponentElement;
-        'pc-layoutgroup': LayoutGroupComponentElement;
+        'pc-layout-child': LayoutChildComponentElement;
+        'pc-layout-group': LayoutGroupComponentElement;
         'pc-light': LightComponentElement;
-        'pc-listener': ListenerComponentElement;
+        'pc-audio-listener': AudioListenerComponentElement;
         'pc-material': MaterialElement;
         'pc-model': ModelElement;
-        'pc-module': ModuleElement;
+        'pc-wasm': WasmElement;
         'pc-node': NodeElement;
-        'pc-particles': ParticleSystemComponentElement;
+        'pc-particle-system': ParticleSystemComponentElement;
         'pc-render': RenderComponentElement;
-        'pc-rigidbody': RigidBodyComponentElement;
+        'pc-rigid-body': RigidBodyComponentElement;
         'pc-scene': SceneElement;
         'pc-screen': ScreenComponentElement;
-        'pc-script': ScriptElement;
-        'pc-scripts': ScriptComponentElement;
+        'pc-script-instance': ScriptInstanceElement;
+        'pc-script': ScriptComponentElement;
         'pc-scrollbar': ScrollbarComponentElement;
-        'pc-scrollview': ScrollViewComponentElement;
+        'pc-scroll-view': ScrollViewComponentElement;
         'pc-sky': SkyElement;
-        'pc-sound': SoundSlotElement;
-        'pc-sounds': SoundComponentElement;
+        'pc-sound-slot': SoundSlotElement;
+        'pc-sound': SoundComponentElement;
     }
 }
 
 export {
     AsyncElement,
-    ModuleElement,
+    WasmElement,
     AppElement,
     EntityElement,
     AssetElement,
+    AnimComponentElement,
+    AnimClipElement,
     ButtonComponentElement,
     CameraComponentElement,
     CollisionComponentElement,
@@ -106,18 +113,19 @@ export {
     LayoutGroupComponentElement,
     ParticleSystemComponentElement,
     LightComponentElement,
-    ListenerComponentElement,
+    AudioListenerComponentElement,
     RenderComponentElement,
     RigidBodyComponentElement,
     ScreenComponentElement,
     ScrollbarComponentElement,
     ScrollViewComponentElement,
     ScriptComponentElement,
-    ScriptElement,
+    ScriptInstanceElement,
     SoundComponentElement,
     SoundSlotElement,
     GSplatComponentElement,
     EntityBaseElement,
+    EntityOwnerElement,
     MaterialElement,
     ModelElement,
     NodeElement,