Mirror Engine
V5
How To
Mirror Engine Logo

Mirror Engine API


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?

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.

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

Asset

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

EventHandler

Self for chaining.

Example

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

Inherited from

EventHandler.fire


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

EventHandler.hasEvent


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

EventHandler

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

EventHandler.off


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

EventHandle

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

EventHandler.on


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

EventHandle

  • 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

EventHandler.once


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}'}`)
})
Mirror Engine Logo