engine.world Functions

This class provides functionality for the world script. It contains methods required for loading the world with all its nodes, managing a spatial tree and handling nodes collisions and intersections.

World Class

Members

void engine.world.set(string function, Variable value)

Arguments

• string function - Variable name.
• Variable value - Value of the variable.

Variable engine.world.get(string function)

Arguments

• string function - Variable name with a namespace, if needed.

Return value

Node engine.world.getAsyncNode(int id)

Arguments

• int id - The loading operation identifier.

Return value

void engine.world.setBudget(float budget)

Arguments

• float budget - The budget value in seconds. The default value is 1/60.

float engine.world.getBudget()

Return value

int engine.world.getCollisionObjects(Variable v, int[] ret)

Searches for all collider objects within a given bounding volume. Intersection is performed with node surfaces (polygons).

Arguments

• Variable v - Variable. Can be one of the following:
  • BoundSphere bs - The bounding sphere.
  • BoundBox bb - The bounding box.
  • BoundFrustum bf - The bounding frustum.
• int[] ret - An array into which the result will be placed.

Return value

int engine.world.getCollisionObjects(vec3 p0, vec3 p1, int[] ret)

Performs tracing from the p0 point to the p1 point to find all collider objects intersecting the line. This function detects intersection with surfaces (polygons) of mesh and terrain objects.

Intersections with the surface can be found only if the following conditions are fulfilled:

1. A per-surface Intersection flag is enabled.
2. An Intersection option of the property in the Properties window is enabled.
3. A surface is enabled.
4. A surface has an assigned material.
5. A surface has an assigned property.

Arguments

• vec3 p0 - Coordinates of the line start point.
• vec3 p1 - Coordinates of the line end point.
• int[] ret - An array into which the result will be placed.

Return value

int engine.world.getCollisionObjectVariables(Variable v, int[] ret)

Searches for all collider objects which have set user variables. Intersection is performed with node surfaces (polygons). The search is performed within a given bounding volume.

Arguments

• Variable v - Variable. Can be one of the following:
  • BoundSphere bs - The bounding sphere.
  • BoundBox bb - The bounding box.
  • BoundFrustum bf - The bounding frustum.
• int[] ret - An array into which the result will be placed.

Return value

int engine.world.getCollisionObjectVariables(vec3 p0, vec3 p1, int[] ret)

Performs tracing from the p0 point to the p1 point to find all collider objects which have set user variables. This function detects intersection with surfaces (polygons) of mesh and terrain objects.

Intersections with the surface can be found only if the following conditions are fulfilled:

1. A per-surface Intersection flag is enabled.
2. An Intersection option of the property in the Properties window is enabled.
3. A surface is enabled.
4. A surface has an assigned material.
5. A surface has an assigned property.

Arguments

• vec3 p0 - Coordinates of the line start point.
• vec3 p1 - Coordinates of the line end point.
• int[] ret - An array into which the result will be placed.

Return value

void engine.world.setData(string data)

Arguments

• string data - New user data.

string engine.world.getData()

Return value

void engine.world.setDistance(float distance)

Arguments

• float distance - New distance in units.

float engine.world.getDistance()

Return value

int engine.world.isFunction(string name, int num_args)

Arguments

• string name - Function name.
• int num_args - Number of function arguments.

Return value

Object engine.world.getIntersection(vec3 p0, vec3 p1, int mask, int[] exclude, Variable value)

Performs tracing from the p0 point to the p1 point to find the list of objects intersecting the line. This function detects intersection with surfaces (polygons) of meshes. An intersection can be found found only if an object is matching the intersection mask.

Intersections with the surface can be found only if the following conditions are fulfilled:

1. A per-surface Intersection flag is enabled.
2. An Intersection option of the property in the Properties window is enabled.
3. A surface is enabled.
4. A surface has an assigned material.
5. A surface has an assigned property.

Arguments

• vec3 p0 - Coordinates of the line start point.
• vec3 p1 - Coordinates of the line end point.
• int mask - Intersection mask. If 0 is passed, the function will return NULL.
• int[] exclude - The list of objects IDs to be excluded.
• Variable value - Variable. Can be one of the following:
  • WorldIntersection intersection - The WorldIntersection class instance.
  • WorldIntersectionNormal normal - The WorldIntersectionNormal class instance.
  • WorldIntersectionTexCoord texcoord - The WorldIntersectionTexCoord class instance.
  Notice

  As a new node becomes a part of the BSP tree only after the updateSpatial() method is called (the engine calls the method automatically each frame after the world script update() code is executed), all engine subsystems can process this node only in the next frame. If you need to get the node in the very first frame, call the updateSpatial() method manually. The engine will call this method automatically after the update() code is executed anyways.

Return value

Object engine.world.getIntersection(vec3 p0, vec3 p1, int mask, Variable value)

Performs tracing from the p0 point to the p1 point to find the nearest object which intersects the line. This function detects intersection with surfaces (polygons) of meshes. An intersection is found only if an object is matching the intersection mask.

Intersections with the surface can be found only if the following conditions are fulfilled:

1. A per-surface Intersection flag is enabled.
2. An Intersection option of the property in the Properties window is enabled.
3. A surface is enabled.
4. A surface has an assigned material.
5. A surface has an assigned property.

Usage Example

The following example shows how you can get the intersection information by using the WorldIntersection class. In this example the line is an invisible traced 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 a 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 cursor pointer (p1)
Unigine::getPlayerMouseDirection(p0,p1);

// create an instance of the WorldIntersection class to get the result
WorldIntersection wis = new WorldIntersection();

// create an instance for intersected object
Object object = engine.world.getIntersection(p0,p1,1,wis);

// 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(wis.getPoint()), wis.getIndex(), wis.getSurface());
	}

}
/* ... */

Arguments

• vec3 p0 - Coordinates of the line start point.
• vec3 p1 - Coordinates of the line end point.
• int mask - Intersection mask. If 0 is passed, the function will return NULL.
• Variable value - Variable. Can be one of the following:
  • WorldIntersection intersection - The WorldIntersection class instance.
  • WorldIntersectionNormal normal - The WorldIntersectionNormal class instance.
  • WorldIntersectionTexCoord texcoord - The WorldIntersectionTexCoord class instance.
  Notice

  As a new node becomes a part of the BSP tree only after the updateSpatial() method is called (the engine calls the method automatically each frame after the world script update() code is executed), all engine subsystems can process this node only in the next frame. If you need to get the node in the very first frame, call the updateSpatial() method manually. The engine will call this method automatically after the update() code is executed anyways.

Return value

int engine.world.getIntersectionNodes(Variable value, int type, int[] ret)

Searches for all nodes (or nodes filtered by type) within a given bounding volume. Intersection is performed with node surfaces (polygons). The search is performed within a given bounding volume.

Arguments

• Variable value - Variable. Can be one of the following:
  • BoundSphere bs - The bounding sphere.
  • BoundBox bb - The bounding box.
  • BoundFrustum bf - The bounding frustum.
• int type - The node type (one of the NODE_* variables); -1 is not to use a filter.
• int[] ret - The array into which the result will be placed.

Return value

int engine.world.getIntersectionNodeVariables(Variable value, int type, int[] ret)

Searches for all nodes (or nodes filtered by type) which have set user variables. Intersection is performed with node surfaces (polygons). The search is performed within a given bounding volume.

Arguments

• Variable value - Variable. Can be one of the following:
  • BoundSphere bs - The bounding sphere.
  • BoundBox bb - The bounding box.
  • BoundFrustum bf - The bounding frustum.
• int type - The node type (one of the NODE_* variables); -1 is not to use a filter.
• int[] ret - The array into which the result will be placed.

Return value

int engine.world.getIntersectionObjects(Variable value, int[] ret)

Searches for all objects within a given bounding volume. Intersection is performed with node surfaces (polygons).

Arguments

• Variable value - Variable. Can be one of the following:
  • BoundSphere bs - The bounding sphere.
  • BoundBox bb - The bounding box.
  • BoundFrustum bf - The bounding frustum.
• int[] ret - The array into which the result will be placed.

Return value

int engine.world.getIntersectionObjects(vec3 p0, vec3 p1, int[] ret)

Performs tracing from the p0 point to the p1 point to find all objects intersecting the line. This function detects intersection with surfaces (polygons) of mesh and terrain objects.

Intersections with the surface can be found only if the following conditions are fulfilled:

1. A per-surface Intersection flag is enabled.
2. An Intersection option of the property in the Properties window is enabled.
3. A surface is enabled.
4. A surface has an assigned material.
5. A surface has an assigned property.

Arguments

• vec3 p0 - Coordinates of the line start point.
• vec3 p1 - Coordinates of the line end point.
• int[] ret - The array into which the result will be placed.

Return value

int engine.world.getIntersectionObjectVariables(Variable v, int[] ret)

Searches for the data associated with all objects (or objects filtered by type) within a given bounding volume. Intersection is performed with object surfaces (polygons).

Arguments

• Variable v - Variable. Can be one of the following:
  • BoundSphere bs - The bounding sphere.
  • BoundBox bb - The bounding box.
  • BoundFrustum bf - The bounding frustum.
• int[] ret - The array into which the result will be placed.

Return value

int engine.world.getIntersectionObjectVariables(vec3 p0, vec3 p1, int[] ret)

Performs tracing from the p0 point to the p1 point to find all objects which have set user variables. This function detects intersection with surfaces (polygons) of meshes.

Intersections with the surface can be found only if the following conditions are fulfilled:

1. A per-surface Intersection flag is enabled.
2. An Intersection option of the property in the Properties window is enabled.
3. A surface is enabled.
4. A surface has an assigned material.
5. A surface has an assigned property.

Arguments

• vec3 p0 - Coordinates of the line start point.
• vec3 p1 - Coordinates of the line end point.
• int[] ret - The array into which the result will be placed.

Return value

int engine.world.isLoaded()

Return value

void engine.world.setName(string name)

Arguments

• string name - Name of the world.

string engine.world.getName()

Return value

Node engine.world.getNode(int id)

Arguments

• int id - Node ID.

Return value

int engine.world.isNode(int id)

Arguments

• int id - Node ID.

Return value

void engine.world.getNodes(Vector<Node> & nodes)

Arguments

• Vector<Node> & nodes - Return array with node smart pointers.

int engine.world.getNumQueuedNodes()

Return value

int engine.world.getNumQueuedResources()

Return value

int engine.world.getNumUpdateNodes()

Return value

float engine.world.getTotalTime()

Return value

Node engine.world.getUpdateNode(int num)

Arguments

• int num - Node ID.

Return value

int engine.world.isVariable(string name)

Arguments

• string name - Variable name.

Return value

void engine.world.addUpdateNode(Node node)

Arguments

• Node node - Node to be updated.

int engine.world.addWorld(string name)

Arguments

• string name - Name of the file describing the world.

Return value

Variable engine.world.call(Variable function)

Arguments

• Variable function - Name of the function to execute.

Return value

Variable engine.world.call(Variable function, Variable arg0)

Arguments

• Variable function - Name of the function to execute.
• Variable arg0 - Argument of the function.

Return value

Variable engine.world.call(Variable function, Variable arg0, Variable arg1)

Arguments

• Variable function - Name of the function to execute.
• Variable arg0 - Argument of the function.
• Variable arg1 - Argument of the function.

Return value

Variable engine.world.call(Variable function, Variable arg0, Variable arg1, Variable arg2)

Arguments

• Variable function - Name of the function to execute.
• Variable arg0 - Argument of the function.
• Variable arg1 - Argument of the function.
• Variable arg2 - Argument of the function.

Return value

Variable engine.world.call(Variable function, Variable arg0, Variable arg1, Variable arg2, Variable arg3)

Arguments

• Variable function - Name of the function to execute.
• Variable arg0 - Argument of the function.
• Variable arg1 - Argument of the function.
• Variable arg2 - Argument of the function.
• Variable arg3 - Argument of the function.

Return value

Variable engine.world.call(Variable function, Variable arg0, Variable arg1, Variable arg2, Variable arg3, Variable arg4)

Arguments

• Variable function - Name of the function to execute.
• Variable arg0 - Argument of the function.
• Variable arg1 - Argument of the function.
• Variable arg2 - Argument of the function.
• Variable arg3 - Argument of the function.
• Variable arg4 - Argument of the function.

Return value

Variable engine.world.call(Variable function, Variable arg0, Variable arg1, Variable arg2, Variable arg3, Variable arg4, Variable arg5)

Arguments

• Variable function - Name of the function to execute.
• Variable arg0 - Argument of the function.
• Variable arg1 - Argument of the function.
• Variable arg2 - Argument of the function.
• Variable arg3 - Argument of the function.
• Variable arg4 - Argument of the function.
• Variable arg5 - Argument of the function.

Return value

Variable engine.world.call(Variable function, int id = [])

Arguments

• Variable function - Name of the function to execute.
• int id - Array of up to 8 arguments.

Return value

int engine.world.checkAsyncNode(int id)

Arguments

• int id - The loading operation identifier.

Return value

int engine.world.clearNode(string name)

Arguments

• string name - File with the node.

Return value

int engine.world.forceAsyncNode(int id)

Arguments

• int id - The loading operation identifier.

Return value

int engine.world.loadAsyncNode(string name, int group = 0, float weight = 0.0f)

Arguments

• string name - The name of the node.
• int group - The number of the node group.
• float weight - The priority of the node.

Return value

int engine.world.removeAsyncNode(int id)

Arguments

• int id - The loading operation identifier.

Return value

int engine.world.saveNode(string name, Node node, int materials = 1, int binary = 0)

Arguments

• string name - Path to the *.node file.
• Node node - Pointer to the node to save.
• int materials - If the node has the materials assigned, and this flag is set to 1, the corresponding material libraries will be also listed in the *.world file.
• int binary - If set to 1, the node is saved to the binary *.xml. This file cannot be read, but using it speeds up the saving of the node and requires less disk space.

Return value

int engine.world.saveNodes(string name, Node[] nodes, int materials = 1, int binary = 0)

Arguments

• string name - Path to the *.node file.
• Node[] nodes - Array of nodes' smart pointers to be saved.
• int materials - If the node has the materials assigned, and this flag is set to 1, the corresponding material libraries will be also listed in the *.world file.
• int binary - If set to 1, the node is saved to the binary *.xml. This file cannot be read, but using it speeds up the saving of the node and requires less disk space.

Return value

void engine.world.updateSpatial()

Updates the node BSP (binary space partitioning) tree.

The engine calls this method automatically each frame after the world script update() code is executed. As a new node becomes a part of the BSP tree only after this method is called, all engine subsystems (renderer, physics, sound, pathfinding, collisions, intersections, etc.) can process this node only in the next frame. If you need the subsystem to process the node in the very first frame, you can call the updateSpatial() method manually. The engine will call this method automatically after the update() code is executed anyways.