Class Tags

Tags is a powerful tag management system for categorizing and filtering objects in PlayCanvas applications. It provides an efficient way to attach string identifiers to objects and query them using logical operations.

Tags are automatically available on Assets and Entitys (see Asset#tags and GraphNode#tags). You can search for specific assets via AssetRegistry#findByTag and specific entities via GraphNode#findByTag.

Hierarchy (View Summary)

EventHandler
- Tags

Index

Constructors

constructor

new Tags(parent?: any): Tags
Create an instance of a Tags.
Parameters
- Optionalparent: any
  Parent object who tags belong to.
Returns Tags
Overrides EventHandler.constructor
- Defined in src/core/tags.js:58

Accessors

size

get size(): number
Number of tags in set.

Returns number
- Defined in src/core/tags.js:295

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.
Example
```
tags.add('level-1');
```
Example
```
tags.add('ui', 'settings');
```
Example
```
tags.add(['level-2', 'mob']);
```
- Defined in src/core/tags.js:76

clear

clear(): void
Remove all tags.

Returns void
Example
```
tags.clear();
```
- Defined in src/core/tags.js:155

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 src/core/event-handler.js:274

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.
Example
```
tags.has('player'); // player
```
Example
```
tags.has('mob', 'player'); // player OR mob
```
Example
```
tags.has(['level-1', 'mob']); // monster AND level-1
```
Example
```
tags.has(['ui', 'settings'], ['ui', 'levels']); // (ui AND settings) OR (ui AND levels)
```
- Defined in src/core/tags.js:188

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
- Defined in src/core/event-handler.js:342

list

list(): string[]
Returns immutable array of tags.

Returns string[]
Copy of tags array.
- Defined in src/core/tags.js:239

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
- Optionalname: string
  Name of the event to unbind.
- Optionalcallback: HandleEventCallback
  Function to be unbound.
- Optionalscope: 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
- Defined in src/core/event-handler.js:154

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.
- Optionalscope: 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.on('test', (a, b) => {
    console.log(a + b);
});
obj.fire('test', 1, 2); // prints 3 to the console
```
Example
```
const evt = obj.on('test', (a, b) => {
    console.log(a + b);
});
// some time later
evt.off();
```
Inherited from EventHandler.on
- Defined in src/core/event-handler.js:112

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.
- Optionalscope: 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
- Defined in src/core/event-handler.js:132

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.
Example
```
tags.remove('level-1');
```
Example
```
tags.remove('ui', 'settings');
```
Example
```
tags.remove(['level-2', 'mob']);
```
- Defined in src/core/tags.js:116

Events

`Static`EVENT_ADD

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}`);
});

`Static`EVENT_CHANGE

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}`);
});

`Static`EVENT_REMOVE

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}`);
});

Class Tags

Hierarchy (View Summary)

Index

Constructors

Accessors

Methods

Events

Constructors

constructor

Parameters

Returns Tags

Accessors

size

Returns number

Methods

add

Parameters

Returns boolean

Example

Example

Example

clear

Returns void

Example

fire

Parameters

Returns EventHandler

Example

has

Parameters

Returns boolean

Example

Example

Example

Example

hasEvent

Parameters

Returns boolean

Example

list

Returns string[]

off

Parameters

Returns EventHandler

Example

on

Parameters

Returns EventHandle

Example

Example

once

Parameters

Returns EventHandle

Example

remove

Parameters

Returns boolean

Example

Example

Example

Events

StaticEVENT_ADD

Example

StaticEVENT_CHANGE

Example

StaticEVENT_REMOVE

Example

Settings

On This Page

`Static`EVENT_ADD

`Static`EVENT_CHANGE

`Static`EVENT_REMOVE