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.
Loading of nodes on demand is managed via the engine.async Class.
See also
- engine.async Class to manage loading nodes and other resources on demand.
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.Return value
1 if automatic reloading of NodeReferences is enabled; otherwise, 0.void engine.world.setAutoReloadNodeReferences(int val)
Enables automatic reloading of NodeReferences. If enabled all NodeReference nodes will reload their *.node files, when the saveNode() method is called.Arguments
- int val - 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).
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.
Collision with the surface can be found only if the following conditions are fulfilled:
- A per-surface Collision flag is enabled.
- An Collision option of the property in the Properties window is enabled.
- A surface is enabled.
- A surface has an assigned material.
- 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 - 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.
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:
- A per-surface Collision flag is enabled.
- An Collision option of the property in the Properties window is enabled.
- A surface is enabled.
- A surface has an assigned material.
- 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 - 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:
- A per-surface Intersection flag is enabled.
- An Intersection option of the property in the Properties window is enabled.
- A surface is enabled.
- A surface has an assigned material.
- 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.
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:
- A per-surface Intersection flag is enabled.
- An Intersection option of the property in the Properties window is enabled.
- A surface is enabled.
- A surface has an assigned material.
- 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.
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.
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.
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).
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:
- A per-surface Intersection flag is enabled.
- An Intersection option of the property in the Properties window is enabled.
- A surface is enabled.
- A surface has an assigned material.
- 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 - 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).
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:
- A per-surface Intersection flag is enabled.
- An Intersection option of the property in the Properties window is enabled.
- A surface is enabled.
- A surface has an assigned material.
- 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 - Array into which the result will be placed.
Return value
Number of nodes found.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.setName(string name)
Assigns a new name to an editable world.Arguments
- string name - Name of the world.
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.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.setScriptName(string name)
Sets the name of the world script file *.cpp.Arguments
- string name - Name of the world script file *.cpp.
string engine.world.getScriptName()
Returns the name of the world script file *.cpp.Return value
Name of the world script file *.cpp.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.Arguments
- int id - Node ID.
Return value
Requested node, if found (NULL otherwise).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(Vector<Node> & nodes)
Gets all of the nodes (either loaded from the *.world file or created dynamically in run-time).Arguments
- Vector<Node> & nodes - Return array with node smart pointers.
int engine.world.getNumUpdateNodes()
Returns the number of currently updating nodes in the world.Return value
Number of updating nodes.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.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.void engine.world.addUpdateNode(Node node)
Adds a node that should be updated even if it is outside of the viewing frustum. This function should be called every frame.Arguments
- Node node - Node to be updated.
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.Arguments
- Variable function - Name of the function to execute.
Return value
Value returned by the function.Variable engine.world.call(Variable function, Variable arg0)
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 arg0 - 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.call(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.clearNode(string name)
Clears a cache of the given NodeReference.Arguments
- string name - File with the node.
Return value
1 if the cache was successfully cleaned; otherwise, 0.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.