Unigine::World Class
| Header: | #include <UnigineWorld.h> |
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.
Notice
C++ methods running editor script functions are described in the Engine class reference.
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#
Members
int 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 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.
void 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.
float 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. The default value is 1/60.int getCollision ( const Math::WorldBoundBox & bb, Vector< Ptr<Object> > & objects ) #
Searches for all collider objects within a given bounding box.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
- const Math::WorldBoundBox & bb - Bounding box.
- Vector< Ptr<Object> > & objects - Array with collider objects' smart pointers.
Return value
1 if collider objects are found; otherwise, 0.int getCollision ( const Math::WorldBoundSphere & bs, Vector< Ptr<Object> > & objects ) #
Searches for all collider objects within a given bounding sphere.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
- const Math::WorldBoundSphere & bs - Bounding sphere.
- Vector< Ptr<Object> > & objects - Array with collider objects' smart pointers.
Return value
1 if collider objects are found; otherwise, 0.int getCollision ( const Math::Vec3 & p0, const Math::Vec3 & p1, Vector< Ptr<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.
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
- const Math::Vec3 & p0 - The start point coordinates.
- const Math::Vec3 & p1 - The end point coordinates.
- Vector< Ptr<Object> > & objects - Array with collider objects' smart pointers.
Return value
1 if collider objects are found; otherwise, 0.void setData ( const char * name, const char * 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
- const char * name - String containing a key identifying user data to be stored in the *.world file.NoticeThe "editor_data" key is reserved for the UnigineEditor.
- const char * data - New user data.
const char * getData ( const char * 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
- const char * name - String containing a key identifying user data stored in the *.world file.NoticeThe "editor_data" key is reserved for the UnigineEditor.
Return value
User string data.void setDistance ( float distance ) #
Updates the distance, at which (and farther) nothing will be rendered or simulated.Arguments
- float distance - New distance in units.
float getDistance ( ) #
Returns a distance, at which (and farther) nothing will be rendered or simulated.Return value
Distance in units.Ptr<Object> getIntersection ( const Math::Vec3 & p0, const Math::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.
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
- const Math::Vec3 & p0 - Line start point coordinates.
- const Math::Vec3 & p1 - Line end point coordinates.
- int mask - Intersection mask. If 0 is passed, the function will return NULL.
Return value
Pointer to the first intersected object.Ptr<Object> getIntersection ( const Math::Vec3 & p0, const Math::Vec3 & p1, int mask, const Vector< Ptr<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.
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
- const Math::Vec3 & p0 - Line start point coordinates.
- const Math::Vec3 & p1 - Line end point coordinates.
- int mask - Intersection mask. If 0 is passed, the function will return NULL.
- const Vector< Ptr<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); otherwise, NULL pointer.Ptr<Object> getIntersection ( const Math::Vec3 & p0, const Math::Vec3 & p1, int mask, const Ptr<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.
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
- const Math::Vec3 & p0 - Coordinates of the line start point.
- const Math::Vec3 & p1 - Coordinates of the line end point.
- int mask - Intersection mask. If 0 is passed, the function will return NULL.
- const Ptr<WorldIntersection> & intersection - Pointer to the WorldIntersection object to be filled.
Return value
Pointer to the first intersected object.Ptr<Object> getIntersection ( const Math::Vec3 & p0, const Math::Vec3 & p1, int mask, const Ptr<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.
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
- const Math::Vec3 & p0 - Coordinates of the line start point.
- const Math::Vec3 & p1 - Coordinates of the line end point.
- int mask - Intersection mask. If 0 is passed, the function will return NULL.
- const Ptr<WorldIntersectionNormal> & intersection - Pointer to the WorldIntersectionNormal object to be filled.
Return value
Pointer to the first intersected object.Ptr<Object> getIntersection ( const Math::Vec3 & p0, const Math::Vec3 & p1, int mask, const Ptr<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.
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
- const Math::Vec3 & p0 - Coordinates of the line start point.
- const Math::Vec3 & p1 - Coordinates of the line end point.
- int mask - Intersection mask. If 0 is passed, the function will return NULL.
- const Ptr<WorldIntersectionTexCoord> & intersection - Pointer to the WorldIntersectionTexCoord object to be filled.
Return value
Pointer to the first intersected object.Ptr<Object> getIntersection ( const Math::Vec3 & p0, const Math::Vec3 & p1, int mask, const Vector< Ptr<Node> > & exclude, const Ptr<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.
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
- const Math::Vec3 & p0 - Coordinates of the line start point.
- const Math::Vec3 & p1 - Coordinates of the line end point.
- int mask - Intersection mask. If 0 is passed, the function will return NULL.
- const Vector< Ptr<Node> > & exclude - The list of nodes to be excluded.
- const Ptr<WorldIntersection> & intersection - Pointer to the WorldIntersection object to be filled.
Return value
Pointer to the first intersected object.Ptr<Object> getIntersection ( const Math::Vec3 & p0, const Math::Vec3 & p1, int mask, const Vector< Ptr<Node> > & exclude, const Ptr<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.
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
- const Math::Vec3 & p0 - Coordinates of the line start point.
- const Math::Vec3 & p1 - Coordinates of the line end point.
- int mask - Intersection mask. If 0 is passed, the function will return NULL.
- const Vector< Ptr<Node> > & exclude - The list of nodes to be excluded.
- const Ptr<WorldIntersectionNormal> & intersection - Pointer to the WorldIntersectionNormal object to be filled.
Return value
Pointer to the first intersected object.Ptr<Object> getIntersection ( const Math::Vec3 & p0, const Math::Vec3 & p1, int mask, const Vector< Ptr<Node> > & exclude, const Ptr<WorldIntersectionTexCoord> & intersection ) #
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 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.
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
- const Math::Vec3 & p0 - Coordinates of the line start point.
- const Math::Vec3 & p1 - Coordinates of the line end point.
- int mask - Intersection mask. If 0 is passed, the function will return NULL.
- const Vector< Ptr<Node> > & exclude - The list of nodes to be excluded.
- const Ptr<WorldIntersectionTexCoord> & intersection - Pointer to the WorldIntersectionTexCoord object to be filled.
Return value
Pointer to the first intersected object.int getIntersection ( const Math::Vec3 & p0, const Math::Vec3 & p1, Vector< Ptr<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.
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
- const Math::Vec3 & p0 - Coordinates of the line start point.
- const Math::Vec3 & p1 - Coordinates of the line end point.
- Vector< Ptr<Object> > & objects - Array of intersected objects' smart pointers.
Return value
1 if intersections are found; otherwise, 0.int getIntersection ( const Math::WorldBoundBox & bb, Vector< Ptr<Object> > & objects ) #
Searches for intersections with objects that are found in a given bounding box.
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
- const Math::WorldBoundBox & bb - Bounding box where intersection search will be performed.
- Vector< Ptr<Object> > & objects - Array of intersected objects' smart pointers.
Return value
1 if intersections are found; otherwise, 0.int getIntersection ( const Math::WorldBoundBox & bb, Vector< Ptr<Node> > & nodes ) #
Searches for intersections with nodes that are found in a given bounding box.
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
- const Math::WorldBoundBox & bb - Bounding box where intersection search will be performed.
- Vector< Ptr<Node> > & nodes - Array of intersected nodes' smart pointers.
Return value
1 if intersections are found; otherwise, 0.int getIntersection ( const Math::WorldBoundBox & bb, int type, Vector< Ptr<Node> > & nodes ) #
Searches for intersections with specified type of nodes that are found in a given bounding box.
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
- const Math::WorldBoundBox & bb - Bounding box where intersection search will be performed.
- int type - Node type filter. Only the nodes of the specified type will be checked.
- Vector< Ptr<Node> > & nodes - Array of intersected nodes' smart pointers.
Return value
1 if intersections are found; otherwise, 0.int getIntersection ( const Math::WorldBoundSphere & bs, Vector< Ptr<Object> > & objects ) #
Searches for intersections with objects that are found in a given bounding sphere.
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
- const Math::WorldBoundSphere & bs - Bounding sphere where intersection search will be performed.
- Vector< Ptr<Object> > & objects - Array of intersected objects' smart pointers.
Return value
1 if intersections are found; otherwise, 0.int getIntersection ( const Math::WorldBoundSphere & bs, Vector< Ptr<Node> > & nodes ) #
Searches for intersections with nodes that are found in a given bounding sphere.
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
- const Math::WorldBoundSphere & bs - Bounding sphere where intersection search will be performed.
- Vector< Ptr<Node> > & nodes - Array of intersected nodes' smart pointers.
Return value
1 if intersections are found; otherwise, 0.int getIntersection ( const Math::WorldBoundSphere & bs, int type, Vector< Ptr<Node> > & nodes ) #
Searches for intersections with nodes of the specified type that are found in a given bounding sphere.
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
- const Math::WorldBoundSphere & bs - Bounding sphere where intersection search will be performed.
- int type - Node type filter. Only the nodes of the specified type will be checked.
- Vector< Ptr<Node> > & nodes - Array of intersected nodes' smart pointers.
Return value
1 if intersections are found; otherwise, 0.int getIntersection ( const Math::WorldBoundFrustum & bf, Vector< Ptr<Object> > & objects ) #
Searches for intersections with Objects that are found in a given bounding frustum. This method catches all objects independent of their visibility (i.e., if an object is disabled, any of its LODs are disabled, or it is out of the visibility distance range, but is located within the bounding frustum, the intersection shall be detected). To check for intersections while taking into account the visibility aspect, use getVisibleIntersection(). Check the usage example applying this method.
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
- const Math::WorldBoundFrustum & bf - Bounding frustum where intersection search will be performed.
- Vector< Ptr<Object> > & objects - Array of intersected objects' smart pointers.
Return value
1 if intersections are found; otherwise, 0.int getIntersection ( const Math::WorldBoundFrustum & bf, int type, Vector< Ptr<Node> > & nodes ) #
Searches for intersections with nodes of the specified type that are found in a given bounding frustum. This method catches all nodes of the specified type independent of their visibility (i.e., if an object is disabled, any of its LODs are disabled, or it is out of the visibility distance range, but is located within the bounding frustum, the intersection shall be detected). To check for intersections while taking into account the visibility aspect, use getVisibleIntersection().
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
- const Math::WorldBoundFrustum & bf - Bounding frustum where intersection search will be performed.
- int type - Node type filter. Only the nodes of the specified type will be checked.
- Vector< Ptr<Node> > & nodes - Array of intersected nodes' smart pointers.
Return value
1 if intersections are found; otherwise, 0.bool getVisibleIntersection ( const Math::Vec3& camera, const Math::WorldBoundFrustum& bf, Vector< Ptr<Object> > & objects, float max_distance ) #
Searches for intersections with objects inside a given bounding frustum that are visible to the specified camera position, i.e. either of its LODs is within the visibility distance distance. Unlike the getIntersection() method, this one takes the "visibility" concept into account (hidden objects or the ones that are too far away won't be found). Check this usage example for more details.Arguments
- const Math::Vec3& camera - Position of the camera from which the visibility distance to objects is checked.
- const Math::WorldBoundFrustum& bf - Bounding frustum inside which intersection search is performed.
- Vector< Ptr<Object> > & objects - Array of intersected objects.
- float max_distance - Maximum visibility distance for objects, in units. If the distance from the specified camera position to an object exceeds this limit, the intersection is not registered even if the node is within the specified bounding frustum.
Return value
true if at least one intersection is found; otherwise, false.bool getVisibleIntersection ( const Math::Vec3& camera, const Math::WorldBoundFrustum& bf, Node::TYPE type, Vector< Ptr<Node> > & nodes, float max_distance ) #
Searches for intersections with nodes inside a given bounding frustum that are visible to the specified camera position, i.e. either of its LODs is within the visibility distance distance. Unlike the getIntersection() method, this one takes the "visibility" concept into account (hidden nodes or the ones that are too far away won't be found). Check this usage example for more details.
Notice
This method can be used only for nodes inherited from the Object class, i.e. they have sufraces that store LOD and visibility distance data.
Arguments
- const Math::Vec3& camera - Position of the camera from which the visibility distance to nodes is checked.
- const Math::WorldBoundFrustum& bf - Bounding frustum inside which intersection search is performed.
- Node::TYPE type - Node type (one of the NODE_* variables); set it to -1 if you won't use this filter.
- Vector< Ptr<Node> > & nodes - Array of intersected nodes.
- float max_distance - Maximum visibility distance for nodes, in units. If the distance from the specified camera position to a node exceeds this limit, the intersection is not registered even if the node is within the specified bounding frustum.
Return value
true if at least one intersection is found; otherwise, false.bool loadWorld ( const char * 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
- const char * path - Path to the file describing the world.
Return value
true if the world is loaded successfully; otherwise, false.bool loadWorld ( const char * 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
- const char * 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 ( const char * 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
- const char * path - Path to the file describing the world.
Return value
true if the world is loaded successfully; otherwise, false.bool loadWorldForce ( const char * 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
- const char * 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.int isLoaded ( ) #
Returns a value indicating if the current world is fully loaded.Return value
1 if the world is loaded; otherwise, 0.bool saveWorld ( ) #
Saves the world.Return value
true, if the world has been saved successfully; otherwise false.bool saveWorld ( const char * path ) #
Saves the world to the specified location.Arguments
- const char * 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 ( ) const#
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.const char * getLoadWorldRequestPath ( ) const#
Returns the path to the world which is going to be loaded.Return value
Path to the world to be loaded.int addWorld ( const char * name ) #
Loads a world from a file and adds it to the current world.Arguments
- const char * name - Name of the file describing the world.
Return value
1 if the world is loaded and added successfully; otherwise, 0.void setPath ( const char * path ) #
Sets the path to the *.world-file where the world is stored.Arguments
- const char * path - Path to the *.world-file.
const char * getPath ( ) #
Returns the current path to the *.world-file where the world is stored.Return value
Path to the *.world-file.void setPhysicsSettings ( const char * settings ) #
Sets the name of the *.physics file containing default physics settings to be used for the world.Arguments
- const char * settings - Name of the default *.physics asset to be used for the world.
const char * 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 ( const char * settings ) #
Sets the name of the *.render file containing default render settings to be used for the world.Arguments
- const char * settings - Name of the default *.render asset to be used for the world.
const char * 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 ( const char * settings ) #
Sets the name of the *.sound file containing default sound settings to be used for the world.Arguments
- const char * settings - Name of the default *.sound asset to be used for the world.
const char * 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 setScriptName ( const char * name ) #
Sets the name of the world script file *.usc.Arguments
- const char * name - Name of the world script file *.usc.
const char * getScriptName ( ) #
Returns the name of the world script file *.usc.Return value
Name of the world script file *.usc.int 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 ( Vector< Ptr<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
int clearNode ( const char * name ) #
Clears cached nodes of the given node file.When the node is cached and you try to access it, take into account the following:
- if the node was loaded by the name — the node gets stored in the cache by its name;
- if the node was loaded from the parent node reference — the node is stored in the cache by its GUID.
Source code (C++)
NodePtr node = World::loadNode(file_name);
// change something in the node...
World::saveNode(file_name, node);
// clear cache by the name
World::clearNode(file_name);
// clear cache by the GUID (if this node is inside another node reference)
World::clearNode(FileSystem::getGUID(file_name).getFileSystemString());
// reload the node
node->deleteForce();
node = World::loadNode(file_name);Arguments
- const char * name - Path to the *.node file.
Return value
1 if the cache is cleared successfully; otherwise, 0.Ptr<Node> loadNode ( const char * 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).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
- const char * 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 ( const char * name, Vector< Ptr<Node> > & nodes ) #
Loads nodes from a file.Arguments
- const char * name - Path to the *.node file.
- Vector< Ptr<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 ( const char * name, const Ptr<Node> & node, int binary = 0 ) #
Saves a given node to a file with due regard for its local transformation.Arguments
- const char * name - Path to the *.node file.
- const Ptr<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 ( const char * name, const Vector< Ptr<Node> > & nodes, int binary = 0 ) #
Saves nodes to a file.Arguments
- const char * name - Path to the *.node file.
- const Vector< Ptr<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 setUnpackNodeReferences ( int references ) #
Enables or disables automatic unpacking of node references at run time. This option can be used to simplify hierarchy management, as when it is enabled all nodes contained in node references will be present in the world hierarchy. When disabled you have to check the hierarchy of each node reference individually (e.g. to find the number of children or manage some of them). The content of NodeReference nodes is unpacked only at run time and does not affect your *.world and *.node files. So, you can use all advantages of node references when building worlds in the UnigineEditor and manage a clear and straightforward hierarchy at run time.Notice
This option is available only via code, can be enabled in the System Script and works for all worlds used in your project.
Notice
Auto-unpacking is disabled in C++ and UnigineScript only projects by default for backward compatibility.
Arguments
- int references - 1 - to enable automatic unpacking of node references at run time, 0 - to disable it.
int isUnpackNodeReferences ( ) #
Returns the value indicating if automatic unpacking of node references at run time is enabled. This option can be used to simplify hierarchy management, as when it is enabled all nodes contained in node references will be present in the world hierarchy. When disabled you have to check the hierarchy of each node reference individually (e.g. to find the number of children or manage some of them). The content of NodeReference nodes is unpacked only at run time and does not affect your *.world and *.node files. So, you can use all advantages of node references when building worlds in the UnigineEditor and manage a clear and straightforward hierarchy at run time.Notice
This option is available only via code, can be enabled in the System Script and works for all worlds used in your project.
Notice
Auto-unpacking is disabled in C++ and UnigineScript only projects by default for backward compatibility.
Return value
1 if automatic unpacking of node references at run time is enabled; 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 setUpdateGridSize ( float size ) #
Sets the size of the grid to be used for spatial tree update. The default value is an average one, and can be adjusted when necessary depending on the scene.Arguments
- float size - New grid size, in units. The default value is 1000 units.
float getUpdateGridSize ( ) #
Returns the current size of the grid to be used for spatial tree update. The default value is an average one, and can be adjusted when necessary depending on the scene.Return value
Current grid size, in units. The default value is 1000 units.void setScriptExecute ( int execute ) #
Sets a value indicating if a logic script associated with the world is to be loaded with it.Arguments
- int execute - 1 - to load the world along with the associated logic script (if any), 0 - to ignore it.
int isScriptExecute ( ) #
Returns a value indicating if a logic script associated with the world is to be loaded with it.Return value
1 if a logic script associated with the world is to be loaded with it; otherwise, 0.Ptr<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, nullptr.Ptr<Node> getNodeByName ( const char * 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.Notice
method filters out isolated node hierarchies and cache nodes, so it does not return nodes having a possessor (NodeReference / Clutter / Cluster) among its predecessors or nodes from cache.
Arguments
- const char * name - Node name.
Return value
Node, if it exists in the world; otherwise, nullptr.void getNodesByName ( const char * name, Vector< Ptr<Node> > & nodes ) #
Generates a list of nodes in the world with a given name and puts it to nodes.Arguments
- const char * name - Node name.
- Vector< Ptr<Node> > & nodes - List of nodes with the given name (if any); otherwise, nullptr.
Ptr<Node> getNodeByType ( int type ) const#
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, nullptr.void getNodesByType ( int type, Vector< Ptr<Node> > & nodes ) const#
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.
- Vector< Ptr<Node> > & nodes - List of nodes of the given type (if any); otherwise, nullptr.
bool isNode ( const char * name ) #
Checks if a node with a given name exists in the world.Arguments
- const char * 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 ( Vector< Ptr<Node> > & nodes ) #
Gets all root nodes in the world hierarchy and puts them to nodes. Doesn't include cached nodes.Arguments
int getRootNodeIndex ( const Ptr<Node> & node ) #
Returns the index for the specified root node, that belongs to the world hierarchy.Arguments
Return value
Index of the specified root node if it exists; otherwise, -1.void setRootNodeIndex ( const Ptr<Node> & node, int index ) #
Sets a new index for the specified root node, that belongs to the world hierarchy.Arguments
- const Ptr<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 * addCallback ( int callback, Unigine::CallbackBase1< const char *> * 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:Source code (C++)
void callback_function_name(const char *world_path);Arguments
- int callback - Callback type. One of the CALLBACK_* variables.
- Unigine::CallbackBase1< const char *> * func - Callback pointer.
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.void * addCallback ( int callback, Unigine::CallbackBase2< const char *, Ptr <Node> > * 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:Source code (C++)
void callback_function_name(const char *world_path, NodePtr node);Arguments
- int callback - Callback type. One of the CALLBACK_* variables.
- Unigine::CallbackBase2< const char *, Ptr <Node> > * func - Callback pointer.
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, void * 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.
- void * 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.
Last update:
20.04.2022
Помогите сделать статью лучше
Была ли эта статья полезной?
(или выберите слово/фразу и нажмите Ctrl+Enter