This page has been translated automatically.
Video Tutorials
Interface
Essentials
Advanced
How To
Professional (SIM)
UnigineEditor
Interface Overview
Assets Workflow
Settings and Preferences
Working With Projects
Adjusting Node Parameters
Setting Up Materials
Setting Up Properties
Lighting
Sandworm
Using Editor Tools for Specific Tasks
Extending Editor Functionality
Built-in Node Types
Nodes
Objects
Effects
Decals
Light Sources
Geodetics
World Nodes
Sound Objects
Pathfinding Objects
Players
Programming
Fundamentals
Setting Up Development Environment
Usage Examples
C++
C#
UnigineScript
UUSL (Unified UNIGINE Shader Language)
Plugins
File Formats
Materials and Shaders
Rebuilding the Engine Tools
GUI
Double Precision Coordinates
API
Containers
Common Functionality
Controls-Related Classes
Engine-Related Classes
Filesystem Functionality
GUI-Related Classes
Math Functionality
Node-Related Classes
Objects-Related Classes
Networking Functionality
Pathfinding-Related Classes
Plugins-Related Classes
IG Plugin
CIGIConnector Plugin
Rendering-Related Classes
Content Creation
Content Optimization
Materials
Material Nodes Library
Miscellaneous
Input
Math
Matrix
Textures
Art Samples
Tutorials
Warning! This version of documentation is OUTDATED, as it describes an older SDK version! Please switch to the documentation for the latest SDK version.
Warning! This version of documentation describes an old SDK version which is no longer supported! Please upgrade to the latest SDK version.

Unigine.Physics Class

Controls the simulation of physics. For more information on principles and implementation of physics in real-time rendering, see the articles Execution Sequence, Physics and Simulation of Physics.

See Also#

  • The Creating a Car with Suspension Joints usage example demonstrating how to set up physics parameters
  • A set of UnigineScript API samples located in the <UnigineSDK>/data/samples/physics/ folder

Physics Class

Enums

UPDATE_MODE#

Physics update mode.
NameDescription
BEFORE_RENDERING = 0Update Before Rendering. Physics update (along with the spatial tree update and user callbacks) is executed in the Main thread just before rendering is performed (render). The number of physics ticks executed before the rendering frame here is defined by the physics and the Engine framerates. This mode is the most clear and straightforward (everything is executed safely in a strictly determined order) with no frame lag (results of physics calculations are applied in the current frame). But, on the other hand, this mode is the slowest as there are no asynchronous parallel calculations (everything's in the Main thread). Use this mode in case the time lag is unacceptabe for your application (you need all physics calculations to be applied in the current frame) and you want maximum simplicity and strictly determined order of execution for user code (physicsUpdate and physics callbacks).
ASYNC_RENDERING = 1Asynchronous update mode. Physics update is performed asynchronously to rendering. In case of several physics ticks per one rendering frame (when the Engine framerate is lower, or catching up is performed), only the first one is executed in parallel, then the physics module waits for the completion of the rendering process, returns to the Main thread and executes the rest of the physics ticks. There is a frame lag (results of physics calculations are applied in the next frame) and there is some ambiguity regarding the time, when user code (physicsUpdate and physics callbacks) is to be executed in case of several physics ticks per one rendering frame (some part is executed before rendering while the other just after it). This mode is the fastest one and is used by default.

Properties

float TotalTime#

The total time that both rendering and calculating of the frame took (the duration of the main loop in the application execution sequence).

float SimulationTime#

The duration of all of the simulation phases added together.

float ResponseTime#

The duration value of the response phase, in which collision response is calculated and joints are solved.

int NumJoints#

The number of joints within the physics radius.

int NumIslands#

The number of physical islands within the physics radius that could be calculated separately. The lower this number, the less efficient multi-threading is, if enabled.

int NumContacts#

The number of contacts within the physics radius; it includes contacts between the bodies (their shapes) and body-mesh contacts.

int NumBodies#

The number of bodies present within the physics radius.

float CollisionTime#

The duration of the collision detection phase, during which collisions between objects are found.

float IntegrateTime#

The duration of the integrate phase, in which physics simulation results are applied to bodies.

int Frame#

The current frame of physics update.

int NumIterations#

The current number of iterations used to solve contacts and constraints.

int NumFrozenFrames#

The current number of frames, during which an object should keep certain angular and linear velocities to become frozen.

float CurrentSubframeTime#

The current time that can be used when shifting between physics update frames.

float Scale#

The value used to scale a frame duration.

float PenetrationTolerance#

The value indicating how deeply one object can penetrate another.

float PenetrationFactor#

The penalty force factor. 0 means no penalty force in contacts. The maximum value is 1.

float MaxLinearVelocity#

The current maximum possible linear velocity.

float MaxAngularVelocity#

The current maximum possible angular velocity.

float LinearDamping#

The current linear damping value.

float IFps#

The physics frame duration.

vec3 Gravity#

The current gravity value.

float FrozenLinearVelocity#

The current linear velocity threshold for freezing object simulation. an object stops to be updated if its linear velocity remains lower than this threshold during the number of Frozen frames (together with angular one).

float FrozenAngularVelocity#

The current angular velocity threshold for freezing object simulation. an object stops to be updated if its angular velocity remains lower than this threshold during the number of Frozen frames (together with linear one).

float AngularDamping#

The current angular damping value.

float Distance#

The distance after which the physics will not be simulated.

float Budget#

The physics simulation budget. physics isn't simulated when time is out of the budget.

string Data#

The User string data associated with the world. this string is written directly into the data tag of the *.world file.

bool SyncEngineUpdateWithPhysics#

The flag indicating if the Engine fps is synchronized to physics one. Such fps limitation makes it possible to calculate physics each rendered frame (rather then interpolate it when this flag is unset). In this mode, there are no twitching of physical objects if they have non-linear velocities. If the Engine fps is lower than the physics one, this flag has no effect.

bool Determinism#

The value indicating if objects are updated in a definite order or not. the default is 0 (the update order may change). Deterministic mode ensures that all contacts are solved in the predefined order and visualization of physics in the world is repetitive (on one computer). When this mode is enabled the Engine performs additional sorting of bodies, shapes and joints inside islands after building them. Deterministic mode is unavailable in case there are missed frames - it is simply impossible. Moreover, there may be differences between visualization of physics on different hardware (e.g., AMD and Intel).
Notice
Determinism is guaranteed if there are no missed frames, the same Engine version is used, and the CPUs perform SSE operations similarly.
Please note that deterministic mode does not come for free, it may eat up 10-20% of the frame rate, and it also depends on the scene a lot.

bool Enabled#

The value indicating if physics simulation is enabled. the default is 1.

float MissedFrameLifetime#

The lifetime for missed frames. This value defines how long missed frames are to be kept in the catch-up buffer. In case the current Engine framerate is lower than the fixed Physics framerate, some of the physics frames get skipped and the simulation starts looking like in a slo-mo effect (e.g., if the target physics framerate is 60 FPS, when the Engine updates at 30 FPS, the simulation will look 2 times slower). The Physics module will try to catch up everything missed later, when possible (e.g. when the Engine framerate grows higher, while waiting for GPU to complete rendering). The missed frames are kept in a buffer for some time (lifetime), as it expires the frame is removed from the buffer and becomes lost forever.

Physics.UPDATE_MODE UpdateMode#

The current physics update mode. Physics can be updated either asynchronously (in parallel with rendering) or in the Main thread before rendering. The async mode is the fastest one and is used by default, however, it has a one-frame lag (calculation results are applied in the next frame) and some nuances regarding user code execution in some cases.

bool StableFPS#

The value indicating if frame time stabilization is enabled. In case the current Engine framerate is much higher than the fixed Physics framerate (e.g. 120 FPS vs 60 FPS), the physics won't be updated each rendering frame (e.g. it may update during every second frame). The resulting frame time will become unstable, shorter-longer-shorter-longer (render -> render+physics -> render -> render+physics...). This option ensures stable frame time for smoother user experience removing unwanted "hiccups" (however, the average framerate is decreased).
Notice
By default, this option is enabled. But you can disable it to increase average framerate in case the application is used for machine learning or for grabbing frame sequences (video grabber), when smoothness is not important.

Members


Body GetBody ( int id ) #

Returns a body with a given ID.

Arguments

  • int id - Body ID.

Return value

Body with a given ID or NULL (0), if there is no body with a given ID.

int IsBody ( int id ) #

Checks if a body with a given ID exists.

Arguments

  • int id - Body ID.

Return value

1 if a body with a given ID exists; otherwise, 0.

Object GetIntersection ( vec3 p0, vec3 p1, int mask, Node[] exclude, PhysicsIntersection intersection ) #

Performs tracing from the p0 point to the p1 point to find a collision object located on that line. If an object is assigned a body, intersection occurs with its shape. If an object has no body, this function detects intersection with surfaces (polygons) of objects with intersection flag set. Intersection is found only for objects with a matching mask if their ID is not found in the exclude list. Intersection is Intersection does not work for disabled objects.

Notice
This function uses world space coordinates.

Arguments

  • vec3 p0 - Line start point coordinates.
  • vec3 p1 - Line end point coordinates.
  • int mask - Physics intersection mask. If 0 is passed, the function will return NULL.
  • Node[] exclude - Array of nodes to be excluded.
  • PhysicsIntersection intersection - PhysicsIntersection class instance containing intersection data.

Return value

The first intersected object, if found; otherwise, 0.

Object GetIntersection ( vec3 p0, vec3 p1, int mask, PhysicsIntersection intersection ) #

Performs tracing from the p0 point to the p1 point to find a collision object located on that line. If an object is assigned a body, intersection occurs with its shape. If an object has no body, this function detects intersection with surfaces (polygons) of objects with intersection flag set. Physics intersection shall only be detected for objects with a matching mask. Intersection does not work for disabled objects.

Notice
This function uses world space coordinates.

Usage Example

The following example shows how you can get the intersection information by using the PhysicsIntersection class. In this example we specify a line from the point of the camera (vec3 p0) to the point of the mouse pointer (vec3 p1). The executing sequence is the following:

  1. Define and initialize two points (p0 and p1) by using the Player.GetDirectionFromScreen() function.
  2. Create an instance of the PhysicsIntersection class to get the intersection information.
  3. Check, if there is an intersection with an object with a shape or a collision object. The GetIntersection() function returns an intersected object when the object intersects with the traced line.
  4. When the object intersects with the traced line, all surfaces of the intersected object change their material parameters. If the object has a shape, its information will be shown in console. The PhysicsIntersection class instance gets the coordinates of the intersection point and the Shape class object. You can get all these fields by using the Shape, Point properties.
Source code (C#)
private void Update()
{
	// initialize points of the mouse direction
	Vec3 p0, p1;

	// get the current player (camera)
	Player player = Game.Player;
		
	// get the size of the current application window
	EngineWindow main_window = WindowManager.MainWindow;
	if (!main_window)
	{
		Engine.Quit();
		return;
	}

	ivec2 main_size = main_window.Size;

	// get the current X and Y coordinates of the mouse pointer
	int mouse_x = Gui.GetCurrent().MouseX;
	int mouse_y = Gui.GetCurrent().MouseY;
	// get the mouse direction from the player's position (p0) to the mouse cursor pointer (p1)
	player.GetDirectionFromScreen(out p0, out p1, mouse_x, mouse_y, 0, 0, main_size.x, main_size.y);

	// create the instance of the PhysicsIntersection object to save the information about the intersection
	PhysicsIntersection intersection = new PhysicsIntersection();
	// get an intersection
	Unigine.Object obj = Physics.GetIntersection(p0, p1, 1, intersection);

	// if the intersection has occurred, change the parameter of the object's material    
	if (obj != null)
	{
		for (int i = 0; i < obj.NumSurfaces; i++)
		{
			obj.SetMaterialParameterFloat4("albedo_color", new vec4(1.0f, 1.0f, 0.0f, 1.0f), i);
		}

		// if the intersected object has a shape, show the information about the intersection   
		Shape shape = intersection.Shape;
		if (shape != null)
		{
			Log.Message("physics intersection info: point: ({0} {1} {2}) shape: {3}\n", intersection.Point.x, intersection.Point.y, intersection.Point.z, shape.TypeName);
		}
	}
	
}

Arguments

  • vec3 p0 - Line start point coordinates.
  • vec3 p1 - Line end point coordinates.
  • int mask - Physics intersection mask. If 0 is passed, the function will return NULL.
  • PhysicsIntersection intersection - PhysicsIntersection class instance containing intersection data.

Return value

The first intersected object, if found; otherwise, 0.

Object GetIntersection ( vec3 p0, vec3 p1, int mask, PhysicsIntersectionNormal intersection ) #

Performs tracing from the p0 point to the p1 point to find a collision object located on that line. If an object is assigned a body, intersection occurs with its shape. If an object has no body, this function detects intersection with surfaces (polygons) of objects with intersection flag set. Physics intersection shall only be detected for objects with a matching mask. Intersection does not work for disabled objects.

Notice
This function uses world space coordinates.

Arguments

Return value

The first intersected object, if found; otherwise, 0.

Object GetIntersection ( vec3 p0, vec3 p1, int mask, Node[] exclude, PhysicsIntersectionNormal intersection ) #

Performs tracing from the p0 point to the p1 point to find a collision object located on that line. If an object is assigned a body, intersection occurs with its shape. If an object has no body, this function detects intersection with surfaces (polygons) of objects with intersection flag set. Intersection is found only for objects with a matching mask if their ID is not found in the exclude list. Intersection is Intersection does not work for disabled objects.

Notice
This function uses world space coordinates.

Arguments

  • vec3 p0 - Line start point coordinates.
  • vec3 p1 - Line end point coordinates.
  • int mask - Physics intersection mask. If 0 is passed, the function will return NULL.
  • Node[] exclude - Array of nodes to be excluded.
  • PhysicsIntersectionNormal intersection - PhysicsIntersectionNormal class instance containing intersection data.

Return value

The first intersected object, if found; otherwise, 0.

Joint GetJoint ( int id ) #

Returns a joint with a given ID.

Arguments

  • int id - Joint ID.

Return value

Joint with a given ID or NULL (0), if there is no joint with a given ID.

int IsJoint ( int id ) #

Checks if a joint with a given ID exists.

Arguments

  • int id - Joint ID.

Return value

1 if a joint with a given ID exists; otherwise, 0.

Shape GetShape ( int id ) #

Returns a shape with a given ID.

Arguments

  • int id - Shape ID.

Return value

Shape with a given ID or NULL (0), if there is no shape with a given ID.

int IsShape ( int id ) #

Checks if a shape with a given ID exists.

Arguments

  • int id - Shape ID.

Return value

1 if a shape with a given ID exists; otherwise, 0.

void AddUpdateNode ( Node node ) #

Adds the node for which physical state should be updated. If a node is not added with this function, it won't be updated when out of physics simulation distance.

Arguments

  • Node node - Node to be updated.

void addUpdateNodes ( Node[] nodes ) #

Adds the nodes for which physical state should be updated. If nodes are not added with this function, they won't be updated when out of physics simulation distance.

Arguments

  • Node[] nodes - Nodes to be updated.

int LoadSettings ( string name, bool clear = false ) #

Loads the physics settings from a given file.

Arguments

  • string name - Path to an XML file with desired settings.
  • bool clear - Clear flag. Set true to clear settings before loading (new settings shall be applied right after loading them), or false not to clear.

Return value

Returns 1 if the settings are loaded successfully; otherwise, 0.

int LoadWorld ( Xml xml ) #

Loads physics settings from the Xml.

Arguments

  • Xml xml - Xml node.

Return value

Returns 1 if settings are loaded successfully; otherwise, 0.

int SaveScene ( ) #

Saves the current physics scene (physical properties of all objects) into the buffer.

Return value

Scene buffer ID.

int RestoreScene ( int id ) #

Restores the previously saved physics scene from the buffer.

Arguments

  • int id - ID number of the scene.

Return value

Returns 1 if the scene is restored successfully; otherwise, 0.

int RemoveScene ( int id ) #

Removes the previously saved physics scene.

Arguments

  • int id - ID number of the scene.

Return value

Returns 1 if the scene is removed successfully; otherwise, 0.

bool SaveState ( Stream stream ) #

Saves physics settings into the stream.

Example using saveState() and restoreState() methods:

Source code (C#)
// set state
Physics.NumIterations = 1; // NumIterations = 1
	
// save state
Blob blob_state = new Blob();
Physics.SaveState(blob_state);
	
// change state
Physics.NumIterations = 16; // now NumIterations = 16
	
// restore state
blob_state.SeekSet(0);		// returning the carriage to the start of the blob
Physics.RestoreState(blob_state); // restore NumIterations = 1

Arguments

  • Stream stream - Stream to save settings into.

Return value

true if settings are saved successfully; otherwise, false.

bool RestoreState ( Stream stream ) #

Restores physics settings from the stream.

Example using saveState() and restoreState() methods:

Source code (C#)
// set state
Physics.NumIterations = 1; // NumIterations = 1
	
// save state
Blob blob_state = new Blob();
Physics.SaveState(blob_state);
	
// change state
Physics.NumIterations = 16; // now NumIterations = 16
	
// restore state
blob_state.SeekSet(0);		// returning the carriage to the start of the blob
Physics.RestoreState(blob_state); // restore NumIterations = 1

Arguments

  • Stream stream - Stream to restore settings from.

Return value

true if settings are restored successfully; otherwise, false.

bool SaveSettings ( string name, int force = 0 ) #

Saves the current physics settings to a given file.

Arguments

  • string name - Path to a target file.
  • int force - Forced saving of physics settings.

Return value

true if the settings are saved successfully; otherwise, false.

bool SaveWorld ( Xml xml, int force = 0 ) #

Saves physics settings to the given Xml node.

Arguments

  • Xml xml - Xml node.
  • int force - Forced saving of physics settings.

Return value

true if settings are saved successfully; otherwise, false.
Last update: 2022-12-14
Build: ()