engine.world Functions

WarningUnigineScript is deprecated and will be removed in future releases. Please consider using C#/C++ instead, as these APIs are the preferred ones. Availability of new Engine features in UnigineScipt is not guaranteed, as the current level of support assumes only fixing critical issues.

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.

Loading of nodes on demand is managed via the engine.async Class.

Notice

C++ methods running editor script functions are described in the Engine class reference.

Methods:

Name	Description View: Sort by:
isAutoReloadNodeReferences	Returns a value indicating if automatic reloading of NodeReferences is enabled.
setAutoReloadNodeReferences	Enables automatic reloading of NodeReferences.
setBudget	Sets the world generation budget value for Grass and Clutter objects.
getBudget	Returns the value of the world generation budget for Grass and Clutter objects.
setData	Sets user data associated with the world.
getData	Returns user string data associated with the world.
setDistance	Updates the distance, at which (and farther) nothing will be rendered or simulated.
getDistance	Returns a distance, at which (and farther) nothing will be rendered or simulated.
isLoaded	Returns a value indicating if the current world is fully loaded.
setPath	Sets the path to the *.world-file where the world is stored.
getPath	Returns the current path to the *.world-file where the world is stored.
setScriptName	Sets the name of the world script file *.usc.
getScriptName	Returns the name of the world script file *.usc.
setUnpackNodeReferences	Enables or disables automatic unpacking of node references at run time.
isUnpackNodeReferences	Returns the value indicating if automatic unpacking of node references at run time is enabled.
setUpdateGridSize	Sets the size of the grid to be used for spatial tree update.
getUpdateGridSize	Returns the current size of the grid to be used for spatial tree update.
set	Set a variable in a world script (this function can be called directly from any other script).
get	Returns a variable from the world script.
getCollisionObjects	Searches for all collider objects within a given bounding volume.
getCollisionObjectVariables	Searches for all collider objects which have set user variables.
isFunction	Returns a value indicating if the given function with the specified number of arguments exists in the world script.
getIntersection	Performs tracing from the p0 point to the p1 point to find the list of objects intersecting the line.
getIntersectionNodes	Searches for all nodes (or nodes filtered by type) within a given bounding volume.
getIntersectionNodeVariables	Searches for all nodes (or nodes filtered by type) which have set user variables.
getIntersectionObjects	Searches for all objects within a given bounding volume.
getIntersectionObjectVariables	Searches for the data associated with all objects (or objects filtered by type) within a given bounding volume.
loadWorld	Loads a world from the specified file path and replaces the current world with it.
setPhysicsSettings	Sets the name of the *.physics file containing default physics settings to be used for the world.
getPhysicsSettings	Returns the name of the *.physics file containing default physics settings currently used by the world.
setRenderSettings	Sets the name of the *.render file containing default render settings to be used for the world.
getRenderSettings	Returns the name of the *.render file containing default render settings currently used by the world.
setSoundSettings	Sets the name of the *.sound file containing default sound settings to be used for the world.
getSoundSettings	Returns the name of the *.sound file containing default sound settings currently used by the world.
isNode	Checks if a node with a given ID exists in the world.
getNodes	Returns all instances of all nodes (either loaded from the *.world file or created dynamically at run time), including cache, Node Reference internals, etc.
isVariable	Returns a value indicating if the given variable exists in the world script.
addWorld	Loads a world from a file and adds it to the current world.
call	Executes a function of the world script from an external script.
clearNode	Clears a cache of the given NodeReference.
updateSpatial	Updates the node BSP (binary space partitioning) tree.
setScriptExecute	Sets a value indicating if a logic script associated with the world is to be loaded with it.
isScriptExecute	Returns a value indicating if a logic script associated with the world is to be loaded with it.
getNodeById	Returns a node by its identifier if it exists.
getNodeByName	Returns a node by its name if it exists.
clearBindings	Clears internal buffers with pointers and instances.
getRootNodeIndex	Returns the index for the specified root node, that belongs to the world hierarchy.
setRootNodeIndex	Sets a new index for the specified root node, that belongs to the world hierarchy.

World Class

Members

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

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

Arguments

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

int engine.world.isAutoReloadNodeReferences ( ) #

Returns a value indicating if automatic reloading of NodeReferences is enabled. If enabled all NodeReference nodes will reload their *.node files, when the saveNode() method is called.

Notice

This option can be used if you modify and save reference nodes at runtime. Otherwise you'll have to manually update pointers for all NodeReferences referring to the changed node.

Return value

1 if automatic reloading of NodeReferences is enabled; otherwise, 0.

void engine.world.setAutoReloadNodeReferences ( int references ) #

Enables automatic reloading of NodeReferences. If enabled all NodeReference nodes will reload their *.node files, when the saveNode() method is called.

Notice

This option can be used if you modify and save reference nodes at runtime. Otherwise you'll have to manually update pointers for all NodeReferences referring to the changed node.

Arguments

int references - 1 to enable automatic reloading of NodeReferences; 0 - to disable it. The default value is 0.

Variable engine.world.get ( string function ) #

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

Arguments

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

Return value

Requested instance.

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.

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.getCollisionObjects ( Variable v, int[] ret ) #

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

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.

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 - Array into which the result will be placed.

Return value

Number of nodes found.

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.

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

The surface is enabled.
Per-surface Collision flag is enabled.
The surface has a material assigned.

Notice

Arguments

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

Return value

Number of nodes found.

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.

Notice

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 - Array into which the result will be placed.

Return value

Number of nodes found.

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.

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

The surface is enabled.
Per-surface Collision flag is enabled.
The surface has a material assigned.

Notice

Arguments

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

Return value

Number of nodes found.

void engine.world.setData ( string data ) #

Sets user data associated with the world. In the *.world file, the data is set in the data tag.

Arguments

string data - New user data.

string engine.world.getData ( ) #

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

Return value

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

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.isFunction ( string name, int num_args ) #

Returns a value indicating if the given function with the specified number of arguments exists in the world script.

Arguments

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

Return value

1 if the function exists; otherwise, 0.

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:

The surface is enabled.
Per-surface Intersection flag is enabled.
The surface has a material assigned.

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

The first intersected object, if found; otherwise, 0.

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:

The surface is enabled.
Per-surface Intersection flag is enabled.
The surface has a material assigned.

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

The first intersected object, if found; otherwise, 0.

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.

Notice

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 - Node type (one of the NODE_* variables); -1 is not to use a filter.
int[] ret - Array into which the result will be placed.

Return value

Number of nodes found.

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.

Notice

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 - Node type (one of the NODE_* variables); -1 is not to use a filter.
int[] ret - Array into which the result will be placed.

Return value

Number of nodes found.

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

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

Notice

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 - Array into which the result will be placed.

Return value

Number of nodes found.

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:

The surface is enabled.
Per-surface Intersection flag is enabled.
The surface has a material assigned.

Notice

Arguments

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

Return value

Number of nodes found.

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

Notice

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 - Array into which the result will be placed.

Return value

Number of nodes found.

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:

The surface is enabled.
Per-surface Intersection flag is enabled.
The surface has a material assigned.

Notice

Arguments

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

Return value

Number of nodes found.

int engine.world.loadWorld ( string path ) #

Loads a world from the specified file path and replaces the current world with it.

Arguments

string path - Path to the file describing the world.

Return value

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

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.

void engine.world.setPath ( string path ) #

Sets the path to the *.world-file where the world is stored.

Arguments

string path - Path to the *.world-file.

string engine.world.getPath ( ) #

Returns the current path to the *.world-file where the world is stored.

Return value

Path to the *.world-file.

void engine.world.setPhysicsSettings ( string settings ) #

Sets the name of the *.physics file containing default physics settings to be used for the world.

Arguments

string settings - Name of the default *.physics asset to be used for the world.

string engine.world.getPhysicsSettings ( ) #

Returns the name of the *.physics file containing default physics settings currently used by the world.

Return value

Name of the default *.physics asset used for the world.

void engine.world.setRenderSettings ( string settings ) #

Sets the name of the *.render file containing default render settings to be used for the world.

Arguments

string settings - Name of the default *.render asset to be used for the world.

string engine.world.getRenderSettings ( ) #

Returns the name of the *.render file containing default render settings currently used by the world.

Return value

Name of the default *.render asset used for the world.

void engine.world.setSoundSettings ( string settings ) #

Sets the name of the *.sound file containing default sound settings to be used for the world.

Arguments

string settings - Name of the default *.sound asset to be used for the world.

string engine.world.getSoundSettings ( ) #

Returns the name of the *.sound file containing default sound settings currently used by the world.

Return value

Name of the default *.sound asset used for the world.

void engine.world.setScriptName ( string name ) #

Sets the name of the world script file *.usc.

Arguments

string name - Name of the world script file *.usc.

string engine.world.getScriptName ( ) #

Returns the name of the world script file *.usc.

Return value

Name of the world script file *.usc.

int engine.world.isNode ( int id ) #

Checks if a node with a given ID exists in the world.

Arguments

int id - Node ID.

Return value

1 if the node with the given ID exists; otherwise, 0.

void engine.world.getNodes ( Node[] nodes ) #

Returns all instances of all nodes (either loaded from the *.world file or created dynamically at run time), including cache, Node Reference internals, etc.

Notice

If you need only root nodes to be returned, use getRootNodes() instead

Arguments

Node[] nodes - Array with node smart pointers.

int engine.world.isVariable ( string name ) #

Returns a value indicating if the given variable exists in the world script.

Arguments

string name - Variable name.

Return value

1 if the variable exists; otherwise, 0.

int engine.world.addWorld ( string name ) #

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

Arguments

string name - Name of the file describing the world.

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.