Tags

Studio

Tags

Tags are string identifiers that can be added to nodes. Tags can be used:

  • To identify or group certain nodes.
  • To easily perform common functions on multiple nodes.
  • To allow Raycasters to detect collisions.

Each node can have zero or more tags.

Adding a Tag

The Properties Panel

The easiest way to add a tag is to select a node in the Hierarchy and scroll down to the bottom of the Properties panel to the 'tags' property. From here, selecting the empty field and clicking on 'Create New Tag' will open a dialog box allowing you to enter a name for your tag.

Hitting 'OK' will add this tag to the node.

Once a tag has been added in this way, an additional entry will be created in the tags property for you to add further tags.

A tag can be removed by selecting the tag in the Properties panel and clicking on the '---' entry.

Script

In a script you can call the pushTag() function on a node to add a tag to it. Similarly you can call the removeTag() function to remove a tag.

Finally you can call the tags() setter function on a node to add multiple tags (in the form of an array) to a node.

Example
// Start with no tags
myObject.pushTag("myTag"); // One tag: myTag
myObject.removeTag("myTag"); // No tags
myObject.tags(["myTag1","myTag2","myTag3"]); // Three tags: myTag1, myTag2, myTag3

Using Tags

Utility Functions

The Z.byTag() function can be used to get an array of nodes with the given tag. This is useful for grouping nodes together.

Z.tagCall() is a powerful function that allows a common function to be called on all the nodes with the given tag. For instance you could change the color of all nodes with a certain tag by passing the color setter function along with the color to change to (see example below.)

Example
var nodesWithTag = Z.byTag("myTag"); // Store all nodes with the tag 'myTag' in 'nodesWithTag'
Z.tagCall("myTag","color",[1,0,0,1]); // Call the color function on all nodes with the tag 'myTag',
// passing in the array value equating to the color red.

Checking and Getting Tags

To check if a node has a certain tag you can use the hasTag() function, passing in the name of the tag you are looking for.

If the node in question has one or more tags you can use the tags() getter function to return an array of tags the node belongs to.

Example
myObject.hasTag("myTag"); // Check if the node 'myObject' has the tag 'myTag'.
var tags = myObject.tags(); // Get all tags belonging to 'myObject' and store them in 'tags'.

Scope

By default tags are symbol-scoped, meaning that functions such as Z.byTag(...) and Z.tagCall(...) will only return nodes in the same symbol as the script node they're called in.

Tags can have project scope by prefixing them with "global:" so they can be accessed across symbols.

Example
myObject.pushTag("global:myTag");

Collision Detection with Raycasters

A Raycaster node will only return intersection events on nodes that have the same tag as its colliderTag property.

For more information on Raycasters please see the Raycaster Overview page.

TriggerRegion Detection

A TriggerRegion node will only return trigger events on nodes that have the same tag as its triggerTag property.

Open in new window