Unigine.World Class
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 AsyncQueue Class.
See also#
- AsyncQueue Class to manage loading nodes and other resources on demand.
- The Intersections article demonstrating how to use intersection-related functions
World Class
Enums
CALLBACK_INDEX#
Properties
bool UnpackNodeReferences#
bool AutoReloadNodeReferences#
float UpdateGridSize#
float Distance#
float Budget#
string Data#
bool IsLoaded#
string ScriptName#
string Path#
bool ScriptExecute#
string PhysicsSettings#
string SoundSettings#
string RenderSettings#
string LoadWorldRequestPath#
bool IsLoadWorldRequested#
Members
bool GetCollision ( WorldBoundBox bb, Object[] objects ) #
Searches for all collider objects within a given bounding box.Arguments
- WorldBoundBox bb - Bounding box.
- Object[] objects - Array with collider objects' smart pointers.
Return value
1 if collider objects are found; otherwise, 0.bool GetCollision ( WorldBoundSphere bs, Object[] objects ) #
Searches for all collider objects within a given bounding sphere.Arguments
- WorldBoundSphere bs - Bounding sphere.
- Object[] objects - Array with collider objects' smart pointers.
Return value
1 if collider objects are found; otherwise, 0.bool GetCollision ( vec3 p0, vec3 p1, Object[] objects ) #
Performs tracing from the p0 point to the p1 point to find all collider objects intersected by 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.
Arguments
- vec3 p0 - The start point coordinates.
- vec3 p1 - The end point coordinates.
- Object[] objects - Array with collider objects' smart pointers.
Return value
1 if collider objects are found; otherwise, 0.Object GetIntersection ( vec3 p0, vec3 p1, int mask ) #
Performs tracing from the p0 point to the p1 point to find the first object intersected by the line. This function detects intersection with surfaces (polygons) of meshes. An intersection can be found only if an object has a matching 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 - Line start point coordinates.
- vec3 p1 - Line end point coordinates.
- int mask - Intersection mask. If 0 is passed, the function will return NULL.
Return value
Intersected object.Object GetIntersection ( vec3 p0, vec3 p1, int mask, Node[] exclude ) #
Performs tracing from the p0 point to the p1 point to find the first object intersected by the line (except for the ones passed in the exclude list). This function detects intersection with surfaces (polygons) of meshes. An intersection can be found only if an object has a matching 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 - Line start point coordinates.
- vec3 p1 - Line end point coordinates.
- int mask - Intersection mask. If 0 is passed, the function will return NULL.
- Node[] exclude - List of nodes to be ignored when searching for intersection by the traced line.
Return value
The first intersected object found at the line (except for the ones passed in the exclude list); nullptr if there was no intersection.Object GetIntersection ( vec3 p0, vec3 p1, int mask, WorldIntersection intersection ) #
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 meshes. An intersection can be 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.
- WorldIntersection intersection - WorldIntersection object to be filled.
Return value
First intersected object.Object GetIntersection ( vec3 p0, vec3 p1, int mask, WorldIntersectionNormal intersection ) #
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 meshes. An intersection can be 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.
- WorldIntersectionNormal intersection - WorldIntersectionNormal object to be filled.
Return value
First intersected object.Object GetIntersection ( vec3 p0, vec3 p1, int mask, WorldIntersectionTexCoord intersection ) #
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 meshes. An intersection can be 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.
- WorldIntersectionTexCoord intersection - WorldIntersectionTexCoord object to be filled.
Return value
First intersected object.Object GetIntersection ( vec3 p0, vec3 p1, int mask, Node[] exclude, WorldIntersection intersection ) #
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 meshes. An intersection can be 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.
- Node[] exclude - The list of nodes to be excluded.
- WorldIntersection intersection - WorldIntersection object to be filled.
Return value
First intersected object.Object GetIntersection ( vec3 p0, vec3 p1, int mask, Node[] exclude, WorldIntersectionNormal intersection ) #
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 meshes. An intersection can be 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.
- Node[] exclude - The list of nodes to be excluded.
- WorldIntersectionNormal intersection - WorldIntersectionNormal object to be filled.
Return value
First intersected object.Object GetIntersection ( vec3 p0, vec3 p1, int mask, Node[] exclude, WorldIntersectionTexCoord intersection ) #
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 meshes. An intersection can be 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.
- Node[] exclude - The list of nodes to be excluded.
- WorldIntersectionTexCoord intersection - WorldIntersectionTexCoord object to be filled.
Return value
First intersected object.bool GetIntersection ( vec3 p0, vec3 p1, Object[] objects ) #
Performs tracing from the p0 point to the p1 point to find objects intersected by the line. This function detects intersection with objects' bounds.
Arguments
- vec3 p0 - Coordinates of the line start point.
- vec3 p1 - Coordinates of the line end point.
- Object[] objects - Array of intersected objects.
Return value
1 if intersections are found; otherwise, 0.bool GetIntersection ( WorldBoundBox bb, Object[] objects ) #
Searches for intersections with objects that are found in a given bounding box.
Arguments
- WorldBoundBox bb - Bounding box where intersection search will be performed.
- Object[] objects - Array of intersected objects.
Return value
1 if intersections are found; otherwise, 0.bool GetIntersection ( WorldBoundSphere bs, Object[] objects ) #
Searches for intersections with objects that are found in a given bounding sphere.
Arguments
- WorldBoundSphere bs - Bounding sphere where intersection search will be performed.
- Object[] objects - Array of intersected objects.
Return value
1 if intersections are found; otherwise, 0.bool GetIntersection ( WorldBoundFrustum bf, Object[] objects ) #
Searches for intersections with objects that are found in a given bounding frustum.
Arguments
- WorldBoundFrustum bf - Bounding frustum where intersection search will be performed.
- Object[] objects - Array of intersected objects.
Return value
1 if intersections are found; otherwise, 0.bool GetIntersection ( WorldBoundBox bb, Node[] nodes ) #
Searches for intersections with nodes that are found in a given bounding box.
Arguments
- WorldBoundBox bb - Bounding box where intersection search will be performed.
- Node[] nodes - Array of intersected nodes.
Return value
1 if intersections are found; otherwise, 0.bool GetIntersection ( WorldBoundSphere bs, Node[] nodes ) #
Searches for intersections with nodes that are found in a given bounding sphere.
Arguments
- WorldBoundSphere bs - Bounding sphere where intersection search will be performed.
- Node[] nodes - Array of intersected nodes.
Return value
1 if intersections are found; otherwise, 0.bool GetIntersection ( WorldBoundBox bb, Node.TYPE type, Node[] nodes ) #
Searches for intersections with specified type of nodes that are found in a given bounding box.
Arguments
- WorldBoundBox bb - Bounding box where intersection search will be performed.
- Node.TYPE type - Node type filter. Only the nodes of the specified type will be checked.
- Node[] nodes - Array of intersected nodes.
Return value
1 if intersections are found; otherwise, 0.bool GetIntersection ( WorldBoundSphere bs, Node.TYPE type, Node[] nodes ) #
Searches for intersections with specified type of nodes that are found in a given bounding sphere.
Arguments
- WorldBoundSphere bs - Bounding sphere where intersection search will be performed.
- Node.TYPE type - Node type filter. Only the nodes of the specified type will be checked.
- Node[] nodes - Array of intersected nodes.
Return value
1 if intersections are found; otherwise, 0.bool GetIntersection ( WorldBoundFrustum bf, Node.TYPE type, Node[] nodes ) #
Searches for intersections with specified type of nodes that are found in a given bounding frustum.
Arguments
- WorldBoundFrustum bf - Bounding frustum where intersection search will be performed.
- Node.TYPE type - Node type filter. Only the nodes of the specified type will be checked.
- Node[] nodes - Array of intersected nodes.
Return value
1 if intersections are found; otherwise, 0.bool 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
true if the world is loaded successfully; otherwise, false.bool LoadWorld ( string path, bool 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.
- bool partial_path - true if the path to the world file is partial; or false if it is a full path.
Return value
true if the world is loaded successfully; otherwise, false.bool 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
true if the world is loaded successfully; otherwise, false.bool LoadWorldForce ( string path, bool 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.
- bool partial_path - true if the path to the world file is partial; or false if it is a full path.
Return value
true if the world is loaded successfully; otherwise, false.bool SaveWorld ( ) #
Saves the world.Return value
true, if the world has been saved successfully; otherwise false.bool 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
true, if the world has been saved successfully; otherwise false.bool ReloadWorld ( ) #
Reloads the world.Return value
true, if the world has been reloaded successfully; otherwise false.bool QuitWorld ( ) #
Closes the world.Return value
true, if the world has been quit successfully; otherwise false.bool IsLoadWorldRequested ( ) #
Returns a value indicating if another world is going to be loaded in the next frame.Return value
true, if another world is going to be loaded in the next frame.string GetLoadWorldRequestPath ( ) #
Returns the path to the world which is going to be loaded.Return value
Path to the world to be loaded.int 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.void 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 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 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 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 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 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.bool IsNode ( int id ) #
Checks if a node with a given ID exists in the world.Arguments
- int id - Node ID.
Return value
true if the node with the given ID exists; otherwise, false.void 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.Arguments
- Node[] nodes - Array with node smart pointers.
int ClearNode ( string name ) #
Clears cached nodes of the given node file.Arguments
- string name - Path to the *.node file.
Return value
1 if the cache is cleared successfully; otherwise, 0.Node LoadNode ( string name, 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).Caching of nodes is used to speed up loading process: a hidden copy of the loaded node (or a hierarchy of nodes) is added to the list of world nodes, thus enabling to simply get clones of cached nodes, instead of parsing the .node file and retrieving data once again.
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
- string name - Path to the *.node file.
- int cache - 1 to use caching of nodes, 0 not to use.
Return value
Loaded node; NULL if the node cannot be loaded.int LoadNodes ( string name, Node[] nodes ) #
Loads nodes from a file.Arguments
- string name - Path to the *.node file.
- Node[] nodes - Array of nodes' smart pointers to which the loaded nodes are appended.
Return value
1 if the nodes are loaded successfully; otherwise, 0.int SaveNode ( string name, Node node, int binary = 0 ) #
Saves a given node to a file with due regard for its local transformation.Arguments
- string name - Path to the *.node file.
- Node node - Pointer to the node to save.
- int binary - If set to 1, the node is saved to the binary *.xml. This file cannot be read, but using it speeds up the saving of the node and requires less disk space.
Return value
1 if the node is saved successfully; otherwise, 0.int SaveNodes ( string name, Node[] nodes, int binary = 0 ) #
Saves nodes to a file.Arguments
- string name - Path to the *.node file.
- Node[] nodes - Array of nodes' smart pointers to be saved.
- int binary - If set to 1, the node is saved to the binary *.xml. This file cannot be read, but using it speeds up the saving of the node and requires less disk space.
Return value
1 if the nodes are saved successfully; otherwise, 0.void 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.
void SetScriptExecute ( bool execute ) #
Sets a value indicating if a logic script associated with the world is to be loaded with it.Arguments
- bool execute - true - to load the world along with the associated logic script (if any), false - to ignore it.
bool IsScriptExecute ( ) #
Returns a value indicating if a logic script associated with the world is to be loaded with it.Return value
true if a logic script associated with the world is to be loaded with it; otherwise, false.Node GetNodeById ( int node_id ) #
Returns a node by its identifier if it exists.Arguments
- int node_id - Node ID.
Return value
Node, if it exists in the world; otherwise, null.Node 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, if it exists in the world; otherwise, null.void GetNodesByName ( string name, Node[] nodes ) #
Generates a list of nodes in the world with a given name and puts it to nodes.Arguments
- string name - Node name.
- Node[] nodes - List of nodes with the given name (if any); otherwise, null.
Node 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
First node of the specified type, if it exists in the world; otherwise, null.void GetNodesByType ( int type, Node[] nodes ) #
Generates a list of nodes of the specified type in the world and puts it to nodes. Hidden and system nodes are ignored.Arguments
- int type - Node type identifier, one of the NODE_* values.
- Node[] nodes - List of nodes of the given type (if any); otherwise, null.
bool IsNode ( string name ) #
Checks if a node with a given name exists in the world.Arguments
- string name - Node name.
Return value
true if a node with the specified name exists in the world; otherwise, false.void 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.void GetRootNodes ( Node[] nodes ) #
Gets all root nodes in the world hierarchy and puts them to nodes.Arguments
- Node[] nodes
int 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 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.
IntPtr AddCallback ( int callback, CallbackDelegate func ) #
Adds a callback of the specified type. Callback functions can be used to determine actions to be performed when the world is loaded, saved, or cleared. The signature of the callback function must be as follows:void callback_function_name(const char *world_path);
Arguments
- int callback - Callback type. One of the CALLBACK_* variables.
- CallbackDelegate func - Callback function with the following signature: void CallbackDelegate(string world_path)
Return value
ID of the last added callback of the specified type, if the callback was added successfully; otherwise, nullptr. This ID can be used to remove this callback when necessary.IntPtr AddCallback ( int callback, CallbackDelegate func ) #
Adds a callback of the specified type. This method adds a callback function to be used to determine actions to be performed when a node in the world is saved. The signature of the callback function must be as follows:void callback_function_name(const char *world_path, NodePtr node);
Arguments
- int callback - Callback type. One of the CALLBACK_* variables.
- CallbackDelegate func - Callback function with the following signature: void CallbackDelegate(string world_path, Node node)
Return value
ID of the last added callback of the specified type, if the callback was added successfully; otherwise, nullptr. This ID can be used to remove this callback when necessary.bool RemoveCallback ( int callback, IntPtr id ) #
Removes the specified callback from the list of callbacks of the specified type. Callback functions can be used to determine actions to be performed when the world is loaded, saved, or cleared.Arguments
- int callback - Callback type. One of the CALLBACK_* variables.
- IntPtr id - Callback ID obtained when adding it.
Return value
True if the callback with the given ID was removed successfully; otherwise false.void ClearCallbacks ( int callback ) #
Clears all added callbacks of the specified type. Callback functions can be used to determine actions to be performed when the world is loaded, saved, or cleared.Arguments
- int callback - Callback type. One of the CALLBACK_* variables.