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.
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.
The constrainee must be a rigidbody. The constrainer may be a rigid or static body, or simply null. If null, the constrainee is dependent upon world origin.
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.
The constrainer constrains the constrainee.
Typically the constrainer is the more stable/fixed body in the relationship (if it is a static body), or the "leader" of movement (if it is a rigid body). The constrainee is the body that moves relative to the constrainer.
In the case of a door hinge, the constrainer would be the door frame and the door would be the constrainee. The constrainer would be a static body.
In a robotic arm the upper arm would be the constrainer and the lower arm would be the constrainee. The constrainer in this case, the upper arm, would be a rigid body.
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.
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.
Constraint
constraint
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
[1] Along X
[2] Along Y
[4] Along Z
[8] Around X
[16] Around Y
[32] Around Z
Default: 0
Unlock motion along/around the specified axis.