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 full)

Constructors

constructor

Properties

loaded loading options registry tags type

Accessors

data file id name preload resource resources

Methods

fire getFileUrl hasEvent off on once ready unload

Events

EVENT_ADDLOCALIZED EVENT_CHANGE EVENT_ERROR EVENT_LOAD EVENT_REMOVE EVENT_REMOVELOCALIZED EVENT_UNLOAD

Constructors

constructor

  • new Asset(name, type, file?, data?, options?): Asset

  • 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: string

      Type of asset. One of ["animation", "audio", "binary", "bundle", "container", "cubemap", "css", "font", "json", "html", "material", "model", "script", "shader", "sprite", "template", text", "texture", "textureatlas"]

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

      • contents: ArrayBuffer

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

      • filename: string

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

      • hash: 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).

      • size: number

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

      • url: string

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

    • Optionaldata: string | object

      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: "anonymous" | "use-credentials";
      }

      The asset handler options. For container options see ContainerHandler.

    Returns Asset

    Example

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

Properties

loaded

loaded: boolean

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

loading: boolean

True if the resource is currently being loaded.

options

options: object

Optional JSON data that contains the asset handler options.

registry

registry: AssetRegistry

The asset registry that this Asset belongs to.

tags

tags: Tags

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

type

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

The type of the asset. One of ["animation", "audio", "binary", "container", "cubemap", "css", "font", "json", "html", "material", "model", "render", "script", "shader", "sprite", "template", "text", "texture", "textureatlas"]

Accessors

data

  • get data(): object

  • Gets optional asset JSON data.

    Returns object

  • set data(value): 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: object

    Returns void

file

id

name

preload

resource

resources

Methods

fire

  • fire(name, arg1?, arg2?, arg3?, arg4?, arg5?, arg6?, arg7?, arg8?): EventHandler

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

    Example

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

getFileUrl

  • getFileUrl(): string

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

    Returns string

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

    Example

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

hasEvent

  • hasEvent(name): boolean

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

    Example

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

off

  • off(name?, callback?, scope?): EventHandler

  • 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: object

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

    Returns EventHandler

    Self for chaining.

    Example

    const handler = function () {
    };
    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

on

  • on(name, callback, scope?): EventHandle

  • 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: object = ...

      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.

    Example

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

    Example

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

once

  • once(name, callback, scope?): EventHandle

  • 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: object = ...

      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.

    Example

    obj.once('test', function (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

ready

  • ready(callback, scope?): void

  • 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: object

      Scope object to use when calling the callback.

    Returns void

    Example

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

unload

  • unload(): void

  • Destroys the associated resource and marks asset as unloaded.

    Returns void

    Example

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

Events

StaticEVENT_ADDLOCALIZED

EVENT_ADDLOCALIZED: string = 'add:localized'

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

Example

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

StaticEVENT_CHANGE

EVENT_CHANGE: string = 'change'

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

Example

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

StaticEVENT_ERROR

EVENT_ERROR: string = 'error'

Fired if the asset encounters an error while loading.

Example

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

StaticEVENT_LOAD

EVENT_LOAD: string = 'load'

Fired when the asset has completed loading.

Example

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

StaticEVENT_REMOVE

EVENT_REMOVE: string = 'remove'

Fired when the asset is removed from the asset registry.

Example

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

StaticEVENT_REMOVELOCALIZED

EVENT_REMOVELOCALIZED: string = 'remove:localized'

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

Example

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

StaticEVENT_UNLOAD

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.

Example

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

Settings

Member Visibility

On This Page

Constructors
Properties
Accessors
Methods
Events