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

EventHandler
- AssetRegistry

Index

Constructors

constructor

new AssetRegistry(loader: ResourceLoader): AssetRegistry
Create an instance of an AssetRegistry.
Parameters
- loader: ResourceLoader
  The ResourceLoader used to load the asset files.
Returns AssetRegistry
Overrides EventHandler.constructor
- Defined in submodules/engine/src/framework/asset/asset-registry.js:212

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: 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);
```
- Defined in submodules/engine/src/framework/asset/asset-registry.js:242

filter

filter(callback: FilterAssetCallback): 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'`);
```
- Defined in submodules/engine/src/framework/asset/asset-registry.js:728

find

find(name: string, type?: string): 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");
```
- Defined in submodules/engine/src/framework/asset/asset-registry.js:741

findAll

findAll(name: string, type?: string): 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'`);
```
- Defined in submodules/engine/src/framework/asset/asset-registry.js:764

findByTag

findByTag(...args: any): 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

...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: string,
    arg1?: any,
    arg2?: any,
    arg3?: any,
    arg4?: any,
    arg5?: any,
    arg6?: any,
    arg7?: any,
    arg8?: any,
): 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');
```
Inherited from EventHandler.fire
- Defined in submodules/engine/src/core/event-handler.js:265

get

get(id: number): Asset
Retrieve an asset from the registry by its id field.
Parameters
- id: number
  The id of the asset to get.
Returns Asset
The asset.
Example
```
const asset = app.assets.get(100);
```
- Defined in submodules/engine/src/framework/asset/asset-registry.js:332

getByUrl

getByUrl(url: string): Asset
Retrieve an asset from the registry by its file's URL field.
Parameters
- url: string
  The url of the asset to get.
Returns Asset
The asset.
Example
```
const asset = app.assets.getByUrl("../path/to/image.jpg");
```
- Defined in submodules/engine/src/framework/asset/asset-registry.js:345

hasEvent

hasEvent(name: string): 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
```
Inherited from EventHandler.hasEvent
- Defined in submodules/engine/src/core/event-handler.js:333

list

list(filters?: object): Asset[]
Create a filtered list of assets from the registry.
Parameters
- filters: object = {}
  Properties to filter on, currently supports: 'preload: true|false'.
Returns Asset[]
The filtered list of assets.
- Defined in submodules/engine/src/framework/asset/asset-registry.js:224

load

load(
    asset: Asset,
    options?: {
        bundlesFilter?: BundlesFilterCallback;
        bundlesIgnore?: boolean;
        force?: boolean;
    },
): 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.
  - OptionalbundlesFilter?: 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.
  - OptionalbundlesIgnore?: boolean
    If set to true, then asset will not try to load from a bundle. Defaults to false.
  - Optionalforce?: 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);
});
```
- Defined in submodules/engine/src/framework/asset/asset-registry.js:380

loadFromUrl

loadFromUrl(url: string, type: string, callback: LoadAssetCallback): 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;
});
```
- Defined in submodules/engine/src/framework/asset/asset-registry.js:507

loadFromUrlAndFilename

loadFromUrlAndFilename(
    url: string,
    filename: string,
    type: string,
    callback: LoadAssetCallback,
): 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;
});
```
- Defined in submodules/engine/src/framework/asset/asset-registry.js:527

off

off(name?: string, callback?: HandleEventCallback, scope?: object): 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
```
Inherited from EventHandler.off
- Defined in submodules/engine/src/core/event-handler.js:145

on

on(name: string, callback: HandleEventCallback, scope?: object): 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();
```
Inherited from EventHandler.on
- Defined in submodules/engine/src/core/event-handler.js:102

once

once(name: string, callback: HandleEventCallback, scope?: object): 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
```
Inherited from EventHandler.once
- Defined in submodules/engine/src/core/event-handler.js:122

remove

remove(asset: 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);
```
- Defined in submodules/engine/src/framework/asset/asset-registry.js:288

Events

`Static`EVENT_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:

add - Fired when any asset is added to the registry.
add:[id] - Fired when an asset is added to the registry, where [id] is the unique id of the asset.
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}`);
});

`Static`EVENT_ERROR

EVENT_ERROR: string = 'error'

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

error - Fired when any asset reports an error in loading.
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);

`Static`EVENT_LOAD

EVENT_LOAD: string = 'load'

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

load - Fired when any asset finishes loading.
load:[id] - Fired when a specific asset has finished loading, where [id] is the unique id of the asset.
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);

`Static`EVENT_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:

remove - Fired when any asset is removed from the registry.
remove:[id] - Fired when an asset is removed from the registry, where [id] is the unique id of the asset.
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}`);
});

Class AssetRegistry

Hierarchy (View Summary)

Index

Constructors

Properties

Methods

Events

Constructors

constructor

Parameters

Returns AssetRegistry

Properties

bundles

prefix

Methods

add

Parameters

Returns void

Example

filter

Parameters

Returns Asset[]

Example

find

Parameters

Returns Asset

Example

findAll

Parameters

Returns Asset[]

Example

findByTag

Parameters

Returns Asset[]

Example

Example

Example

Example

fire

Parameters

Returns EventHandler

Example

get

Parameters

Returns Asset

Example

getByUrl

Parameters

Returns Asset

Example

hasEvent

Parameters

Returns boolean

Example

list

Parameters

Returns Asset[]

load

Parameters

OptionalbundlesFilter?: BundlesFilterCallback

OptionalbundlesIgnore?: boolean

Optionalforce?: boolean

Returns void

Example

loadFromUrl

Parameters

Returns void

Example

loadFromUrlAndFilename

Parameters

Returns void

Example

off

Parameters

Returns EventHandler

Example

on

Parameters

Returns EventHandle

Example

`Optional`bundlesFilter?: BundlesFilterCallback

`Optional`bundlesIgnore?: boolean

`Optional`force?: boolean

`Static`EVENT_ADD

`Static`EVENT_ERROR

`Static`EVENT_LOAD

`Static`EVENT_REMOVE