Programming
Fundamentals
Setting Up Development Environment
UnigineScript
High-Level Systems
C++
C#
UUSL (Unified UNIGINE Shader Language)
File Formats
Rebuilding the Engine and Tools
GUI
Double Precision Coordinates
API
Containers
Common Functionality
Controls-Related Classes
Filesystem Functionality
GUI-Related Classes
Math Functionality
Node-Related Classes
Networking Functionality
Pathfinding-Related Classes
Physics-Related Classes
Plugins-Related Classes
Rendering-Related Classes

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.

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

World Class

Members


World * get()

Returns a pointer to the World instance.

Return value

Pointer to World.

Ptr<Node> getAsyncNode(int id)

Gets the loaded node. If the loaded node consists of multiple objects, a new dummy object is created to combine them and its smart pointer is returned.

Arguments

  • int id - Loading operation identifier.

Return value

Returns the loaded node smart pointer, if found; otherwise, 0.

int getAsyncNodes(int id, Vector< Ptr<Node> > & nodes)

Gets an array of the loaded nodes. If the loaded node consists of multiple objects, they are put into the array.

Arguments

  • int id - Loading operation identifier.
  • Vector< Ptr<Node> > & nodes - Array of loaded nodes' smart pointers.

Return value

1 if the operation is successful; otherwise, 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 UNIGINE_BOUND_BOX & 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 UNIGINE_BOUND_BOX & 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 UNIGINE_BOUND_SPHERE & 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 UNIGINE_BOUND_SPHERE & 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 intersecting the line. This function detects intersection with surfaces (polygons) of mesh and terrain objects.

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

  1. A per-surface Collision flag is enabled.
  2. An Collision option of the property in the Properties window is enabled.
  3. A surface is enabled.
  4. A surface has an assigned material.
  5. A surface has an assigned property.
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 * data)

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

Arguments

  • const char * data - New user data.

const char * getData()

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

Return value

User string data.

void 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, Math::Vec3 * ret_point, Math::vec3 * ret_normal, Math::vec4 * ret_texcoord, int * ret_index, int * ret_surface)

Performs tracing from the p0 point to the p1 point to find the first object intersecting the line. This function detects intersection with surfaces of a mesh. 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:

  1. A per-surface Intersection flag is enabled.
  2. An Intersection option of the property in the Properties window is enabled.
  3. A surface is enabled.
  4. A surface has an assigned material.
  5. A surface has an assigned property.
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.
  • Math::Vec3 * ret_point - Intersection point of the line and object.
  • Math::vec3 * ret_normal - Normal vector to the intersection point.
  • Math::vec4 * ret_texcoord - Texture coordinates of the intersection point (vec4, where vec4.xy is for the first (0) UV channel, vec4.zw is for the second (1) UV channel).
  • int * ret_index - Intersected triangle (polygon) number.
  • int * ret_surface - Intersected surface number.

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, Math::Vec3 * ret_point, Math::vec3 * ret_normal, Math::vec4 * ret_texcoord, int * ret_index, int * ret_surface)

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:

  1. A per-surface Intersection flag is enabled.
  2. An Intersection option of the property in the Properties window is enabled.
  3. A surface is enabled.
  4. A surface has an assigned material.
  5. A surface has an assigned property.
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.
  • Math::Vec3 * ret_point - Intersection point of the line and object.
  • Math::vec3 * ret_normal - Normal vector to the intersection point.
  • Math::vec4 * ret_texcoord - Texture coordinates of the intersection point (vec4, where vec4.xy is for the first (0) UV channel, vec4.zw is for the second (1) UV channel).
  • int * ret_index - Intersected triangle (polygon) number.
  • int * ret_surface - Intersected surface number.

Return value

Pointer to the first intersected object.

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:

  1. A per-surface Intersection flag is enabled.
  2. An Intersection option of the property in the Properties window is enabled.
  3. A surface is enabled.
  4. A surface has an assigned material.
  5. A surface has an assigned property.
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:

  1. A per-surface Intersection flag is enabled.
  2. An Intersection option of the property in the Properties window is enabled.
  3. A surface is enabled.
  4. A surface has an assigned material.
  5. A surface has an assigned property.
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:

  1. A per-surface Intersection flag is enabled.
  2. An Intersection option of the property in the Properties window is enabled.
  3. A surface is enabled.
  4. A surface has an assigned material.
  5. A surface has an assigned property.
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:

  1. A per-surface Intersection flag is enabled.
  2. An Intersection option of the property in the Properties window is enabled.
  3. A surface is enabled.
  4. A surface has an assigned material.
  5. A surface has an assigned property.
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:

  1. A per-surface Intersection flag is enabled.
  2. An Intersection option of the property in the Properties window is enabled.
  3. A surface is enabled.
  4. A surface has an assigned material.
  5. A surface has an assigned property.
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 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:

  1. A per-surface Intersection flag is enabled.
  2. An Intersection option of the property in the Properties window is enabled.
  3. A surface is enabled.
  4. A surface has an assigned material.
  5. A surface has an assigned property.
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 that 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:

  1. A per-surface Intersection flag is enabled.
  2. An Intersection option of the property in the Properties window is enabled.
  3. A surface is enabled.
  4. A surface has an assigned material.
  5. A surface has an assigned property.
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 UNIGINE_BOUND_BOX & 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 UNIGINE_BOUND_BOX & 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 UNIGINE_BOUND_SPHERE & 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 UNIGINE_BOUND_SPHERE & 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 UNIGINE_BOUND_FRUSTUM & bf, Vector< Ptr<Object> > & objects)

Searches for intersections with objects that are found in a given bounding frustum.

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 UNIGINE_BOUND_FRUSTUM & 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 UNIGINE_BOUND_BOX & 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 UNIGINE_BOUND_BOX & 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 UNIGINE_BOUND_SPHERE & 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 UNIGINE_BOUND_SPHERE & 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 UNIGINE_BOUND_BOX & 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 UNIGINE_BOUND_BOX & 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 UNIGINE_BOUND_SPHERE & bs, int type, Vector< Ptr<Node> > & nodes)

Searches for intersections with specified type of 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 UNIGINE_BOUND_SPHERE & 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 UNIGINE_BOUND_FRUSTUM & bf, int type, Vector< Ptr<Node> > & nodes)

Searches for intersections with specified type of nodes that are found in a given bounding frustum.

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 UNIGINE_BOUND_FRUSTUM & 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.

int isLoaded()

Returns a value indicating if the current world is fully loaded.

Return value

1 if the world is loaded; otherwise, 0.

void setName(const char * name)

Sets a new name for the world.

Arguments

  • const char * name - Name of the world.

const char * getName()

Returns the name of the currently loaded world. (If a path was specified in the name, the returned string will contain both the world name and a path).

Return value

Name of the world.

Ptr<Node> getNode(int id)

Returns a node by its ID. This can be any node: either created dynamically in run-time or loaded from the *.world file.

Arguments

  • int id - Node ID.

Return value

Node smart pointer if the node with the specified ID exists; otherwise, NULL.

int 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 getNodes(Vector< Ptr<Node> > & nodes)

Gets all of the nodes (either loaded from the *.world file or created dynamically in run-time).

Arguments

  • Vector< Ptr<Node> > & nodes - Return array with node smart pointers.

int getNumQueuedNodes()

Returns the number of queued nodes waiting for the background loading. The return value also includes the currently processed node. To add node for the background loading, use the loadAsyncNode() function.

Return value

Number of queued nodes including the currently processed node.

int getNumQueuedResources()

Returns the number of queued resources waiting for the background loading. The return value also includes the currently processed node.

Return value

Number of queued resources including the currently processed resource.

int getNumUpdateNodes()

Returns the number of currently updating nodes in the world.

Return value

Number of updating nodes.

float getTotalTime()

Returns the total time (in milliseconds) of loading a resource.

Return value

The total time value, milliseconds.

Ptr<Node> getUpdateNode(int num)

Returns an updated node by its ID.

Arguments

  • int num - Node ID.

Return value

The node smart pointer, if found; otherwise - 0.

void addUpdateNode(const Ptr<Node> & node)

Adds a node that should be updated even if it is outside of the viewing frustum. This function should be called every frame.

Arguments

  • const Ptr<Node> & node - Node to be updated.

void addUpdateNodes(const Vector< Ptr<Node> > & nodes)

Adds a node array that should be updated even if the nodes are outside of the viewing frustum. This function should be called every frame.

Arguments

  • const Vector< Ptr<Node> > & nodes - Nodes array to be updated.

int addWorld(const char * name)

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

Arguments

Return value

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

int checkAsyncNode(int id)

Returns a value indicating if the node is in the loading queue or already loaded.

Arguments

  • int id - Loading operation identifier.

Return value

1 if the node is in queue or already loaded; otherwise, 0.

int clearNode(const char * name)

Clears a cache of a given node.

Arguments

  • const char * name - Path to the *.node file.

Return value

1 if the cache is cleared successfully; otherwise, 0.

int forceAsyncNode(int id)

Forces the node loading. The specified node gets the higher priority and will be loaded first.

Arguments

  • int id - Loading operation identifier.

Return value

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

int loadAsyncNode(const char * name, int group = 0, float weight = 0.0f)

Loads the node with the specified group and priority to the thread.

Arguments

  • const char * name - Node name.
  • int group - Number of a node group.
  • float weight - Node priority.

Return value

Returns the loading operation identifier.

Ptr<Node> loadNode(const char * name, int cache = 1, int is_world = 0)

Loads a node from a file. If the node is loaded successfully, it does not belong to any node hierarchy or list, so be careful and make sure to handle it properly, when it is no longer needed.

Arguments

  • const char * name - Path to the *.node file.
  • int cache - 1 to use the file cache, 0 not to use.
  • int is_world - If set to 1, the material library of the node is loaded as a world library (i.e. is specified in the *.world file and is automatically loaded on the world initialization).

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.

Ptr<Node> loadPrefab(const char * name, int cache = 1)

Loads a prefab from a file. All nested prefabs are also loaded.

Arguments

  • const char * name - Path to the *.node file.
  • int cache - 1 to use the file cache, 0 not to use.

Return value

Loaded prefab node; NULL if the prefab cannot be loaded.

int removeAsyncNode(int id)

Removes node from the loading queue.

Arguments

Return value

1 if the node is removed successfully; otherwise, 0.

int saveNode(const char * name, const Ptr<Node> & node, int materials = 1, int binary = 0)

Saves a given node to a file.

Arguments

  • const char * name - Path to the *.node file.
  • const Ptr<Node> & node - Pointer to the node to save.
  • int materials - If the node has the materials assigned, and this flag is set to 1, the corresponding material libraries will be also listed in the *.world file.
  • 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 materials = 1, 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 materials - If the node has the materials assigned, and this flag is set to 1, the corresponding material libraries will be also listed in the *.world file.
  • 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.

int savePrefab(const char * name, const Ptr<Node> & node, int materials = 1, int binary = 0)

Saves a given prefab to a file. Nested prefab instances won't be saved, node links with corresponding prefab names and transformations will be saved instead.

Arguments

  • const char * name - Path to the *.node file.
  • const Ptr<Node> & node - Pointer to the prefab to save.
  • int materials - If the prefab has the materials assigned, and this flag is set to 1, the corresponding material libraries will be also listed in the *.world file.
  • int binary - If set to 1, the prefab is saved to the binary *.xml. This file cannot be read, but using it speeds up the saving of the prefab and requires less disk space.

Return value

1 if the prefab is 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.

Last update: 2017-07-03