This page has been translated automatically.
Video Tutorials
Interface
Essentials
Advanced
How To
Rendering
Professional (SIM)
UnigineEditor
Interface Overview
Assets Workflow
Version Control
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
Animations-Related Classes
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
VR-Related Classes
Content Creation
Content Optimization
Materials
Material Nodes Library
Miscellaneous
Input
Math
Matrix
Textures
Art Samples
Tutorials

Unigine::Joint Class

Header: #include <UniginePhysics.h>

This class is used to simulate various types of joints and define common parameters shared by all joints.

See Also#

  • A C++ API sample located in the <UnigineSDK>/source/samples/Api/Physics/JointCallbacks folder
  • A C# API sample located in the <UnigineSDK>/source/csharp/samples/Api/Physics/JointCallbacks folder
  • A UnigineScript API sample <UnigineSDK>/data/samples/physics/callbacks_03

Joint Class

Enums

TYPE#

Type of the joint defining its properties.
NameDescription
JOINT_FIXED = 0Fixed joint.
JOINT_BALL = 1Ball joint.
JOINT_HINGE = 2Hinge joint.
JOINT_PRISMATIC = 3Prismatic joint.
JOINT_CYLINDRICAL = 4Cylindrical joint.
JOINT_SUSPENSION = 5Suspension joint.
JOINT_WHEEL = 6Wheel joint.
JOINT_PARTICLES = 7Particles joint.
JOINT_PATH = 8Path joint.
NUM_JOINTS = 9Number of joints.

Members

isEnabledSelf() const#

Returns the current A value indicating is the joint is enabled.

Return value

Current

getTypeName() const#

Returns the current The name of the joint type.

Return value

Current

getType() const#

Returns the current The type of the joint.

Return value

Current

Event<const Ptr<Joint> &> getEventBroken() const#

Event triggered when the joint breaks. The event handler must receive a Joint as an argument. You can subscribe to events via connect()  and unsubscribe via disconnect(). You can also use EventConnection  and EventConnections  classes for convenience (see examples below).
Notice
For more details see the Event Handling article.
The event handler signature is as follows: myhandler(const Ptr<Joint> & joint)

Usage Example

Source code (C++)
// implement the Broken event handler
void broken_event_handler(const Ptr<Joint> & joint)
{
	Log::message("\Handling Broken event\n");
}


//////////////////////////////////////////////////////////////////////////////
//  1. Multiple subscriptions can be linked to an instance of the EventConnections 
//  class that you can use later to remove all these subscriptions at once
//////////////////////////////////////////////////////////////////////////////

// create an instance of the EventConnections class
EventConnections broken_event_connections;

// link to this instance when subscribing for an event (subscription for various events can be linked)
publisher->getEventBroken().connect(broken_event_connections, broken_event_handler);

// other subscriptions are also linked to this EventConnections instance 
// (e.g. you can subscribe using lambdas)
publisher->getEventBroken().connect(broken_event_connections, [](const Ptr<Joint> & joint) { 
		Log::message("\Handling Broken event (lambda).\n");
	}
);

// ...

// later all of these linked subscriptions can be removed with a single line
broken_event_connections.disconnectAll();

//////////////////////////////////////////////////////////////////////////////
//  2. You can subscribe and unsubscribe via an instance of the EventConnection 
//  class. And toggle this particular connection off and on, when necessary.
//////////////////////////////////////////////////////////////////////////////

// create an instance of the EventConnection class
EventConnection broken_event_connection;

// subscribe for the Broken event with a handler function keeping the connection
publisher->getEventBroken().connect(broken_event_connection, broken_event_handler);

// ...

// you can temporarily disable a particular event connection to perform certain actions
broken_event_connection.setEnabled(false);

// ... actions to be performed

// and enable it back when necessary
broken_event_connection.setEnabled(true);

// ...

// remove subscription for the Broken event via the connection
broken_event_connection.disconnect();

//////////////////////////////////////////////////////////////////////////////
//  3. You can add EventConnection/EventConnections instance as a member of the
//  class that handles the event. In this case all linked subscriptions will be 
//  automatically removed when class destructor is called
//////////////////////////////////////////////////////////////////////////////

// Class handling the event
class SomeClass
{
public:
	// instance of the EventConnections class as a class member
	EventConnections e_connections;

	// A Broken event handler implemented as a class member
	void event_handler(const Ptr<Joint> & joint)
	{
		Log::message("\Handling Broken event\n");
		// ...
	}
};

SomeClass *sc = new SomeClass();

// ...

// specify a class instance in case a handler method belongs to some class
publisher->getEventBroken().connect(sc->e_connections, sc, &SomeClass::event_handler);

// ...

// handler class instance is deleted with all its subscriptions removed automatically
delete sc;

//////////////////////////////////////////////////////////////////////////////
//  4. You can subscribe and unsubscribe via the handler function directly
//////////////////////////////////////////////////////////////////////////////

// subscribe for the Broken event with a handler function
publisher->getEventBroken().connect(broken_event_handler);


// remove subscription for the Broken event later by the handler function
publisher->getEventBroken().disconnect(broken_event_handler);


//////////////////////////////////////////////////////////////////////////////
//   5. Subscribe to an event saving an ID and unsubscribe later by this ID
//////////////////////////////////////////////////////////////////////////////

// define a connection ID to be used to unsubscribe later
EventConnectionId broken_handler_id;

// subscribe for the Broken event with a lambda handler function and keeping connection ID
broken_handler_id = publisher->getEventBroken().connect([](const Ptr<Joint> & joint) { 
		Log::message("\Handling Broken event (lambda).\n");
	}
);

// remove the subscription later using the ID
publisher->getEventBroken().disconnect(broken_handler_id);


//////////////////////////////////////////////////////////////////////////////
//   6. Ignoring all Broken events when necessary
//////////////////////////////////////////////////////////////////////////////

// you can temporarily disable the event to perform certain actions without triggering it
publisher->getEventBroken().setEnabled(false);

// ... actions to be performed

// and enable it back when necessary
publisher->getEventBroken().setEnabled(true);

Return value

Event reference.

Ptr<Joint> createJoint ( int type ) #

Creates a new joint of the specified type.

Arguments

  • int type - Joint type. One of the JOINT_* values.

Return value

New created joint smart pointer.

Ptr<Joint> createJoint ( const char * type_name ) #

Creates a new joint of the specified type.

Arguments

  • const char * type_name - Joint type name.

Return value

New created joint smart pointer.

void setAnchor0 ( const Math::Vec3 & anchor ) #

Sets coordinates of the anchor point in a system of coordinates of the first connected body.

Arguments

  • const Math::Vec3 & anchor - Coordinates of the anchor point in the body coordinate space.

Math::Vec3 getAnchor0 ( ) const#

Returns the coordinates of the anchor point in a system of coordinates of the first connected body.

Return value

Coordinates of the anchor point in the body coordinate space.

void setAnchor1 ( const Math::Vec3 & anchor ) #

Sets coordinates of the anchor point in a system of coordinates of the second connected body.

Arguments

  • const Math::Vec3 & anchor - Coordinates of the anchor point in the body coordinate space.

Math::Vec3 getAnchor1 ( ) const#

Returns the coordinates of the anchor point in a system of coordinates of the second connected body.

Return value

Coordinates of the anchor point in the body coordinate space.

void setAngularRestitution ( float restitution ) #

Sets the current angular restitution (stiffness) of the joint. Angular restitution defines how fast the joint compensates for change of the angle between two bodies. When bodies are turned relative each other, restitution controls the magnitude of force which is applied to both bodies so that their anchor points to become aligned again. For example:
  • 1 means that the joint is to return bodies in place throughout 1 physics tick.
  • 0.2 means that the joint is to return bodies in place throughout 5 physics ticks.
The maximum value of 1 can lead to destabilization of physics (as too great forces are applied).

Arguments

  • float restitution - Angular restitution. The provided value will be clamped in the range [0;1].

float getAngularRestitution ( ) const#

Returns the current angular restitution (stiffness) of the joint. Angular restitution defines how fast the joint compensates for change of the angle between two bodies. When bodies are turned relative each other, restitution controls the magnitude of force which is applied to both bodies so that their anchor points to become aligned again. For example:
  • 1 means that the joint is to return bodies in place throughout 1 physics tick.
  • 0.2 means that the joint is to return bodies in place throughout 5 physics ticks.
The maximum value of 1 can lead to destabilization of physics (as too great forces are applied).

Return value

Angular restitution in the range [0;1].

void setAngularSoftness ( float softness ) #

Sets the angular softness (elasticity) of the joint. When the joint is twisted, angular softness defines whether angular velocities of the bodies are averaged out. For example:
  • 0 means that the joint is rigid. Angular velocities of the first and the second body are independent.
  • 1 means that the joint is elastic (jelly-like). If the first body changes its velocity, velocity of the second body is equalized with it.

Arguments

  • float softness - Angular softness. The provided value will be clamped in the range [0;1].

float getAngularSoftness ( ) const#

Returns the current angular softness (elasticity) of the joint. When the joint is twisted, angular softness defines whether angular velocities of the bodies are averaged out. For example:
  • 0 means that the joint is rigid. Angular velocities of the first and the second body are independent.
  • 1 means that the joint is elastic (jelly-like). If the first body changes its velocity, velocity of the second body is equalized with it.

Return value

Angular softness in the range [0;1].

void setNode0 ( const Ptr<Node> & node0 ) #

Sets the node possessing the first body to be connected to the joint.

Arguments

  • const Ptr<Node> & node0 - Node possessing the first body connected to the joint is assigned. The node must be an object and must have a body assigned.

Ptr<Node> getNode0 ( ) const#

Returns a node possessing the first body connected to the joint.

Return value

Node possessing the first body connected to the joint is assigned (if it exists).

void setNode1 ( const Ptr<Node> & node1 ) #

Sets the node possessing the second body to be connected to the joint.

Arguments

  • const Ptr<Node> & node1 - Node possessing the second body connected to the joint is assigned. The node must be an object and must have a body assigned.

Ptr<Node> getNode1 ( ) const#

Returns a node possessing the second body connected to the joint.

Return value

Node possessing the second body connected to the joint is assigned (if it exists).

void setBody0 ( const Ptr<Body> & body ) #

Sets the first body connected using the joint.

Arguments

  • const Ptr<Body> & body - The first body connected with the joint.

Ptr<Body> getBody0 ( ) const#

Returns the first body connected using the joint.

Return value

The first body connected with the joint.

void setBody1 ( const Ptr<Body> & body ) #

Sets the second body connected using the joint.

Arguments

  • const Ptr<Body> & body - The second body connected with the joint.

Ptr<Body> getBody1 ( ) const#

Returns the second body connected using the joint.

Return value

The second body connected with the joint.

Ptr<BodyRigid> getBodyRigid0 ( ) #

Returns the first connected body as a rigid body.

Return value

The first rigid body connected using the joint or NULL (0), if the body is not rigid.

Ptr<BodyRigid> getBodyRigid1 ( ) #

Returns the second connected body as a rigid body.

Return value

The second rigid body connected using the joint or NULL (0), if the body is not rigid.

void setBroken ( bool broken ) #

Sets a value indicating if the joint is broken or not.

Arguments

  • bool broken - Positive number to break the joint, 0 to make it intact.

bool isBroken ( ) const#

Returns a value indicating if the joint is broken or not.

Return value

Positive number if the joint is broken; otherwise, 0.

void setCollision ( int c ) #

Sets a value indicating if collisions between the connected bodies are enabled.

Arguments

  • int c - Positive number to enable collisions between the bodies, 0 to disable them.

int getCollision ( ) const#

Returns a value indicating if collisions between the connected bodies are enabled.

Return value

Positive number if collisions between the bodies are enabled; otherwise, 0.

void setEnabled ( bool enable ) #

Enables or disables joint calculations.

Arguments

  • bool enable - Positive number to enable the joint, 0 to disable it.

bool isEnabled ( ) const#

Returns a value indicating if the joint calculations are enabled.

Return value

1 if the joint is enabled; otherwise, 0.

bool isEnabledSelf ( ) const#

Returns a value indicating is the joint is enabled.

Return value

1 if the joint is enabled; otherwise, 0.

void setFrozen ( bool f ) #

Freezes or unfreezes the joint.

Arguments

  • bool f - Positive number to freeze the joint, 0 to unfreeze it.

bool isFrozen ( ) const#

Returns a value indicating if the joint is frozen or not.

Return value

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

int setID ( int id ) #

Sets the unique ID for the joint.

Arguments

  • int id - Unique ID.

Return value

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

int getID ( ) const#

Returns the unique ID of the joint.

Return value

Unique ID.

void setLinearRestitution ( float restitution ) #

Sets the linear restitution (stiffness) of the joint. Linear restitution defines how fast the joint compensates for linear coordinate change between two bodies. When bodies are dragged apart, restitution controls the magnitude of force which is applied to both bodies so that their anchor points to become aligned again. For example:
  • 1 means that the joint is to return bodies in place throughout 1 physics tick.
  • 0.2 means that the joint is to return bodies in place throughout 5 physics ticks.
The maximum value of 1 can lead to destabilization of physics (as too great forces are applied).

Arguments

  • float restitution - Linear restitution. The provided value will be clamped in the range [0;1].

float getLinearRestitution ( ) const#

Returns the current linear restitution (stiffness) of the joint. Linear restitution defines how fast the joint compensates for linear coordinate change between two bodies. When bodies are dragged apart, restitution controls the magnitude of force which is applied to both bodies so that their anchor points to become aligned again. For example:
  • 1 means that the joint is to return bodies in place throughout 1 physics tick.
  • 0.2 means that the joint is to return bodies in place throughout 5 physics ticks.
The maximum value of 1 can lead to destabilization of physics (as too great forces are applied).

Return value

Linear restitution in the range [0;1].

void setLinearSoftness ( float softness ) #

Sets the linear softness (elasticity) of the joint. When the joint is stretched, linear softness defines whether linear velocities of the bodies are averaged out. For example:
  • 0 means that the joint is rigid. Linear velocities of the first and the second body are independent.
  • 1 means that the joint is elastic (jelly-like). If the first body changes its velocity, velocity of the second body is equalized with it.

Arguments

  • float softness - Linear softness. The provided value will be clamped in the range [0;1].

float getLinearSoftness ( ) const#

Returns the current linear softness (elasticity) of the joint. When the joint is stretched, linear softness defines whether linear velocities of the bodies are averaged out. For example:
  • 0 means that the joint is rigid. Velocities of the first and the second body are independent.
  • 1 means that the joint is elastic (jelly-like). If the first body changes its velocity, velocity of the second body is equalized with it.

Return value

Linear softness value in the range [0;1].

void setMaxForce ( float force ) #

Sets the maximum amount of force that can be exerted on the joint. If this limit is exceeded, the joint breaks.

Arguments

  • float force - Maximum amount of force.

float getMaxForce ( ) const#

Returns the maximum amount of force that can be exerted on the joint. If this limit is exceeded, the joint breaks.

Return value

Maximum amount of force.

void setMaxTorque ( float torque ) #

Sets the maximum amount of torque that can be exerted on the joint. If this limit is exceeded, the joint breaks.

Arguments

  • float torque - Maximum amount of torque.

float getMaxTorque ( ) const#

Returns the maximum amount of torque that can be exerted on the joint. If this limit is exceeded, the joint breaks.

Return value

Maximum amount of torque.

void setName ( const char * name ) #

Sets the name of the joint.

Arguments

  • const char * name - Name of the joint.

const char * getName ( ) const#

Returns the name of the joint.

Return value

Name of the joint.

void setNumIterations ( int num_iterations ) #

Sets the number of iterations used to solve joints. Note that if this value is too low, the precision of calculations will suffer.

Arguments

  • int num_iterations - Number of iterations. If a non-positive value is provided, 1 will be used instead.

int getNumIterations ( ) const#

Returns the current number of iterations used to solve joints.

Return value

Number of iterations.

Joint::TYPE getType ( ) const#

Returns the type of the joint.

Return value

One of the JOINT_* pre-defined variables.

const char * getTypeName ( ) const#

Returns the name of the joint type.

Return value

Type name.

const char * getTypeName ( int type ) #

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

Arguments

  • int type - Joint type ID. One of the JOINT_* values.

Return value

Joint type name.

void setWorldAnchor ( const Math::Vec3 & anchor ) #

Sets the anchor point in the world coordinates.

Arguments

  • const Math::Vec3 & anchor - Coordinates of the anchor point in the world space.

Math::Vec3 getWorldAnchor ( ) const#

Returns the anchor point in the world coordinates.

Return value

Coordinates of the anchor point in the world space.

Ptr<Joint> clone ( ) const#

Clones the joint.

Return value

Copy of the joint.

void renderVisualizer ( const Math::vec4 & color ) #

Renders the joint.
Notice
You should enable the engine visualizer by the show_visualizer 1 console command.

Arguments

  • const Math::vec4 & color - Color, in which the joint will be rendered.

int saveState ( const Ptr<Stream> & stream ) const#

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.

Example using saveState() and restoreState() methods:

Source code (C++)
// set the joint state
joint->setAngularRestitution(0.8f);

// save state
BlobPtr blob_state = Blob::create();
joint->saveState(blob_state);

// change the state
joint->setAngularRestitution(0.4f);

// restore state
blob_state->seekSet(0);       // returning the carriage to the start of the blob
joint->restoreState(blob_state);

Arguments

  • const Ptr<Stream> & stream - Stream to save node state data.

Return value

true if the node state is saved successfully; otherwise, false.

int restoreState ( const Ptr<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.

Example using saveState() and restoreState() methods:

Source code (C++)
// set the joint state
joint->setAngularRestitution(0.8f);

// save state
BlobPtr blob_state = Blob::create();
joint->saveState(blob_state);

// change the state
joint->setAngularRestitution(0.4f);

// restore state
blob_state->seekSet(0);       // returning the carriage to the start of the blob
joint->restoreState(blob_state);

Arguments

  • const Ptr<Stream> & stream - Stream with saved node state data.

Return value

true if the node state is restored successfully; otherwise, false.

void swap ( const Ptr<Joint> & joint ) #

Swaps the joints saving the pointers.

Arguments

  • const Ptr<Joint> & joint - A joint to swap.
Last update: 2024-02-06
Build: ()