Programming
Fundamentals
Setting Up Development Environment
Usage Examples
UnigineScript
High-Level Systems
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
Networking Functionality
Pathfinding-Related Classes
Physics-Related Classes
Plugins-Related Classes
Rendering-Related Classes

Joints

Joints provide constraints removing degrees of freedom from a body and are used to connect pairs of bodies. Each joint has an anchor point, which is by default placed between the centers of mass of connected bodies. The properties of each connection depend on the selected joint type and its parameters. Joint parameters can be divided into two groups:

  • Common parameters - basic set of parameters shared by all joints.
  • Type-specific parameters - a set of specific parameters for each joint type.

See also

Programming realization:

Usage examples:

Adding a Joint

Assume you have two objects with physical bodies assigned. Remember that a body must have a shape assigned. To connect them using a joint via UnigineEditor, perform the following steps:

  • Open the Nodes window by pressing the N key
  • Select the first body to connect
  • Go to the Joints tab. Choose an appropriate type of joint and click Add.

    Adding a joint

  • Select the second body either by clicking it directly in the editor window, or by picking its name in the dialog window and click Ok.

    Selecting a body

  • Set joint parameters in the Joints tab of the Nodes panel.

You can enable visualization of joint by checking Helpers panel -> Physics item -> Joints option (Visualizer should be enabled).

Fixed Joint

Fixed joints connect two bodies in a manner that strictly preserves their positions with respect to each other.

Fixed joint

The basic constraint parameters of this joint include:

Rotation 0 Specifies orientation of the first body relative to the anchor point.
Rotation 1 Specifies orientation of the second body relative to the anchor point

This joint also has a set of common parameters shared by all joint types.

For more information refer to JointFixed Class description. An example illustrating connection of two bodies using a fixed joint can be found here.

Hinge Joint

Hinge joints allow the connected bodies to rotate along the joint's axis at the anchor point. This joint has an angular motor attached.

Hinge joint Hinge joint

The basic constraint parameters of this joint include:

Joint axis Coordinates of the joint axis, around which the bodies rotate.
Angular damping Angular damping coefficient of the hinge joint.
Angular limit from Minimum angle in the range of movement at which the hinge stops. The angle is specified in degrees in the [-180; 180] range.
Angular limit to Maximum angle in the range of movement at which the hinge stops. The angle is specified in degrees in the [-180; 180] range.
Angular spring Spring rigidity coefficient, determines how strong the joint resists rotation. If rigidity is set to 0, the spring is disabled.
Angular angle Target angle of the attached angular spring. The spring (if it is enabled) tries to keep the specified angle between the connected bodies.
Motor parameters
Angular Torque Maximum torque of the angular motor. 0 detaches the motor.
Angular Velocity Target velocity of the attached angular motor.

This joint also has a set of common parameters shared by all joint types.

For more information refer to JointHinge Class description. An example illustrating connection of two bodies using a hinge joint can be found here.

Ball Joint

Ball joints provide a point around which the connected objects can rotate.

Ball joint Ball joint

The basic constraint parameters of this joint include:

Joint axis Coordinates of the joint axis.
Angular limit angle Swing angle limit, specifies how much connected bodies can bend from the joint axis.
Angular limit from Minimum angle in the range of twisting around the joint axis. The angle is specified in degrees in the [-180; 180] range.
Angular limit to Maximum angle in the range of twisting around the joint axis. The angle is specified in degrees in the [-180; 180] range.

This joint also has a set of common parameters shared by all joint types.

For more information refer to JointBall Class description. An example illustrating connection of two bodies using a ball joint can be found here.

Prismatic Joint

Prismatic joints allow movement along the joint axis. This joint has a linear motor attached.

Prismatic joint Prismatic joint

The basic constraint parameters of this joint include:

Joint axis Coordinates of the joint axis.
Linear damping Linear damping coefficient of the prismatic joint.
Linear limit from Minimum distance between the bodies along the joint axis.
Linear limit to Maximum distance between the bodies along the joint axis.
Linear spring Spring rigidity coefficient, determines how strong the joint resists linear motion. If rigidity is set to 0, the spring is disabled.
Linear distance Target linear distance of the attached spring. The spring (if it is enabled) tries to keep the specified distance between the connected bodies.
Motor parameters
Linear Force Maximum force of the attached linear motor. 0 detaches the motor.
Linear Velocity Target velocity of the attached linear motor.

This joint also has a set of common parameters shared by all joint types.

For more information refer to JointPrismatic Class description. An example illustrating connection of two bodies using a prismatic joint can be found here.

Cylindrical Joint

Cylindrical joints are like prismatic ones with an additional degree of freedom: rotation around the joint axis. This joint has a linear and an angular motors attached.

Cylindrical joint Cylindrical joint

The basic constraint parameters of this joint include:

Joint axis Coordinates of the joint axis.
Linear damping Linear damping coefficient of the cylindrical joint.
Linear limit from The minimum distance between the bodies along the joint axis.
Linear limit to The maximum distance between the bodies along the joint axis.
Linear spring Spring rigidity coefficient, determines how strong the joint resists linear motion. If rigidity is set to 0, the spring is disabled.
Linear distance A target linear distance of the attached spring. The spring (if it is enabled) tries to keep the specified distance between the connected bodies.
Angular damping Angular damping coefficient of the cylindrical joint.
Angular limit from The minimum angle in the range of twisting around the joint axis. The angle is specified in degrees in the [-180; 180] range.
Angular limit to The maximum angle in the range of twisting around the joint axis. The angle is specified in degrees in the [-180; 180] range.
Angular spring Spring rigidity coefficient, determines how strong the joint resists rotation. If rigidity is set to 0, the spring is disabled.
Angular angle A target angle of the attached angular spring. The spring (if it is enabled) tries to keep the specified angle between the connected bodies.
Motor parameters
Angular Torque Maximum torque of the angular motor. 0 detaches the motor.
Angular Velocity Target velocity of the attached angular motor.
Linear Force Maximum force of the attached linear motor. 0 detaches the motor.
Linear Velocity Target velocity of the attached linear motor.

This joint also has a set of common parameters shared by all joint types.

For more information refer to JointCylindrical Class description. An example illustrating connection of two bodies using a cylindrical joint can be found here.

Wheel Joint

Wheel joints are used to create ray-cast vehicle wheels. It connects two rigid bodies: the first body is a frame, the second one is a wheel. There is no need to assign a shape to the wheel: ray casting is used to detect collision of the wheel with a surface. This joint has an angular motor attached.

Notice
The order of the bodies, connected using a wheel joint, matters!
  • If the bodies are connected using UnigineEditor:
    1. Select the vehicle frame.
    2. Add a wheel joint.
    3. Specify the wheel to be attached.
  • If the bodies are connected programmatically:
    • b0 is a frame.
    • b1 is a wheel.
Wheel joint Wheel joint

The basic constraint parameters of this joint include:

Suspension axis (Axis 0) Coordinates of a vertical axis, which acts like a cylindrical joint providing steering and damping.
Wheel spindle axis (Axis 1) Coordinates of a horizontal axis, around which the wheel rotates.
Linear damping Linear damping coefficient of the suspension.
Linear limit from Lower suspension ride limit.
Linear limit to Upper suspension ride limit.
Linear spring Suspension spring rigidity coefficient, determines how strong the joint resists vertical linear motion. If rigidity is set to 0, the spring is disabled.
Linear distance Target suspension height. The suspension spring (if it is enabled) tries to keep the specified height.
Angular damping Angular damping coefficient of wheel rotation.
Motor parameters
Angular Torque Maximum torque of the angular motor. 0 detaches the motor.
Angular Velocity Target velocity of the attached angular motor.

This joint also has a set of common parameters shared by all joint types.

For more information refer to JointWheel Class description. An example illustrating connection of two bodies using a wheel joint can be found here.

Suspension Joint

Suspension joints are used to create wheel suspension for vehicles. It connects two rigid bodies: the first body is a frame, the second one is a wheel. This joint has an angular motor attached.

Notice
The order of the bodies, connected using a suspension joint, matters!
  • If the bodies are connected using UnigineEditor:
    1. Select the vehicle frame.
    2. Add a suspension joint.
    3. Specify the wheel to be attached.
  • If the bodies are connected programmatically:
    • b0 is a frame.
    • b1 is a wheel.
Suspension joint Suspension joint

The basic constraint parameters of this joint include:

Suspension axis (Axis 0) Coordinates of a vertical axis, which acts like a cylindrical joint providing steering and damping.
Wheel spindle axis (Axis 1) Coordinates of a horizontal axis, around which the wheel rotates.
Linear damping Linear damping coefficient of the suspension.
Linear limit from Lower suspension ride limit.
Linear limit to Upper suspension ride limit.
Linear spring Suspension spring rigidity coefficient, determines how strong the joint resists vertical linear motion. If rigidity is set to 0, the spring is disabled.
Linear distance Target suspension height. The suspension spring (if it is enabled) tries to keep the specified height.
Angular damping Angular damping coefficient of wheel rotation.
Motor parameters
Angular Torque Maximum torque of the angular motor. 0 detaches the motor.
Angular Velocity Target velocity of the attached angular motor.

This joint also has a set of common parameters shared by all joint types.

For more information refer to JointSuspension Class description. An example illustrating connection of two bodies using a suspension joint can be found here.

Path Joint

Path joint is used to attach a rigid body to a path body and to make it move along this path. This joint can be used to make a train move along the tracks. This joint has a linear motor attached.

Notice

Assign a shape to a rigid body before connecting it to a path body!

The order of the bodies, connected using a path joint, matters!
  • If the bodies are connected using UnigineEditor:
    1. Select a rigid body.
    2. Add a path joint.
    3. Specify the path body.
  • If the bodies are connected programmatically:
    • b0 is a BodyRigid.
    • b1 is a BodyPath.
Path joint

The basic constraint parameters of this joint include:

Rotation Specifies orientation of the body relative to the path.
Linear damping Linear damping coefficient of the path joint.
Motor parameters
Linear Force Maximum force of the attached linear motor. 0 detaches the motor.
Linear Velocity Target velocity of the attached linear motor.

This joint also has a set of common parameters shared by all joint types.

For more information refer to JointPath Class description. An example illustrating connection of two bodies using a path joint can be found here.

Particles Joint

Particles joint is used to pin cloth body or rope body to a rigid body, ragdoll body or a dummy body.

Notice
The order of the bodies, connected using a particles joint, matters!
  • If the bodies are connected using UnigineEditor:
    1. Select a rigid body, a ragdoll body or a dummy body.
    2. Add a particles joint.
    3. Specify a cloth body or a rope body.
  • If the bodies are connected programmatically:
    • b0 is a BodyRigid, a BodyRagdoll or a BodyDummy.
    • b1 is a BodyCloth or a BodyRope.
Particles joint

The basic constraint parameters of this joint include:

Threshold Determines the distance for pinning vertices of cloth or rope body to another body.
Size Specifies the area for pinning vertices of cloth or rope body to another body.

This joint also has a set of common parameters shared by all joint types.

For more information refer to JointParticles Class description. An example illustrating connection of two bodies using a particles joint can be found here.

An example illustrating the use of rope body and particles joint can be found here.

Common Joint Parameters

All joints regardless of their type have some common parameters:

Enabled A flag indicating if a joint is enabled.
Collision A flag indicating if collision detection between the connected bodies is enabled.
Anchor Position of the anchor point around which the joint's motion is constrained. By default the anchor is placed between the centers of mass of connected bodies.
Linear restitution Linear stiffness of the joint. Defines how fast it 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.
  • 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.
Notice
The maximum value of 1 can lead to destabilization of physics (as too great forces are applied).
Angular restitution Angular stiffness of the joint. Defines how fast it 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.
  • 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.
Notice
The maximum value of 1 can lead to destabilization of physics (as too great forces are applied).
Linear softness Linear elasticity of the joint. Defines whether linear velocities of the bodies are averaged out when the joint is stretched.
  • 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.
Angular softness Angular elasticity of the joint. Defines whether linear velocities of the bodies are averaged out when the joint is twisted.
  • 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.
Max force Maximum force that can be exerted on the joint. If this limit is exceeded, the joint breaks. The default value is inf, i.e. the joint is unbreakable.
Max torque Maximum torque that can be exerted on the joint. If this limit is exceeded, the joint breaks. The default value is inf, i.e. the joint is unbreakable.
Number of iterations Joints, like collisions, are calculated iteratively. This parameter specifies the number of iterations used to solve joints. Note that if this value is too low, the precision of calculations will suffer.

Motors and Springs

Joints can have motors and springs associated with them.

Springs try to keep the bodies connected with a joint at some specific distance (linear) or angle (angular). The behavior of a particular spring depends on its rigidity and damping coefficient.

Motors provide movement or rotation of bodies connected with a joint relative to each other by applying a torque (or force) to a joint's degree of freedom. There are linear and angular motors that exert a limited force to a joint, pushing or rotating connected objects.

Springs and Motors

Motors have two parameters:

  • Target velocity
  • Maximum force (or torque) that is available to reach that velocity.
This is a very simple model of real life motors. However, is it quite useful when modeling a motor, that is geared down with a gearbox before being connected to the joint. Such devices are often controlled by setting a target velocity, and can only generate a maximum amount of power to achieve that speed (which corresponds to a certain amount of force available at the joint).

To activate an angular motor perform the following steps:

  1. Set angular velocity - target angular velocity of the motor, This value determines how fast the motor can rotate.
    • positive value - the motor rotates counterclockwise.
    • negative value - the motor rotates clockwise.
  2. Set angular torque - maximum torque applied by the motor to reach target velocity. This value determines how fast the motor reaches maximum velocity.
    • 0 disables the motor.
    • If a negative value is provided, 0 will be used instead.

To activate a linear motor perform the following steps:

  1. Set linear velocity - target linear velocity of the motor, This value determines how fast the motor can push.
    • positive value - the motor pushes forward.
    • negative value - the motor pulls backward.
  2. Set linear force - maximum force applied by the motor to reach target velocity. This value determines how fast the motor reaches maximum velocity.
    • 0 disables the motor.
    • If a negative value is provided, 0 will be used instead.

Vehicles

Vehicles are important in real-time games, therefore, they are to be described separately. There are two approaches to simulation of moving vehicles. Each approach has a corresponding joint type to connect wheels to vehicle body.

  • The first approach uses a suspension joint and assumes that wheels are represented as physical bodies with shapes. As each wheel has a collider shape, collisions with objects on the ground are handled correctly. For example, such car runs on a curb smoothly. This approach requires more calculations and is to be used when more accurate simulation is needed especially for step-like ground surface and wheels have a complex shape.
  • The second approach uses a wheel joint and assumes that the wheels are virtual. Wheels do not collide with the surface of the road. Instead, rays are cast down from the car body to detect surface unevenness. In this case steep changes of the terrain are not handled accurately. This approach is faster then the first one and provides acceptable results for smooth terrain, e.g. for racing cars simulation. However, on cross-country terrains it may not work correctly.

Both joints have a motor associated with them, which rotates the wheels and pushes the vehicle forward.

Problems with ray cars and steep obstacles

A problem with the wheels simulated using ray casting
Last update: 2017-07-03