@playcanvas/web-components 0.13.1 → 0.14.0

package/dist/vscode.html-custom-data.json

@@ -544,6 +544,11 @@
           "description": "The UV channel the metalness map samples.",
           "values": []
         },
+        {
+          "name": "name",
+          "description": "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.",
+          "values": []
+        },
         {
           "name": "normal-map",
           "description": "The id of the `pc-asset` used as the normal map.",
@@ -698,7 +703,7 @@
     },
     {
       "name": "pc-model",
-      "description": "The ModelElement interface provides properties and methods for manipulating\n[`<pc-model>`](https://developer.playcanvas.com/user-manual/web-components/tags/pc-model/) elements.\nThe ModelElement interface also inherits the properties and methods of the\nHTMLElement interface.\n\nThe element becomes ready once its container asset has loaded and the instantiated hierarchy has\nbeen added to the scene — `entity` is non-null by then. A failed load also settles readiness,\nwith `entity` remaining `null`: readiness means the load settled, not that it succeeded — listen\nfor `error`, or check `entity`, to tell the outcomes apart. Changing `asset` re-arms readiness\nand instantiates anew, so a `ready()` obtained after the change resolves against the new\nhierarchy. A `pc-model` outside a `pc-app`, or referencing an unknown asset id, warns and never\nbecomes ready.\n\n---\n\n\n### **Events:**\n - **error** - Fired when the container asset fails to load, with the engine's error in `message`. Does not bubble. The element still becomes ready — readiness means the load settled, not that it succeeded.\n- **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.\n- **ready** - Fired when the element is fully initialized — once per readiness cycle, so an element that is torn down and re-initialized (for example by removing and re-inserting it) fires it again. Bubbles and is composed.\n\n### **Methods:**\n - **ready(): __** - Returns a promise that resolves with this element when it's ready. This is the low-level\nprimitive underlying whenReady, which is the recommended way to wait for elements.\n\nReadiness tracks the element's current lifecycle: once a ready element is torn down (for\nexample by removing it from the document), this returns a fresh promise that resolves when\nthe element is next ready. A promise obtained earlier stays resolved — call this again\nafter re-inserting an element rather than reusing a promise from before its removal.",
+      "description": "The ModelElement interface provides properties and methods for manipulating\n[`<pc-model>`](https://developer.playcanvas.com/user-manual/web-components/tags/pc-model/) elements.\nThe ModelElement interface also inherits the properties and methods of the\nHTMLElement interface.\n\nThe element becomes ready once its container asset has loaded and the instantiated hierarchy has\nbeen added to the scene — `entity` is non-null by then. A failed load also settles readiness,\nwith `entity` remaining `null`: readiness means the load settled, not that it succeeded — listen\nfor `error`, or check `entity`, to tell the outcomes apart. Changing `asset` re-arms readiness\nand instantiates anew, so a `ready()` obtained after the change resolves against the new\nhierarchy. A `pc-model` outside a `pc-app`, or referencing an unknown asset id, warns and never\nbecomes ready.\n\n---\n\n\n### **Events:**\n - **error** - Fired when the container asset fails to load, with the engine's error in `message`. Does not bubble. The element still becomes ready — readiness means the load settled, not that it succeeded.\n- **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.\n- **ready** - Fired when the element is fully initialized — once per readiness cycle, so an element that is torn down and re-initialized (for example by removing and re-inserting it) fires it again. Bubbles and is composed.\n\n### **Methods:**\n - **hierarchy(): __** - Returns a snapshot of the instantiated node tree, or `null` while there is none (the\ncontainer asset has not loaded, or the element has left the document). One call grounds a\nsession — a browser console, a test, an agent — in the vocabulary `pc-node` binding\nresolves against: the instantiated names (HierarchyNode.name), paths, match\nindices, attached component types and the material assignments of render components\n(HierarchyNode.materials). `String(...)` of the result, or of any node in it,\nis the printable form.\n\nThe snapshot is plain data, computed afresh each call: it does not follow later changes\nto the hierarchy, and mutating it changes nothing.\n- **ready(): __** - Returns a promise that resolves with this element when it's ready. This is the low-level\nprimitive underlying whenReady, which is the recommended way to wait for elements.\n\nReadiness tracks the element's current lifecycle: once a ready element is torn down (for\nexample by removing it from the document), this returns a fresh promise that resolves when\nthe element is next ready. A promise obtained earlier stays resolved — call this again\nafter re-inserting an element rather than reusing a promise from before its removal.",
       "attributes": [
         {
           "name": "asset",
@@ -749,6 +754,11 @@
           "description": "Which match to bind when `name` matches more than one node, 0-based in depth-first order. Optional for a unique match; required for an ambiguous one.",
           "values": []
         },
+        {
+          "name": "material-overrides",
+          "description": "Overrides material assignments on the bound node's render component, as a JSON object from selector to `pc-material` id — for example `{\"name:CarPaint\": \"candy-red\", \"index:7\": \"smoked-glass\"}`. A `name:X` key selects every mesh instance whose baseline material is named `X`; an `index:N` key selects mesh instance `N` and wins over a name rule for the same instance. Assignments no rule matches keep their baseline materials, and removing the attribute restores all of them. Use `pc-model.hierarchy()` to discover the names and indices a node offers.",
+          "values": []
+        },
         {
           "name": "name",
           "description": "The name of the node to bind, resolved within the nearest ancestor `pc-model` (or `pc-node`) once it has instantiated.",

package/dist/web-types.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://raw.githubusercontent.com/JetBrains/web-types/master/schema/web-types.json",
   "name": "@playcanvas/web-components",
-  "version": "0.13.1",
+  "version": "0.14.0",
   "description-markup": "markdown",
   "contributions": {
     "html": {
@@ -785,6 +785,11 @@
               "description": "The UV channel the metalness map samples.",
               "value": { "type": "number", "default": "0" }
             },
+            {
+              "name": "name",
+              "description": "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.",
+              "value": { "type": "string" }
+            },
             {
               "name": "normal-map",
               "description": "The id of the `pc-asset` used as the normal map.",
@@ -1162,6 +1167,10 @@
                 "name": "metalnessMapUv",
                 "description": "Gets the UV channel the metalness map samples."
               },
+              {
+                "name": "name",
+                "description": "Gets the name of the material - the label shown wherever materials surface by name, such\nas profilers, GPU captures and the assignments `pc-model.hierarchy()` reports. Purely a\nlabel: element references resolve through `id`."
+              },
               {
                 "name": "normalMap",
                 "description": "Gets the id of the `pc-asset` used as the normal map."
@@ -1284,7 +1293,7 @@
         },
         {
           "name": "pc-model",
-          "description": "The ModelElement interface provides properties and methods for manipulating\n[`<pc-model>`](https://developer.playcanvas.com/user-manual/web-components/tags/pc-model/) elements.\nThe ModelElement interface also inherits the properties and methods of the\nHTMLElement interface.\n\nThe element becomes ready once its container asset has loaded and the instantiated hierarchy has\nbeen added to the scene — `entity` is non-null by then. A failed load also settles readiness,\nwith `entity` remaining `null`: readiness means the load settled, not that it succeeded — listen\nfor `error`, or check `entity`, to tell the outcomes apart. Changing `asset` re-arms readiness\nand instantiates anew, so a `ready()` obtained after the change resolves against the new\nhierarchy. A `pc-model` outside a `pc-app`, or referencing an unknown asset id, warns and never\nbecomes ready.\n\n---\n\n\n### **Events:**\n - **error** - Fired when the container asset fails to load, with the engine's error in `message`. Does not bubble. The element still becomes ready — readiness means the load settled, not that it succeeded.\n- **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.\n- **ready** - Fired when the element is fully initialized — once per readiness cycle, so an element that is torn down and re-initialized (for example by removing and re-inserting it) fires it again. Bubbles and is composed.\n\n### **Methods:**\n - **ready(): __** - Returns a promise that resolves with this element when it's ready. This is the low-level\nprimitive underlying whenReady, which is the recommended way to wait for elements.\n\nReadiness tracks the element's current lifecycle: once a ready element is torn down (for\nexample by removing it from the document), this returns a fresh promise that resolves when\nthe element is next ready. A promise obtained earlier stays resolved — call this again\nafter re-inserting an element rather than reusing a promise from before its removal.",
+          "description": "The ModelElement interface provides properties and methods for manipulating\n[`<pc-model>`](https://developer.playcanvas.com/user-manual/web-components/tags/pc-model/) elements.\nThe ModelElement interface also inherits the properties and methods of the\nHTMLElement interface.\n\nThe element becomes ready once its container asset has loaded and the instantiated hierarchy has\nbeen added to the scene — `entity` is non-null by then. A failed load also settles readiness,\nwith `entity` remaining `null`: readiness means the load settled, not that it succeeded — listen\nfor `error`, or check `entity`, to tell the outcomes apart. Changing `asset` re-arms readiness\nand instantiates anew, so a `ready()` obtained after the change resolves against the new\nhierarchy. A `pc-model` outside a `pc-app`, or referencing an unknown asset id, warns and never\nbecomes ready.\n\n---\n\n\n### **Events:**\n - **error** - Fired when the container asset fails to load, with the engine's error in `message`. Does not bubble. The element still becomes ready — readiness means the load settled, not that it succeeded.\n- **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.\n- **ready** - Fired when the element is fully initialized — once per readiness cycle, so an element that is torn down and re-initialized (for example by removing and re-inserting it) fires it again. Bubbles and is composed.\n\n### **Methods:**\n - **hierarchy(): __** - Returns a snapshot of the instantiated node tree, or `null` while there is none (the\ncontainer asset has not loaded, or the element has left the document). One call grounds a\nsession — a browser console, a test, an agent — in the vocabulary `pc-node` binding\nresolves against: the instantiated names (HierarchyNode.name), paths, match\nindices, attached component types and the material assignments of render components\n(HierarchyNode.materials). `String(...)` of the result, or of any node in it,\nis the printable form.\n\nThe snapshot is plain data, computed afresh each call: it does not follow later changes\nto the hierarchy, and mutating it changes nothing.\n- **ready(): __** - Returns a promise that resolves with this element when it's ready. This is the low-level\nprimitive underlying whenReady, which is the recommended way to wait for elements.\n\nReadiness tracks the element's current lifecycle: once a ready element is torn down (for\nexample by removing it from the document), this returns a fresh promise that resolves when\nthe element is next ready. A promise obtained earlier stays resolved — call this again\nafter re-inserting an element rather than reusing a promise from before its removal.",
           "doc-url": "",
           "attributes": [
             {
@@ -1422,6 +1431,11 @@
               "description": "Which match to bind when `name` matches more than one node, 0-based in depth-first order. Optional for a unique match; required for an ambiguous one.",
               "value": { "type": "string" }
             },
+            {
+              "name": "material-overrides",
+              "description": "Overrides material assignments on the bound node's render component, as a JSON object from selector to `pc-material` id — for example `{\"name:CarPaint\": \"candy-red\", \"index:7\": \"smoked-glass\"}`. A `name:X` key selects every mesh instance whose baseline material is named `X`; an `index:N` key selects mesh instance `N` and wins over a name rule for the same instance. Assignments no rule matches keep their baseline materials, and removing the attribute restores all of them. Use `pc-model.hierarchy()` to discover the names and indices a node offers.",
+              "value": { "type": "string" }
+            },
             {
               "name": "name",
               "description": "The name of the node to bind, resolved within the nearest ancestor `pc-model` (or `pc-node`) once it has instantiated.",
@@ -1532,6 +1546,11 @@
                 "description": "Gets which match to bind.",
                 "type": "number | null"
               },
+              {
+                "name": "materialOverrides",
+                "description": "Gets the material overrides.",
+                "type": "MaterialOverrides | null"
+              },
               {
                 "name": "name",
                 "description": "Gets the name of the node to bind.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@playcanvas/web-components",
-  "version": "0.13.1",
+  "version": "0.14.0",
   "author": "PlayCanvas <support@playcanvas.com>",
   "homepage": "https://playcanvas.com",
   "description": "Web Components for the PlayCanvas Engine",
@@ -96,9 +96,9 @@
     "custom-element-vs-code-integration": "1.5.0",
     "earcut": "3.2.3",
     "eslint": "9.39.5",
-    "globals": "17.9.0",
+    "globals": "17.11.0",
     "jsdom": "30.0.1",
-    "mediabunny": "1.53.0",
+    "mediabunny": "1.53.1",
     "opentype.js": "2.0.0",
     "playcanvas": "2.22.0-beta.12",
     "prettier": "3.9.6",

package/src/colors.ts

@@ -1,3 +1,8 @@
+/**
+ * The CSS color keywords, lowercase name to hex value. Read by `parseColor` to accept color
+ * names as attribute values.
+ * @internal
+ */
 export const CSS_COLORS: Record<string, string> = {
     aliceblue: '#f0f8ff',
     antiquewhite: '#faebd7',

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/index.ts

@@ -123,3 +123,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 };