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 for working with variables can be found in the Variable category.
To ease the setting or getting the values of variable nodes, set variable and get variable nodes may be used.
The usage involves giving an unique ID to the variable node in the Sidebar of the Node Editor as shown below:
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. - 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.