API Migration

We’ve removed the NodePivot as redundant, as you actually can control transformation of a group of nodes by simply building their hierarchy placing dependent ones as children of the one considered as the main one.

Layers, Clusters, and Clutters#

Sectors and Portals#

Dataset Classes#

Updating of Engine's logic for objects (simulation of particles, water, cloth, or ropes, and playback of skinned mesh animations) is now controlled via the set of Periodic Update parameters with visibility of an object having an impact on how often it is updated.

The list of objects that require to be updated now includes the following:

• Particle Systems
• Skinned Meshes
• Dynamic Meshes (only with a rope, a cloth, or a water body assigned)
• World Expressions
• World Transform Paths

For each of them you can now specify an Update Distance Limit - a distance from the camera up to which the object should be updated.

In addition to that, for Particle Systems, Skinned and Dynamic Meshes, you can set the following update rate values:

• FPSVisibleCamera - for the case when the object is rendered to viewport
• FPSVisibleShadow - when only its shadow is rendered (here we can cut even more)
• FPSInvisible - when the object is not rendered at all.

Before 2.11 to enable force updating for a node you could use the addUpdateNode() method of the World class. Now to enable constant updating for an object regardless of its visibility you can set the Update Distance Limit and corresponding update rate values for it to infinity:

World::addUpdateNode(object);

object->setUpdateDistanceLimit(Consts::INF);
object->setFPSInvisible(Consts::INF);
object->setFPSVisibleShadow(Consts::INF);
object->setFPSVisibleCamera(Consts::INF);

For example this can be used in case in your project you have an invisible particle system (e.g., using the viewport mask) and some logic attached to its update (e.g. spawning some visible particles on collision with objects).

Some nodes having their bounds defined by the bounds of their children, such as DummyNode, NodeReference, or NodeLayer, especially the ones with complex hierarchies took a lot of time to recalculate such hierarchical bounds. Moreover, calculation sometimes was incorrect, for example, in case the hierarchy contained skinned meshes or particle systems having their bounds changed every frame, as recalculation of all bounds in the hierarchy every frame would certainly drop performance drastically in projects with sophisticated node hierarchies.

We have revised the whole bounds system making it fast, clear and straightforward. The following "abstract" objects (having no visual representation or their own size) now do not have bounds at all and therefore are excluded from the spatial tree: DummyNode, NodeReference, NodeLayer, WorldSwitcher, WorldTransformPath, WorldTransformBone, WorldExpression, and ObjectDummy (if it has no body assigned). This significantly reduces the size of the tree and improves performance due to saving time on bound recalculation when transforming such nodes.

The following types of bounds are used:

• Local Bounds - bound objects with local coordinates which do not take into account physics and children: BoundBox, and BoundSphere.
• World Bounds - same as local ones, but with world coordinates: WorldBoundBox and WorldBoundSphere.
• Spatial Bounds - bound objects with world coordinates used by the spatial tree, and therefore taking physics into account (shape bounds, etc.): SpatialBoundBox and SpatialBoundSphere.
  Notice

  Spatial bounds are calculated faster than World ones.

And their hierarchical analogues (taking into account all children) to be used where hierarchical bounds are required (they are slow, but offer correct calculations):

• Local Hierarchical Bounds - bound objects with local coordinates taking bounds of all node’s children into account: HierarchyBoundBox and HierarchyBoundSphere.
• World Hierarchical Bounds - same as local ones, but with world coordinates: HierarchyWorldBoundBox and HierarchyWorldBoundSphere.
• Spatial Hierarchical Bounds - hierarchical bound objects used by the spatial tree, and therefore taking physics into account (shape bounds, etc.): HierarchySpatialBoundBox and HierarchySpatialBoundSphere.

New Spatial Hierarchical Bounds are equivalent to former bounds of a NodeDummy with all its hierarchy.

Regarding the changes described above you should pay attention to the following:

• Intersections are detected only for nodes having bounds. So, to find an intersected NodeReference or a NodeDummy you’ll have to find one running up the hierarchy from an intersected node.
• WorldExpression node does not take into account bounds of its children anymore, only its own. So, it is now critical to update its size in a timely manner to ensure proper behavior.

We have changed the way of detecting intersections - world intersections (i.e. between object bound volumes, or ray intersections with object surfaces) and physics intersections (between physical objects with bodies and collider shapes, or ray intersections with collider geometry) now use separate masks, enabling you to control them independently, which gives more flexibility. So, a new Physics Intersection option with its own Physics Intersection Mask were added to the list of surface parameters.

Physics intersections can be used, for example, to detect collisions of spawned particles with physical shapes and bodies or static collider surfaces to ensure proper interaction, or as a quick way to detect collisions for raycast-wheels of a simulated ground vehicle, or to check if a destructible object was hit by a projectile. Particle systems, shapes, fracture bodies, and wheel joints now use the new Physics Intersection mask.

The Intersection option and the Intersection mask remain responsible for such features as selecting and highlighting objects under the mouse cursor, or cutting grass in areas occupied by other objects.

To manage detection of physics intersections for a surface you can use the following new methods of the Object class:

• setPhysicsIntersection().
• getPhysicsIntersection().
• setPhysicsIntersectionMask().
• getPhysicsIntersectionMask().

The Intersection option of the ObjectParticles class was renamed as Physics Intersection:

New Physics Intersection mask replaces the Intersection mask in the following cases:

Collision detection is now automatically enabled for an object if it has a body assigned or at least one of its surfaces has the Collision flag set. This makes the Collider flag of the node redundant - so we removed it. Fewer boxes to check - simpler adjustment and less chance to make a mistake (false-colliders waste resources).

So, instead of setting the Collider flag via setCollider() for an object in 2.10, in 2.11 you should either enable collision detection per surface via setCollision() per surface or assign a physical body to it via the setBody() method:

object->setCollider(1);

object->setCollision(true, 0);
// or
object->setBody(some_body);

For more information on collision detection please refer to the Collision Detection article.

Mouse behavior is now controlled directly via API without using defines. You can either select the desired behavior in the UnigineEditor or set it via code and change on the fly, if required.

In the Editor, open Windows -> Settings -> Controls and set the required mouse handle:

• Grab - the mouse is grabbed when clicked (the cursor disappears and camera movement is controlled by the mouse).
• Soft - the mouse cursor disappears after being idle for a short time period.
• User - the mouse is not handled by the system (allows input handling by some custom module).

In your code (world or system logic, components, expressions, etc.), you can set the mouse behavior as follows:

ControlsApp::setMouseHandle(Input::MOUSE_HANDLE_GRAB);
// or
ControlsApp::setMouseHandle(Input::MOUSE_HANDLE_SOFT);

ControlsApp.MouseHandle = Input.MOUSE_HANDLE.GRAB;
// or
ControlsApp.MouseHandle = Input.MOUSE_HANDLE.SOFT;

engine.controls.setMouseHandle(MOUSE_HANDLE_GRAB);
// or
engine.controls.setMouseHandle(MOUSE_HANDLE_SOFT);

Please check out the updated usage example on Customizing Mouse Cursor and Behavior

Switch parameter of the property is now one step closer to enums in C#/C++. Now it is a set of values, each of these values may have an optional arbitrary name (Item) associated with it. Items can have positive or negative values, several items can have the same value.

Suppose we have a property switch parameter declared as follows:

<parameter items="red=-1,green,blue=5,yellow"/>

After loading we'll have switch items with the following values: red = -1, green = 0, blue = 5, yellow = 6.

PropertyParameter::setValue(5); // "blue" is selected in the corresponding combobox in the UnigineEditor
PropertyParameter::setSwitchItem(3); // "yellow" is selected (3rd item, starting from 0)

// If "green" item is selected in the UnigineEditor:
PropertyParameter::getValueInt(); // returns 0, as "green" corresponds to the value of 0.
PropertyParameter::getSwitchItem() // returns 1, as "green" is the 1st element in the combobox (starting from 0).

As GPU-based modification ensures significantly higher performance and stability, its CPU-based counterpart is considered redundant. So the corresponding methods were marked as deprecated and will be removed in the next release. As for other changes, operation ID's are now managed differently:

int id = Landscape::asyncTextureDraw(file_guid, coord, resolution, flags_file_data);
// user's code (bounding to ID)

int id = Landscape::generateOperationID();
// user's code (bounding to ID)
Landscape::asyncTextureDraw(id, file_guid, coord, resolution, flags_file_data);

Landscape Class Changes#

For more information on the current implementation of terrain modification please refer to the Landscape Class article.

• setExternalWindowFocused()
• isExternalWindowFocused()
• dialogSaveFile()
• dialogSaveFile()
• dialogSaveFile()
• dialogOpenFile()
• dialogOpenFile()
• dialogOpenFile()
• dialogOpenFiles()
• dialogOpenFiles()
• dialogOpenFiles()
• dialogOpenFolder()
• dialogOpenFolder()
• showSystemDialog()
• dialogError()
• dialogWarning()
• dialogMessage()
• updateMouseCursor()
• setMouseCursorCustom()
• clearMouseCursorCustom()
• setMouseCursorSkinDefault()
• setMouseCursorSkinSystem()
• setMouseCursorSkinCustom()
• setMouseCursorNeedUpdate()
• isMouseCursorNeedUpdate()
• setMouseCursorSystem()
• isMouseCursorSystem()
• setMouseCursorHide()
• isMouseCursorHide()
• isMouseGrab()

• setMouseHandle()
• getMouseHandle().

• getRandomColor()

• assignFrom()
• resizeFrom()

• MOUSE_HANDLE_GRAB
• MOUSE_HANDLE_SOFT
• MOUSE_HANDLE_USER
• KEY_SPACE
• setMouseHandle()
• getMouseHandle()

• TEXTURE_LIGHT_SHADOW_DEPTH
• TEXTURE_LIGHT_SHADOW_COLOR
• OPTION_BLEND
• OPTION_ORDER
• OPTION_OFFSET
• OPTION_SHADOW_MASK
• OPTION_VIEWPORT_MASK
• OPTION_TRANSPARENT
• OPTION_DEPTH_MASK
• OPTION_DEPTH_TEST
• OPTION_TWO_SIDED
• OPTION_RECEIVE_SHADOW
• OPTION_CAST_PROJ_OMNI_SHADOW
• OPTION_RECEIVE_WORLD_SHADOW
• OPTION_CAST_WORLD_SHADOW
• OPTION_OVERLAP
• getOptionGroup()
• getOptionTitle()
• getOptionTooltip()
• getOptionWidgetIndex()
• isOptionHidden()

• getNumWorldTriggers()
• getWorldTrigger()
• getHierarchySpatialBoundSphere()
• getHierarchySpatialBoundBox()
• getHierarchyWorldBoundSphere()
• getHierarchyWorldBoundBox()
• getHierarchyBoundSphere()
• getHierarchyBoundBox()
• getSpatialBoundSphere()
• getSpatialBoundBox()

• clearSurfaceProperty()
• setPhysicsIntersection().
• getPhysicsIntersection().
• setPhysicsIntersectionMask().
• getPhysicsIntersectionMask().
• isVisibleShadow().
• isVisibleCamera().

• setUpdateDistanceLimit()
• getUpdateDistanceLimit().
• setFPSInvisible()
• getFPSInvisible().
• setFPSVisibleShadow()
• getFPSVisibleShadow().
• setFPSVisibleCamera()
• getFPSVisibleCamera().

• setUpdateDistanceLimit()
• getUpdateDistanceLimit().
• setFPSInvisible()
• getFPSInvisible().
• setFPSVisibleShadow()
• getFPSVisibleShadow().
• setFPSVisibleCamera()
• getFPSVisibleCamera().
• updateSkinned().

• setUpdateDistanceLimit()
• getUpdateDistanceLimit().
• setFPSInvisible()
• getFPSInvisible().
• setFPSVisibleShadow()
• getFPSVisibleShadow().
• setFPSVisibleCamera()
• getFPSVisibleCamera().

• PARAMETER_VEC2
• PARAMETER_DVEC2
• PARAMETER_DVEC3
• PARAMETER_DVEC4
• PARAMETER_IVEC2
• PARAMETER_IVEC3
• PARAMETER_IVEC4
• PARAMETER_MASK_PHYSICS_INTERSECTION
• RESTORE_MODE_FULL

• setSwitchItem()
• getSwitchItemName().
• getSwitchItemValue().
• isVec2()
• isDVec2()
• isDVec3()
• isDVec4()
• isIVec2()
• isIVec3()
• isIVec4()
• setValue()
• setValue()
• setValue()
• setValue()
• setValue()
• setValue()
• setValue()
• setValueVec2()
• getValueVec2()
• setValueDVec2()
• getValueDVec2()
• setValueDVec3()
• getValueDVec3()
• setValueDVec4()
• getValueDVec4()
• setValueIVec2()
• getValueIVec2()
• setValueIVec3()
• getValueIVec3()
• setValueIVec4()
• getValueIVec4()

• setFfpAntialiasingLines()
• isFfpAntialiasingLines()
• setWireframeAntialiasing()
• isWireframeAntialiasing()
• setStreamingParticlesMemoryLimit()
• getStreamingParticlesMemoryLimit()

• getPosition()

• getNumElements()
• copy()
• clearBuffer()

• copyRegion()
• getVideoMemoryUsage()

• setFileSystemString()

• renderNodeHandler()

• setIntersectionEnabled()
• isIntersectionEnabled()

• setCurrentItem()
• resetCurrentItem()
• setCurrentItemHighlight()
• isCurrentItemHighlight()
• setCurrentItemColor()
• getCurrentItemColor()

• setIntersectionImageThreshold()
• getIntersectionImageThreshold()
• setIntersectionImageTransform()
• getIntersectionImageTransform()
• setIntersectionImage()
• setIntersectionImageName()
• setIntersectionImageEnabled()
• isIntersectionImageEnabled()

• setPhysicsSettings()
• getPhysicsSettings()
• setSoundSettings()
• getSoundSettings()
• setRenderSettings()
• getRenderSettings()

• setUpdateDistanceLimit()
• getUpdateDistanceLimit()

• setUpdateDistanceLimit()
• getUpdateDistanceLimit()

getProjections()->setConfiguratorEnabled()

getProjections()->setEnabled(false);

( getProjections()->isEnabled() == false )

New Functions#

New Functions#

New Functions#

New Functions#