Mirror Engine API / Tags
Class: Tags
Set of tag names. Tags are automatically available on Entity and Asset as tags
field.
Extends
Constructors
new Tags()
new Tags(parent?: any): Tags
Create an instance of a Tags.
Parameters
parent?
any
Parent object who tags belong to.
Returns
Overrides
EventHandler.constructor
size
Get Signature
get size(): number
Number of tags in set.
Returns
number
Methods
add()
add(...args: any[]): boolean
Add a tag, duplicates are ignored. Can be array or comma separated arguments for multiple tags.
Parameters
args
...any[]
Name of a tag, or array of tags.
Returns
boolean
True if any tag were added.
Examples
tags.add('level-1')
tags.add('ui', 'settings')
tags.add([
'level-2',
'mob'
])
clear()
clear(): void
Remove all tags.
Returns
void
Example
tags.clear()
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
has()
has(...query: any[]): boolean
Check if tags satisfy filters. Filters can be provided by simple name of tag, as well as by array of tags. When an array is provided it will check if tags contain each tag within the array. If any of comma separated argument is satisfied, then it will return true. Any number of combinations are valid, and order is irrelevant.
Parameters
query
...any[]
Name of a tag or array of tags.
Returns
boolean
True if filters are satisfied.
Examples
tags.has('player') // player
tags.has('mob', 'player') // player OR mob
tags.has([
'level-1',
'mob'
]) // monster AND level-1
tags.has(
[
'ui',
'settings'
],
[
'ui',
'levels'
]
) // (ui AND settings) OR (ui AND levels)
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
list()
list(): string[]
Returns immutable array of tags.
Returns
string[]
Copy of tags array.
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
remove()
remove(...args: any[]): boolean
Remove tag.
Parameters
args
...any[]
Name of a tag or array of tags.
Returns
boolean
True if any tag were removed.
Examples
tags.remove('level-1')
tags.remove('ui', 'settings')
tags.remove([
'level-2',
'mob'
])
Events
EVENT_ADD
static EVENT_ADD: string = 'add';
Fired for each individual tag that is added.
Example
tags.on('add', (tag, parent) => {
console.log(`${'${tag}'} added to ${'${parent.name}'}`)
})
EVENT_CHANGE
static EVENT_CHANGE: string = 'change';
Fired when tags have been added or removed. It will fire once on bulk changes, while add
and remove will fire on each tag operation.
Example
tags.on('change', (parent) => {
console.log(`Tags changed on ${'${parent.name}'}`)
})
EVENT_REMOVE
static EVENT_REMOVE: string = 'remove';
Fired for each individual tag that is removed.
Example
tags.on('remove', (tag, parent) => {
console.log(`${'${tag}'} removed from ${'${parent.name}'}`)
})