This page has been translated automatically.
UnigineEditor
Interface Overview
Assets Workflow
Settings and Preferences
Working With Projects
Adjusting Node Parameters
Setting Up Materials
Setting Up Properties
Landscape Tool
Using Editor Tools for Specific Tasks
Extending Editor Functionality
Programming
Fundamentals
Setting Up Development Environment
Usage Examples
UnigineScript
C++
C#
UUSL (Unified UNIGINE Shader Language)
File Formats
Rebuilding the Engine Tools
GUI
Double Precision Coordinates
API
Containers
Common Functionality
Controls-Related Classes
Engine-Related Classes
Filesystem Functionality
GUI-Related Classes
Math Functionality
Node-Related Classes
Objects-Related Classes
Networking Functionality
Pathfinding-Related Classes
Physics-Related Classes
Plugins-Related Classes
IG Plugin
CIGIConnector Plugin
Rendering-Related Classes
Warning! This version of documentation is OUTDATED, as it describes an older SDK version! Please switch to the documentation for the latest SDK version.
Warning! This version of documentation describes an old SDK version which is no longer supported! Please upgrade to the latest SDK version.

NodeReference Class

Warning
The scope of applications for UnigineScript is limited to implementing materials-related logic (material expressions, scriptable materials, brush materials). Do not use UnigineScript as a language for application logic, please consider C#/C++ instead, as these APIs are the preferred ones. Availability of new Engine features in UnigineScipt (beyond its scope of applications) is not guaranteed, as the current level of support assumes only fixing critical issues.
Inherits: Node

A node reference is a node that refers to an external .node file on the disk, which is obtained by exporting a node from the world.

Notice
The world can contain several instances of node references referring to the same .node file.
The .node file usually contains a pre-fabricated node (or a hierarchy of nodes) with all the materials and properties that are required for its rendering. All changes that are made for the node reference via UnigineEditor are saved into this file.
Notice
When editing the node reference via the code, implement saving changes into the .node file.

The node reference should be used instead of the node if there a lot of identical objects repeated in the world: it will enable to avoid manual editing each object if you need to make the same changes in all of these objects.

Notice
A bounding box of the reference node is equal to the bounding box of its root node stored by the reference (child nodes are disregarded).

Unlike regular nodes, reference nodes are loaded into the world faster because of the internal cache usage.

An NodeReference instance is an owner of the node (or nodes) stored by the reference, so it is responsible for loading and deleting them.

Node Reference Transformations#

NodeReference transformation differs from transformation of the node (or nodes) stored by the reference. However, matrix hierarchy is used for a NodeReference. So, when moving the NodeReference, its root node stored by the reference will also move relatively to this NodeReference. At that, the local transformation matrix of the root reference node won't be changed.

See Also#

  • Article on Nodes that lists the main differences between the regular nodes and reference nodes
  • Article on Node Reference

Creating a Node Reference#

To create a NodeReference, you should specify a path to the existing .node file. For example, you can export a node into a .node file and then create a NodeReference by using it:

Source code (UnigineScript)
#include <core/unigine.h>

int init() {

	// create a mesh
	Mesh mesh = new Mesh();
	mesh.addBoxSurface("box_0", vec3(1.0f));
	// create a dynamic mesh by using the mesh
	ObjectMeshDynamic dynamic = new ObjectMeshDynamic(mesh);
	// export the dynamic mesh into a .node file
	engine.world.saveNode("unigine_project/nodes/node_reference_0.node", dynamic);
	// create a node reference
	NodeReference nodeRef = new NodeReference("unigine_project/nodes/node_reference_0.node");

	return 1;
}

Also you can cast a Node instance to the NodeReference. However, such type casting is possible only if the Node type is NODE_REFERENCE. For example:

Source code (UnigineScript)
#include <core/unigine.h>

void nodeCast(Node node) {
	
	// check if the node is a NodeReference
	if (node.getType() == NODE_REFERENCE)
	{	
		// cast the node to the NodeReference
		NodeReference nodeRef = node_cast(node);	
		// set a name for the NodeReference
		nodeRef.setName("NodeReference_casted");
	}
}

int init() {

	// create a NodeReference from the file
	NodeReference nodeRef_0 = new NodeReference("unigine_project/nodes/node_reference_0.node");
	// set a name
	nodeRef_0.setName("NodeReference_0");

	// save changes into the .world file
	engine.console.run("world_save");
	// get the added NodeReference as a Node
	Node node = engine.world.getNodeByName("NodeReference_0");
	// cast the obtained Node to a NodeReference
	nodeCast(node);
	
	return 1;
}

In the result, the NodeReference_0 node will be converted to the NodeReference_casted node.

Editing a Node Reference#

Editing a NodeReference includes:

  • Changing the path to the referenced .node file.
  • Editing the node stored by the reference.
To access the node to which the NodeReference refers, use the getReference() method as follows:
Source code (UnigineScript)
#include <core/unigine.h>

int init() {

	// create a NodeReference instance
	NodeReference nodeRef = new NodeReference("unigine_project/nodes/node_reference_0.node");
	// set a name
	nodeRef.setName("NodeReference_0");
	
	// get a node stored by the reference and check if it is an ObjectMeshDynamic
	if (nodeRef.getReference().getType() == NODE_OBJECT_MESH_DYNAMIC) {
		// cast the referenced node to the ObjectMeshDynamic type
		ObjectMeshDynamic dynamic = node_cast(nodeRef.getReference());
		// set a material
		dynamic.setMaterial("mesh_base", 0);
		// save changes on the referenced node into the .node file
		engine.world.saveNode(nodeRef.getNodeName(), dynamic);
	}
	
	return 1;
}

In the result, the source .node file, to which the NodeReference refers, will be updated and the NodeReference_0 node will refer to the updated node with the material assigned.

NodeReference Class

Members


static NodeReference ( string name ) #

Constructor. Creates a new object that references a node from a given file.

Arguments

  • string name - Path to a *.node file.

string getNodeName ( ) #

Returns the path to the referenced *.node file.
Source code (UnigineScript)
// create an NodeReference instance
NodeReference nodeRef = new NodeReference("unigine_project/nodes/reference_0.node");
// ...
// return the path to the reference node
log.message("The referenced node is: %s\n",nodeRef.getNodeName());

Return value

Path to the referenced *.node file.

Node getReference ( ) #

Returns the node stored by the reference. The method should be used when you need to change the referenced node. If getReference() has returned a NodeDummy instance, it means that several nodes of the same hierarchy level has been converted into the NodeReference.
Source code (UnigineScript)
// create a NodeReference instance
NodeReference nodeRef = new NodeReference("unigine_project/nodes/single_nref.node");
// get a node stored by the reference
Node node = nodeRef.getReference();
// if the node is a NodeDummy
if (node.getType() == NODE_DUMMY){
	// print the type name of each child node of the root node stored by the reference 
	forloop(int i = 0; node.getNumChildren();1) {
		log.message("%d: %s\n",i,node.getChild(i).getTypeName());
	}
}

Return value

Node instance.

int canBeReference ( string name, Node node ) #

Returns a value indicating if the hierarchy of the given node does not contain a node reference with the given name.

Arguments

  • string name - Node reference name.
  • Node node - Node to check.

Return value

1 if the hierarchy of the given node does not contain a node reference with the given name; otherwise, 0.

Node detachReference ( ) #

Returns the node stored by the reference and releases this node of ownership so it is no longer owned and referred to by the NodeReference. The node is managed by the World.
Source code (UnigineScript)
// create a new NodeReference instance
NodeReference nodeRef = new NodeReference("unigine_project/nodes/node_reference_0.node");
// perform something
// ...
// get the node stored by the reference and release NodeReference ownership of the node
Node node = nodeRef.detachReference();

Return value

Root node of the internal hierarchy.

static int type ( ) #

Returns the type of the node.

Return value

NodeReference type identifier.
Last update: 2020-07-31
Build: ()