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

    Class AssetElement

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

    The element becomes ready once the containing application has started and the asset is in the state declared by the markup: loaded for preloaded assets (even if loading failed — check the asset's resource), or registered and awaiting a load for lazy assets. Elements inserted while the application is running are created and registered on insertion, and begin loading immediately unless lazy. A pc-asset must be a direct child of pc-app — elements placed elsewhere, or with an unsupported asset type, never become ready.

    A lazy asset loads on first use: the first time any element resolves it by id — a model, a material map, a sky, a script asset: reference — or when the lazy attribute is removed, whichever comes first. Until then it stays registered and unloaded.

    For texture and textureatlas assets, the texture options (address-u, address-v, min-filter, mag-filter, anisotropy, mipmaps, srgb, flip-y) apply when the texture is created and — like lazy — are observed: changing one updates a texture that has already loaded, and removing one restores the engine default. Changing srgb or mipmaps on a loaded texture recreates the underlying GPU resource, so prefer declaring those up front. Each option overrides the matching key in the data JSON; options left unset write nothing, leaving the engine's per-format defaults in force.

    Apart from lazy and the texture options, these attributes are read once when the asset is created, so changing them later has no effect.

    id - The identifier used to reference the asset from other elements.

    src - The URL of the asset to load.

    type - The asset type. Inferred from the src file extension when omitted.

    data - Additional asset data, as a JSON object.

    atlas - For a sprite asset, the id of the texture atlas asset it uses. The atlas must be declared before the sprite.

    frame-keys - For a sprite asset, the atlas frame keys it uses, separated by spaces or commas.

    pixels-per-unit - For a sprite asset, the number of pixels per world unit.

    render-mode - For a sprite asset, how the sprite is rendered when resized.

    load - Fired each time the asset finishes loading, including a lazy asset loaded later and any subsequent reloads. Does not bubble — listen on this element, or use a capture-phase listener on an ancestor to observe every asset.

    error - Fired when the 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
    asset
    addressU addressV anisotropy closestApp closestEntity flipY lazy magFilter minFilter mipmaps srgb
    _onReady _resetReady ready get
    asset: Asset | null = null

    The asset that is loaded. Available once the element is ready — await whenReady or the element's ready() promise before accessing it.

    • get addressU(): AddressMode | null

      Gets the texture's horizontal (U) address mode.

      Returns AddressMode | null

      The address mode, or null when unset.

    • set addressU(value: AddressMode | null): void

      Sets the texture's horizontal (U) address mode: how texture coordinates outside the 0 to 1 range sample the texture. Applies to texture and textureatlas assets, both when the texture is created and after it has loaded.

      Parameters

      • value: AddressMode | null

        The address mode, or null to use the engine default of 'repeat'.

      Returns void

    • get addressV(): AddressMode | null

      Gets the texture's vertical (V) address mode.

      Returns AddressMode | null

      The address mode, or null when unset.

    • set addressV(value: AddressMode | null): void

      Sets the texture's vertical (V) address mode: how texture coordinates outside the 0 to 1 range sample the texture. Applies to texture and textureatlas assets, both when the texture is created and after it has loaded.

      Parameters

      • value: AddressMode | null

        The address mode, or null to use the engine default of 'repeat'.

      Returns void

    • get anisotropy(): number | null

      Gets the texture's maximum anisotropic filtering level.

      Returns number | null

      The anisotropy level, or null when unset.

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

      Sets the texture's maximum anisotropic filtering level, which improves quality at oblique viewing angles. Applies to texture and textureatlas assets, both when the texture is created and after it has loaded.

      Parameters

      • value: number | null

        The anisotropy level, or null to use the engine default of 1.

      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 flipY(): boolean | null

      Gets whether the texture's image data is flipped vertically at upload.

      Returns boolean | null

      The flip flag, or null when unset.

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

      Sets whether the texture's image data is flipped vertically at upload. Applies to texture and textureatlas assets, both when the texture is created and after it has loaded.

      Parameters

      • value: boolean | null

        The flip flag, or null to use the engine default of false.

      Returns void

    • get lazy(): boolean

      Gets whether the asset should be loaded lazily.

      Returns boolean

      The lazy loading flag.

    • set lazy(value: boolean): void

      Sets whether the asset should be loaded lazily. A lazy asset is registered without being loaded; it loads on first use - the first time any element resolves it by id - or when this flag is cleared on a registered asset, whichever comes first.

      Parameters

      • value: boolean

        The lazy loading flag.

      Returns void

    • get magFilter(): MagFilterMode | null

      Gets the texture's magnification filter.

      Returns MagFilterMode | null

      The filter, or null when unset.

    • set magFilter(value: MagFilterMode | null): void

      Sets the texture's magnification filter, used when the texture is displayed larger than its source size. Applies to texture and textureatlas assets, both when the texture is created and after it has loaded.

      Parameters

      • value: MagFilterMode | null

        The filter, or null to use the engine default of 'linear'.

      Returns void

    • get minFilter(): MinFilterMode | null

      Gets the texture's minification filter.

      Returns MinFilterMode | null

      The filter, or null when unset.

    • set minFilter(value: MinFilterMode | null): void

      Sets the texture's minification filter, used when the texture is displayed smaller than its source size. The mip variants blend within (and, for the second linear, between) mipmap levels. Applies to texture and textureatlas assets, both when the texture is created and after it has loaded.

      Parameters

      • value: MinFilterMode | null

        The filter, or null to use the engine default of 'linear-mip-linear'.

      Returns void

    • get mipmaps(): boolean | null

      Gets whether the texture generates and uses mipmaps.

      Returns boolean | null

      The mipmaps flag, or null when unset.

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

      Sets whether the texture generates and uses mipmaps. Changing this on a loaded texture recreates the underlying GPU resource, so prefer declaring it up front. Applies to texture and textureatlas assets.

      Parameters

      • value: boolean | null

        The mipmaps flag, or null to use the engine default of true.

      Returns void

    • get srgb(): boolean | null

      Gets whether the texture holds sRGB (gamma-encoded) color data.

      Returns boolean | null

      The sRGB flag, or null when unset.

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

      Sets whether the texture holds sRGB (gamma-encoded) color data, enabling hardware gamma decode. Free when set before the texture loads; changing it on a loaded texture recreates the underlying GPU resource. Applies to texture and textureatlas assets.

      Parameters

      • value: boolean | null

        The sRGB flag, or null to use the engine default of false.

      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_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

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

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

    • Returns the Asset created by the <pc-asset> element with the given id, or undefined if there is no such element or its asset has not been created yet.

      Parameters

      • id: string

        The id of the <pc-asset> element.

      Returns Asset | null | undefined

      The asset, or undefined.

    Settings
    Member Visibility

    On This Page
    Properties
    Accessors
    Methods