Subsymbol Communication

Passing information between symbols is key to getting the most use out of them.

Symbol communication can be broken down into three main subheadings:

  • Accessing controllers
  • Accessing nodes
  • Accessing exported functions and variables

For the purposes of this article, we will use the example of a parent symbol communicating with a subsymbol, though the same is also true of subsymbol-to-subsymbol communication.

Creating an instance of the subsymbol

Before we can proceed we need a variable storing an instance of the subsymbol we want to access within a script node. We'll use this variable to access the information within the subsymbol.

Dragging a subsymbol from the Symbol Definitions Panel into a script and selecting 'Construct symbol' adds code that constructs a new instance of the symbol and assigns it to a variable.

Alternatively, dragging an instance of a subsymbol from the Hierarchy into a script and selecting 'insert local variable' will create a variable referencing the instance created in the Hierarchy.

// constructing from the Symbol Definitions Panel
var mySubsymbolConstructed = symbol.symbolDefinitions.mySubsymbol();

// instance referenced from the Hierarchy
var mySubsymbolInstance = symbol.nodes.mySubsymbol;

Symbols constructed within a script node will not display automatically. For Blank symbols, we recommend adding them to the Hierarchy at runtime using the Z.Group push function. For Screen symbols we recommend using the symbol's display function, for more information see the Screen Symbol article.

Accessing controllers

Accessing the timelines and states of a subsymbol allows us to control the animations from the parent symbol.

In order to activate a state or play a timeline within a subsymbol from the parent symbol, you need to be able to access the controller for that subsymbol.

To access the list of controllers in a subsymbol you use the following syntax:

mySubsymbol.controllers

Adding a further dot will allow you to specify a controller by name:

mySubsymbol.controllers.myController

To access the states and timelines within that controller, which are of the Z.Element type, you use the elements keyword:

mySubsymbol.controllers.myController.elements

From there the individual states and timelines can be accessed:

mySubsymbol.controllers.myController.elements.myState

You can then use the functions of the given state or timeline:

mySubsymbol.controllers.myController.elements.myState.activate();

Accessing nodes

You can access the nodes within a subsymbol's Hierarchy using the nodes keyword:

mySubsymbol.nodes

From there the individual nodes can be accessed by name:

mySubsymbol.nodes.myPlane

You can then use the functions of the node (in this case the Z.Object color function):

mySubsymbol.nodes.myPlane.color([1,0,0,1]);

Accessing exported functions and variables

Functions and variables can be declared in one script and retrieved in another using the export keyword. The example below uses two script nodes, script1 and script2, within the same symbol.

// script1
export let myVariable;
// script2
symbol.nodes.script1.myVariable;

The same functionality can be used to access exported variables and functions within subsymbols.

// 'myScript' script node within the subsymbol
export let myVariable;
// script node within the parent symbol
mySubsymbol.nodes.myScript.myVariable;
zapcode branded_zapcode i