UnigineScript
The Language
Core Library
Engine Library
Node-Related Classes
GUI-Related Classes
Plugins Library
High-Level Systems
Samples
C++ API
API Reference
Integration Samples
Usage Examples
C++ Plugins
Content Creation
Materials
Unigine Material Library
Tutorials

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.

Return value

The budget value in milliseconds.

int engine.world.getCollisionObjectsVariable (variable p0, variable p1, int ret_id)

Searches for the data associated with Collider objects that are found in the specified area. If repeated data items are found, they are omitted. Intersection is performed with node surfaces (polygons). Depending on the variables passed as the first and the second arguments, the intersection area can be:
  • vec3 and vec3 — search is performed within the bounding box. Variables set the points of the bounding box minimum and maximum (by x, y, and z axes), respectively.
  • vec3 and float — search is performed within the bounding sphere. Variables set the sphere center and its radius, respectively.
  • mat4 and mat4 — search is performed within the view frustum. Variables set projection and modelview matrices, respectively.
World space coordinates are used for this function.
Notice
You may want to call updateSpatial() before finding collisions.

Arguments

  • variable p0 - First variable.
  • variable p1 - Second variable.
  • int ret_id - ID of the return array with data associated with the found objects.

Return value

Number of unique found data items (i.e. elements in the return array).

int engine.world.getCollisionObjects (variable p0, variable p1, int ret_id)

Searches only for Collider objects that are found in the specified area. Intersection is performed with node surfaces (polygons). Depending on the variables passed as the first and the second arguments, the intersection area can be:
  • vec3 and vec3 — search is performed within the bounding box. Variables set the points of the bounding box minimum and maximum (by x, y, and z axes), respectively.
  • vec3 and float — search is performed within the bounding sphere. Variables set the sphere center and its radius, respectively.
  • mat4 and mat4 — search is performed within the view frustum. Variables set projection and modelview matrices, respectively.
World space coordinates are used for this function.
Notice
You may want to call updateSpatial() before finding collisions.

Arguments

  • variable p0 - First variable.
  • variable p1 - Second variable.
  • int ret_id - ID of the return array of objects.

Return value

The number of 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.getIntersectionNodesVariable (variable p0, variable p1, int type, int ret[])

Searches for the data associated with all Nodes (or filtered by type) that are found in the specified area. If repeated data items are found, they are omitted. Intersection is performed with node surfaces (polygons). Depending on the variables passed as the first and the second arguments, the intersection area can be:
  • vec3 and vec3 — search is performed within the bounding box. Variables set the points of the bounding box minimum and maximum (by x, y, and z axes), respectively.
  • vec3 and float — search is performed within the bounding sphere. Variables set the sphere center and its radius, respectively.
  • mat4 and mat4 — search is performed within the view frustum. Variables set projection and modelview matrices, respectively.
World space coordinates are used for this function.
Notice
You may want to call updateSpatial() before finding intersections.

Arguments

  • variable p0 - First variable.
  • variable p1 - Second variable.
  • int type - Node type filter (one of the NODE_* variables), -1 not to use a filter.
  • int ret[] - An array, into which the result will be placed.

Return value

Number of unique found data items (i.e. elements in the return array with nodes' data).

int engine.world.getIntersectionNodes (variable p0, variable p1, int type, int ret[])

Searches for all the Nodes (or filtered by type) that are found in the specified area. Intersection is performed with nodes surfaces (polygons). Depending on the variables passed as the first and the second arguments, the intersection area can be:
  • vec3 and vec3 — search is performed within the bounding box. Variables set the points of the bounding box minimum and maximum (by x, y, and z axes), respectively.
  • vec3 and float — search is performed within the bounding sphere. Variables set the sphere center and its radius, respectively.
  • mat4 and mat4 — search is performed within the view frustum. Variables set projection and modelview matrices, respectively.
World space coordinates are used for this function.
Notice
You may want to call updateSpatial() before finding intersections.

Arguments

  • variable p0 - First variable.
  • variable p1 - Second variable.
  • int type - Node type filter (one of the NODE_* variables), -1 not to use a filter.
  • int ret[] - An array, into which the result will be placed.

Return value

Number of found nodes.

int engine.world.getIntersectionObjectsVariable (variable p0, variable p1, int ret[])

Searches for the data associated with all Objects that are found in the specified area. If repeated data items are found, they are omitted. Intersection is performed with object surfaces (polygons). Depending on the variables passed as the first and the second arguments, the area can be:
  • vec3 and vec3 — search is performed within the bounding box. Variables set the points of the bounding box minimum and maximum (by x, y, and z axes), respectively.
  • vec3 and float — search is performed within the bounding sphere. Variables set the sphere center and its radius, respectively.
  • mat4 and mat4 — search is performed within the view frustum. Variables set projection and modelview matrices, respectively.
World space coordinates are used for this function.
Notice
You may want to call updateSpatial() before finding intersections.

Arguments

  • variable p0 - First variable.
  • variable p1 - Second variable.
  • int ret[] - An array, into which the result will be placed.

Return value

Number of unique found data items (i.e. elements in the return array with objects' data).

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

Searches for all the Objects that are found in the specified area. Intersection is performed with object surfaces (polygons). Depending on the variables passed as the first and the second arguments, the intersection area can be:
  • vec3 and vec3 — search is performed within the bounding box. Variables set the points of the bounding box minimum and maximum (by x, y, and z axes), respectively.
  • vec3 and float — search is performed within the bounding sphere. Variables set the sphere center and its radius, respectively.
  • mat4 and mat4 — search is performed within the view frustum. Variables set projection and modelview matrices, respectively.
World space coordinates are used for this function.
Notice
You may want to call updateSpatial() before finding intersections.

Arguments

  • variable p0 - First variable.
  • variable p1 - Second variable.
  • int ret[] - An array, into which the result will be placed.

Return value

A list of the found objects.

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

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.

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 has an assigned material.
  4. A surface has an assigned property.
  5. A surface is enabled.
Notice
You may need to call updateSpatial() before finding intersections.

Arguments

  • vec3 p0 - Start point coordinates.
  • vec3 p1 - End point coordinates.
  • int ret[] - An array, into which the result will be placed.

Return value

A list of objects, intersecting the line, if found; otherwise - 0.

Object engine.world.getIntersection (vec3 p0, vec3 p1, int mask, int ret[])

Performs tracing from the p0 point to the p1 point to find the first object 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 mask.

An intersection 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 has an assigned material.
  4. A surface has an assigned property.
  5. A surface is enabled.
Notice
You may need to call updateSpatial() before finding intersections.

Arguments

  • vec3 p0 - Start point coordinates.
  • vec3 p1 - End point coordinates.
  • int mask - Intersection mask.
  • int ret[] - A type of the array, into which the result will be placed. Available values:
    • ret[0]: coordinates of the intersection point (vec3), in the world coordinates
    • ret[1]: a normal of the intersection point (vec3)
    • ret[2]: texture coordinates of the intersection point (vec4, where vec4.xy is for first UV channel, vec4.zw is for second UV channel)
    • ret[3]: the intersected surface number

Return value

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

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

Performs tracing from the p0 point to the p1 point to find the first object 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 mask. A list of objects can be specified to be skipped while checking for an intersection.

An intersection 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 has an assigned material.
  4. A surface has an assigned property.
  5. A surface is enabled.
Notice
You may need to call updateSpatial() before finding intersections.

Arguments

  • vec3 p0 - Start point coordinates.
  • vec3 p1 - End point coordinates.
  • int mask - Intersection mask.
  • int exclude[] - A list of the objects IDs to exclude.
  • int ret[] - A type of the array, into which the result will be placed. Available values:
    • ret[0]: coordinates of the intersection point (vec3), in the world coordinates
    • ret[1]: a normal of the intersection point (vec3)
    • ret[2]: texture coordinates of the intersection point (vec4, where vec4.xy is for first UV channel, vec4.zw is for second UV channel)
    • ret[3]: the intersected surface number

Return value

A 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 num)

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 num - 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, float weight)

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)

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.

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, int binary)

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, int binary)

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.

Arguments

  • float budget - The budget value in milliseconds.

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