Mirror Engine API / Asset
Class: Asset
Work in progress for integrating with Mirror Engine's Asset Management system.
Extends
Constructors
new Asset()
new Asset(
name: string,
type: string,
file?: {
contents: ArrayBuffer;
filename: string;
hash: string;
size: number;
url: string;
},
data?: any,
options?: {
crossOrigin: null | "anonymous" | "use-credentials";
}): 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"]
file?
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?
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.
data?
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).
options?
The asset handler options. For container options see ContainerHandler.
crossOrigin?
null | "anonymous" | "use-credentials"
For use with texture assets that are loaded using the browser. This setting overrides the default crossOrigin specifier. For more details on crossOrigin and its use, see https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/crossOrigin.
Returns
Example
const asset = new Asset('a texture', 'texture', {
url: 'http://example.com/my/assets/here/texture.png'
})
Overrides
EventHandler.constructor
Properties
_file
_file: null | AssetFile
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: any
Optional JSON data that contains the asset handler options.
registry
registry: null | 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"
| "binary"
| "texture"
| "model"
| "sprite"
| "render"
| "cubemap"
| "material"
| "css"
| "shader"
| "textureatlas";
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"]
data
Get Signature
get data(): any
Gets optional asset JSON data.
Returns
any
Set Signature
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
file
Get Signature
get file(): any
Gets the file details or null if no file.
Returns
any
Set Signature
set file(value: any): void
Sets the file details or null if no file.
Parameters
value
any
Returns
void
id
Get Signature
get id(): number
Gets the asset id.
Returns
number
Set Signature
set id(value: number): void
Sets the asset id.
Parameters
value
number
Returns
void
name
Get Signature
get name(): string
Gets the asset name.
Returns
string
Set Signature
set name(value: string): void
Sets the asset name.
Parameters
value
string
Returns
void
preload
Get Signature
get preload(): boolean
Gets whether to preload an asset.
Returns
boolean
Set Signature
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
resource
Get Signature
get resource(): any
Gets the asset resource.
Returns
any
Set Signature
set resource(value: any): void
Sets the asset resource. For example, a Texture or a Model.
Parameters
value
any
Returns
void
resources
Get Signature
get resources(): any[]
Gets the asset resources.
Returns
any[]
Set Signature
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()
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.
arg1?
any
First argument that is passed to the event handler.
arg2?
any
Second argument that is passed to the event handler.
arg3?
any
Third argument that is passed to the event handler.
arg4?
any
Fourth argument that is passed to the event handler.
arg5?
any
Fifth argument that is passed to the event handler.
arg6?
any
Sixth argument that is passed to the event handler.
arg7?
any
Seventh argument that is passed to the event handler.
arg8?
any
Eighth argument that is passed to the event handler.
Returns
Self for chaining.
Example
obj.fire('test', 'This is the message')
Inherited from
getFileUrl()
getFileUrl(): null | string
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.
Example
const assets = app.assets.find('My Image', 'texture')
const img = "<img src='" + assets[0].getFileUrl() + "'>"
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', () => {}) // bind an event to 'test'
obj.hasEvent('test') // returns true
obj.hasEvent('hello') // returns false
Inherited from
off()
off(
name?: string,
callback?: HandleEventCallback,
scope?: any): 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
name?
string
Name of the event to unbind.
callback?
HandleEventCallback
Function to be unbound.
scope?
any
Scope that was used as the this when the event is fired.
Returns
Self for chaining.
Example
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
Inherited from
on()
on(
name: string,
callback: HandleEventCallback,
scope?: any): 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.
scope?
any = ...
Object to use as 'this' when the event is fired, defaults to current this.
Returns
Can be used for removing event in the future.
Examples
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()
Inherited from
once()
once(
name: string,
callback: HandleEventCallback,
scope?: any): 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.
scope?
any = ...
Object to use as 'this' when the event is fired, defaults to current this.
Returns
- can be used for removing event in the future.
Example
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
Inherited from
ready()
ready(callback: AssetReadyCallback, scope?: any): 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.
scope?
any
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
EVENT_ADDLOCALIZED
static 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}'}`
)
})
EVENT_CHANGE
static 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}'}`
)
})
EVENT_ERROR
static 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}'}`)
})
EVENT_LOAD
static EVENT_LOAD: string = 'load';
Fired when the asset has completed loading.
Example
asset.on('load', (asset) => {
console.log(`Asset loaded: ${'${asset.name}'}`)
})
EVENT_PROGRESS
static 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
Example
asset.on('progress', (receivedBytes, totalBytes) => {
console.log(
`Asset ${'${asset.name}'} progress ${'${readBytes / totalBytes}'}`
)
})
EVENT_REMOVE
static 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}'}`)
})
EVENT_REMOVELOCALIZED
static 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}'}`
)
})
EVENT_UNLOAD
static 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}'}`)
})