API Reference

Class List

pc.Asset

Extends: pc.EventHandler

An asset record of a file or data resource that can be loaded by the engine. The asset contains three 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)
resource: contains the final resource when it is loaded. (e.g. a pc.StandardMaterial or a pc.Texture)
See the pc.AssetRegistry for details on loading resources from assets.

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

Summary

Properties

dataJSON data that contains either the complete resource data (e.
fileThe file details or null if no file
file.filenameThe filename of the resource file
file.hashThe MD5 hash of the resource file data and the Asset data field
file.sizeThe size of the resource file
file.urlThe URL of the resource file that contains the asset data
idThe asset id
loadedTrue if the resource is loaded.
nameThe name of the asset
preloadIf true the asset will be loaded during the preload phase of application set up.
registryThe asset registry that this Asset belongs to
resourceA reference to the resource when the asset is loaded.
resourcesA reference to the resources of the asset when it's loaded.
tagsInterface for tagging.
typeThe type of the asset.

Methods

getFileUrlReturn the URL required to fetch the file for this asset.
readyTake a callback which is called as soon as the asset is loaded.
unloadDestroys the associated resource and marks asset as unloaded.

Events

add:localizedFired when we add a new localized asset id to the asset.
changeFired when one of the asset properties `file`, `data`, `resource` or `resources` is changed
errorFired if the asset encounters an error while loading
loadFired when the asset has completed loading
removeFired when the asset is removed from the asset registry
remove:localizedFired when we remove a localized asset id from the asset.

Inherited

Methods

fireFire an event, all additional arguments are passed on to the event listener
hasEventTest if there are any handlers bound to an event name
offDetach an event handler from an event.
onAttach an event handler to an event
onceAttach an event handler to an event.

Details

Constructor

Asset(name, type, [file], [data])

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

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

Parameters

nameStringA non-unique but human-readable name which can be later used to retrieve the asset.
typeStringType of asset. One of ["animation", "audio", "binary", "cubemap", "css", "font", "json", "html", "material", "model", "script", "shader", "text", "texture"]
fileObjectDetails 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.
dataObjectJSON object 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)

Properties

Objectdata

JSON data that contains either the complete resource data (e.g. in the case of a material) or additional data (e.g. in the case of a model it contains mappings from mesh to material)

Objectfile

The file details or null if no file

Stringfile.filename

The filename of the resource file

Stringfile.hash

The MD5 hash of the resource file data and the Asset data field

Numberfile.size

The size of the resource file

Stringfile.url

The URL of the resource file that contains the asset data

Numberid

The asset id

Booleanloaded

True if the resource is loaded. e.g. if asset.resource is not null

Stringname

The name of the asset

Booleanpreload

If true the asset will be loaded during the preload phase of application set up.

pc.AssetRegistryregistry

The asset registry that this Asset belongs to

Objectresource

A reference to the resource when the asset is loaded. e.g. a pc.Texture or a pc.Model

Arrayresources

A reference to the resources of the asset when it's loaded. An asset can hold more runtime resources than one e.g. cubemaps

pc.Tagstags

Interface for tagging. Allows to find assets by tags using pc.AssetRegistry#findByTag method.

Stringtype

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

Methods

getFileUrl()

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

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

Returns

String The URL

ready(callback, [scope])

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

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

Parameters

callbackpc.callbacks.AssetReadyThe function called when the asset is ready. Passed the (asset) arguments
scopeObjectScope object to use when calling the callback

unload()

Destroys the associated resource and marks asset as unloaded.

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

Events

add:localized

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

Parameters

localeStringThe locale
assetIdNumberThe asset id we added.

change

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

Parameters

assetpc.AssetThe asset that was loaded
propertyStringThe name of the property that changed
value*The new property value
oldValue*The old property value

error

Fired if the asset encounters an error while loading

Parameters

errStringThe error message
assetpc.AssetThe asset that generated the error

load

Fired when the asset has completed loading

Parameters

assetpc.AssetThe asset that was loaded

remove

Fired when the asset is removed from the asset registry

Parameters

assetpc.AssetThe asset that was removed

remove:localized

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

Parameters

localeStringThe locale
assetIdNumberThe asset id we removed.

Inherited

Methods

fire(name, [arg1], [arg2], [arg3], [arg4], [arg5], [arg6], [arg7], [arg8])

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

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

Parameters

nameObjectName of event to fire
arg1*First argument that is passed to the event handler
arg2*Second argument that is passed to the event handler
arg3*Third argument that is passed to the event handler
arg4*Fourth argument that is passed to the event handler
arg5*Fifth argument that is passed to the event handler
arg6*Sixth argument that is passed to the event handler
arg7*Seventh argument that is passed to the event handler
arg8*Eighth argument that is passed to the event handler

Returns

pc.EventHandler Self for chaining.

hasEvent(name)

Test if there are any handlers bound to an event name

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

Parameters

nameStringThe name of the event to test

Returns

Boolean true if the object has handlers bound to the specified event name.

off([name], [callback], [scope])

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.

var 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 hander functions, called 'test' with scope this

Parameters

nameStringName of the event to unbind
callbackpc.callbacks.HandleEventFunction to be unbound.
scopeObjectScope that was used as the this when the event is fired

Returns

pc.EventHandler Self for chaining.

on(name, callback, [scope])

Attach an event handler to an event

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

Parameters

nameStringName of the event to bind the callback to
callbackpc.callbacks.HandleEventFunction that is called when event is fired. Note the callback is limited to 8 arguments.
scopeObjectObject to use as 'this' when the event is fired, defaults to current this

Returns

pc.EventHandler Self for chaining.

once(name, callback, [scope])

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

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

Parameters

nameStringName of the event to bind the callback to
callbackpc.callbacks.HandleEventFunction that is called when event is fired. Note the callback is limited to 8 arguments.
scopeObjectObject to use as 'this' when the event is fired, defaults to current this

Returns

pc.EventHandler Self for chaining.