engine.world Functions

World Class

Members

void setUnpackNodeReferences ( int references ) #

Arguments

• int references - The automatic unpacking of Node References at run time

int isUnpackNodeReferences() const#

Return value

Current automatic unpacking of Node References at run time

void setAutoReloadNodeReferences ( int references ) #

Arguments

• int references - The automatic reloading of Node References

int isAutoReloadNodeReferences() const#

Return value

Current automatic reloading of Node References

void setUpdateGridSize ( float size ) #

Arguments

• float size - The grid size, in units. The default value is 1000 units.

float getUpdateGridSize() const#

Return value

Current grid size, in units. The default value is 1000 units.

void setDistance ( float distance ) #

Arguments

• float distance - The distance at which (and farther) nothing will be rendered or simulated, in units.

float getDistance() const#

Return value

Current distance at which (and farther) nothing will be rendered or simulated, in units.

void setBudget ( float budget ) #

Arguments

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

float getBudget() const#

Return value

Current budget value in seconds. The default value is 1/60.

int isLoaded() const#

Return value

Current the world is fully loaded

void setScriptName ( string name ) #

Arguments

• string name - The name of the world script *.usc file.

string getScriptName() const#

Return value

Current name of the world script *.usc file.

void setPath ( string path ) #

Arguments

• string path - The path to the *.world-file where the world is stored.

string getPath() const#

Return value

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

void setScriptExecute ( int execute ) #

Arguments

• int execute - The a logic script associated with the world is to be loaded with it

int isScriptExecute() const#

Return value

Current a logic script associated with the world is to be loaded with it

void setPhysicsSettings ( string settings ) #

Arguments

• string settings - The name of the *.physics file containing default physics settings used by the World.

string getPhysicsSettings() const#

Return value

Current name of the *.physics file containing default physics settings used by the World.

void setSoundSettings ( string settings ) #

Arguments

• string settings - The name of the *.sound file containing default sound settings used by the World.

string getSoundSettings() const#

Return value

Current name of the *.sound file containing default sound settings used by the World.

void setRenderSettings ( string settings ) #

Arguments

• string settings - The name of the *.render file containing default render settings used by the World.

string getRenderSettings() const#

Return value

Current name of the *.render file containing default render settings used by the World.

string getLoadWorldRequestPath() const#

Return value

Current path to the world to be loaded.

int isLoadWorldRequested() const#

Return value

Current another world is going to be loaded in the next frame

void setMovingImmovableNodeMode ( ) #

Arguments

• mode - The handling mode for attempts to move nodes having the Immovable flag enabled. One of the following values:
  • 0 - movement of nodes having the Immovable flag is prohibited.
  • 1 - movement of nodes having the Immovable flag is accompanied by a warning in the Console. (by default)
  • 2 - movement of nodes having the Immovable flag is allowed (no warnings displayed).

getMovingImmovableNodeMode() const#

Return value

Current handling mode for attempts to move nodes having the Immovable flag enabled. One of the following values:

• 0 - movement of nodes having the Immovable flag is prohibited.
• 1 - movement of nodes having the Immovable flag is accompanied by a warning in the Console. (by default)
• 2 - movement of nodes having the Immovable flag is allowed (no warnings displayed).

static getEventNodeRemoved() const#

The event handler signature is as follows: myhandler()

Return value

Event reference.

static getEventNodeAdded() const#

The event handler signature is as follows: myhandler()

Return value

Event reference.

static getEventPostWorldShutdown() const#

The event handler signature is as follows: myhandler()

Return value

Event reference.

static getEventPreWorldShutdown() const#

The event handler signature is as follows: myhandler()

Return value

Event reference.

static getEventPostWorldInit() const#

The event handler signature is as follows: myhandler()

Return value

Event reference.

static getEventPreWorldInit() const#

The event handler signature is as follows: myhandler()

Return value

Event reference.

static getEventPostNodeSave() const#

The event handler signature is as follows: myhandler()

Return value

Event reference.

static getEventPreNodeSave() const#

The event handler signature is as follows: myhandler()

Return value

Event reference.

static getEventPostWorldClear() const#

The event handler signature is as follows: myhandler()

Return value

Event reference.

static getEventPreWorldClear() const#

The event handler signature is as follows: myhandler()

Return value

Event reference.

static getEventPostWorldSave() const#

The event handler signature is as follows: myhandler()

Return value

Event reference.

static getEventPreWorldSave() const#

The event handler signature is as follows: myhandler()

Return value

Event reference.

static getEventPostWorldLoad() const#

The event handler signature is as follows: myhandler()

Return value

Event reference.

static getEventPreWorldLoad() const#

The event handler signature is as follows: myhandler()

Return value

Event reference.

---

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.

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.

int engine.world.getCollisionObjects ( Variable v, Variable value ) #

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.
• Variable value - 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:

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

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, Variable value ) #

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.
• Variable value - 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:

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

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 name, string data ) #

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

Arguments

• string name - String containing a key identifying user data to be stored in the *.world file.
  Notice

  The "editor_data" key is reserved for the UnigineEditor.
• string data - New user data.

string engine.world.getData ( string name ) #

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

Arguments

• string name - String containing a key identifying user data stored in the *.world file.
  Notice

  The "editor_data" key is reserved for the UnigineEditor.

Return value

User string data.

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, vec3 mask, int[] exclude, Variable value ) #

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

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

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

Arguments

• vec3 p0 - Coordinates of the line start point.
• vec3 p1 - Coordinates of the line end point.
• vec3 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:

1. The surface is enabled.
2. Per-surface Intersection flag is enabled.
3. 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

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.

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:

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

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, Variable value ) #

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.
• Variable value - 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:

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

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. The world is not loaded immediately — loading starts at the beginning of the next frame, while the current world is unloaded at the end of the current frame.

Arguments

• string path - Path to the file describing the world.

Return value

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

int engine.world.loadWorld ( string path, int partial_path ) #

Loads a world from the specified file path and replaces the current world with it. The world is not loaded immediately — loading starts at the beginning of the next frame, while the current world is unloaded at the end of the current frame.

Arguments

• string path - Path to the file describing the world.
• int partial_path - 1 if the path to the world file is partial; or 0 if it is a full path.

Return value

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

int engine.world.loadWorldForce ( string path ) #

Loads a world from the specified file path and replaces the current world with it. The world is loaded immediately, breaking the Execution Sequence, therefore should be used either before Engine::update() or after Engine::swap(). If called in Engine::update(), the Execution Sequence will be as follows: update() before calling loadWorldForce(), loadWorldForce(), shutdown(), continuation of update() from the place of interruption, postUpdate(), swap(), init(), etc. This function is recommended for the Editor-related use.

Arguments

• string path - Path to the file describing the world.

Return value

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

int engine.world.loadWorldForce ( string path, int partial_path ) #

Loads a world from the specified file path and replaces the current world with it. The world is loaded immediately, breaking the Execution Sequence, therefore should be used either before Engine::update() or after Engine::swap(). If called in Engine::update(), the Execution Sequence will be as follows: update() before calling loadWorldForce(), loadWorldForce(), shutdown(), continuation of update() from the place of interruption, postUpdate(), swap(), init(), etc. This function is recommended for the Editor-related use.

Arguments

• string path - Path to the file describing the world.
• int partial_path - 1 if the path to the world file is partial; or 0 if it is a full path.

Return value

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

int engine.world.saveWorld ( ) #

Saves the World.

Return value

1, if the world has been saved successfully; otherwise 0.

int engine.world.saveWorld ( string path ) #

Saves the world to the specified location.

Arguments

• string path - Path to where the world is going to be saved.

Return value

1, if the world has been saved successfully; otherwise 0.

int engine.world.reloadWorld ( ) #

Reloads the World.

Return value

1, if the world has been reloaded successfully; otherwise 0.

int engine.world.quitWorld ( ) #

Closes the World.

Return value

1, if the world has been quit successfully; 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.

bool 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 ( ) #

Collects all instances of all nodes (either loaded from the *.world file or created dynamically at run time), including cache, Node Reference internals, etc. and puts them to the specified output list.

Arguments

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.

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

Arguments

• string name - Path to the *.node file.

Return value

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

engine.world.loadNode ( int cache = 1 ) #

Loads a node (or a hierarchy of nodes) from a .node / .fbx file. If the node is loaded successfully, it is managed by the current world (its Lifetime is World).

Cached nodes remain in the memory. If you don't intend to load more node references from a certain .node asset, set the cache argument to 0 or you can delete cached nodes from the list of world nodes afterwards by using the clearNode() method.

Arguments

• int cache - 1 to use caching of nodes, 0 not to use.

Return value

Loaded node; NULL if the node cannot be loaded.

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.

Node engine.world.getNodeByID ( int node_id ) #

Returns a node by its identifier if it exists.

Arguments

• int node_id - Node ID.

Return value

Node engine.world.getNodeByName ( string name ) #

Returns a node by its name if it exists. If the world contains multiple nodes having the same name, only the first one found shall be returned. To get all nodes having the same name, use the getNodesByName() method.

Arguments

• string name - Node name.

Return value

Node engine.world.getNodeByType ( int type ) #

Returns the first node of the specified type in the World. Hidden and system nodes are ignored.

Arguments

• int type - Node type identifier, one of the NODE_* values.

Return value

void engine.world.clearBindings ( ) #

Clears internal buffers with pointers and instances. This function is used for proper cloning of objects with hierarchies, for example, bodies and joints. Should be called before cloning.

int engine.world.getRootNodeIndex ( Node node ) #

Returns the index for the specified root node, that belongs to the world hierarchy.

Arguments

• Node node - Root node, for which an index is to be obtained.

Return value

Index of the specified root node if it exists; otherwise, -1.

void engine.world.setRootNodeIndex ( Node node, int index ) #

Sets a new index for the specified root node, that belongs to the world hierarchy.

Arguments

• Node node - Root node, for which a new index is to be set.
• int index - New index to be set for the specified root node.

void engine.world.setNodeIdSeed ( unsigned int seed ) #

Sets a seed value for random generation of a node ID. This method is used for deterministic generation.

Arguments

• unsigned int seed - A seed value.

void engine.world.setNodeIdRange ( int from, int to ) #

Sets a range for random generation of a node ID. This method can be used, for example, to generate IDs for nodes divided in several groups: within a group, IDs will be generated in a separate range.

Arguments

• int from - Beginning of the range.
• int to - End of the range.