Introduction to Logic Nodes
Armory's logic nodes provide a visual way of creating interactive behaviour. Nodes are "building blocks" for some common procedures, which grouped together create a node tree that describes the behaviour of a trait. Each node can be executed and will then run the functionality it represents. When you build your project, the logic node trees that you've created are automatically translated into Haxe code.
A common mistake is to forget to add a trait to an object or scene when a new logic node tree was created. A logic tree alone is not a trait, it needs to be referenced from a node trait to be used!
The compilation to Haxe can lead to warnings depending on the name of the node tree. If you see such a warning, please read this note.
The functionality of individual logic nodes is described in the reference, for an in-depth look over the internals of logic nodes, please read the page on logic node development.
Logic nodes can be edited in the Logic Node Editor. To open it, change the type of an area in the Blender user interface to Logic Node Editor as shown in the following screenshot:
To create a new node tree, click on New at the header of the node editor. A node tree contains all logic nodes that belong to the trait.
You can add nodes to the current tree with Shift + A or via Add in the node editor's menu bar. If you press S while the Add menu is opened, you can search for logic nodes. Logic nodes can also be added via Blender's search operator (F3). Logic nodes are grouped into categories for easier navigation.
A logic node looks like this:
The inputs and outputs of Blender nodes are called sockets. To connect nodes, simply drag with the mouse from one input socket to another output socket.
- Input sockets can either activate the node (execute it) or can be used by the node to retrieve data from other node's outputs.
- Output sockets can send impulses to other connected nodes to activate them or hold data to be retrieved.
So sockets allow you to send information between connected nodes. The kind of information is explained in more detail further below.
Tip:
Because most nodes need an active input to be activated, nodes from the event and input categories are a good starting point for your node tree!
In addition to that, nodes can have further settings (operators and properties in Blender terminology), which can alter the functionality of a node. Operators are buttons in the user interface with some functionality (for example adding new outputs). Properties are values that are unique to a node, they behave like input sockets but without the ability to connect them to another node.
Each socket has a type which is denoted by the socket's color. The type defines the kind of data with which the socket can interact, for example this could be numbers or objects. If the socket is an input socket it expects to receive data of its type, and if it's an output socket, it holds data of its type. When connecting nodes, make sure to only connect sockets that are compatible with each other and do not create cyclic connections.
The following is a list of sockets used in Armory's logic nodes. External logic node packages might define their own socket types. Please click on a socket type below to see its corresponding description.
Action socket
Special socket that represents an impulse to activate connected nodes. If an output with an action socket is activated, all nodes that are connected to it are activated through the connected inputs. A node can have different functionality depending on what input is activated. This is usually described by the input's name, and in more detail in the node's documentation in the Logic Nodes Reference.
Please do not confuse action sockets with boolean sockets! Action sockets do not have a value, they're either active or not. They're simply connections between nodes, nothing more.
Animation socket
Represents an animation.
Array socket
Represents a sequence of arbitrary data. The contained data might have different types depending on the use case, please make sure to only use types that fit the specific use case.
More information: Haxe manual: Array.
Boolean socket
Represents a value that is either true or false.
Color socket
Dynamic socket
Special socket for values of arbitrary/dynamic types. For more information on this, please read Haxe manual: Dynamic.
Float socket
Represents a floating point number, the precision might vary between platforms. Many math related logic nodes use the 32 bit kha.FastFloat type.
Integer socket
Represents an integer number.
Object socket
Represents an object in the scene.
Rotation socket
Represents an 3-dimensional rotation. Rotation sockets let you specify rotations in a large variety of representations. Internally the socket data is converted to a quaternion.
There are the following ways of specifying a rotation:
-
Euler Angles: specifies the amount of rotation (in degrees or radians) around the X, Y and Z axis.
The order of the Euler representation (here shown as its default value,XYZ) specifies in which order the 1-axis rotations are applied. For instanceXYZcorresponds to having a pure-X rotation on the object, but also having a parent object with a pure-Y rotation, which itself has a parent object with a pure-Z rotation. -
Axis/Angle: The XYZ vector describes the axis around which to rotate. The angle is the amount of rotation in degrees or radians. -
Quaternion: specifies the rotation with a quaternion.
String socket
Represents a sequence of characters (text).
Vector socket
Represents a vector of iron.math.Vec4. The actual used dimension might vary between nodes.
Tip:
Connections between sockets have something like an "inherent direction":
- Connections between Action sockets go from output to input. An output will activate all inputs of other nodes that are connected to it and thus execute the connected nodes.
- All other connections used for data transfer are the other way around: each input socket will "grab" the value from the connected output socket.
Some sockets have a small dot inside of them. This dot tells you that this socket is an interface to a variable value that is stored between executions of this trait (over multiple frames). Nodes with those sockets are called variable nodes, documentation for the individual nodes can be found in the reference.
By default, indiviual variable nodes have a unique identity just like any other node. However, multiple variable nodes can be linked together so that they share the same value at runtime. This helps to make node trees more readable.
In previous versions of Armory, this could be done by assigning an ID to variable nodes, but since SDK 2022.03 there exists a new system for so-called tree variables as explained below. Files saved with older versions of Armory are automatically updated to the new system.
Variable nodes share their values by linking them to the same tree variable. Each tree variable has a unique name, a color, and a data type that is identical to the type of the variable nodes linked to it. Variable nodes can only be linked to tree variables of the same type.
Tree variables are managed in the Tree Variables panel of the Armory tab in the node editor's sidebar (default shortcut: N):
Explanations of the highlighted areas in the screenshot above:
-
New Var From Node: creates a new tree variable and links the selected variable node to it. After linking, the selected node is colored in the variable's color, hides its input sockets and other settings, and shows that it is linked:
The tree variable's values can now be edited in the sidebar when the tree variable is selected in the list (see 7. below).
This operator is only available if the selected variable node is not yet linked to a tree variable.
-
Make Node Local: unlinks the selected variable node from the selected tree variable. If the selected node was the last to link to the tree variable, the tree variable is removed since tree variables only exist as long as there are nodes that link to them. This is due to technical reasons.
This operator is only available if the selected variable node is linked to a tree variable.
-
The list of tree variables that belong to the current logic tree. The color of a variable can be changed by clicking on the colored square and the name of the variable by double-clicking on the name. The arrows on the right next to the variable list move the selected variable up or down in the list.
-
Assign To Node: assign the selected tree variable to the selected variable node.
-
Add Getter: Convenience operator to add a new variable node that links to the selected tree variable. This operation is identical to creating a new variable node and using the Assign To Node operator.
-
Add Setter: Convenience operator to add a new variable node that links to the selected tree variable and a node that sets the variable's value.
-
The value of the selected tree variable.
If tree variables are used in node groups, their values are unique per group instance. More information can be found in the Special Cases section of the node group documentation.
Node groups may be used to reduce the repetitive usage of logic nodes in a node tree and make the tree more elegant.
Armory logic node trees can be used as node groups in other logic node trees. To create a new node group, first create a new logic tree. In this tree, add a Group Input Node and/or a Group Output Node. So a node group may have just an input, just an output or both an input and an output.
Note that each logic node tree can have only one Group Input Node and one Group Output Node.
Once the group inputs and/ or outputs are added, they may be connected with more logic nodes for functionality. To use this node group in other logic node trees, add a Call Node Group node in the other tree and select the node tree to be used as a group.
Group with both inputs and outputs:
Group with outputs only:
Group inputs only:
-
Function nodes will not work when used inside a
node group. However, it will work if used outside of thenode groupsitself. -
Variable nodes are fully supported in a
node group.Each variable node in a group instance (a group instance is one individual reference to a node group, so there is one instance per
Call Node Groupnode) is also a unique instance at runtime (just as any other node), so variables are local per group instance.When a variable node in a group is linked to a tree variable, the tree variable's value is only shared locally within a group instance and can't be changed from outside the group, the same goes for tree variables in the main tree which are also not accessible from inside the group. This holds true even if two tree variables with the same name and type exist in the main tree and the group tree. In this case the two variables with the same name are still treated as two different variables, depending on which tree references them.
-
Live patching does not work for nodes inside a
node group. Any node outside anode groupsupports live patching.
Although logic nodes are automatically converted to Haxe code, using them results in a slight overhead compared to hand-made Haxe scripts. The connections between nodes have to be followed before executing a connected node and calling functions of node classes usually requires a very small amount of time, with no inlining possible.
Also, logic nodes don't know anything about their surrounding context which can lead to redundant calculations, for example due to two different nodes doing the same sub-task twice. If in doubt, you can check the source code of each logic node by selecting Open [.hx/.py] source in the browser in its right-click context menu in Blender or by clicking the links in its documentation on the Logic Nodes Reference page.