Class AssetRegistry

Container for all assets that are available to this application. Note that PlayCanvas scripts are provided with an AssetRegistry instance as app.assets.

Hierarchy (view full)

Constructors

constructor

Properties

bundles prefix

Methods

add filter find findAll findByTag fire get getByUrl hasEvent list load loadFromUrl loadFromUrlAndFilename off on once remove

Events

EVENT_ADD EVENT_ERROR EVENT_LOAD EVENT_REMOVE

Constructors

constructor

Properties

bundles

bundles: BundleRegistry = null

BundleRegistry

prefix

prefix: string = null

A URL prefix that will be added to all asset loading requests.

Methods

add

  • add(asset): void

  • Add an asset to the registry.

    Parameters

    • asset: Asset

      The asset to add.

    Returns void

    Example

    const asset = new pc.Asset("My Asset", "texture", {
        url: "../path/to/image.jpg"
    });
    app.assets.add(asset);

filter

  • filter(callback): Asset[]

  • Return all Assets that satisfy a filter callback.

    Parameters

    • callback: FilterAssetCallback

      The callback function that is used to filter assets. Return true to include an asset in the returned array.

    Returns Asset[]

    A list of all Assets found.

    Example

    const assets = app.assets.filter(asset => asset.name.includes('monster'));
    console.log(`Found ${assets.length} assets with a name containing 'monster'`);

find

  • find(name, type?): Asset

  • Return the first Asset with the specified name and type found in the registry.

    Parameters

    • name: string

      The name of the Asset to find.

    • Optionaltype: string

      The type of the Asset to find.

    Returns Asset

    A single Asset or null if no Asset is found.

    Example

    const asset = app.assets.find("myTextureAsset", "texture");

findAll

  • findAll(name, type?): Asset[]

  • Return all Assets with the specified name and type found in the registry.

    Parameters

    • name: string

      The name of the Assets to find.

    • Optionaltype: string

      The type of the Assets to find.

    Returns Asset[]

    A list of all Assets found.

    Example

    const assets = app.assets.findAll('brick', 'texture');
    console.log(`Found ${assets.length} texture assets named 'brick'`);

findByTag

  • findByTag(...args): Asset[]

  • Return all Assets that satisfy the search query. Query can be simply a string, or comma separated strings, to have inclusive results of assets that match at least one query. A query that consists of an array of tags can be used to match assets that have each tag of array.

    Parameters

    • Rest...args: any

    Returns Asset[]

    A list of all Assets matched query.

    Example

    const assets = app.assets.findByTag("level-1");
    // returns all assets that tagged by `level-1`

    Example

    const assets = app.assets.findByTag("level-1", "level-2");
    // returns all assets that tagged by `level-1` OR `level-2`

    Example

    const assets = app.assets.findByTag(["level-1", "monster"]);
    // returns all assets that tagged by `level-1` AND `monster`

    Example

    const assets = app.assets.findByTag(["level-1", "monster"], ["level-2", "monster"]);
    // returns all assets that tagged by (`level-1` AND `monster`) OR (`level-2` AND `monster`)

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');

get

getByUrl

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

list

load

  • load(asset, options?): void

  • Load the asset's file from a remote source. Listen for "load" events on the asset to find out when it is loaded.

    Parameters

    • asset: Asset

      The asset to load.

    • Optionaloptions: {
          bundlesFilter: BundlesFilterCallback;
          bundlesIgnore: boolean;
          force: boolean;
      }

      Options for asset loading.

      • bundlesFilter: BundlesFilterCallback

        A callback that will be called when loading an asset that is contained in any of the bundles. It provides an array of bundles and will ensure asset is loaded from bundle returned from a callback. By default smallest filesize bundle is choosen.

      • bundlesIgnore: boolean

        If set to true, then asset will not try to load from a bundle. Defaults to false.

      • force: boolean

        If set to true, then the check of asset being loaded or is already loaded is bypassed, which forces loading of asset regardless.

    Returns void

    Example

    // load some assets
    const assetsToLoad = [
        app.assets.find("My Asset"),
        app.assets.find("Another Asset")
    ];
    let count = 0;
    assetsToLoad.forEach(function (assetToLoad) {
        assetToLoad.ready(function (asset) {
            count++;
            if (count === assetsToLoad.length) {
                // done
            }
        });
        app.assets.load(assetToLoad);
    });

loadFromUrl

  • loadFromUrl(url, type, callback): void

  • Use this to load and create an asset if you don't have assets created. Usually you would only use this if you are not integrated with the PlayCanvas Editor.

    Parameters

    • url: string

      The url to load.

    • type: string

      The type of asset to load.

    • callback: LoadAssetCallback

      Function called when asset is loaded, passed (err, asset), where err is null if no errors were encountered.

    Returns void

    Example

    app.assets.loadFromUrl("../path/to/texture.jpg", "texture", function (err, asset) {
        const texture = asset.resource;
    });

loadFromUrlAndFilename

  • loadFromUrlAndFilename(url, filename, type, callback): void

  • Use this to load and create an asset when both the URL and filename are required. For example, use this function when loading BLOB assets, where the URL does not adequately identify the file.

    Parameters

    • url: string

      The url to load.

    • filename: string

      The filename of the asset to load.

    • type: string

      The type of asset to load.

    • callback: LoadAssetCallback

      Function called when asset is loaded, passed (err, asset), where err is null if no errors were encountered.

    Returns void

    Example

    const file = magicallyObtainAFile();
    app.assets.loadFromUrlAndFilename(URL.createObjectURL(file), "texture.png", "texture", function (err, asset) {
        const texture = asset.resource;
    });

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

remove

  • remove(asset): boolean

  • Remove an asset from the registry.

    Parameters

    • asset: Asset

      The asset to remove.

    Returns boolean

    True if the asset was successfully removed and false otherwise.

    Example

    const asset = app.assets.get(100);
    app.assets.remove(asset);

Events

StaticEVENT_ADD

EVENT_ADD: string = 'add'

Fired when an asset is added to the registry. This event is available in three forms. They are as follows:

  1. add - Fired when any asset is added to the registry.
  2. add:[id] - Fired when an asset is added to the registry, where [id] is the unique id of the asset.
  3. add:url:[url] - Fired when an asset is added to the registry and matches the URL [url], where [url] is the URL of the asset.

Example

app.assets.on('add', (asset) => {
   console.log(`Asset added: ${asset.name}`);
});

Example

const id = 123456;
app.assets.on('add:' + id, (asset) => {
   console.log(`Asset added: ${asset.name}`);
});

Example

const id = 123456;
const asset = app.assets.get(id);
app.assets.on('add:url:' + asset.file.url, (asset) => {
   console.log(`Asset added: ${asset.name}`);
});

StaticEVENT_ERROR

EVENT_ERROR: string = 'error'

Fired when an error occurs during asset loading. This event is available in two forms. They are as follows:

  1. error - Fired when any asset reports an error in loading.
  2. error:[id] - Fired when an asset reports an error in loading, where [id] is the unique id of the asset.

Example

const id = 123456;
const asset = app.assets.get(id);
app.assets.on('error', (err, asset) => {
    console.error(err);
});
app.assets.load(asset);

Example

const id = 123456;
const asset = app.assets.get(id);
app.assets.on('error:' + id, (err, asset) => {
    console.error(err);
});
app.assets.load(asset);

StaticEVENT_LOAD

EVENT_LOAD: string = 'load'

Fired when an asset completes loading. This event is available in three forms. They are as follows:

  1. load - Fired when any asset finishes loading.
  2. load:[id] - Fired when a specific asset has finished loading, where [id] is the unique id of the asset.
  3. load:url:[url] - Fired when an asset finishes loading whose URL matches [url], where [url] is the URL of the asset.

Example

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

Example

const id = 123456;
const asset = app.assets.get(id);
app.assets.on('load:' + id, (asset) => {
    console.log(`Asset loaded: ${asset.name}`);
});
app.assets.load(asset);

Example

const id = 123456;
const asset = app.assets.get(id);
app.assets.on('load:url:' + asset.file.url, (asset) => {
    console.log(`Asset loaded: ${asset.name}`);
});
app.assets.load(asset);

StaticEVENT_REMOVE

EVENT_REMOVE: string = 'remove'

Fired when an asset is removed from the registry. This event is available in three forms. They are as follows:

  1. remove - Fired when any asset is removed from the registry.
  2. remove:[id] - Fired when an asset is removed from the registry, where [id] is the unique id of the asset.
  3. remove:url:[url] - Fired when an asset is removed from the registry and matches the URL [url], where [url] is the URL of the asset.

Param: asset

The asset that was removed.

Example

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

Example

const id = 123456;
app.assets.on('remove:' + id, (asset) => {
   console.log(`Asset removed: ${asset.name}`);
});

Example

const id = 123456;
const asset = app.assets.get(id);
app.assets.on('remove:url:' + asset.file.url, (asset) => {
   console.log(`Asset removed: ${asset.name}`);
});

Settings

Member Visibility

On This Page

Constructors
Properties
Methods
Events