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
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
Content Creation
Content Optimization
Materials
Material Nodes Library
Miscellaneous
Input
Math
Matrix
Textures
Art Samples
Tutorials
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.

Unigine::WorldTrigger Class

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

World triggers fire callbacks when any nodes (colliders or not) get inside or outside of them. The trigger can detect a node of any type by its bounding box.

You can either specify a list of nodes, for which the callbacks will be fired, or let the trigger react to all nodes (default behavior). In the latter case, the list of target nodes should be empty. There can be also specified a list of nodes that are skipped by the trigger and are free to pass unnoticed.

The callback function of World Trigger is actually executed only when the next engine function is called: that is, before updatePhysics() (in the current frame) or before update() (in the next frame) — whatever comes first.

Notice
If you have moved some nodes and want to get callbacks based on changed positions in the same frame, you need to call World::updateSpatial() first.

Example#

The example below allows creating a line of boxes moving in and out of the World Trigger area and triggering the callbacks. Getting inside the World Trigger enables emission for the boxes, and getting out of it disables the emission.

Source code (C++)
// AppWorldLogic.cpp
/* .. */
#include "AppWorldLogic.h"
#include <UnigineObjects.h>
#include <UnigineGame.h>
#include <UnigineVisualizer.h>

using namespace Unigine;

using namespace Math;

WorldTriggerPtr trigger;

const int MAX_OBJECTS = 10;
Vector<ObjectMeshStaticPtr> objects;

static void set_state(const NodePtr& node, const char* name, int value)
{
	ObjectPtr object = checked_ptr_cast<Object>(node);
	if (object.get() == NULL)
		return;

	for (int i = 0; i < object->getNumSurfaces(); i++)
	{
		MaterialPtr material = object->getMaterialInherit(i);
		if (material.get() == NULL)
			continue;
		int id = material->findState(name);
		if (id != -1)
			material->setState(id, value);
	}
}

static void trigger_enter(NodePtr node)
{
	set_state(node, "emission", 1);
}

static void trigger_leave(NodePtr node)
{
	set_state(node, "emission", 0);
}

int AppWorldLogic::init()
{

	// create trigger
	trigger = WorldTrigger::create(vec3(3.0f));
	trigger->addEnterCallback(MakeCallback(&trigger_enter));
	trigger->addLeaveCallback(MakeCallback(&trigger_leave));

	// create objects
	for (int i = 0; i < MAX_OBJECTS; i++)
	{
		ObjectMeshStaticPtr mesh = ObjectMeshStatic::create("cbox.mesh");
		mesh->setTriggerInteractionEnabled(true);
		mesh->setMaterialParameterFloat4("albedo_color", vec4(1.0f, 0.0f, 0.0f, 1.0f), 0);
		objects.append(mesh);
	}

	// enable the visualizer
	Visualizer::setEnabled(true);

	return 1;
}

int AppWorldLogic::update()
{

	trigger->renderVisualizer();
	float time = Game::getTime();

	float hsize = objects.size() / 2.0f;

	for (int i = 0; i < objects.size(); i++)
	{
		float x = Math::sin(time) * hsize - hsize + i;
		objects[i]->setWorldTransform(translate(Vec3(x, -x, 0.0f)));
	}

	return 1;
}

int AppWorldLogic::shutdown()
{

	objects.clear();

	return 1;
}

See Also#

  • A video tutorial on How To Use World Triggers to Detect Nodes by Their Bounds
  • An article on Event Handling Callbacks
  • A C++ API sample located in the <UnigineSDK>/source/samples/Api/Nodes/WorldTrigger folder
  • A C# API sample located in the <UnigineSDK>/source/csharp/samples/Api/Nodes/WorldTrigger folder
  • A set of UnigineScript API samples located in the <UnigineSDK>/data/samples/worlds/ folder:
    • trigger_00
    • trigger_01
    • trigger_02

WorldTrigger Class

Members


static WorldTriggerPtr create ( const Math::vec3 & size ) #

Constructor. Creates a new world trigger with given dimensions.

Arguments

  • const Math::vec3 & size - Dimensions of the new world trigger. If negative values are provided, 0 will be used instead of them.

void * addEnterCallback ( Unigine::CallbackBase1< Ptr<Node> > * func ) #

Adds a callback function to be fired when a node enters the world trigger. The callback function must receive a Node as its first argument. In addition, it can also take 2 arguments of any type.
Source code (C++)
// implement the enter callback
void AppWorldLogic::enter_callback(NodePtr node)
{
	Log::message("\nA node named %s has entered the trigger\n", node->getName());
}

WorldTriggerPtr trigger;

int AppWorldLogic::init()
{

	// create a world trigger node
	trigger = WorldTrigger::create(Math::vec3(3.0f));

	// add the enter callback to be fired when a node enters the world trigger
	trigger->addEnterCallback(MakeCallback(this, &AppWorldLogic::enter_callback));
	

	return 1;
}

Arguments

Return value

ID of the last added enter callback, if the callback was added successfully; otherwise, nullptr. This ID can be used to remove this callback when necessary.

bool removeEnterCallback ( void * id ) #

Removes the specified callback from the list of enter callbacks.

Arguments

  • void * id - Enter callback ID obtained when adding it.

Return value

True if the enter callback with the given ID was removed successfully; otherwise false.

void clearEnterCallbacks ( ) #

Clears all added enter callbacks.

void setEnterCallbackName ( const char * name ) #

Sets a callback function to be fired when nodes are entering the world trigger. Unlike setEnterCallback(), this callback function accepts a node that entered the world trigger and world trigger itself as arguments.

Arguments

  • const char * name - World script function name.

const char * getEnterCallbackName ( ) const#

Returns the name of callback function to be fired on entering the world trigger. This callback function is set via setEnterCallbackName().

Return value

World script function name.

void setExcludeNodes ( const Set< Ptr<Node> > & nodes ) #

Sets a list of excluded nodes, on which the world trigger will not react.

Arguments

  • const Set< Ptr<Node> > & nodes - Exclude nodes vector.

Set< Ptr<Node> > getExcludeNodes ( ) const#

Returns the current list of excluded nodes, on which the world trigger does not react.

Arguments

    void setExcludeTypes ( const Set< int > & types ) #

    Sets a list of excluded node types, on which the world trigger will not react.

    Arguments

    • const Set< int > & types - Exclude node types vector.

    Set< int > getExcludeTypes ( ) const#

    Returns the current list of excluded node types, on which the world trigger does not react.

    Arguments

      void * addLeaveCallback ( Unigine::CallbackBase1< Ptr<Node> > * func ) #

      Adds a callback function to be fired when a node leaves the world trigger. The callback function must receive a Node as its first argument. In addition, it can also take 2 arguments of any type.
      Source code (C++)
      WorldTriggerPtr trigger;
      
      int AppWorldLogic::init()
      {
      
      	// create a world trigger node
      	trigger = WorldTrigger::create(Math::vec3(3.0f));
      
      		// add the leave callback to be fired when a node leaves the world trigger
      	trigger->addLeaveCallback(MakeCallback(this, &AppWorldLogic::leave_callback));
      	
      
      	return 1;
      }

      Arguments

      Return value

      ID of the last added leave callback, if the callback was added successfully; otherwise, nullptr. This ID can be used to remove this callback when necessary.

      bool removeLeaveCallback ( void * id ) #

      Removes the specified callback from the list of leave callbacks.

      Arguments

      • void * id - Leave callback ID obtained when adding it.

      Return value

      True if the leave callback with the given ID was removed successfully; otherwise false.

      void clearLeaveCallbacks ( ) #

      Clears all added leave callbacks.

      void setLeaveCallbackName ( const char * name ) #

      Sets a callback function to be fired when nodes are leaving the world trigger. Unlike setLeaveCallback(), this callback function accepts a node that left the world trigger and world trigger itself as arguments.

      Arguments

      • const char * name - World script function name.

      const char * getLeaveCallbackName ( ) const#

      Returns the name of the callback function name to be fired on leaving the world trigger. This callback function is set via setLeaveCallbackName().

      Return value

      World script function name.

      Ptr<Node> getNode ( int num ) const#

      Returns a specified node contained in the world trigger.
      Source code (C++)
      #include <UnigineWorlds.h>
      
      #include <UnigineInput.h>
      
      using namespace Unigine;
      
      WorldTriggerPtr trigger;
      
      int AppWorldLogic::init()
      {
      
      	// create a world trigger node
      	trigger = WorldTrigger::create(Math::vec3(3.0f));
      
      	return 1;
      }
      
      int AppWorldLogic::update()
      {
      	// press the i key to get the info about nodes inside the trigger
      	if (trigger && Input::isKeyDown(Input::KEY_I))
      	{
      		//get the number of nodes inside the trigger
      		int numNodes = trigger->getNumNodes();
      		Log::message("The number of nodes inside the trigger is %i \n", numNodes);
      
      		//loop through all nodes to print their names and types
      		for (int i = 0; i < numNodes; i++)
      		{
      			NodePtr node = trigger->getNode(i);
      			Log::message("The type of the %f node is %f \n", node->getName(), node->getType());
      		}
      	}
      	return 1;
      }

      Arguments

      • int num - Node number in range from 0 to the total number of nodes.

      Return value

      Node pointer.

      Vector< Ptr<Node> > getNodes ( ) const#

      Gets nodes contained in the trigger.

      Arguments

        int getNumNodes ( ) const#

        Returns the number of nodes contained in the world trigger.

        Return value

        Number of nodes contained in the trigger.

        void setSize ( const Math::vec3 & size ) #

        Updates the current dimensions of the world trigger. The minimum size is vec3(0,0,0).

        Arguments

        • const Math::vec3 & size - Dimensions of the world trigger. If negative values are provided, 0 will be used instead of them.

        Math::vec3 getSize ( ) const#

        Returns the current dimensions of the world trigger.

        Return value

        Current dimensions of the world trigger.

        void setTargetNodes ( const Set< Ptr<Node> > & nodes ) #

        Sets a list of target nodes, which will fire callbacks. If this list is empty, all nodes fire callbacks.

        Arguments

        • const Set< Ptr<Node> > & nodes - Target nodes vector.

        Set< Ptr<Node> > getTargetNodes ( ) const#

        Returns the current list of target nodes, which fire callbacks. If this list is empty, all nodes fire callbacks.

        Arguments

          void setTargetTypes ( const Set< int > & types ) #

          Sets a list of target node types, which will fire callbacks. If this list is empty, all nodes fire callbacks.

          Arguments

          • const Set< int > & types - Target node types vector.

          Set< int > getTargetTypes ( ) const#

          Returns the current list of target node types, which fire callbacks. If this list is empty, all nodes fire callbacks.

          Arguments

            void setTouch ( bool touch ) #

            Sets a touch mode for the trigger. With this mode on, the trigger will react to the node by partial contact. When set to off, the trigger reacts only if the whole bounding sphere/box gets inside or outside of it. The default is 0.

            Arguments

            • bool touch - Touch mode flag: true to enable the touch mode, false to disable it.

            bool isTouch ( ) const#

            Returns a value indicating if a touch mode is enabled for the trigger. With this mode on, the trigger will react to the node by partial contact. When set to off, the trigger reacts only if the whole bounding sphere/box gets inside or outside of it.

            Return value

            true if the touch mode is enabled; otherwise, false.

            static int type ( ) #

            Returns the type of the node.

            Return value

            World type identifier.
            Last update: 2023-06-23
            Build: ()