Skip to main content

Joints

Joints constrain the way two physics bodies move relative to one another. A typical use for a joint would be to model a door hinge or a robotic arm.

Every joint requires a

Joint
component.

Joint component
Joint component

This component specifies the base attributes needed to create a joint, such as the two physics bodies constrained by the joint: the constrainer and the constrainee entity.

The joint constrains the constrainer and constrainee's position and rotation to be dependent on one another. Further information on the specifics of the constraints in the sections below.

A joint can be broken. You can specify the maximum breaking force and torque with breakForce and breakTorque.

You can also enable or disable collision between the constrainer and the constrainee using enableCollision. Although it depends on the use case, disabling collision is usually preferred and leads to more stable results.

To further customize the constraints of individual degrees of freedom, you can add the

Constraint
component.

Simple Joint​

The simplest joint that can be created is a fixed joint. If you simply attach a

Joint
WITHOUT a
Constraint
, a fixed joint will be created.

A fixed joint restricts the constrainee's movement to be dependent on the constrainer. It locks the orientations and relative position of the two physics bodies.

This is somewhat similar to parenting but is implemented through physics rather than the scene graph hierarchy. You should use fixed joints to lock the movement of two physics bodies that you then want to easily break apart from each other, or to connect two physics bodies’ movement without parenting.

Joint with Constraints​

If you attach a

Joint
AND a
Constraint
 to an entity, a joint will be created with constraints that are configurable according to what was set in the
Constraint
component.

Constraint component
Constraint component

The constraint component gives you granular control over each degree of freedom (movement along X,Y,Z and rotation around X,Y,Z). You can:

  • lock specific axes (no movement or rotation allowed)
  • free axes for unrestricted movement or rotation
  • limit movement or rotation within specified ranges

Use unlockedMotion to lock/unlock the degrees of freedom.

References to twist in the attributes (e.g. twistLimitAngle) refers to rotation around the X axis. Swing (e.g. swingLimitAngle) refers to rotation around the Y axis and the Z axis.

Constraint

constraint

A physics constraint that can be configured along 6 degrees of freedom. In its default state it behaves as a fixed constraint - that is, it rigidly fixes the constraint frames of its two entities. However, individual degrees of freedom may be unlocked to permit any combination of rotation around the x-, y- and z- axes, and translation along these axes.

motionLimitSpringDamping

Vector3

Default: [0,0,0]

If greater than zero, this is the damping of the limit spring.

motionLimitSpringStiffness

Vector3

Default: [0,0,0]

If greater than zero, the limit is soft, i.e. a spring pulls the joint back to the limit.

motionLowerLimit

Vector3

Default: [0,0,0]

The lower distance of the limit.

motionUpperLimit

Vector3

Default: [0,0,0]

The upper distance of the limit.

swingLimitAngle

Vector2

Default: [0,0]

The limit angle from the Y-axis and the Z-axis of the constraint frame. The cone limit is used if either or both swing axes are limited. The extents are symmetrical and measured in the frame of the parent. If only one swing degree of freedom is limited, the corresponding value from the cone limit defines the limit range. An angle of 0° will not restrict the rotation around the axis. The maximum value for each angle is 180°.

swingSpringDamping

Float

Default: 0

If greater than zero, this is the damping of the limit spring.

swingSpringStiffness

Float

Default: 0

If greater than zero, the limit is soft, i.e. a spring pulls the joint back to the limit.

twistLimitAngle

Vector2

Default: [0,0]

The twist limit controls the range of motion around the twist axis. The limit angle range is (-360, 360).

twistSpringDamping

Float

Default: 0

If greater than zero, this is the damping of the limit spring.

twistSpringStiffness

Float

Default: 0

If greater than zero, the limit is soft, i.e. a spring pulls the joint back to the limit.

unlockedMotion

Unsigned Integer

Default: 0

[1] Along X [2] Along Y [4] Along Z [8] Around X [16] Around Y [32] Around Z

Unlock motion along/around the specified axis.