Intersections
Unigine has different methods to detect intersections. Intersection is a generic point of the defined area (or line) and an object. This article describes different types of intersections and their usage.
So, there are three main types of intersections:
 World intersection  an intersection with objects and nodes. The search of intersections performs by using engine.world functions.
 Physics intersection  an intersection with shapes and collision objects. The search of intersections performs by using engine.physics functions.
 Game intersection  an intersection with obstacles. The search of intersections performs by using engine.game functions.
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.
All of the intersection functions, except for the Object.getIntersection() function, use world coordinates.
World Intersection
By using different engine.world functions you can find world intersections. 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. There are 3 groups of world intersection functions:
 Functions to find nodes within a bounding volume.
 Functions to find objects within a bounding volume or intersected with a traced line.
 Functions to find first intersected object with a traced line.
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 nodes of specified type) 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.
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:
 Define an array for output values and a BoundBox instance.
 Check, if there is an intersection with a node. The engine.world.getIntersectionNodes() function returns an integer value: the amount of found nodes.
 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.
/* ... */
// It is supposed that you have these variables in your code:
// a BoundBox instance
BoundBox boundBox;
// Array for the result
int resultArray[0];
/* ... */
/* 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");
}
/* ... */
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):
 engine.world.getIntersectionObjectVariables(variable v, int ret = [])
 engine.world.getIntersectionObjectVariables(vec3 p0, vec3 p1, int ret = [])
 engine.world.getIntersectionObjects(variable v, int ret = [])
 engine.world.getIntersectionObjects(vec3 p0, vec3 p1, int ret = [])
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:
 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.
 Check, if there is an intersection with an object. The engine.world.getIntersectionObjects() function returns an integer value: the amount of found nodes.
 In this example, when the object intersects with the traced line, console shows the information about that object.
#include <core/scripts/utils.h>
/* ... */
// it is supposed that you have this variable in your code:
// array for the result
int resultArray[0];
/* ... */
// 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() );
}
}
/* ... */
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.
This function detects intersection with surfaces (polygons) of mesh and terrain objects. But there are some conditions to detect the intersection with the surface:

A persurface Intersection flag is enabled.
You can set this flag to the object's surface by using the Object.setIntersection() function.

An Intersection option of the property in the Properties window is enabled.
You can enable this property by using the Property.setIntersection() function.
 A surface is enabled.
 A surface has an assigned material.
 A surface has an assigned property.
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 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.
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:
 Define and initialize two points (p0 and p1) by using the Unigine::getPlayerMouseDirection() function from core/scripts/utils.h.
 Create an instance of the WorldIntersection class to get the intersection information.
 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.
 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
#include <core/scripts/utils.h>
/* ... */
// 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.setMaterialParameter("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());
}
}
/* ... */
Physics Intersection
Physics intersection function detects the intersection with a shape of bodies. If the object has no body, this function detects intersection with surfaces (polygons) of the object with intersection flag. 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.
There are 2 engine.physics functions to find physics intersections:
 engine.physics.getIntersection (vec3 p0, vec3 p1, int mask, variable v)
 engine.physics.getIntersection (vec3 p0, vec3 p1, int mask, int exclude[] = [], variable v)
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.
 WorldIntersectionNormal normal  The PhysicsIntersectionNormal class instance. By using this class you can get only the the normal of the intersection point.
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 intersection mask. An intersection is found only if an object is matching the intersection mask, 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:
 Define and initialize two points (p0 and p1) by using the Unigine::getPlayerMouseDirection() function from core/scripts/utils.h.
 Create an instance of the PhysicsIntersection class to get the intersection information.
 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.
 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
#include <core/scripts/utils.h>
/* ... */
// 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
// and the texture of the object's material
if(object != NULL)
{
forloop(int i=0; object.getNumSurfaces())
{
object.setMaterialParameter("diffuse_color", vec4(1.0f, 0.0f, 0.0f, 1.0f),i);
object.setMaterialTexture("diffuse","", 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());
}
}
/* ... */
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 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.
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:
 Define and initialize two points (p0 and p1) by using the Unigine::getPlayerMouseDirection() function from core/scripts/utils.h.
 Create an instance of the GameIntersection class to get the intersection point coordinates.
 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.
 After that GameIntersection instance gets the point of the nearest intersection point and you can get it by using the getPoint() function.
#include <core/scripts/utils.h>
/* ... */
// 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()));
}
/* ... */