Engine API Reference - v2.7.2
    Preparing search index...

    Class Asset

    An asset record of a file or data resource that can be loaded by the engine. The asset contains four important fields:

    • file: contains the details of a file (filename, url) which contains the resource data, e.g. an image file for a texture asset.
    • data: contains a JSON blob which contains either the resource data for the asset (e.g. material data) or additional data for the file (e.g. material mappings for a model).
    • options: contains a JSON blob with handler-specific load options.
    • resource: contains the final resource when it is loaded. (e.g. a StandardMaterial or a Texture).

    See the AssetRegistry for details on loading resources from assets.

    Hierarchy (View Summary)

    Index

    Constructors

    constructor

    Properties

    id loaded loading options registry tags type

    Accessors

    data file name preload resource resources

    Methods

    fire getFileUrl hasEvent off on once ready unload

    Events

    EVENT_ADDLOCALIZED EVENT_CHANGE EVENT_ERROR EVENT_LOAD EVENT_PROGRESS EVENT_REMOVE EVENT_REMOVELOCALIZED EVENT_UNLOAD

    Constructors

    • Create a new Asset record. Generally, Assets are created in the loading process and you won't need to create them by hand.

      Parameters

      • name: string

        A non-unique but human-readable name which can be later used to retrieve the asset.

      • type:
            | "animation"
            | "container"
            | "font"
            | "audio"
            | "html"
            | "script"
            | "template"
            | "text"
            | "json"
            | "binary"
            | "texture"
            | "model"
            | "material"
            | "textureatlas"
            | "cubemap"
            | "shader"
            | "css"
            | "sprite"
            | "render"
            | "gsplat"

        Type of asset.

      • Optionalfile: {
            contents?: ArrayBuffer;
            filename?: string;
            hash?: string;
            size?: number;
            url?: string;
        }

        Details about the file the asset is made from. At the least must contain the 'url' field. For assets that don't contain file data use null.

        • Optionalcontents?: ArrayBuffer

          Optional file contents. This is faster than wrapping the data in a (base64 encoded) blob. Currently only used by container assets.

        • Optionalfilename?: string

          The filename of the resource file or null if no filename was set (e.g from using AssetRegistry#loadFromUrl).

        • Optionalhash?: string

          The MD5 hash of the resource file data and the Asset data field or null if hash was set (e.g from using AssetRegistry#loadFromUrl).

        • Optionalsize?: number

          The size of the resource file or null if no size was set (e.g. from using AssetRegistry#loadFromUrl).

        • Optionalurl?: string

          The URL of the resource file that contains the asset data.

      • Optionaldata: any = {}

        JSON object or string with additional data about the asset. (e.g. for texture and model assets) or contains the asset data itself (e.g. in the case of materials).

      • Optionaloptions: { crossOrigin?: null | "anonymous" | "use-credentials" } = {}

        The asset handler options. For container options see ContainerHandler.

      Returns Asset

      const asset = new pc.Asset("a texture", "texture", {
          url: "http://example.com/my/assets/here/texture.png"
      });

    Properties

    id: number = ...

    The asset id.

    loaded: boolean = false

    True if the asset has finished attempting to load the resource. It is not guaranteed that the resources are available as there could have been a network error.

    loading: boolean = false

    True if the resource is currently being loaded.

    options: any = {}

    Optional JSON data that contains the asset handler options.

    registry: null | AssetRegistry = null

    The asset registry that this Asset belongs to.

    tags: Tags = ...

    Asset tags. Enables finding of assets by tags using the AssetRegistry#findByTag method.

    type:
        | "animation"
        | "container"
        | "font"
        | "audio"
        | "html"
        | "script"
        | "template"
        | "text"
        | "json"
        | "binary"
        | "texture"
        | "model"
        | "material"
        | "textureatlas"
        | "cubemap"
        | "shader"
        | "css"
        | "sprite"
        | "render"
        | "gsplat"

    The type of the asset.

    Accessors

    • get data(): any

      Gets optional asset JSON data.

      Returns any

    • set data(value: any): void

      Sets optional asset JSON data. This contains either the complete resource data (such as in the case of a material) or additional data (such as in the case of a model which contains mappings from mesh to material).

      Parameters

      • value: any

      Returns void

    • get preload(): boolean

      Gets whether to preload an asset.

      Returns boolean

    • set preload(value: boolean): void

      Sets whether to preload an asset. If true, the asset will be loaded during the preload phase of application set up.

      Parameters

      • value: boolean

      Returns void

    • get resources(): any[]

      Gets the asset resources.

      Returns any[]

    • set resources(value: any[]): void

      Sets the asset resources. Some assets can hold more than one runtime resource (cube maps, for example).

      Parameters

      • value: any[]

      Returns void

    Methods

    • Fire an event, all additional arguments are passed on to the event listener.

      Parameters

      • name: string

        Name of event to fire.

      • Optionalarg1: any

        First argument that is passed to the event handler.

      • Optionalarg2: any

        Second argument that is passed to the event handler.

      • Optionalarg3: any

        Third argument that is passed to the event handler.

      • Optionalarg4: any

        Fourth argument that is passed to the event handler.

      • Optionalarg5: any

        Fifth argument that is passed to the event handler.

      • Optionalarg6: any

        Sixth argument that is passed to the event handler.

      • Optionalarg7: any

        Seventh argument that is passed to the event handler.

      • Optionalarg8: any

        Eighth argument that is passed to the event handler.

      Returns EventHandler

      Self for chaining.

      obj.fire('test', 'This is the message');

    • Return the URL required to fetch the file for this asset.

      Returns null | string

      The URL. Returns null if the asset has no associated file.

      const assets = app.assets.find("My Image", "texture");
      const img = "<img src='" + assets[0].getFileUrl() + "'>";

    • Test if there are any handlers bound to an event name.

      Parameters

      • name: string

        The name of the event to test.

      Returns boolean

      True if the object has handlers bound to the specified event name.

      obj.on('test', () => {}); // bind an event to 'test'
      obj.hasEvent('test'); // returns true
      obj.hasEvent('hello'); // returns false

    • Detach an event handler from an event. If callback is not provided then all callbacks are unbound from the event, if scope is not provided then all events with the callback will be unbound.

      Parameters

      • Optionalname: string

        Name of the event to unbind.

      • Optionalcallback: HandleEventCallback

        Function to be unbound.

      • Optionalscope: any

        Scope that was used as the this when the event is fired.

      Returns EventHandler

      Self for chaining.

      const handler = () => {};
      obj.on('test', handler);

      obj.off(); // Removes all events
      obj.off('test'); // Removes all events called 'test'
      obj.off('test', handler); // Removes all handler functions, called 'test'
      obj.off('test', handler, this); // Removes all handler functions, called 'test' with scope this

    • Attach an event handler to an event.

      Parameters

      • name: string

        Name of the event to bind the callback to.

      • callback: HandleEventCallback

        Function that is called when event is fired. Note the callback is limited to 8 arguments.

      • Optionalscope: any = ...

        Object to use as 'this' when the event is fired, defaults to current this.

      Returns EventHandle

      Can be used for removing event in the future.

      obj.on('test', (a, b) => {
          console.log(a + b);
      });
      obj.fire('test', 1, 2); // prints 3 to the console

      const evt = obj.on('test', (a, b) => {
          console.log(a + b);
      });
      // some time later
      evt.off();

    • Attach an event handler to an event. This handler will be removed after being fired once.

      Parameters

      • name: string

        Name of the event to bind the callback to.

      • callback: HandleEventCallback

        Function that is called when event is fired. Note the callback is limited to 8 arguments.

      • Optionalscope: any = ...

        Object to use as 'this' when the event is fired, defaults to current this.

      Returns EventHandle

      • can be used for removing event in the future.
      obj.once('test', (a, b) => {
          console.log(a + b);
      });
      obj.fire('test', 1, 2); // prints 3 to the console
      obj.fire('test', 1, 2); // not going to get handled

    • Take a callback which is called as soon as the asset is loaded. If the asset is already loaded the callback is called straight away.

      Parameters

      • callback: AssetReadyCallback

        The function called when the asset is ready. Passed the (asset) arguments.

      • Optionalscope: any

        Scope object to use when calling the callback.

      Returns void

      const asset = app.assets.find("My Asset");
      asset.ready(function (asset) {
        // asset loaded
      });
      app.assets.load(asset);

    • Destroys the associated resource and marks asset as unloaded.

      Returns void

      const asset = app.assets.find("My Asset");
      asset.unload();
      // asset.resource is null

    Events

    EVENT_ADDLOCALIZED: string = 'add:localized'

    Fired when we add a new localized asset id to the asset.

    asset.on('add:localized', (locale, assetId) => {
       console.log(`Asset ${asset.name} has added localized asset ${assetId} for locale ${locale}`);
    });
    EVENT_CHANGE: string = 'change'

    Fired when one of the asset properties file, data, resource or resources is changed.

    asset.on('change', (asset, property, newValue, oldValue) => {
       console.log(`Asset ${asset.name} has property ${property} changed from ${oldValue} to ${newValue}`);
    });
    EVENT_ERROR: string = 'error'

    Fired if the asset encounters an error while loading.

    asset.on('error', (err, asset) => {
       console.error(`Error loading asset ${asset.name}: ${err}`);
    });
    EVENT_LOAD: string = 'load'

    Fired when the asset has completed loading.

    asset.on('load', (asset) => {
        console.log(`Asset loaded: ${asset.name}`);
    });
    EVENT_PROGRESS: string = 'progress'

    Fired when the asset's stream download progresses.

    Please note:

    • only gsplat assets current emit this event
    • totalBytes may not be reliable as it is based on the content-length header of the response
    asset.on('progress', (receivedBytes, totalBytes) => {
       console.log(`Asset ${asset.name} progress ${readBytes / totalBytes}`);
    });
    EVENT_REMOVE: string = 'remove'

    Fired when the asset is removed from the asset registry.

    asset.on('remove', (asset) => {
       console.log(`Asset removed: ${asset.name}`);
    });
    EVENT_REMOVELOCALIZED: string = 'remove:localized'

    Fired when we remove a localized asset id from the asset.

    asset.on('remove:localized', (locale, assetId) => {
      console.log(`Asset ${asset.name} has removed localized asset ${assetId} for locale ${locale}`);
    });
    EVENT_UNLOAD: string = 'unload'

    Fired just before the asset unloads the resource. This allows for the opportunity to prepare for an asset that will be unloaded. E.g. Changing the texture of a model to a default before the one it was using is unloaded.

    asset.on('unload', (asset) => {
       console.log(`Asset about to unload: ${asset.name}`);
    });

    Settings

    Member Visibility

    On This Page

    Constructors
    Properties
    Accessors
    Methods
    Events