HomeWeb Components API Reference - v0.18.0
    Preparing search index...

    Class NodeElement

    The NodeElement interface provides properties and methods for manipulating <pc-node> elements. The NodeElement interface also inherits the properties and methods of the HTMLElement interface.

    A pc-node is an override element: where pc-entity creates an entity, pc-node binds to a node a pc-model loaded and declares overrides against the authored asset — components to add, properties to change, content to attach. Attributes present apply as overrides; attributes absent leave authored values untouched, and removing an attribute (or assigning null to the matching property) restores the authored value.

    name selects among the host model's nodes (first match in depth-first order), nesting a pc-node inside another scopes the search to that subtree, and index picks among identically named matches. When name matches more than one node and no index is given, the element warns and binds nothing.

    The element becomes ready once bound, and never while unresolved — a missing or ambiguous name warns and records the failure in state, readiness stays unresolved, and descendants wait with it.

    The pointer events below are dispatched by the containing <pc-app> element when the pointer intersects the bound node's geometry, exactly as for <pc-entity>.

    name - The name of the node to bind, resolved within the nearest ancestor pc-model (or pc-node) once it has instantiated.

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

    enabled - Overrides the node's enabled state.

    position - Overrides the node's local position, as an "x y z" triple.

    rotation - Overrides the node's local rotation (Euler angles), as an "x y z" triple.

    scale - Overrides the node's local scale, as an "x y z" triple.

    tags - Overrides the node's tags, separated by spaces or commas.

    material-overrides - 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.

    onpointerenter - Script to run when the pointer moves onto the node.

    onpointerleave - Script to run when the pointer moves off the node.

    onpointermove - Script to run when the pointer moves over the node.

    onpointerdown - Script to run when a pointer button is pressed over the node.

    onpointerup - Script to run when a pointer button is released over the node.

    pointerenter - Fired when the pointer moves onto the node.

    pointerleave - Fired when the pointer moves off the node.

    pointermove - Fired when the pointer moves over the node.

    pointerdown - Fired when a pointer button is pressed over the node.

    pointerup - Fired when a pointer button is released over the node.

    Hierarchy (View Summary)

    Index
    _appElement
    closestApp closestEntity enabled entity index materialOverrides name path position rotation scale state tags
    _onReady _registerEntity _resetReady _unregisterEntity _updateInlineHandler ready

    Protected_appElement

    _appElement: AppElement | 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.

    • get closestApp(): AppElement | null

      The nearest ancestor <pc-app> element, or null if this element has no <pc-app> ancestor. The search starts at the parent, so an element never resolves to itself.

      Returns AppElement | null

      The closest app element, or null.

    • get closestEntity(): EntityBaseElement | null

      The nearest ancestor element that fronts an entity — <pc-entity>, <pc-model> 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 EntityBaseElement | null

      The closest entity-fronting element, or null.

    • get enabled(): boolean | null

      Gets the enabled override.

      Returns boolean | null

      The enabled state, or null while no override is set.

    • set enabled(value: boolean | null): void

      Sets the enabled override. null clears it, restoring the authored state.

      Parameters

      • value: boolean | null

        The enabled state, or null.

      Returns void

    • get entity(): Entity | null

      The PlayCanvas entity instance. null until the element is ready, and again once the entity is gone — await whenReady or the element's ready() promise before accessing it.

      Returns Entity | null

      The entity instance, or null.

    • get index(): number | null

      Gets which match to bind.

      Returns number | null

      The match index, or null when unset.

    • set index(value: number | null): void

      Sets which match to bind when name matches more than one node, 0-based in depth-first order. A change retargets, like name. null means unset - required when the name is ambiguous, optional otherwise.

      Parameters

      • value: number | null

        The match index, or null.

      Returns void

    • get materialOverrides(): Readonly<Record<string, string>> | null

      Gets the material overrides.

      Returns Readonly<Record<string, string>> | null

      The mapping, or null while no override is set.

    • set materialOverrides(value: Readonly<Record<string, string>> | null): void

      Sets the material overrides: a sparse mapping from selector to pc-material id, applied to the bound node's authored render component. 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. null clears the mapping, restoring every baseline assignment.

      Parameters

      • value: Readonly<Record<string, string>> | null

        The mapping, or null.

      Returns void

    • get name(): string

      Gets the name of the node to bind.

      Returns string

      The node name.

    • set name(value: string): void

      Sets the name of the node to bind. A change retargets: the current binding's overrides revert and the new name resolves afresh. name on a pc-node is never a rename of the authored node - it is only ever a reference.

      Parameters

      • value: string

        The node name.

      Returns void

    • get path(): string | null

      The path of the bound node below the search root, /-separated, or null while not bound.

      Returns string | null

      The bound node's path, or null.

    • get position(): Vec3 | null

      Gets the local position override.

      Returns Vec3 | null

      The position, or null while no override is set.

    • set position(value: Vec3 | null): void

      Sets the local position override. null clears it, restoring the authored position.

      Parameters

      • value: Vec3 | null

        The position, or null.

      Returns void

    • get rotation(): Vec3 | null

      Gets the local rotation override.

      Returns Vec3 | null

      The rotation, or null while no override is set.

    • set rotation(value: Vec3 | null): void

      Sets the local rotation override, as Euler angles in degrees. null clears it, restoring the authored rotation.

      Parameters

      • value: Vec3 | null

        The rotation, or null.

      Returns void

    • get scale(): Vec3 | null

      Gets the local scale override.

      Returns Vec3 | null

      The scale, or null while no override is set.

    • set scale(value: Vec3 | null): void

      Sets the local scale override. null clears it, restoring the authored scale.

      Parameters

      • value: Vec3 | null

        The scale, or null.

      Returns void

    • get state(): NodeBindingState

      The binding state: pending until the host instantiates and name resolves, bound once decorated, missing/ambiguous/duplicate when resolution failed (each also warns). Useful for asserting a document's bindings programmatically.

      Returns NodeBindingState

      The binding state.

    • get tags(): string[] | null

      Gets the tags override.

      Returns string[] | null

      The tags, or null while no override is set.

    • set tags(value: string[] | null): void

      Sets the tags override. null clears it, restoring the authored tags.

      Parameters

      • value: string[] | null

        The tags, or null.

      Returns void

    Protected_onReady

    • _onReady(): void

      Called when the element is fully initialized and ready. Subclasses should call this when they're ready. Resolves the ready promise and dispatches a bubbling, composed ready event. Signals at most once per readiness cycle: a repeat call before _resetReady has re-armed the promise does nothing.

      Returns void

    Protected_registerEntity

    • _registerEntity(entity: Entity): void

      Registers entity as this element's backing entity with the owning application, which joins engine nodes back to elements by identity (never by name).

      Parameters

      • entity: Entity

        The entity to register.

      Returns void

    Protected_resetReady

    • _resetReady(): void

      Returns the ready promise to its pending state. Subclasses should call this when the resource their readiness announced is torn down (typically from disconnectedCallback), so that a later re-initialization can signal readiness again. Does nothing while the promise is still pending — an in-flight waiter carries over to the next readiness cycle rather than being stranded on a promise nothing will ever resolve.

      Returns void

    Protected_unregisterEntity

    Protected_updateInlineHandler

    • _updateInlineHandler(name: string, value: string | null): void

      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 EventTarget.addEventListener, the connect/disconnect bookkeeping that lets the application lazily attach its canvas pointer handlers must be kept in sync here.

      Parameters

      • name: string

        The attribute name (e.g. 'onpointerdown').

      • value: string | null

        The attribute value, or null when the attribute has been removed.

      Returns void

    • Returns a promise that resolves with this element when it's ready. This is the low-level primitive underlying whenReady, which is the recommended way to wait for elements.

      Readiness tracks the element's current lifecycle: once a ready element is torn down (for example by removing it from the document), this returns a fresh promise that resolves when the element is next ready. A promise obtained earlier stays resolved — call this again after re-inserting an element rather than reusing a promise from before its removal.

      Returns Promise<NodeElement>

      A promise that resolves with this element when it's ready.

    Settings
    Member Visibility

    On This Page
    Properties
    Accessors
    Methods