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

    Class ModelElement

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

    The element creates and fronts a stable host entity: entity is that host, created when the application builds its hierarchy and kept across asset changes, so the element's transform and tags are instance placement that composes with whatever transform the asset authored on its root. The instantiated content is parented beneath the host and exposed as contentEntity.

    The element becomes ready once its current asset selection has settled: the container asset has loaded and its content root has been parented beneath the host, the load has failed (contentEntity stays null — listen for error, or check contentEntity, to tell the outcomes apart), or no asset is assigned at all. Changing asset re-arms readiness and instantiates anew, so a ready() obtained after the change resolves against the new content. A pc-model outside a pc-app, or referencing an unknown asset id, warns and never becomes ready.

    The pointer events below are dispatched by the containing <pc-app> element when the pointer intersects the model's geometry, exactly as for <pc-entity> — a hit on a content node that no pc-node fronts resolves to this element.

    enabled - The enabled state of the model.

    name - The name of the model.

    position - The position of the model.

    rotation - The rotation of the model.

    scale - The scale of the model.

    tags - The tags of the model.

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

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

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

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

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

    pointerenter - Fired when the pointer moves onto the model.

    pointerleave - Fired when the pointer moves off the model.

    pointermove - Fired when the pointer moves over the model.

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

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

    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.

    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.

    Hierarchy (View Summary)

    Index
    _appElement _built
    asset closestApp closestEntity contentEntity enabled entity name position rotation scale tags
    _onBuilt _onEntityDestroy _onReady _registerEntity _resetReady _unregisterEntity _updateInlineHandler hierarchy 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.

    Protected_built

    _built: boolean = false

    Whether the hierarchy has been built for this entity — set once _buildHierarchy has parented it. Read by subclasses that gate work on the entity being in the scene graph.

    • get asset(): string

      Gets the id of the pc-asset to use for the model.

      Returns string

      The asset ID.

    • set asset(value: string): void

      Sets the id of the pc-asset to use for the model.

      Parameters

      • value: string

        The asset ID.

      Returns void

    • 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 contentEntity(): Entity | null

      The root entity of the instantiated model content, parented beneath the host entity. null until the container asset has loaded and been instantiated, after a failed load, and again once the element has been removed from the document.

      Returns Entity | null

      The content root entity, or null.

    • get enabled(): boolean

      Gets the enabled state of the entity.

      Returns boolean

      Whether the entity is enabled.

    • set enabled(value: boolean): void

      Sets the enabled state of the entity.

      Parameters

      • value: boolean

        Whether the entity is enabled.

      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 name(): string

      Gets the name of the entity.

      Returns string

      The name of the entity.

    • set name(value: string): void

      Sets the name of the entity.

      Parameters

      • value: string

        The name of the entity.

      Returns void

    • get position(): Vec3

      Gets the position of the entity.

      Returns Vec3

      The position of the entity.

    • set position(value: Vec3): void

      Sets the position of the entity.

      Parameters

      • value: Vec3

        The position of the entity.

      Returns void

    • get rotation(): Vec3

      Gets the rotation of the entity.

      Returns Vec3

      The rotation of the entity.

    • set rotation(value: Vec3): void

      Sets the rotation of the entity.

      Parameters

      • value: Vec3

        The rotation of the entity.

      Returns void

    • get scale(): Vec3

      Gets the scale of the entity.

      Returns Vec3

      The scale of the entity.

    • set scale(value: Vec3): void

      Sets the scale of the entity.

      Parameters

      • value: Vec3

        The scale of the entity.

      Returns void

    • get tags(): string[]

      Gets the tags of the entity.

      Returns string[]

      The tags of the entity.

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

      Sets the tags of the entity.

      Parameters

      • value: string[]

        The tags of the entity.

      Returns void

    Protected_onBuilt

    • _onBuilt(): void

      Starts (or restarts) the content load once the host has been parented. Readiness is not announced here — it tracks the content settling, not the host entering the scene graph.

      Returns void

    Protected_onEntityDestroy

    • _onEntityDestroy(entity: Entity): void

      Extends the owner reset for the content: the engine's destroy cascade has already taken the content root down with the host subtree, so only the reference and the in-flight load are dropped here. The next build re-creates the host and re-instantiates the content.

      Parameters

      • entity: Entity

        The host entity that was destroyed.

      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 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 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 (HierarchyNode.name), paths, match indices, attached component types and the material assignments of render components (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. It covers the instantiated content only — the host entity the element fronts is not part of the asset's node tree.

      Returns HierarchyNode | null

      The root of the instantiated node tree, or null.

    • 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<ModelElement>

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

    Settings
    Member Visibility

    On This Page
    Properties
    Accessors
    Methods