Node Reference
Node Reference is a node that refers to a .node file in the project directory, which is obtained by exporting a node from the world.
The .node file usually contains a pre-fabricated node (or a hierarchy of nodes) with links to all materials and properties and configured physical bodies that are required for its rendering and behaviour. All changes made for the Node Reference content via UnigineEditor are saved into this file.
Node References should be used if a lot of identical objects are placed in the world: unlike regular nodes, Node Reference are loaded into the world faster because of the internal cache usage.
Using Node Reference enables to avoid manual editing each identical object if you need to make the same changes in all of them. You can simply add several Node References that point to one .node file and then edit only one Node Reference in order to update them all. Such approach enables to hold to integrity of instanced objects, especially if they are complex and sophisticated.
For example, the Node Reference can be used to add identical vehicles, characters, or buildings that should have the same look and behaviour and be updated at once, if necessary.
Node References support nesting, i.e. a Node Reference can include other Node References which is helpful for implementing complex instancing solutions.
Watch the following tutorial to learn the important things about Node Reference:
Important Notes#
Referencing Content Outside#
A Node Reference should be thought of as a container for a self-sufficient hierarchy of nodes. When designing your world in UnigineEditor, avoid referencing nodes that are stored in a Node Reference directly from the outside (e.g. when manipulating nodes via Tracker, creating physical joints, specifying nodes in component parameters or the target node of a Player Persecutor) as such references will be lost as soon as the world is reloaded.
Transformations#
The transformation of a Node Reference is not affected by the transformation of the nodes stored by it. Thus, logic-driven and physics-driven nodes inside a Node Reference will make no influence on its direct children.
In the following example, the moving grouped Node_1 and Node_2 nodes (e.g. driven by physics) contained by a Node Reference will not modify the transformation of the Node Reference and, therefore, the DirectChild node will not be affected as well.
So, it is recommended to enclose all interconnected nodes in a single Node Reference to ensure logical and hierarchical integrity.
See Also#
- The Instancing Nodes article to learn more about using Node References to create identical objects.
- The NodeReference class to edit Node References via API
- The Randomizer plugin to work with multiple Node References
- Node References: Must-Knows demonstrating the specifics of Node Reference
Creating a Node Reference#
There are two ways to create a Node Reference via UnigineEditor:
-
Create a Node Reference from a previously created .node asset. In this case, you should export a node into a .node file first.
- Convert a node with all its child nodes present in the nodes hierarchy list into a Node Reference. In this case, the source node will change its type to a Node Reference.
By Using a Node Asset#
- Export a node into a .node file or import the desired node file to the project.
-
Add the Node Reference to the world by either of the following ways:
On the Menu bar, click Create -> Node -> Reference and select the desired .node asset in the window that opens:
It is not recommended to select a geometry container (.fbx, .dae, .gtlf, etc.) as the changes made to its node runtime will not be saved when reimporting the asset.- Drag the .node asset from the Asset Browser window.
You can repeat Step 2 in order to add the required number of Node References. Or you can simply clone the added node.
By Converting an Existing Node#
- Select a node in the World Nodes Hierarchy window (or directly in the scene).
On the Menu bar, click Edit -> Convert to NodeReference (or press Ctrl+Shift+G).
As a result, a new .node asset is created at the current folder and the source node is converted into the Node Reference:
Source node to be converted
|
Converted node
|
You can also clone the converted node in order to get the required number of Node References.
Source nodes to be converted
|
Nodes grouped under a Dummy Node to which Node Reference refers
|
Editing a Node Reference#
In the Reference section of the Node tab, you can change the asset of the source node or open the ReferenceNode Editor used to edit the source node:
To edit the source node, to which the Node Reference points:
- Select the Node Reference in the World Nodes Hierarchy window.
Click Edit in the Node tab of the Parameters window.
The source node becomes available in the World Nodes Hierarchy window as a child of the Node Reference and can be edited via the Parameters window.
World Nodes Hierarchy window: source node in the edit modeEdit the source node. For example, you can change the material applied to it:
Node References with the red material appliedNode References with the changed materialYou can also reorganize hierarchy and replace the source nodes, but keep note that only the first child will be saved in the Node Reference as Node Reference can contain only one root node.
-
After all changes are made, select the parent node in the World Nodes Hierarchy window and click Apply to save changes to the source node or Cancel changes to keep nodes unchanged.
Reference section in the Node tab of the parent Node Reference
It is also possible to quick-replace the source node with another one stored in the same folder. To do that, select a Node Reference in the World Nodes Hierarchy window or the Viewport, hold Shift and use the mouse wheel or Page Up and Page Down buttons.
Baking Light and Shadows for a Node Reference#
Instances of a Node Reference may be illuminated differently. Thus, when light is baked for each of them, they will have individual lightmaps and depth textures (shadow maps). If you modify the Node Reference (change its hierarchy, replace the referenced asset, etc), these textures will be rebaked automatically after the Apply button is clicked. In code, the textures are updated by using the corresponding method.
However, modifying (resetting) the path to the Node Reference's baked texture will affect all instances of the Node Reference, and automatic replacement of the unique baked texture for each individual Node Reference won't be available anymore. (You will have to replace baked textures manually for each instance.)
Deleting a Node Reference#
You can delete the Node Reference the same way as any other node.