This page has been translated automatically.
UnigineEditor
Interface Overview
Assets Workflow
Settings and Preferences
Adjusting Node Parameters
Setting Up Materials
Setting Up Properties
Landscape Tool
Using Editor Tools for Specific Tasks
FAQ
Programming
Fundamentals
Setting Up Development Environment
Usage Examples
UnigineScript
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
Engine-Related Classes
Filesystem Functionality
GUI-Related Classes
Math Functionality
Node-Related Classes
Objects-Related Classes
Networking Functionality
Pathfinding-Related Classes
Plugins-Related Classes
CIGI Client Plugin
Rendering-Related Classes
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.Body Class

This class is used to simulate physical bodies that allow an object to participate in physical interactions. A body can have one or several collision shapes assigned and can be connected together with joints. To transform a body, one of the following functions can be used:

All of these functions take effect when physics calculations are over and flush() is performed. Only after that transformations of the body are applied to the rendered node. If a node needs to be transformed immediately after its physical body, flushTransform() is to be called.

The simulation of the body can be frozen (if a setFrozen flag is set).

You can set callbacks for a body to handle certain events:

See Also#

  • The Creating and Attaching a Cloth usage example demonstrating how to create objects, assign bodies, and add shapes to them
  • A C++ API sample located in the <UnigineSDK>/source/samples/Api/Physics/BodyCallbacks folder
  • A C# API sample located in the <UnigineSDK>/source/csharp/samples/Api/Physics/BodyCallbacks folder
  • A set of UnigineScript API samples located in the <UnigineSDK>/data/samples/physics/ folder:
    • callbacks_00
    • callbacks_01
    • callbacks_02

Body Class

Properties

int NumContacts#

The number of contacts in which the body participates and which it handles.
Notice
A contact can be handled by any of the bodies that participate in it. To which body it will be assigned is completely random. If the contact is assigned to and handled by another body, the number of contacts for the current body is not incremented.
To detect all contacts in which the body participates addContactCallback() should be used.

int NumJoints#

The number of joints in the body.

int NumShapes#

The number of shapes comprising the body.

int NumChildren#

The number of child bodies.

quat Rotation#

The body rotation.
set
Updates the body rotation (in world coordinates).
set value - New rotation in the world coordinates.

Vec3 Position#

The body position.
set
Updates the body position (in world coordinates). Body's linear and angular velocities will be reset to 0.
set value - New position in the world coordinates.

Mat4 Transform#

The transformation matrix of the body (in world coordinates). this matrix describes position and orientation of the body.
set
Sets a transformation matrix for the body (in world coordinates). This method resets body's linear and angular velocities to defaults, sets forces and torques to zeros, nullifies counted down frozen frames. It is called, for example, when the node is dragged to a new position in the editor.
set value - Transformation matrix. This matrix describes position, orientation and scale of the body.

int PhysicalMask#

The bit mask for interactions with physicals. Two objects interact, if they both have matching masks.
set
Sets the bit mask for interactions with physicals. Two objects interact, if they both have matching masks.
set value - Integer, each bit of which is a mask.

string Name#

The name of the body.
set
Sets the name of the body.
set value - Name of the body.

bool IsGravity#

A value indicating if gravity is affecting the body.
set
Sets a value indicating if gravity is affecting the body.
set value - 1 if the body is affected by gravity; otherwise, 0.

bool IsImmovable#

Return a value indicating if the body is immovable (static).
set
Sets a value indicating if the body is immovable (static).
set value - 1 if the body is immovable (static); otherwise, 0.

bool IsFrozen#

A value indicating if the body is frozen. When a body is frozen, it is not simulated (though its contacts are still calculated), until a collision with a frozen body occurs or some force is applied.
set
Freezes or unfreezes the body. When a body is frozen, it is not simulated (though its contacts are still calculated), until a collision with a frozen body occurs or some force is applied.
set value - 1 to freeze the object, 0 to unfreeze it.

bool IsEnabledSelf#

A value indicating if the body is enabled.

bool IsEnabled#

A value indicating if physical interactions with the body are enabled.
set
Enables or disables physical interactions with the body.
set value - 1 to enable physical interactions, 0 to disable them.

string TypeName#

The name of the body type.

int Type#

The type of the body.

int ID#

The unique id of the body.
set
Sets the unique ID for the body.
set value - Unique ID.

Object Object#

The object, which is approximated with the body.
set
Sets an object, which the body approximates.
set value - Object to approximate.

Members


Body CreateBody ( int type ) #

Creates a new body of the specified type.

Arguments

  • int type - Body type. One of the BODY_* values.

Return value

New created body instance.

Body CreateBody ( string type_name ) #

Creates a new body of the specified type.

Arguments

  • string type_name - Body type name.

Return value

New created body instance.

Body GetBody ( ) #

Returns the pointer to the Body class instance.

Return value

Body instance.

string GetTypeName ( int type ) #

Returns the name of a body type with a given ID.

Arguments

  • int type - Body type ID. One of the BODY_* values.

Return value

Body type name.

void SetObject ( Object val ) #

Sets an object, which the body approximates.

Arguments

  • Object val - Object to approximate.

Object GetObject ( ) #

Returns the object, which is approximated with the body.

Return value

Approximated object.

void SetPreserveTransform ( Mat4 transform ) #

Sets a transformation matrix for the body (in world coordinates). This method safely preserves body's linear and angular velocities. It changes only body coordinates - all other body parameters stay the same.

Arguments

  • Mat4 transform - Transformation matrix. This matrix describes position, orientation and scale of the body.

void SetVelocityTransform ( Mat4 transform ) #

Sets a transformation matrix (in world coordinates) and computes linear and angular velocities of the body depending on its trajectory from the current position to the specified one. The time used in calculations corresponds to physics ticks. It clears forces and torques to zeros and nullifies counted down frozen frames.

Arguments

  • Mat4 transform - Transformation matrix. This matrix describes position, orientation and scale of the body.

void FlushTransform ( ) #

Forces to set the transformations of the body for the node.

void SetDirection ( vec3 dir, vec3 up ) #

Updates the direction vector of the body (in world coordinates). By default, a direction vector points along -Z axis. This function changes its direction and reorients the body.

Arguments

  • vec3 dir - New direction vector in the world coordinates. The direction vector always has unit length.
  • vec3 up - New up vector in the world coordinates.

vec3 GetDirection ( ) #

Returns the normalized direction vector of the body (in world coordinates). By default, a direction vector points along -Z axis. It always has an unit length.

Return value

Normalized direction vector in the world coordinates.

Body GetParent ( ) #

Returns the parent of the current body.

Return value

Parent body.

int IsChild ( Body body ) #

Checks if a given body is a child of the current body.

Arguments

  • Body body - Body to check.

Return value

1 if the provided body is a child; otherwise, 0.

int FindChild ( string name ) #

Searches for a child body with a given name.

Arguments

  • string name - Name of the child body.

Return value

Number of the child in the list of children, if it is found; otherwise, -1.

Body GetChild ( int num ) #

Returns a given child body.

Arguments

  • int num - Child number.

Return value

Corresponding body.

void AddShape ( Shape shape, mat4 transform ) #

Adds a shape to the list of shapes comprising the body.

Arguments

  • Shape shape - New shape to add.
  • mat4 transform - Shape transformation matrix (in the body's coordinate system).

void AddShape ( Shape shape ) #

Adds a shape to the list of shapes comprising the body.

Arguments

  • Shape shape - New shape to add.

void RemoveShape ( Shape shape, bool destroy = 0 ) #

Removes a given shape from the body.

Arguments

  • Shape shape - Shape to be removed.
  • bool destroy - Flag indicating whether the shape is to be destroyed after removal: use 1 to destroy the shape after removal, or 0 if you plan to use the shape later. The default value is 0.

void RemoveShape ( int num, bool destroy = 0 ) #

Removes a shape with a given number from the body.

Arguments

  • int num - Shape number.
  • bool destroy - Flag indicating whether the shape is to be destroyed after removal: use 1 to destroy the shape after removal, or 0 if you plan to use the shape later. The default value is 0.

void ClearShapes ( int destroy = 0 ) #

Clears all shapes from the body.

Arguments

  • int destroy - Flag indicating whether shapes are to be destroyed after removal: use 1 to destroy shapes after removal, or 0 if you plan to use them later. The default value is 0.

int IsShape ( Shape shape ) #

Checks if a given shape belongs to the body.

Arguments

  • Shape shape - Shape to check.

Return value

1 if the shape belongs to the body; otherwise, 0.

bool InsertShape ( int pos, Shape shape ) #

Inserts a given shape at the specified position in the list of body's shapes.

Arguments

  • int pos - Position in the list at which the shape is to be inserted in the range from 0 to the number of shapes.
  • Shape shape - Shape to be inserted.

Return value

1 if a shape was successfully inserted; otherwise, 0.

bool InsertShape ( int pos, Shape shape, mat4 transform ) #

Inserts a given shape at the specified position in the list of body's shapes and sets the specified transformation for it.

Arguments

  • int pos - Position in the list at which the shape is to be inserted in the range from 0 to the number of shapes.
  • Shape shape - Shape to be inserted.
  • mat4 transform - Shape's transformation (in the body's coordinate system).

Return value

1 if a shape was successfully inserted; otherwise, 0.

int FindShape ( string name ) #

Searches for a shape with a given name.

Arguments

  • string name - Name of the shape.

Return value

Number of the shape in the list of shapes, if it is found; otherwise, -1.

Shape GetShape ( int num ) #

Returns a given shape.

Arguments

  • int num - Shape number.

Return value

Corresponding shape object.

void SetShapeTransform ( int num, mat4 transform ) #

Sets a transformation matrix for a given shape (in local coordinates). This matrix describes position and orientation of the shape.

Arguments

  • int num - Shape number.
  • mat4 transform - Transformation matrix (in the body's coordinate system).

mat4 GetShapeTransform ( int num ) #

Returns the transformation matrix of a given shape (in local coordinates). This matrix describes position and orientation of the shape.

Arguments

  • int num - Shape number.

Return value

Transformation matrix.

void UpdateShapes ( ) #

Updates all shapes of the body.

void AddJoint ( Joint joint ) #

Adds a joint to the body.

Arguments

  • Joint joint - New joint to add.

void RemoveJoint ( Joint joint ) #

Removes a given joint from the body.

Arguments

  • Joint joint - Joint to be removed.

void RemoveJoint ( int num ) #

Removes a joint with a given number from the body.

Arguments

  • int num - Joint number.

void InsertJoint ( Joint joint, int num ) #

Inserts a given joint at the specified position in the list of body's joints.

Arguments

  • Joint joint - Joint to be inserted.
  • int num - Position in the list at which the joint is to be inserted in the range from 0 to the number of joints.

int IsJoint ( Joint joint ) #

Checks if a given joint belongs to the body.

Arguments

  • Joint joint - Joint to check.

Return value

1 if the joint belongs to the body; otherwise, 0.

int FindJoint ( string name ) #

Searches for a joint with a given name.

Arguments

  • string name - Name of the joint.

Return value

Number of the joint in the list of joints, if it is found; otherwise, -1.

Joint GetJoint ( int num ) #

Returns a given joint.

Arguments

  • int num - Joint number.

Return value

Corresponding joint.

Shape GetIntersection ( Vec3 p0, Vec3 p1, int mask, Vec3[] ret_point, vec3[] ret_normal ) #

Performs tracing from the p0 point to the p1 point to find a body shape intersected by this line. Intersection is found only for objects with a matching intersection mask. On success ret_point and ret_normal shall contain information about intersection.

Notice
World space coordinates are used for this function.

Arguments

  • Vec3 p0 - Start point of the line (in world coordinates).
  • Vec3 p1 - End point of the line (in world coordinates).
  • int mask - Intersection mask.
  • Vec3[] ret_point - Container to which contact point coordinates (if any) shall be put (in world coordinate system).
  • vec3[] ret_normal - Container to which contact point normal coordinates (if any) shall be put (in world coordinate system).

Return value

First intersected shape, if found; otherwise, 0.

int GetContactID ( int num ) #

Returns the contact ID by the contact number.

Arguments

  • int num - Contact number.

Return value

Contact ID.

Vec3 GetContactPoint ( int num ) #

Returns world coordinates of the contact point.

Arguments

  • int num - Contact number.

Return value

Contact point (in world coordinates).

vec3 GetContactNormal ( int num ) #

Returns a normal of the contact point, in world coordinates.

Arguments

  • int num - Contact number.

Return value

Contact normal (in world coordinates).

vec3 GetContactVelocity ( int num ) #

Returns relative velocity at the given contact point.

Arguments

  • int num - Contact number.

Return value

Velocity vector.

float GetContactImpulse ( int num ) #

Returns the relative impulse at the given contact point.

Arguments

  • int num - Contact number.

Return value

Impulse value.

float GetContactTime ( int num ) #

Returns the time when the given contact occurs. By CCD (for spheres or capsules), it returns the time starting from the current physics simulation tick to the moment when the calculated contact is bound to happen. By non-continuous collision detection, 0 is always returned.

Arguments

  • int num - Contact number.

Return value

Time of the calculated contact to happen, in seconds.

float GetContactDepth ( int num ) #

Returns the depth by which the body penetrated with an obstacle by the given contact. This distance is measured along the contact normal.

Arguments

  • int num - Contact number.

Return value

Penetration depth, in units.

float GetContactFriction ( int num ) #

Returns relative friction at the given contact point.

Arguments

  • int num - Contact number.

Return value

Friction value.

float GetContactRestitution ( int num ) #

Returns relative restitution at the given contact point.

Arguments

  • int num - Contact number.

Return value

Restitution.

Body GetContactBody0 ( int num ) #

Returns the first body participating in a given contact. This is not necessarily the current body.

Arguments

  • int num - Contact number.

Return value

First body.

Body GetContactBody1 ( int num ) #

Returns the second body participating in a given contact. This is not necessarily the current body.

Arguments

  • int num - Contact number.

Return value

Second body.

Shape GetContactShape0 ( int num ) #

Returns the first shape participating in a given contact. This shape does not necessarily belong to the current body.

Arguments

  • int num - Contact number.

Return value

First shape.

Shape GetContactShape1 ( int num ) #

Returns the second shape participating in a given contact. This shape does not necessarily belong to the current body.

Arguments

  • int num - Contact number.

Return value

Second shape.

Object GetContactObject ( int num ) #

Returns an object participating in the contact (used for collisions with non-physical object).

Arguments

  • int num - Contact number.

Return value

Object in contact.

int GetContactSurface ( int num ) #

Returns the surface of the current object, which is in contact (used for collisions with non-physical object).

Arguments

  • int num - Contact number.

Return value

Surface number.

IntPtr addFrozenCallback ( FrozenDelegate func ) #

Adds a callback function to be called when a given body freezes. The signature of the frozen callback function must be as follows:
Source code (C#)
void frozen_callback_function_name(Body body);

You can set a callback function as follows:

Source code (C#)
addFrozenCallback(b => frozen_callback_function_name(b));
Notice
Physics-based callbacks are executed in parallel with the main tread, so you should not modify nodes inside these functions. If you want to reposition, transform, create or delete nodes captured by your callback function, you can store them in the array and then perform all necessary operations in the update(). See the example for contact callbacks

Example: Setting a body frozen callback function for a certain class:

Source code (C#)
class SomeClass
{
	// body for which a frozen callback function is to be set
	Unigine.Body body;

	/*...*/

	// callback function
	private void on_freezing(Body body)
	{
		// insert your code handling freezing here
	}

	private void registerCallback()
	{
		// setting the on_freezing() function to handle freezing for the body
		body.addFrozenCallback(b => on_freezing(b));
	}
	
	/*...*/
}
Notice
Physics-based callbacks are not executed immediately, but before the next flush() or next update() of the world script.

Arguments

  • FrozenDelegate func - Callback function with the following signature: void FrozenDelegate(Body body)

Return value

ID of the last added frozen callback, if the callback was added successfully; otherwise, nullptr. This ID can be used to remove this callback when necessary.

bool removeFrozenCallback ( IntPtr id ) #

Removes the specified callback from the list of frozen callbacks.

Arguments

  • IntPtr id - Frozen callback ID obtained when adding it.

Return value

True if the frozen callback with the given ID was removed successfully; otherwise false.

void clearFrozenCallbacks ( ) #

Clears all added frozen callbacks.

IntPtr addPositionCallback ( PositionDelegate func ) #

Adds a callback function to be called when a given body moves a certain distance (rotation is not taken into account). The signature of the position callback function must be as follows:
Source code (C#)
void position_callback_function_name(Body body);

You can set a callback function as follows:

Source code (C#)
addPositionCallback(b => position_callback_function_name(b));
Notice
Physics-based callbacks are executed in parallel with the main tread, so you should not modify nodes inside these functions. If you want to reposition, transform, create or delete nodes captured by your callback function, you can store them in the array and then perform all necessary operations in the update(). See the example for contact callbacks

Example: Setting a body position callback function for a certain class:

Source code (C#)
class SomeClass
{
	// body for which a position callback function is to be set
	Unigine.Body body;

	/*...*/

	// callback function
	private void on_position(Body body)
	{
		// insert your code handling position changes here
	}

	private void registerCallback()
	{
		// setting the on_position() function to handle position changes for the body
		body.addPositionCallback(b => on_position(b));
	}
	
	/*...*/
}
Notice
Physics-based callbacks are not executed immediately, but before the next flush() or next update() of the world script.

Arguments

  • PositionDelegate func - Callback function with the following signature: void PositionDelegate(Body body)

Return value

ID of the last added position callback, if the callback was added successfully; otherwise, nullptr. This ID can be used to remove this callback when necessary.

bool removePositionCallback ( IntPtr id ) #

Removes the specified callback from the list of position callbacks.

Arguments

  • IntPtr id - Position callback ID obtained when adding it.

Return value

True if the position callback with the given ID was removed successfully; otherwise false.

void clearPositionCallbacks ( ) #

Clears all added position callbacks.

IntPtr addContactCallback ( ContactDelegate func ) #

Adds a callback function to be called when a contact with the body emerges. The body might have no information on some of its contacts with other physical bodies, as these contacts can be handled by other bodies. The contact callback function is to be used to detect all contacts in which the body participates.
Notice
Physics-based callbacks are not executed immediately, but before the next flush() or next update() of the world script.
The signature of the contact callback function must be as follows:
Source code (C#)
void contact_callback_function_name(Body body, int num);

You can set a callback function as follows:

Source code (C#)
addContactCallback((b, num) => contact_callback_function_name(b, num));

Example: Setting a body contact callback function for a certain class:

Source code (C#)
class SomeClass
{
	// body for which a contact callback function is to be set
	Unigine.Body body;

	/*...*/

	// callback function
	private void contact_callback(Body body, int num)
	{
		// insert your code handling contacts here
	}

	private void registerCallback()
	{
		// setting the on_position() function to handle contacts for the body
		body.addContactCallback((b, num) => contact_callback(b, num));
	}
	
	/*...*/
}
Notice
Physics-based callbacks are executed in parallel with the main tread, so you should not modify nodes inside these functions.

If you want to reposition, transform, create or delete nodes captured by your callback function, you can store them in the array and then perform all necessary operations in the update():

Source code (C#)
// list of collisions that were processed by other bodies
List<Body> unregistered_collisions = new List<Body>();

// flag indicating if collisions were detected
bool collision_detected = false;

/*...*/

private void contact_callback(Body body, int num)
{
	// collision was detected
	collision_detected = true;

	// if the collision is processed by other body, adding it to the list
	if (body != this_body)
		unregistered_collisions.Add(body);
}

/*...*/

public override int update()
{
	if (collision_detected)
	{
		// resetting collision flag
		collision_detected = false;
		for (int i = 0; i < body.getNumContacts(); i++)
		{
			// process all nodes with which collisions were registered
			Node node = body.getContactObject(i).getNode();

			// changing node's rotation
			if (node.checkPtr())
				node.setRotation(new quat(0.0f, 1.0f, 0.0f, 90.0f));
		}
		for (int i = 0; i < unregistered_collisions.Count; i++)
		{
			// process all unregistered collisions
			Node node = unregistered_collisions[i].getObject().getNode();

			// deleting a node
			if (node.checkPtr())
				Editor.get().removeNode(node);
        }
		// clearing the list of unregistered collisions after processing them
		unregistered_collisions.Clear();
	}
}

Arguments

  • ContactDelegate func - Callback function with the following signature: void ContactDelegate(Body body, int num)

Return value

ID of the last added contact callback, if the callback was added successfully; otherwise, nullptr. This ID can be used to remove this callback when necessary.

bool removeContactCallback ( IntPtr id ) #

Removes the specified callback from the list of contact callbacks.

Arguments

  • IntPtr id - Contact callback ID obtained when adding it.

Return value

True if the contact callback with the given ID was removed successfully; otherwise false.

void clearContactCallbacks ( ) #

Clears all added contact callbacks.

void RenderContacts ( ) #

Renders contact points of the body.

void RenderJoints ( ) #

Renders joints in the body.

void RenderShapes ( ) #

Renders shapes comprising the body.

void RenderVisualizer ( ) #

Renders shapes, joints and contact points of the body.
Notice
You should enable the engine visualizer by the show_visualizer 1 console command.

Body Clone ( Object object ) #

Clones the body and assigns a copy to a given object.

Arguments

  • Object object - Object, to which the copy will be assigned.

Return value

Copy of the body.

void Swap ( Body body ) #

Swaps the bodies saving the pointers.

Arguments

  • Body body - Body to swap.

int SaveState ( Stream stream ) #

Saves the state of a given node into a binary stream.
  • If a node is a parent for other nodes, states of these child nodes need to be saved manually.
  • To save the state from a buffer, file or a message from a socket, make sure the stream is opened. For buffers and files, you also need to set the proper position for reading.
Warning
This function is deprecated and will be removed in the next release.

Arguments

  • Stream stream - Stream to save node state data.

Return value

1 if node state is successfully saved; otherwise, 0.

int RestoreState ( Stream stream ) #

Restores the state of a given node from a binary stream.
  • If a node is a parent for other nodes, states of these child nodes need to be restored manually.
  • To save the state into a buffer, file or a message from a socket, make sure the stream is opened. If necessary, you can set a position for writing for buffers and files.
Warning
This function is deprecated and will be removed in the next release.

Arguments

  • Stream stream - Stream with saved node state data.

Return value

1 if node state is successfully restored; otherwise, 0.
Last update: 2019-11-28
Build: ()