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
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.

Intersections

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.

Unigine has different methods to detect intersections. Intersection is a shared point of the defined area (or line) and an object. This article describes different types of intersections and their usage.

There are three main types of intersections:

Shape and Object classes have their own getIntersection() functions. They are used for detecting intersections with the specific shape or the specific surface of the object.

World Intersection#

By using different overloaded World class getIntersection() functions you can find objects and nodes that intersect bounds of the specified bounding volume or find the first intersection of the object with the invisible tracing line.

World class functions for intersection search can be divided into 3 groups:

Intersection with Nodes#

To find the intersection of nodes with bounds of the specified volume, you should use these 2 functions:

  • engine.world.getIntersectionNodeVariables() to find all the nodes (or specified type nodes) that intersect bounds of the specified volume: BoundBox, BoundFrustum, BoundSphere. This function finds nodes which have set user variables.
  • engine.world.getIntersectionNodes() functions to find all the nodes (or nodes of specified type) in within a given bounding volume: BoundBox, BoundFrustum, BoundSphere.

The picture above shows how the engine.world.getIntersection() function detects the nodes that intersect with the bounds of the BoundBox volume.

These functions return the amount of found nodes as an integer value and save the data in the ret[] array which you can pass to the function as an argument.

Usage Example

The following example shows how you can get the intersection nodes by using the engine.world.getIntersectionNodes() function. It is supposed that you already have a world containing nodes and you have the BoundBox instance with the specified size. This code is taken from the world script's update() method. In this example the function checks if there is a node of any type inside the specified BoundBox object. The executing sequence is the following:

  1. Define an array for output values and a BoundBox instance.
  2. Check, if there is an intersection with a node. The engine.world.getIntersectionNodes() function returns an integer value: the amount of found nodes.
  3. In this example, when the node intersects with the BoundBox, console shows the information about that node. If there is no intersected node, console shows another message.
Source code (UnigineScript)
/* ... */
// It is supposed that you have these variables in your code:
// a BoundBox instance
WorldBoundBox boundBox;
// Array for the result
int resultArray[0];

/* ... */
int update() {
	boundBox = new WorldBoundBox(dvec3(0.0f, 0.0f, 0.0f), dvec3(10.0f, 10.0f, 10.0f));
	/* ... */
	/* this part is from update() method */
	// check if there is any node inside the BoundBox 
	int result = engine.world.getIntersectionNodes(boundBox, -1, resultArray);
	
	// if there is an intersection, do the following in a loop:
	if(result != 0)
	{	
		// get the size of the array and perform a for loop 
		forloop(int i=0; resultArray.size())
		{
			// get the Node from the array and show its name and type in console
			Node node = resultArray[i];
			log.message("node %i is : %s %i\n", i, node.getName(), node.getType() );
		}
	}
	else
	{
		log.message("sorry, but your intersection is in another castle!\n");
	}
	return 1;
}
/* ... */

Intersection with Objects#

engine.world class functions have 2 overloaded functions to get objects with and without user data. Intersection is performed with surfaces (polygons):

The picture above shows how the engine.world.getIntersection() function detects the objects that intersect with the bounds of the BoundBox volume.

All these functions return the amount of found objects as an integer value and save the data in the ret[] array which you can pass to the function as an argument. You can pass the start (vec3 p0) and the end (vec3 p1) point of the intersecting line or pass the variable v (BoundBox, BoundFrustum, BoundSphere) to get the intersection of objects with a line or with a bounding volume, respectively.

Usage Example

The following example shows how you can get the intersected objects by using the engine.world.getIntersectionObjects() function. It is supposed that you already have a world containing objects. This code is taken from the world script's update() method. In this example we specify a line from the point of the camera (vec3 p0) to the point of the mouse pointer (vec3 p1). The executing sequence is the following:

  1. Define an array for output values. Also define and initialize two points (p0 and p1) by using the Unigine::getPlayerMouseDirection() function from core/scripts/utils.h.
  2. Check, if there is an intersection with an object. The engine.world.getIntersectionObjects() function returns an integer value: the amount of found nodes.
  3. In this example, when the object intersects with the traced line, console shows the information about that object.
Source code (UnigineScript)
#include <core/scripts/utils.h>

/* ... */
// it is supposed that you have this variable in your code:
// array for the result
int resultArray[0];

/* ... */
int update() {
	// define two vec3 coordinates
	vec3 p0,p1;
	// get the mouse direction from camera (p0) to the cursor pointer (p1)
	Unigine::getPlayerMouseDirection(p0,p1);
	
	// check if there is any node inside the BoundBox 
	int result = engine.world.getIntersectionObjects(p0, p1, resultArray);
	
	// if there is an intersection, do the following in a loop:
	if(result != 0)
	{	
		// get the size of the array
		// perform a loop from 0 up to the size of the array 
		// to show the information about all objects
		forloop(int i=0; resultArray.size())
		{
			// get the Object from the array and show its material name and type in console
			Object object = resultArray[i];
			log.message("object %i is : %s %i\n", i, object.getMaterialName(0), object.getType());
		}
	}
	return 1;
}
/* ... */

First Intersected Object#

The engine.world.getIntersection() function is used to find the nearest intersected object with the traced line. You should specify the start point and the end point of the line, and the function detects if there are any object on the way of this line.

The picture above shows how the engine.world.getIntersection() function detects the object that intersects with the line.

This function detects intersection with surfaces (polygons) of mesh and terrain objects. But there are some conditions to detect the intersection with the surface:

  1. The surface is enabled.
  2. The surface has a material assigned.
  3. Per-surface Intersection flag is enabled.
    Notice
    You can set this flag to the object's surface by using the Object.setIntersection() function.

The engine.world.getIntersection() function is overloaded and receives 4 or 5 arguments:

  • vec3 p0 - the start point coordinates of the trace line.
  • vec3 p1 - the end point coordinates of the trace line.
  • int mask - the intersection mask. Use the intersection mask to find object only with specified intersection mask.
  • int exclude[] - the list of objects IDs to exclude.
  • variable v - The function returns an intersected object which is the nearest to the start point (p0). Information about the intersection will be presented in variable which you pass to the function as an argument:
    • WorldIntersection intersection - the WorldIntersection class instance. By using this class you can get the intersection point (coordinates), the index of the intersected triangle of the object and the index of the intersected surface.
    • WorldIntersectionNormal normal - the WorldIntersectionNormal class instance. By using this class you can get only the normal of the intersection point.
    • WorldIntersectionTexCoord texcoord - the WorldIntersectionTexCoord class instance. By using this class you can get only the texture coordinates of the intersection point.
    Notice
    Passing NULL instead of the intersection query object will perform fast intersection algorithm without the closest intersection point searching.

Thus, to exclude some objects you should use these methods:

  • Use an intersection mask. An intersection is found only if an object is matching the intersection mask.
  • Specify the list of objects IDs to exclude and pass to the function as an argument.
Usage Example

The following example shows how you can get the intersection information by using the WorldIntersection class. It is supposed that you already have a world containing objects. This code is taken from the world script's update() method. In this example we specify a line from the point of the camera (vec3 p0) to the point of the mouse pointer (vec3 p1). The executing sequence is the following:

  1. Define and initialize two points (p0 and p1) by using the Unigine::getPlayerMouseDirection() function from core/scripts/utils.h.
  2. Create an instance of the WorldIntersection class to get the intersection information.
  3. Check, if there is an intersection with an object. The engine.world.getIntersection() function returns an intersected object when the object intersects with the traced line.
  4. In this example, when the object intersects with the traced line, all the surfaces of the intersected object change their material parameters. The WorldIntersection class instance gets the coordinates of the intersection point, the index of the surface and the index of the intersected triangle. You can get all these fields by using getIndex(), getPoint() and getSurface() functions
Source code (UnigineScript)
#include <core/scripts/utils.h>
/* ... */
int update() {
	// define two vec3 coordinates
	vec3 p0,p1;
	// get the mouse direction from camera (p0) to the cursor pointer (p1)
	Unigine::getPlayerMouseDirection(p0,p1);
	
	// create an instance of the WorldIntersection class to get the result
	WorldIntersection intersection = new WorldIntersection();
	
	// create an instance for intersected object
	Object object = engine.world.getIntersection(p0,p1,1,intersection);
	
	// if the intersection has been occurred, change the parameter and the texture of the object's material
	if(object != NULL)
	{
	  forloop(int i=0; object.getNumSurfaces())
	  {
	    object.setMaterialParameterFloat4("diffuse_color", vec4(1.0f, 0.0f, 0.0f, 1.0f),i);
	    object.setMaterialTexture("diffuse","", i);
	    
	    // show intersection details in console
	    log.message("point: %s index: %i surface: %i \n", typeinfo(intersection.getPoint()), intersection.getIndex(), intersection.getSurface());
	  }
	}
	return 1;
}
/* ... */

Physics Intersection#

Physics intersection function detects intersections with a physical shape or a fracture body. If the object has no body, this function detects intersection with surfaces (polygons) of the object having the physics intersection flag enabled. When you need to find the intersection with the shape of the object (not with polygons), engine.physics intersection function is the best way to get it.

The picture above shows how the engine.physics.getIntersection() function detects the shape that intersects with the line.

There are 2 engine.physics functions to find physics intersections:

These functions perform tracing from the start p0 point to the end p1 point to find a collision object (or a shape) located on that line. Functions use world space coordinates.

The engine.physics.getIntersection() function is overloaded and receives 4 or 5 arguments:

  • vec3 p0 - the start point coordinates of the trace line.
  • vec3 p1 - the end point coordinates of the trace line.
  • int mask - the intersection mask. Use the intersection mask to find object only with specified intersection mask.
  • int exclude[] - the list of objects IDs to exclude, all these objects will be ignored.
  • variable v - The function returns an intersected object which is the nearest to the start point (p0). Information about the intersection will be presented in variable which you pass to the function as an argument:
    • PhysicsIntersection intersection - the PhysicsIntersection class instance. By using this class you can get the intersection point (coordinates), the index of the intersected surface and the intersection Shape.
    • PhysicsIntersectionNormal normal - the PhysicsIntersectionNormal class instance. By using this class you can get only the normal of the intersection point.
    Notice
    Passing NULL instead of the intersection query object will perform fast intersection algorithm without the closest intersection point searching.

Thus, to exclude some obstacles you should use these methods:

  • Use a physics intersection mask. A physics intersection is detected only if the physics intersection mask of the surface/shape/body matches the intersection mask passed as a function argument, otherwise it is ignored.
  • Specify the list of objects to exclude and pass to the function as an argument.

Usage Example

The following example shows how you can get the intersection information by using the PhysicsIntersection class. In this example we specify a line from the point of the camera (vec3 p0) to the point of the mouse pointer (vec3 p1). The executing sequence is the following:

  1. Define and initialize two points (p0 and p1) by using the Unigine::getPlayerMouseDirection() function from core/scripts/utils.h.
  2. Create an instance of the PhysicsIntersection class to get the intersection information.
  3. Check, if there is an intersection with an object with a shape or a collision object. The engine.physics.getIntersection() function returns an intersected object when the object intersects with the traced line.
  4. In this example, when the object intersects with the traced line, all the surfaces of the intersected object change their material parameters. If the object has a shape, its information will be shown in console. The PhysicsIntersection class instance gets the coordinates of the intersection point, the index of the surface and the Shape class object. You can get all these fields by using getShape(), getPoint() and getSurface() functions
Source code (UnigineScript)
#include <core/scripts/utils.h>
/* ... */
int update {
	// define two vec3 coordinates
	vec3 p0,p1;
	// get the mouse direction from camera (p0) to the cursor pointer (p1)
	Unigine::getPlayerMouseDirection(p0,p1);
	
	// create the instance of the PhysicsIntersection object to save the result
	PhysicsIntersection intersection = new PhysicsIntersection();
	// create an instance for intersected object and check the intersection
	Object object = engine.physics.getIntersection(p0,p1,1,intersection);
	
	// if the intersection has been occurred, change the parameter of the object's material
	if(object != NULL)
	{
		forloop(int i=0; object.getNumSurfaces())
		{
			object.setMaterialParameterFloat4("albedo_color", vec4(1.0f, 0.0f, 0.0f, 1.0f),i);
		}
		
		// if the intersected object has a shape, show the information about the intersection   
		Shape shape = intersection.getShape();
		if (shape != NULL)
		{
			log.message("physics intersection info: point: %s shape: %s surface: %i \n", typeinfo(intersection.getPoint()), typeinfo(shape.getType()), intersection.getSurface());
		}
	}
	return 1;
}
/* ... */

Game Intersection#

You can check the intersection with obstacles by using the engine.game.getIntersection() function. This function creates an invisible cylinder between two points and check if an obstacle is presented inside of it.

The picture above shows how the engine.game.getIntersection() function detects the obstacle that intersects with the cylinder.

The function returns an intersected obstacle which is the nearest to the start point (p0). Information about the intersection will be presented in the GameIntersection class instance which you pass to the function as an argument. The GameIntersection class instance saves the intersection point which is the nearest to the start (p0) point.

The engine.game.getIntersection() function is overloaded and receives 5 or 6 arguments:

  • vec3 p0 - the start point coordinates.
  • vec3 p1 - the end point coordinates.
  • float radius - the end point coordinates.
  • int mask - the obstacle intersection mask. Use the intersection mask to find object only with specified intersection mask.
  • int exclude[] - the list of obstacles to exclude.
  • GameIntersection intersection - The function returns an intersected obstacle which is the nearest to the start point (p0). Information about the intersection will be presented in the GameIntersection class instance which you pass to the function as an argument.
    Notice
    Passing NULL instead of the intersection query object will perform fast intersection algorithm without the closest intersection point searching.

Thus, to exclude some obstacles you should use these methods:

  • Use an obstacle intersection mask. An intersection is found only if an object is matching the intersection mask, otherwise it is ignored.
  • Specify the list of obstacles to exclude and pass to the function as an argument.

Usage Example

The following example shows how you can get the intersection point (vec3) of the cylinder between two points with an obstacle. In this example we specify a cylinder from the point of the camera (vec3 p0) to the point of the mouse pointer (vec3 p1) with the specified radius. The executing sequence is the following:

  1. Define and initialize two points (p0 and p1) by using the Unigine::getPlayerMouseDirection() function from core/scripts/utils.h.
  2. Create an instance of the GameIntersection class to get the intersection point coordinates.
  3. Check, if there is an intersection with an obstacle. The engine.game.getIntersection() function returns an intersected obstacle when the obstacle appears in the area of the cylinder.
  4. After that GameIntersection instance gets the point of the nearest intersection point and you can get it by using the getPoint() function.
Source code (UnigineScript)
#include <core/scripts/utils.h>

/* ... */
int update {
	/* ... */
	// define two vec3 coordinates
	vec3 p0,p1;
	// get the mouse direction from camera (p0) to the cursor pointer (p1)
	Unigine::getPlayerMouseDirection(p0,p1);
	
	// create an instance of the GameIntersection class
	GameIntersection intersection = new GameIntersection();
	
	// try to get the intersection with an obstacle.
	// cylinder has radius 0.1f, intersection mask equals to 1
	Obstacle obstacle = engine.game.getIntersection(p0,p1,0.1f, 1, intersection);
	
	// check, if the intersection of mouse direction with any obstacle was occurred;
	if(obstacle !=NULL)
	{
		// show the coordinates of the intersection in console 
		log.message("The intersection with obstacle was here: %s\n", typeinfo(intersection.getPoint()));
	}
	return 1;
}
/* ... */
Last update: 2020-07-31
Build: ()