@playcanvas/web-components 0.13.1 → 0.15.0

package/src/entity-base.ts

@@ -6,9 +6,9 @@ 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
+ * @internal
  */
-const POINTER_ATTRIBUTES = [
+export const POINTER_ATTRIBUTES = [
     'onpointerenter',
     'onpointerleave',
     'onpointerdown',
@@ -133,4 +133,4 @@ class EntityBaseElement extends AsyncElement {
     }
 }
 
-export { EntityBaseElement, POINTER_ATTRIBUTES };
+export { EntityBaseElement };

package/src/entity.ts

@@ -4,6 +4,33 @@ import { Entity, Vec3 } from 'playcanvas';
 import { EntityBaseElement, POINTER_ATTRIBUTES } from './entity-base';
 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.
@@ -172,13 +199,7 @@ class EntityElement extends EntityBaseElement {
             this._buildHierarchy(app);
 
             // Handle any child entities that might exist
-            const childEntities = this.querySelectorAll<EntityElement>('pc-entity');
-            childEntities.forEach((child) => {
-                child._createEntity(app);
-            });
-            childEntities.forEach((child) => {
-                child._buildHierarchy(app);
-            });
+            buildDescendantEntities(this, app);
         }
     }
 

package/src/index.ts

@@ -21,6 +21,7 @@ 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 { LightComponentElement } from './components/light-component';
@@ -50,6 +51,7 @@ import type {
 
 declare global {
     interface HTMLElementEventMap {
+        break: CustomEvent;
         scriptattributeschange: ScriptAttributesChangeEvent;
         scriptenablechange: ScriptEnableChangeEvent;
         scriptnamechange: ScriptNameChangeEvent;
@@ -64,6 +66,7 @@ declare global {
         'pc-element': ElementComponentElement;
         'pc-entity': EntityElement;
         'pc-gsplat': GSplatComponentElement;
+        'pc-joint': JointComponentElement;
         'pc-layoutchild': LayoutChildComponentElement;
         'pc-layoutgroup': LayoutGroupComponentElement;
         'pc-light': LightComponentElement;
@@ -98,6 +101,7 @@ export {
     CollisionComponentElement,
     ComponentElement,
     ElementComponentElement,
+    JointComponentElement,
     LayoutChildComponentElement,
     LayoutGroupComponentElement,
     ParticleSystemComponentElement,
@@ -123,3 +127,5 @@ export {
 };
 
 export type { AsyncElementTagName } from './async-element';
+export type { HierarchyMaterial, HierarchyNode } from './model';
+export type { MaterialOverrides } from './node';

package/src/loading-bar.ts

@@ -8,8 +8,9 @@ const REMOVAL_DELAY_MS = 250;
  * All styling is inline, so the library injects no stylesheet. The colors and height resolve CSS
  * custom properties — `--pc-loading-bar-color`, `--pc-loading-bar-background` and
  * `--pc-loading-bar-height` — so a page can theme the bar from `pc-app` or `:root`.
+ * @internal
  */
-class LoadingBar {
+export class LoadingBar {
     private _track: HTMLDivElement;
 
     private _fill: HTMLDivElement;
@@ -118,5 +119,3 @@ class LoadingBar {
         this._track.remove();
     }
 }
-
-export { LoadingBar };

package/src/material.ts

@@ -251,6 +251,8 @@ class MaterialElement extends HTMLElement {
 
     private _metalnessMapUv = 0;
 
+    private _name = 'Untitled';
+
     private _normalMap = '';
 
     private _normalMapOffset = new Vec2(0, 0);
@@ -402,6 +404,7 @@ class MaterialElement extends HTMLElement {
         material.metalnessMapRotation = this._metalnessMapRotation;
         material.metalnessMapTiling = this._metalnessMapTiling;
         material.metalnessMapUv = this._metalnessMapUv;
+        material.name = this._name;
         material.normalMapOffset = this._normalMapOffset;
         material.normalMapRotation = this._normalMapRotation;
         material.normalMapTiling = this._normalMapTiling;
@@ -1615,6 +1618,28 @@ class MaterialElement extends HTMLElement {
         return this._metalnessMapUv;
     }
 
+    /**
+     * Sets the name of the material.
+     * @param value - The material name.
+     */
+    set name(value: string) {
+        this._name = value;
+        if (this.material) {
+            // A label rather than shader state, so no update() is scheduled
+            this.material.name = value;
+        }
+    }
+
+    /**
+     * Gets the name of the material - the label shown wherever materials surface by name, such
+     * as profilers, GPU captures and the assignments `pc-model.hierarchy()` reports. Purely a
+     * label: element references resolve through `id`.
+     * @returns The material name.
+     */
+    get name() {
+        return this._name;
+    }
+
     /**
      * Sets the id of the `pc-asset` to use as the normal map.
      * @param value - The asset id.
@@ -2243,6 +2268,7 @@ class MaterialElement extends HTMLElement {
             'metalness-map-rotation',
             'metalness-map-tiling',
             'metalness-map-uv',
+            'name',
             'normal-map',
             'normal-map-offset',
             'normal-map-rotation',
@@ -2444,6 +2470,9 @@ class MaterialElement extends HTMLElement {
             case 'metalness-map-uv':
                 this.metalnessMapUv = parseNumber(newValue, 0, name);
                 break;
+            case 'name':
+                this.name = newValue ?? 'Untitled';
+                break;
             case 'normal-map':
                 this.normalMap = newValue ?? '';
                 break;

package/src/model.ts

@@ -3,6 +3,101 @@ import type { ContainerResource, Entity, EventHandle } from 'playcanvas';
 import { useAsset } from './asset';
 import { AsyncElement } from './async-element';
 
+/**
+ * One material assignment of a {@link HierarchyNode} with a render component: a mesh instance's
+ * position within the component and the runtime name of its current material.
+ */
+type HierarchyMaterial = {
+    /** The mesh instance's position in the render component's `meshInstances` array. */
+    index: number;
+    /**
+     * The runtime name of the mesh instance's current material, reported as-is: the engine
+     * names an unnamed glTF material `Untitled`, and assigns a shared material named
+     * `defaultGlbMaterial` to a primitive authored without one — neither is a unique authored
+     * identifier. `null` when a script has cleared the assignment.
+     */
+    name: string | null;
+};
+
+/**
+ * One node of the tree returned by {@link ModelElement.hierarchy}. A plain-data snapshot —
+ * `JSON.stringify` serializes it — whose `toString()` renders the node's subtree as a printable
+ * tree.
+ */
+type HierarchyNode = {
+    /**
+     * The node's name as instantiated, which is the name `pc-node` binding resolves: the engine
+     * parser synthesizes `node_<index>` names for unnamed nodes and renames identically named
+     * siblings apart (`Wheel`, `Wheel1`, ...), so it can differ from the name authored in the
+     * source asset.
+     */
+    name: string;
+    /**
+     * The node's `/`-separated path below the model root — the path a `pc-node` bound to this
+     * node reports. The root's path is its own name.
+     */
+    path: string;
+    /**
+     * The node's position among identically named nodes in the model, counted in depth-first
+     * order over the whole tree: the match a `pc-node`'s `index` attribute selects when `name`
+     * alone is ambiguous.
+     */
+    index: number;
+    /** The types of the components attached to the node (e.g. 'render'), sorted. */
+    components: string[];
+    /**
+     * The material assignments of the node's render component, one entry per mesh instance in
+     * component order. Empty for a node without a render component.
+     */
+    materials: HierarchyMaterial[];
+    /** The node's children. */
+    children: HierarchyNode[];
+    /**
+     * Renders the subtree rooted at this node as a printable tree, one line per node: the name,
+     * `[index]` after a name that several nodes in the model share, the component types in
+     * parentheses, and the material names of a render component in braces.
+     */
+    toString(): string;
+};
+
+/**
+ * Formats one line of the printable hierarchy: the node's name, an `[index]` marker when the
+ * name is shared by several nodes in the model, the attached component types, and the material
+ * names of a render component.
+ *
+ * @param node - The node to format.
+ * @param counts - The number of nodes bearing each name.
+ * @returns The formatted line.
+ */
+const formatNode = (node: HierarchyNode, counts: ReadonlyMap<string, number>): string => {
+    const index = (counts.get(node.name) ?? 0) > 1 ? ` [${node.index}]` : '';
+    const components = node.components.length > 0 ? ` (${node.components.join(', ')})` : '';
+    // Braces rather than brackets: `[N]` already means a match index on this line
+    const materials =
+        node.materials.length > 0 ? ` {${node.materials.map((slot) => slot.name ?? 'null').join(', ')}}` : '';
+    return `${node.name}${index}${components}${materials}`;
+};
+
+/**
+ * Formats the printable form of a hierarchy subtree.
+ *
+ * @param root - The subtree root.
+ * @param counts - The number of nodes bearing each name.
+ * @returns The tree, one line per node.
+ */
+const formatHierarchy = (root: HierarchyNode, counts: ReadonlyMap<string, number>): string => {
+    const lines = [formatNode(root, counts)];
+    const walk = (node: HierarchyNode, prefix: string) => {
+        node.children.forEach((child, i) => {
+            const last = i === node.children.length - 1;
+            lines.push(`${prefix}${last ? '└─ ' : '├─ '}${formatNode(child, counts)}`);
+            walk(child, `${prefix}${last ? '   ' : '│  '}`);
+        });
+    };
+    walk(root, '');
+    return lines.join('\n');
+};
+
 /**
  * The ModelElement interface provides properties and methods for manipulating
  * {@link https://developer.playcanvas.com/user-manual/web-components/tags/pc-model/ | `<pc-model>`} elements.
@@ -55,6 +150,66 @@ class ModelElement extends AsyncElement {
         return this._entity;
     }
 
+    /**
+     * Returns a snapshot of the instantiated node tree, or `null` while there is none (the
+     * container asset has not loaded, or the element has left the document). One call grounds a
+     * session — a browser console, a test, an agent — in the vocabulary `pc-node` binding
+     * resolves against: the instantiated names ({@link HierarchyNode.name}), paths, match
+     * indices, attached component types and the material assignments of render components
+     * ({@link HierarchyNode.materials}). `String(...)` of the result, or of any node in it,
+     * is the printable form.
+     *
+     * The snapshot is plain data, computed afresh each call: it does not follow later changes
+     * to the hierarchy, and mutating it changes nothing.
+     *
+     * @returns The root of the instantiated node tree, or `null`.
+     */
+    hierarchy(): HierarchyNode | null {
+        const root = this._entity;
+        if (!root) {
+            return null;
+        }
+
+        // Ordinals are assigned in the traversal resolution searches — pre-order depth-first
+        // from the model root, the root itself included — so each node's index is exactly what
+        // a pc-node's index attribute selects. Once the walk completes, the map holds the total
+        // count per name, which is what the printable form reads to annotate only shared names.
+        const ordinals = new Map<string, number>();
+
+        const describe = (entity: Entity, pathBelowRoot: string): HierarchyNode => {
+            const index = ordinals.get(entity.name) ?? 0;
+            ordinals.set(entity.name, index + 1);
+
+            const node: HierarchyNode = {
+                name: entity.name,
+                // The root has no path below itself; its own name stands in, as it does for
+                // the path a pc-node bound to the root reports.
+                path: pathBelowRoot || entity.name,
+                index,
+                // A plain GraphNode grafted into the hierarchy has no component storage
+                components: Object.keys(entity.c ?? {}).sort(),
+                materials: (entity.render?.meshInstances ?? []).map((meshInstance, slot) => ({
+                    index: slot,
+                    name: meshInstance.material?.name ?? null
+                })),
+                children: entity.children.map((child) =>
+                    describe(child as Entity, pathBelowRoot ? `${pathBelowRoot}/${child.name}` : child.name)
+                )
+            };
+
+            // Non-enumerable, keeping the snapshot plain data under JSON.stringify, spreads and
+            // key enumeration. Deferred to call time, by which the ordinal map holds its totals.
+            Object.defineProperty(node, 'toString', {
+                enumerable: false,
+                value: () => formatHierarchy(node, ordinals)
+            });
+
+            return node;
+        };
+
+        return describe(root, '');
+    }
+
     connectedCallback() {
         // A model outside an application is inert and never becomes ready, so awaiting it hangs.
         // Warn rather than fail silently, naming the parent it requires, as every other misplaced
@@ -235,3 +390,4 @@ class ModelElement extends AsyncElement {
 customElements.define('pc-model', ModelElement);
 
 export { ModelElement };
+export type { HierarchyMaterial, HierarchyNode };