Getting Started
Migrating to UNIGINE 2.0
C++ API Migration
UnigineScript
The Language
Core Library
Engine Library
Node-Related Classes
GUI-Related Classes
Plugins Library
High-Level Systems
Samples
Usage Examples
C++ API
API Reference
Integration Samples
Usage Examples
C++ Plugins

engine.world Functions

The set of functions describes how to load the world with all its nodes, manage a spatial tree and handle nodes collisions and intersections.

void engine.world.addUpdateNode (Node node)

Adds a node that should be updated even if it is out of the view frustum. This function should be called every frame.

Arguments

  • Node node - Node to be updated.

void engine.world.addUpdateNodes (int id = [])

Adds multiple nodes that should be updated even if they are out of the view frustum. This function should be called every frame.

Arguments

  • int id - Nodes array ID.

int engine.world.addWorld (string filename)

Loads a world from a file and adds it to the current world.

Arguments

Return value

1 if the world is loaded and added successfully; otherwise, 0.

variable engine.world.call (variable function)

Executes a function of the world script from an external script. The function should not take any arguments.

Arguments

  • variable function - Name of the function to execute.

Return value

Value returned by the function.

variable engine.world.call (variable function, variable arg)

Executes a function of the world script from an external script. The function should take one argument.

Arguments

  • variable function - Name of the function to execute.
  • variable arg - Argument of the function.

Return value

Value returned by the function.

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

Executes a function of the world script from an external script. The function should take two arguments.

Arguments

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

Return value

Value returned by the function.

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

Executes a function of the world script from an external script. The function should take three arguments.

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

Value returned by the function.

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

Executes a function of the world script from an external script. The function should take four arguments.

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

Value returned by the function.

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

Executes a function of the world script from an external script. The function should take five arguments.

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

Value returned by the function.

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

Executes a function of the world script from an external script. The function should take six arguments.

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

Value returned by the function.

variable engine.world.callv (variable function, int id = [])

Executes a function of the world script from an external script. The function takes an array of arguments (up to 8 arguments are supported).

Arguments

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

Return value

Value returned by the function.

int engine.world.checkAsyncNode (int id)

Checks if the node is in the loading queue or already loaded.

Arguments

Return value

1 if the node is in the loading queue or already loaded; otherwise, 0.

int engine.world.clearNode (string filename)

Clears a cache of the given NodeReference.

Arguments

  • string filename - File with the node.

Return value

1 if the cache was successfully cleaned; otherwise, 0.

int engine.world.forceAsyncNode (int id)

Forces the loading of the node (the specified node gets the higher priority and will be loaded first).

Arguments

Return value

1 if the node is successfully loaded; otherwise, 0.

Node engine.world.getAsyncNode (int id)

Gets the loaded node. If the loaded node consists of multiple objects, a new dummy object to combine them is created and its smart pointer is returned.

Arguments

Return value

The loaded node smart pointer, if found; otherwise - 0.

int engine.world.getAsyncNodes (int id, int nodes = [])

Gets the array of nodes. If the loaded node consists of multiple objects, they are put into the array.

Arguments

Return value

1 if the operation was successful; otherwise, 0.

float engine.world.getBudget ()

Returns the value of the world generation budget for Grass and Clutter objects. New objects are not created when time is out of the budget.

Return value

The budget value in seconds.

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. Depending on the variable passed as the argument, the bounding volume can be:

  • BoundSphere bs - The bounding sphere.
  • BoundBox bb - The bounding box.
  • BoundFrustum bf - The bounding frustum.

Arguments

  • variable v - The variable.
  • int ret - An array into which the result will be placed.

Return value

The amount of found nodes.

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 - The start point coordinates.
  • vec3 p1 - The end point coordinates.
  • int ret - An array into which the result will be placed.

Return value

The amount of found objects.

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). Depending on the variable passed as the argument, the intersection volume can be:

  • BoundSphere bs - The bounding sphere.
  • BoundBox bb - The bounding box.
  • BoundFrustum bf - The bounding frustum.

Arguments

  • variable v - The variable.
  • int ret - The array into which the result will be placed.

Return value

The amount of found objects.

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 - The start point coordinates.
  • vec3 p1 - The end point coordinates.
  • int ret - An array into which the result will be placed.

Return value

The amount of found objects.

string engine.world.getData ()

Returns user string data associated with the node. This string is written directly into a *.world file.

Return value

User string data.

float engine.world.getDistance ()

Returns a distance, at which (and farther) nothing will be rendered or simulated.

Return value

Distance in units.

int engine.world.getIntersectionNodeVariables (variable v, 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. Depending on the variable passed as the argument, the bounding volume can be:

  • BoundSphere bs - The bounding sphere.
  • BoundBox bb - The bounding box.
  • BoundFrustum bf - The bounding frustum.

Arguments

  • variable v - The variable.
  • 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

The amount of found nodes.

int engine.world.getIntersectionNodes (variable v, 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). Depending on the variable passed as the argument, the intersection volume can be:

  • BoundSphere bs - The bounding sphere.
  • BoundBox bb - The bounding box.
  • BoundFrustum bf - The bounding frustum.

Arguments

  • variable v - The variable.
  • 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

The amount of found nodes.

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). Depending on the variable passed as the argument, the intersection volume can be:

  • BoundSphere bs - The search is performed within the bounding sphere.
  • BoundBox bb - The search is performed within the bounding box.
  • BoundFrustum bf - The search is performed within the bounding frustum.

Arguments

  • variable v - The variable.
  • int ret - An array into which the result will be placed.

Return value

The amount of found objects.

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 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 - The start point coordinates.
  • vec3 p1 - The end point coordinates.
  • int ret - An array into which the result will be placed.

Return value

The amount of found objects.

int engine.world.getIntersectionObjects (variable v, int ret = [])

Searches for all objects within a given bounding volume. Intersection is performed with node surfaces (polygons). Depending on the variable passed as the argument, the intersection volume can be:

  • BoundSphere bs - The bounding sphere.
  • BoundBox bb - The bounding box.
  • BoundFrustum bf - The bounding frustum.

Arguments

  • variable v - The variable.
  • int ret - The array into which the result will be placed.

Return value

The amount of found objects.

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 - The start point coordinates.
  • vec3 p1 - The end point coordinates.
  • int ret - An array into which the result will be placed.

Return value

The amount of found objects.

Object engine.world.getIntersection (vec3 p0, vec3 p1, int mask, int exclude[] = [], variable v)

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 mesh and terrain objects. 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.

Depending on the variable passed as an argument, the result will be presented as following:

Arguments

  • vec3 p0 - The start point coordinates.
  • vec3 p1 - The end point coordinates.
  • int mask - An intersection mask.
    Notice
    If 0 is passed, the function will return NULL.
  • int exclude[] - The list of objects IDs to exclude.
  • variable v - The variable.

Return value

The reference to the first intersected object, if found; otherwise - 0.

Object engine.world.getIntersection (vec3 p0, vec3 p1, int mask, variable v)

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 mesh and terrain objects. An intersection is found only if an object is matching the intersection mask.

Depending on the variable passed as an argument, the result will be presented as following:

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
Source code (UnigineScript)
#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 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());
  }

}
/* ... */
      			

Arguments

  • vec3 p0 - The start point coordinates.
  • vec3 p1 - The end point coordinates.
  • int mask - The intersection mask.
    Notice
    If 0 is passed, the function will return NULL.
  • variable v - The variable.

Return value

The reference to the first intersected object, if found; otherwise - 0.

string engine.world.getName ()

Returns the name of the currently loaded world. (If a path was specified in the name, the returned string will contain both the world name and a path).

Return value

Name of the current world.

Node engine.world.getNode (int id)

Returns a node by its ID. This can be any node: either created in scripts or loaded from the *.world file.
Notice
See also engine.editor.getNodeByName() and engine.editor.getNode() functions to get nodes loaded from the *.world file.

Arguments

  • int id - Node ID.

Return value

Requested node, if found (NULL otherwise).

Examples

Source code (UnigineScript)
Node node = new NodeDummy();
int id = node.getID();
Node n = engine.world.getNode(id);

int engine.world.getNumQueuedNodes ()

Returns the number of queued nodes waiting for the background loading. The return value also includes the currently processed node. To add node for the background loading, use the engine.world.loadAsyncNode() function.

Return value

Number of queued nodes including the currently processed node.

int engine.world.getNumQueuedResources ()

Returns the number of queued resources waiting for the background loading. The return value also includes the currently processed node.

Return value

Number of queued resources including the currently processed resource.

int engine.world.getNumUpdateNodes ()

Returns the number of currently updating nodes in the world.

Return value

Number of updating nodes.

float engine.world.getTotalTime ()

Returns the total time (in milliseconds) of loading a resource.

Return value

The total time value, milliseconds.

Node engine.world.getUpdateNode (int num)

Returns an updated node by its ID.

Arguments

  • int num - Node ID.

Return value

The node smart pointer, if found; otherwise - 0.

variable engine.world.get (string var)

Returns a variable from the world script. Instances of user-defined classes cannot be requested in such a manner.

Arguments

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

Return value

Requested instance.

int engine.world.isLoaded ()

Returns a value indicating if the current world is fully loaded.

Return value

1 if the world is loaded; otherwise, 0.

int engine.world.isNode (variable v)

Checks a given node for validity. Either a node itself can be passed or the node ID.

Arguments

  • variable v - A node or its ID to test.

Return value

1 if the variable holds a valid Node instance; otherwise, 0.

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

Loads the node with the specified group and priority to the thread.

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

The loading operation identifier.

Node engine.world.loadNode (string filename, int cache = 1, int is_world = 0)

Loads a node from a file. If the node is loaded successfully, it does not belong to any node hierarchy or list, so be careful and make sure to handle it properly, when it is no longer needed.

Arguments

  • string filename - Name of the node.
  • int cache - 1 to use the file cache; otherwise, 0.
  • int is_world -

Return value

Loaded node or 0 if the node cannot be loaded.

int engine.world.loadNodes (string name, int[] nodes = [])

Loads nodes from the specified file.

Arguments

  • string name - File with the nodes.
  • int[] nodes - Array of nodes to be loaded.

Return value

1 if the nodes are loaded successfully; otherwise, 0.

int engine.world.removeAsyncNode (int id)

Removes the node from the loading queue.

Arguments

Return value

1 if the node is successfully removed; otherwise, 0.

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

Saves the specified node with all the properties and materials to the file.

Arguments

  • string name - The name of the file, to which the node will be saved.
  • Node node - The node to be saved.
  • int materials - 1 to save a node with materials assigned to it; otherwise, 0. By default, 1 is used.
  • int binary - A flag indicating if the node will be saved into a binary XML format (disabled by default).

Return value

1 if the node is saved successfully; otherwise, 0.

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

Saves nodes with all the properties and materials assigned to them into a specified file.

Arguments

  • string name - The name of the file, to which the nodes are going to be saved.
  • int[] nodes - The array to which the nodes will be saved.
  • int materials - 1 to save nodes with materials assigned to them; otherwise, 0. By default, 1 is used.
  • int binary - A flag indicating if the node will be saved into a binary XML format (disabled by default).

Return value

1 if nodes are saved successfully; otherwise, 0.

void engine.world.setBudget (float budget)

Sets the world generation budget value for Grass and Clutter objects. New objects are not created when time is out of the budget.

Arguments

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

void engine.world.setData (string data)

Updates user data associated with the node.

Arguments

  • string data - New user data.

void engine.world.setDistance (float distance)

Updates the distance, at which (and farther) nothing will be rendered or simulated.

Arguments

  • float distance - New distance in units.

void engine.world.setName (string name)

Assigns a new name to an editable world.

Arguments

  • string name - Name of the world.

void engine.world.set (string name, variable variable)

Set a variable in a world script (this function can be called directly from any other script).

Arguments

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

void engine.world.updateSpatial ()

Updates the BSP tree. This function is automatically called each frame. This function is called manually if a new object was added through the script and it needs to participate in spatial intersection during one and the same frame. Or if you have moved the node, and then want to get callbacks on basis of changed position in the same frame.
You may want to call updateSpatial() before: You can call updateSpatial() several times during one frame, but do not use it once too many times. It is more rational to change position of all required nodes first and only after that call updateSpatial().
Last update: 2017-07-03