Unigine::NodeReference Class

The Automatic Unpacking mode defines where the content of NodeReferences is placed in the world nodes hierarchy when it is loaded at run time (at the world startup or when a new NodeReference is created). When enabled, the content of node references is extracted to simplify hierarchy management. This is a global setting for all worlds used in your project.

// AppSystemLogic.cpp
#include <UnigineWorld.h>

using namespace Unigine;

int AppSystemLogic::init() {

	// enable automatic unpacking before the world is loaded
	World::setUnpackNodeReferences(1);

	return 1;
}

The auto-unpacking mode affects the relation between the transformations of the NodeReference and the nodes stored by it.

Automatic Unpacking Disabled#

// AppWorldLogic.cpp

#include <UnigineNodes.h>

using namespace Unigine;

int AppWorldLogic::init() {
	
	// create a NodeReference instance
	NodeReferencePtr nodeRef = NodeReference::create("unigine_project/nodes/node_reference_0.node");
	
	// get the reference node
	NodePtr group = nodeRef->getReference();

	// find the desired node
	NodePtr node_2 = group->getChild(group->findChild("Node_2"));

	return 1;
}

Automatic Unpacking Enabled#

// AppWorldLogic.cpp

#include <UnigineNodes.h>

using namespace Unigine;

int AppWorldLogic::init() {
	
	// create a NodeReference instance
	NodeReferencePtr nodeRef = NodeReference::create("nodes/node_reference_0.node");

	// get the root node of the pre-fabricated hierarchy
	NodePtr group = nodeRef->getChild(0);

	// find the desired node among all descendants
	NodePtr node_2 = nodeRef->findNode("Node_2", 1);

	return 1;
}

Local transformation of the root node stored by the NodeReference is not necessarily identity, it can be displaced relative to the NodeReference position, for example.

If automatic unpacking of node references is enabled, the transformations of nodes are simply subject to parent-child relation. However, if automatic unpacking was disabled (i.e. the node content was added to the root of world nodes hierarchy), matrix hierarchy is used for the content of the NodeReference. Thus, when moving the NodeReference, the root node of its content also moves relatively to this NodeReference. At that, the local transformation matrix of the root reference node changes.

This relation of transformations can be destroyed by detaching the reference node from the NodeReference instance. Keep note that the unpacked detached node will remain child of the NodeReference and its tranformation matrix will still be affected by the NodeReference transformation. In this case you may need to unparent the detached node by using setParent() method.

Each Node Reference has its internal copy of nodes loaded from the .node asset and therefore this allows applying unique changes to each instance of identical Node References separately at runtime (adding, deleting, and changing the nodes inside of a Node Reference).

Other Node Reference instances will not be updated at runtime when changes are applied to a single instance. If you want to propagate these changes at runtime from one instance of a Node Reference to all the other Node Reference in the world that are linked to the same .node asset on disk, you should save changes to the asset and reload all Node References. Automatic runtime reloading is available.

• Article on Nodes that lists the main differences between the regular nodes and reference nodes
• Article on 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:

#include <UnigineEditor.h>
#include <UnigineNodes.h>
#include <UnigineObjects.h>
#include <UnigineWorld.h>

using namespace Unigine;

int AppWorldLogic::init() {

	// create a mesh
	MeshPtr mesh = Mesh::create();
	mesh->addBoxSurface("box_0", Math::vec3(1.0f));
	// create a dynamic mesh by using the mesh
	ObjectMeshDynamicPtr dynamic = ObjectMeshDynamic::create(mesh);
	// export the dynamic mesh into a .node file
	World::saveNode("unigine_project/nodes/node_reference_0.node", dynamic->getNode());
	// create a node reference
	NodeReferencePtr nodeRef = NodeReference::create("unigine_project/nodes/node_reference_0.node");

	return 1;
}

// AppWorldLogic.h

#include <UnigineLogic.h>
#include <UnigineStreams.h>
#include <UnigineNode.h>
#include <UnigineNodes.h>

class AppWorldLogic : public Unigine::WorldLogic {
	
public:
	AppWorldLogic();
	virtual ~AppWorldLogic();
	
	virtual int init();
	
	virtual int update();
	virtual int postUpdate();
	virtual int updatePhysics();
	
	virtual int shutdown();
	
	virtual int save(const Unigine::StreamPtr &stream);
	virtual int restore(const Unigine::StreamPtr &stream);

private:

	void nodeCast(Unigine::NodePtr node);
};

// AppWorldLogic.cpp

#include <UnigineConsole.h>
#include <UnigineObjects.h>
#include <UnigineWorld.h>

using namespace Unigine;

void AppWorldLogic::nodeCast(NodePtr node) {
	
	// check if the node is a NodeReference
	if (node->getType() == Node::NODE_REFERENCE)
	{	
		// cast the node to the NodeReference
		NodeReferencePtr nodeRef = checked_ptr_cast<NodeReference>(node);
		// set a name for the NodeReference
		nodeRef->setName("NodeReference_casted");
	}
}

int AppWorldLogic::init() {
	
	// create a NodeReference from the file
	NodeReferencePtr nodeRef_0 = NodeReference::create("unigine_project/nodes/node_reference_0.node");

	// set a name
	nodeRef_0->setName("NodeReference_0");

	// save changes into the .world file
	Console::run("world_save");
	// get the added NodeReference as a Node
	NodePtr node = World::getNodeByName("NodeReference_0");
	// cast the obtained Node to a NodeReference
	nodeCast(node);

	return 1;
}

Editing a NodeReference includes:

• Changing the path to the referenced .node file.
• Editing the node stored by the reference.

#include <UnigineConsole.h>
#include <UnigineEditor.h>
#include <UnigineNodes.h>
#include <UnigineObjects.h>
#include <UnigineWorld.h>

using namespace Unigine;

int AppWorldLogic::init() {
	
	// create a NodeReference instance
	NodeReferencePtr nodeRef = NodeReference::create("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
		ObjectMeshDynamicPtr dynamic = checked_ptr_cast<ObjectMeshDynamic>(nodeRef->getReference());
		// save changes on the referenced node into the .node file
		World::saveNode(nodeRef->getNodePath(), 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. If you want all NodeReferences that refer to the modifed .node asset to update automatically, you should enable automatic reloading of NodeReferences by calling the setAutoReloadNodeReferences() method preliminarily.