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;