Body Class

List of functions:

List of Variables:

BODY_DUMMY
BODY_RIGID
BODY_RAGDOLL
BODY_FRACTURE
BODY_ROPE
BODY_CLOTH
BODY_WATER
BODY_PATH
NUM_BODIES

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

All of these function take effect when physics calculations are over and its flush is performed. Only after that transformations of the body are applied to the rendered node. If a node need 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).

Body Class

Members

quat getRotation ()

Returns the body rotation.

Return value

The body rotation in the world coordinates.

Vec3 getPosition ()

Returns the body position.

Return value

The body position in the world coordinates.

Vec3 getContactPoint (int num)

Returns world coordinates of the contact point.

Arguments

int num - Contact number.

Return value

Contact point.

void setPositionCallback (CallbackBase * func)

Adds a callback function that will be run when a given body moves a certain distance (rotation is not taken into account).

Notice

Physics-based callbacks are executed not immediately, but before the next flush() or next update() of the world script.

Arguments

CallbackBase * func - Name of the callback function.

int getNumChildren ()

Returns the number of child bodies.

Return value

Number of children.

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.

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.

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.

void setName (string name)

Sets the name of the body.

Arguments

string name - Name of the body.

void flushTransform ()

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

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.

int isFrozen ()

Returns 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.

Return value

Positive number if the body is frozen; otherwise, 0.

Shape getIntersection (vec3 p0, vec3 p1, int mask, variable v)

Performs tracing from the p0 point to the p1 point to find a body shape located on that line. Intersection is found only for objects with a matching mask.

Notice
		                    World space coordinates are used for this function.
		                

Depending on the variable passed as an argument, the result can be presented as the PhysicsIntersection or PhysicsIntersectionNormal node.

Arguments

vec3 p0 - Start point of the line.
vec3 p1 - End point of the line.
int mask - Intersection mask.
variable v - Variable defining which type of intersection object will be returned:
- PhysicsIntersectionintersection - The PhysicsIntersection node.
- PhysicsIntersectionNormalnormal - The PhysicsIntersectionNormal node.

Return value

Reference to the first intersected shape, if found; otherwise - 0.

string getName ()

Returns the name of the body.

Return value

Name of the body.

void renderShapes ()

Renders shapes comprising the body.

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.

Arguments

Stream stream - Stream to save node state data.

Return value

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

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.

int isEnabledSelf ()

Returns a value indicating if the body is enabled.

Return value

1 if the body is enabled; otherwise, 0.

Object getObject ()

Returns the object, which is approximated with the body.

Return value

Approximated object.

void setContactCallback (CallbackBase * func)

Adds a callback function that will be run when a contact with a given body emerges.

Notice

Physics-based callbacks are executed not immediately, but before the next flush() or next update() of the world script.

The signature of the contact callback function must be one of the following:

Source code(UnigineScript)

contact_callback_function_name(Body body);
contact_callback_function_name(Body body,int num); // num is the contact ID
contact_callback_function_name(Body body,int num,variable arg0); // num is the contact ID
contact_callback_function_name(Body body,int num,variable arg0,variable arg1); // num is the contact ID

For example, if you set the callback function as follows:

Source code(UnigineScript)

setContactCallback("contact_callback_function_name",arg0,arg1);

The called function contact_callback_function_name() must have the following signature:

Source code(UnigineScript)

contact_callback_function_name(Body body,int num,variable arg0,variable arg1);

Arguments

CallbackBase * func - Name of the callback function.

vec3 getContactVelocity (int num)

Returns relative velocity in the point of a given contact.

Arguments

int num - Contact number.

Return value

Velocity vector.

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.

Arguments

Stream stream - Stream with saved node state data.

Return value

1 if node state is successfully restored; otherwise, 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.

void updateShapes ()

void setObject (Object object)

Sets an object, which the body approximates.

Arguments

Object object - Object to approximate.

Joint getJoint (int num)

Returns a given joint.

Arguments

int num - Joint number.

Return value

Corresponding joint.

void setTransform (Mat4 transform)

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.

Arguments

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

void setDirection (vec3 dir, vec3 up)

Updates the direction vector of the body. 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.

float getContactImpulse (int num)

Returns the relative impulse arising in the point of a given contact.

Arguments

int num - Contact number.

Return value

Impulse value.

void setPhysicalMask (int mask)

Sets the bit mask for interactions with physicals. Two objects interact, if they both have matching masks.

Arguments

int mask - Integer, each bit of which is a mask.

void addJoint (Joint joint)

Adds a joint to the body.

Arguments

Joint joint - New joint to add.

int setID (int id)

Sets the unique ID for the body.

Arguments

int id - Unique ID.

Return value

1 if the ID is set successfully; otherwise, 0.

float getContactFriction (int num)

Returns relative friction arising in the point of a given contact.

Arguments

int num - Contact number.

Return value

Friction value.

void setFrozenCallback (CallbackBase * func)

Adds a callback function that will be run when a given body freezes.

Notice

Physics-based callbacks are executed not immediately, but before the next flush() or next update() of the world script.

Arguments

CallbackBase * func - Name of the callback function.

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.

Shape getShape (int num)

Returns a given shape.

Arguments

int num - Shape number.

Return value

Corresponding shape object.

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.

void setPosition (Vec3 pos)

Updates the body position. Body's linear and angular velocities will be reset to 0.

Arguments

Vec3 pos - New position in the world coordinates.

void renderVisualizer ()

Renders shapes, joints and contact points of the body.

NoticeYou should enable the engine visualizer by the show_visualizer 1 console command.

Body getParent ()

Returns the parent of the current body.

Return value

Parent body.

int getPhysicalMask ()

Returns the bit mask for interactions with physicals. Two objects interact, if they both have matching masks.

Return value

Integer, each bit of which is a mask.

void setGravity (int gravity)

Sets a value indicating if gravity is affecting the body.

Arguments

int gravity - Positive number if the body is affected by gravity; otherwise, 0.

string getTypeName ()

Returns the name of the body type.

Return value

Type name.

Body getBody ()

Return value

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.

vec3 getContactNormal (int num)

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

Arguments

int num - Contact number.

Return value

Normal.

int getType ()

Returns the type of the body.

Return value

One of the BODY_* pre-defined variables.

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.

int getID ()

Returns the unique ID of the body.

Return value

Unique ID.

void swap (Body body)

Swaps the bodies saving the pointers.

Arguments

Body body - Body to swap.

void removeShape (Shape shape)

Removes a given shape from the body.

Arguments

Shape shape - Shape to be removed.

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.

vec3 getDirection ()

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

Return value

Normalized direction vector in the world coordinates.

void addShape (Shape shape)

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

Arguments

Shape shape - New shape to add.

void renderJoints ()

Renders joints in the body.

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.

void setRotation (quat rot)

Updates the body rotation.

Arguments

quat rot - New rotation in the world coordinates.

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.

void setFrozen (int frozen)

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.

Arguments

int frozen - Positive number to freeze the object, 0 to unfreeze it.

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 renderContacts ()

Renders contact points of the body.

float getContactRestitution (int num)

Returns relative restitution arising in the point of a given contact.

Arguments

int num - Contact number.

Return value

Restitution.

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.

Mat4 getTransform ()

Returns the transformation matrix of the body (in world coordinates). This matrix describes position and orientation of the body.

Return value

Transformation matrix.

int isGravity ()

Returns a value indicating if gravity is affecting the body.

Return value

1 if the body is affected by gravity; otherwise, 0.

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.

int getContactID (int num)

Returns the contact ID.

Arguments

int num - Contact number.

Return value

Contact ID

int getNumShapes ()

Returns the number of shapes comprising the body.

Return value

Number of shapes.

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.

int getNumJoints ()

Returns the number of joints in the body.

Return value

Number of joints.

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 removeJoint (Joint joint)

Removes a given joint from the body.

Arguments

Joint joint - Joint to be removed.

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.

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 getNumContacts ()

Returns 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 setContactCallback() should be used.

Return value

Number of contacts.

int isEnabled ()

Returns a value indicating if physical interactions with the body are enabled.

Return value

Positive number if physical interactions with the body are enabled; otherwise, 0.

Body getChild (int num)

Returns a given child body.

Arguments

int num - Child number.

Return value

Corresponding body.

void setEnabled (int enable)

Enables or disables physical interactions with the body.

Arguments

int enable - Positive number to enable physical interactions, 0 to disable them.

int BODY_DUMMY

Description

This body is used to create an immovable collider for an object.

int BODY_RIGID

Description

This is a base body describing a rigid object.

int BODY_RAGDOLL

Description

This body contains joints connecting parts of the body (represented with rigid bodies).

int BODY_FRACTURE

Description

This body simulates breakable objects.

int BODY_ROPE

Description

This body simulates ropes.

int BODY_CLOTH

Description

This body simulates cloth.

int BODY_WATER

Description

This body simulates water and other fluids.

int BODY_PATH

Description

This body simulates a path along which rigid bodies are moving, for example, like a train along the railtrack.

int NUM_BODIES

Last update: 2017-07-03

Help improve this article

Was this article helpful?

Report a problem related to this article

(or select a word/phrase and press Ctrl+Enter)