GETTING A NodeTool WINDOW
To open a new NodeTool window, select the NodeTool option from the Window menu. You can open multiple NodeTool windows if you want to view different levels of the scene hierarchy at the same time.
The most important thing to understand about working with NodeTool is that nodes are just GameObjects. To get a feel for this:
- Create new a NodeTool window and dock it to the editor.
- Open the scene file at NodeTool/Examples/Conversation
- Select the GameObject named Conversation in the Hierarchy window.
- Press the Step Into button at the upper left of the NodeTool window.
You should now see the children of Conversation displayed as nodes. Select one, and notice how the same GameObject is represented in three different places: the Hierarchy, the Inspector, and NodeTool. Also notice that selecting an object in the Hierarchy selects it in NodeTool and vis versa.
STEPPING INTO OR OUT OF NODES
When you have any single GameObject selected, pressing the Step Into button makes that node the new head GameObject and displays its children as nodes. You can also step into a node by right clicking over it and selecting Step Into from the context menu.
The Step Out button will switch the head GameObject to the parent of the current head GameObject.
To pan around the NodeTool window, hold the middle mouse button and drag. If your mouse doesn't have a middle button, hold alt and drag.
You'll also find several navigation tools in the upper right corner of the window.
Clicking anywhere on the mini-map will jump to that location. Hitting the Origin button will jump back to the origin. To jump to a specific node, select it in the Hierarchy and clicks the Center on Selection button.
Creating new nodes
While you can create nodes manually by creating GameObjects and attaching components to them in the inspector, this can become tedious. To remedy this, NodeTool includes a quick Creation Menu that makes this process much faster. To create a node with the Creation Menu, right click on an empty part of the window and select a type. This will create a new GameObject at the current level of the hierarchy and attach a component of that type.
To avoid overwhelming you with too many options, the Creation Menu only displays object types that have been decorated with the HBD.NodeTool.ShowInNodeToolAttribute. The constructor for this attribute takes an optional path string argument that you can use to group node types under submenus. For example, the StickyNote node has the following implementation:
Any object reference field that expects a subclass of MonoBehaviour, a GameObject, or a UnityEngine.Object will be drawn with an out going connection circle.
To connect that field to another node, click down in the circle and drag out the connection. Compatible targets will turn green. If you release the mouse over one of these, a connection will be made. To break a connection, release the mouse while the connection is over the window or an incompatible target.
Note that aside from the connection circle, the object reference fields on nodes are the same as those in the Inspector. You can drag and drop objects into them just like any other object reference field.
Groups and exported components
If you find yourself with too many nodes, you may want to group a bunch of nodes together under a new parent node. To do this, hold shift and drag a selection box over all the nodes you want to group. Then right click on one of the nodes and select the Group option.
The grouped nodes will be parented to a new group node and any components that the nodes remaining at the current level reference will be "exported" on the group's GameObject. This means that the component is drawn both on the node for the GameObject to which it's attached, and the group node, which is the parent of that GameObject
Sometimes it's convenient to view a parent node on the same level as its children. You can do this with a Parent Proxy. To create one, right click on an empty part of the window and select the Create Parent Proxy option. The created node represents the parent, allowing you to easily make connections from its components to those of its children and vice versa.
Deleting the Parent Proxy has no effect on the actual parent, or any object references. It is purely a cosmetic convenience. You can also make these types of connections by dragging objects from the Hierarchy or the Inspector into object reference fields.
You may notice that when you step into a GameObject for the first time, NodeTool will attach a script called NodeTransform. This script merely keeps track of a node's position, size, and other meta-data. It has no Update loop and will not affect performance. If you later decide you don't want to use NodeTool with your objects, you can remove these from a hierarchy by selecting the parent GameObject and choosing the "Remove NodeTransforms" option from the GameObjects menu at the top of the screen.
The example's I've included are intended to show you the types of things that NodeTool makes it easy to build. They also demonstrate a common pattern in Unity that is especially useful when working with NodeTool: the head of a hierarchy has some control object, while its children represent the data on which it operates.
In the state machine example, the StateMachine component at the top level operates on the State components of its children. Similarly in the conversation example, the Conversation component at the top level does all of the bookkeeping, functioning as an interface to the data contained in the CharacterSays and MultipleChoice components of its children.
If you need more help, have a feature request or bug report, don't hesitate to contact me at firstname.lastname@example.org.