This page has been translated automatically.
Video Tutorials
Interface
Essentials
Advanced
How To
Professional (SIM)
UnigineEditor
Interface Overview
Assets Workflow
Version Control
Settings and Preferences
Working With Projects
Adjusting Node Parameters
Setting Up Materials
Setting Up Properties
Lighting
Sandworm
Using Editor Tools for Specific Tasks
Extending Editor Functionality
Built-in Node Types
Nodes
Objects
Effects
Decals
Light Sources
Geodetics
World Nodes
Sound Objects
Pathfinding Objects
Players
Programming
Fundamentals
Setting Up Development Environment
Usage Examples
C++
C#
UnigineScript
UUSL (Unified UNIGINE Shader Language)
Plugins
File Formats
Materials and Shaders
Rebuilding the Engine Tools
GUI
Double Precision Coordinates
API
Animations-Related Classes
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
VR-Related Classes
Content Creation
Content Optimization
Materials
Material Nodes Library
Miscellaneous
Input
Math
Matrix
Textures
Art Samples
Tutorials

Unigine::NodeTrigger Class

Header: #include <UnigineNodes.h>
Inherits from: Node

A Trigger node is a zero-sized node that has no visual representation and triggers events when:

  • It is enabled/disabled (the Enabled event is triggered).
  • Its transformation is changed (the Position event is triggered).

The Trigger node is usually added as a child node to another node, so that the handler functions were executed on the parent node enabling/disabling or transforming.

For example, to detect if some node has been enabled (for example, a world clutter node that renders nodes only around the camera has enabled it), the Trigger node is added as a child to this node and executes the corresponding function.

Creating a Trigger Node#

To create a Trigger node, simply call the NodeTrigger constructor and then add the node as a child to another node, for which handlers should be executed.

AppWorldLogic.h (C++)
#include <UnigineLogic.h>

using namespace Unigine;

class AppWorldLogic : public Unigine::WorldLogic {

public:

	virtual int init();
	virtual int update();

	/*...*/

private:

	ObjectMeshStaticPtr object;
	NodeTriggerPtr trigger;
};
AppWorldLogic.cpp (C++)
#include "AppWorldLogic.h"

using namespace Math;

int AppWorldLogic::init() {

	// create a mesh
	object = ObjectMeshStatic::create("core/meshes/box.mesh");
	// change material albedo color
	object->setMaterialParameterFloat4("albedo_color", vec4(1.0f, 0.0f, 0.0f, 1.0f), 0);

	// create a trigger node
	trigger = NodeTrigger::create();

	// add the trigger node to the static mesh as a child node
	object->addWorldChild(trigger);

	return 1;
}

Editing a Trigger Node#

Editing a trigger node includes implementing and specifying the Enabled and Position event handlers that are executed on enabling or positioning the Trigger node correspondingly.

The event handler must receive at least 1 argument of the NodeTrigger type. In addition, it can also take another 2 arguments of any type.

The event handlers are set via pointers specified when subscribing to the following events: EventEnabled and EventPosition.

AppWorldLogic.h (C++)
#include <UnigineLogic.h>
#include <UnigineGame.h>

using namespace Unigine;

class AppWorldLogic : public Unigine::WorldLogic {

public:

	virtual int init();
	virtual int update();

	/*...*/

private:

	ObjectMeshStaticPtr object;
	NodeTriggerPtr trigger;

	void position_event_handler(const NodeTriggerPtr &trigger)
	{
		Log::message("Object position has been changed. New position is: (%f %f %f)\n", trigger->getWorldPosition().x, trigger->getWorldPosition().y, trigger->getWorldPosition().z);
	}

	void enabled_event_handler(const NodeTriggerPtr &trigger)
	{
		Log::message("The enabled flag is %d\n", trigger->isEnabled());
	}
};
AppWorldLogic.cpp (C++)
#include "AppWorldLogic.h"

using namespace Math;

int AppWorldLogic::init() {

	// create a mesh
	object = ObjectMeshStatic::create("core/meshes/box.mesh");
	// change material albedo color
	object->setMaterialParameterFloat4("albedo_color", vec4(1.0f, 0.0f, 0.0f, 1.0f), 0);

	// create a trigger node
	trigger = NodeTrigger::create();

	// add the trigger node to the static mesh as a child node
	object->addWorldChild(trigger);

	// subscribe for the Enabled and Position events
	trigger->getEventEnabled().connect(this, &AppWorldLogic::enabled_event_handler);
	trigger->getEventPosition().connect(this, &AppWorldLogic::position_event_handler);

	return 1;
}

int AppWorldLogic::update()
{

	float time = Game::getTime();
	Vec3 pos = Vec3(Math::sin(time) * 2.0f, Math::cos(time) * 2.0f, 0.0f);
	object->setEnabled(pos.x > 0.0f || pos.y > 0.0f);
	object->setWorldPosition(pos);

	return 1;
}

See Also#

NodeTrigger Class

Members

Event<const Ptr<NodeTrigger> &> getEventPosition() const#

Event triggered when the trigger node position has changed. The event handler must receive a NodeTrigger as its first argument. In addition, it can also take 2 arguments of any type. You can subscribe to events via connect()  and unsubscribe via disconnect(). You can also use EventConnection  and EventConnections  classes for convenience (see examples below).
Notice
For more details see the Event Handling article.
The event handler signature is as follows: myhandler(const Ptr<NodeTrigger> & trigger)

Usage Example

Source code (C++)
// implement the Position event handler
void position_event_handler(const Ptr<NodeTrigger> & trigger)
{
	Log::message("\Handling Position event\n");
}


//////////////////////////////////////////////////////////////////////////////
//  1. Multiple subscriptions can be linked to an instance of the EventConnections 
//  class that you can use later to remove all these subscriptions at once
//////////////////////////////////////////////////////////////////////////////

// create an instance of the EventConnections class
EventConnections position_event_connections;

// link to this instance when subscribing for an event (subscription for various events can be linked)
publisher->getEventPosition().connect(position_event_connections, position_event_handler);

// other subscriptions are also linked to this EventConnections instance 
// (e.g. you can subscribe using lambdas)
publisher->getEventPosition().connect(position_event_connections, [](const Ptr<NodeTrigger> & trigger) { 
		Log::message("\Handling Position event (lambda).\n");
	}
);

// ...

// later all of these linked subscriptions can be removed with a single line
position_event_connections.disconnectAll();

//////////////////////////////////////////////////////////////////////////////
//  2. You can subscribe and unsubscribe via an instance of the EventConnection 
//  class. And toggle this particular connection off and on, when necessary.
//////////////////////////////////////////////////////////////////////////////

// create an instance of the EventConnection class
EventConnection position_event_connection;

// subscribe for the Position event with a handler function keeping the connection
publisher->getEventPosition().connect(position_event_connection, position_event_handler);

// ...

// you can temporarily disable a particular event connection to perform certain actions
position_event_connection.setEnabled(false);

// ... actions to be performed

// and enable it back when necessary
position_event_connection.setEnabled(true);

// ...

// remove subscription for the Position event via the connection
position_event_connection.disconnect();

//////////////////////////////////////////////////////////////////////////////
//  3. You can add EventConnection/EventConnections instance as a member of the
//  class that handles the event. In this case all linked subscriptions will be 
//  automatically removed when class destructor is called
//////////////////////////////////////////////////////////////////////////////

// Class handling the event
class SomeClass
{
public:
	// instance of the EventConnections class as a class member
	EventConnections e_connections;

	// A Position event handler implemented as a class member
	void event_handler(const Ptr<NodeTrigger> & trigger)
	{
		Log::message("\Handling Position event\n");
		// ...
	}
};

SomeClass *sc = new SomeClass();

// ...

// specify a class instance in case a handler method belongs to some class
publisher->getEventPosition().connect(sc->e_connections, sc, &SomeClass::event_handler);

// ...

// handler class instance is deleted with all its subscriptions removed automatically
delete sc;

//////////////////////////////////////////////////////////////////////////////
//  4. You can subscribe and unsubscribe via the handler function directly
//////////////////////////////////////////////////////////////////////////////

// subscribe for the Position event with a handler function
publisher->getEventPosition().connect(position_event_handler);


// remove subscription for the Position event later by the handler function
publisher->getEventPosition().disconnect(position_event_handler);


//////////////////////////////////////////////////////////////////////////////
//   5. Subscribe to an event saving an ID and unsubscribe later by this ID
//////////////////////////////////////////////////////////////////////////////

// define a connection ID to be used to unsubscribe later
EventConnectionId position_handler_id;

// subscribe for the Position event with a lambda handler function and keeping connection ID
position_handler_id = publisher->getEventPosition().connect([](const Ptr<NodeTrigger> & trigger) { 
		Log::message("\Handling Position event (lambda).\n");
	}
);

// remove the subscription later using the ID
publisher->getEventPosition().disconnect(position_handler_id);


//////////////////////////////////////////////////////////////////////////////
//   6. Ignoring all Position events when necessary
//////////////////////////////////////////////////////////////////////////////

// you can temporarily disable the event to perform certain actions without triggering it
publisher->getEventPosition().setEnabled(false);

// ... actions to be performed

// and enable it back when necessary
publisher->getEventPosition().setEnabled(true);

Return value

Event reference.

Event<const Ptr<NodeTrigger> &> getEventEnabled() const#

Event triggered when the trigger node is enabled or disabled. The event handler must receive a NodeTrigger as its first argument. In addition, it can also take 2 arguments of any type. You can subscribe to events via connect()  and unsubscribe via disconnect(). You can also use EventConnection  and EventConnections  classes for convenience (see examples below).
Notice
For more details see the Event Handling article.
The event handler signature is as follows: myhandler(const Ptr<NodeTrigger> & trigger)

Usage Example

Source code (C++)
// implement the Enabled event handler
void enabled_event_handler(const Ptr<NodeTrigger> & trigger)
{
	Log::message("\Handling Enabled event\n");
}


//////////////////////////////////////////////////////////////////////////////
//  1. Multiple subscriptions can be linked to an instance of the EventConnections 
//  class that you can use later to remove all these subscriptions at once
//////////////////////////////////////////////////////////////////////////////

// create an instance of the EventConnections class
EventConnections enabled_event_connections;

// link to this instance when subscribing for an event (subscription for various events can be linked)
publisher->getEventEnabled().connect(enabled_event_connections, enabled_event_handler);

// other subscriptions are also linked to this EventConnections instance 
// (e.g. you can subscribe using lambdas)
publisher->getEventEnabled().connect(enabled_event_connections, [](const Ptr<NodeTrigger> & trigger) { 
		Log::message("\Handling Enabled event (lambda).\n");
	}
);

// ...

// later all of these linked subscriptions can be removed with a single line
enabled_event_connections.disconnectAll();

//////////////////////////////////////////////////////////////////////////////
//  2. You can subscribe and unsubscribe via an instance of the EventConnection 
//  class. And toggle this particular connection off and on, when necessary.
//////////////////////////////////////////////////////////////////////////////

// create an instance of the EventConnection class
EventConnection enabled_event_connection;

// subscribe for the Enabled event with a handler function keeping the connection
publisher->getEventEnabled().connect(enabled_event_connection, enabled_event_handler);

// ...

// you can temporarily disable a particular event connection to perform certain actions
enabled_event_connection.setEnabled(false);

// ... actions to be performed

// and enable it back when necessary
enabled_event_connection.setEnabled(true);

// ...

// remove subscription for the Enabled event via the connection
enabled_event_connection.disconnect();

//////////////////////////////////////////////////////////////////////////////
//  3. You can add EventConnection/EventConnections instance as a member of the
//  class that handles the event. In this case all linked subscriptions will be 
//  automatically removed when class destructor is called
//////////////////////////////////////////////////////////////////////////////

// Class handling the event
class SomeClass
{
public:
	// instance of the EventConnections class as a class member
	EventConnections e_connections;

	// A Enabled event handler implemented as a class member
	void event_handler(const Ptr<NodeTrigger> & trigger)
	{
		Log::message("\Handling Enabled event\n");
		// ...
	}
};

SomeClass *sc = new SomeClass();

// ...

// specify a class instance in case a handler method belongs to some class
publisher->getEventEnabled().connect(sc->e_connections, sc, &SomeClass::event_handler);

// ...

// handler class instance is deleted with all its subscriptions removed automatically
delete sc;

//////////////////////////////////////////////////////////////////////////////
//  4. You can subscribe and unsubscribe via the handler function directly
//////////////////////////////////////////////////////////////////////////////

// subscribe for the Enabled event with a handler function
publisher->getEventEnabled().connect(enabled_event_handler);


// remove subscription for the Enabled event later by the handler function
publisher->getEventEnabled().disconnect(enabled_event_handler);


//////////////////////////////////////////////////////////////////////////////
//   5. Subscribe to an event saving an ID and unsubscribe later by this ID
//////////////////////////////////////////////////////////////////////////////

// define a connection ID to be used to unsubscribe later
EventConnectionId enabled_handler_id;

// subscribe for the Enabled event with a lambda handler function and keeping connection ID
enabled_handler_id = publisher->getEventEnabled().connect([](const Ptr<NodeTrigger> & trigger) { 
		Log::message("\Handling Enabled event (lambda).\n");
	}
);

// remove the subscription later using the ID
publisher->getEventEnabled().disconnect(enabled_handler_id);


//////////////////////////////////////////////////////////////////////////////
//   6. Ignoring all Enabled events when necessary
//////////////////////////////////////////////////////////////////////////////

// you can temporarily disable the event to perform certain actions without triggering it
publisher->getEventEnabled().setEnabled(false);

// ... actions to be performed

// and enable it back when necessary
publisher->getEventEnabled().setEnabled(true);

Return value

Event reference.

static NodeTriggerPtr create ( ) #

Constructor. Creates a new trigger node.

void setEnabledCallbackName ( const char * name ) #

Sets a callback function to be fired when the trigger node is enabled. The callback function must be implemented in the world script (on the UnigineScript side). The callback function can take no arguments, a Nodeor a NodeTrigger.
Notice
The method allows for setting a callback with 0 or 1 argument only.
On UnigineScript side:
Source code (UnigineScript)
// implement the enabled callback
void enabled_callback(Node node) {
	log.message("The enabled flag is %d\n", node.isEnabled());
}
On C++ side:
Source code (C++)
int AppWorldLogic::init() {

	// create a trigger node
	trigger = NodeTrigger::create();

	// set the enabled event handler function to be executed when the node is enabled/disabled

	trigger->setEnabledCallbackName("enabled_event_handler");

	return 1;
}

Arguments

  • const char * name - Name of the callback function implemented in the world script (UnigineScript side).

const char * getEnabledCallbackName ( ) const#

Returns the name of callback function to be fired on enabling the trigger node. This callback function is set via setEnabledCallbackName().

Return value

Name of the callback function implemented in the world script (UnigineScript side).

void setPositionCallbackName ( const char * name ) #

Sets a callback function to be fired when the trigger node position has changed. The callback function must be implemented in the world script (on the UnigineScript side). The callback function can take no arguments, a Nodeor a NodeTrigger.
Notice
The method allows for setting a callback with 0 or 1 argument only.
On UnigineScript side:
Source code (UnigineScript)
// implement the position callback
void position_changed(NodeTriggerPtr trigger) {
	log.message("A new position of the node is %s\n", typeinfo(node.getWorldPosition()));
}
On C++ side:
Source code (C++)
int AppWorldLogic::init() {

	// create a trigger node
	trigger = NodeTrigger::create();

	// set the position event handler function to be executed when the node position is changed

	trigger->setPositionCallbackName("position_event_handler");

	return 1;
}

Arguments

  • const char * name - Name of the callback function implemented in the world script (UnigineScript side).

const char * getPositionCallbackName ( ) const#

Returns the name of callback function to be fired on changing the trigger node position. This function is set by using the setPositionCallbackName()function.

Return value

Name of the callback function implemented in the world script (UnigineScript side).

static int type ( ) #

Returns the type of the node.

Return value

NodeTriggertype identifier.
Last update: 2024-02-06
Build: ()