Configurable Joint
Switch to Scripting
Configurable Joints incorporate all the functionality of the other joint types and provide greater control of character movement. They are particularly useful when you want to customize the movement of a ragdoll and enforce certain poses on your characters. You can also use them to adapt jointsA physics component allowing a dynamic connection between Rigidbody components, usually allowing some degree of movement such as a hinge. More info
See in Glossary into highly specialized joints of your own design.
Properties
| Property: | Function: | |
|---|---|---|
| Edit Joint Angular Limits | Adds a visual gizmoA graphic overlay associated with a GameObject in a Scene, and displayed in the Scene View. Built-in scene tools such as the move tool are Gizmos, and you can create custom Gizmos using textures or scripting. Some Gizmos are only drawn when the GameObject is selected, while other Gizmos are drawn by the Editor regardless of which GameObjects are selected. More info See in Glossary to the Scene viewAn interactive view into the world you are creating. You use the Scene View to select and position scenery, characters, cameras, lights, and all other types of Game Object. More info See in Glossary that helps you edit joint angular limits. To use this gizmo, set the Angular X, Y, Z Motion to Limited and then handles appear for you to drag and adjust the joint’s rotational space. |
|
| Connected Body | The RigidbodyA component that allows a GameObject to be affected by simulated gravity and other forces. More info See in Glossary object which the joint connects to. You can set this to None to indicate that the joint attaches to a fixed position in space rather than another Rigidbody. |
|
| AnchorA UI layout tool that fixes a UI element to a parent element. Anchors are shown as four small triangular handles in the Scene View and anchor information is also shown in the Inspector. More info See in Glossary |
The point which defines the center of the joint. All physics-based simulations use this point as the center in calculations. | |
| Axis | The local axis that defines the object’s natural rotation based on physics simulation. | |
| Auto Configure Connected Anchor | Enable this setting to automatically calculate the Connected Anchor position to match the global position of the anchor property. This is the default setting. Disable it to configure the position of the connected anchor manually. | |
| Connected Anchor | Manually configure the connected anchor position. | |
| Secondary Axis | The Axis and Secondary Axis define the local coordinate system of the joint. The third axis is orthogonal to the other two. | |
| X, Y, Z Motion | Set the movement along the X, Y or Z axes to be Free, completely Locked, or Limited according to the limit properties described below. | |
| Angular X, Y, Z Motion | Set the rotation around the X, Y or Z axes to be Free, completely Locked, or Limited according to the limit properties described below. | |
| Linear Limit Spring | Apply a spring force to pull the object back when it goes past the limit position. | |
| Spring | The spring force. Set this value to zero to make the limit impassable. A value other than zero makes the limit elastic. | |
| Damper | The reduction of the spring force in proportion to the speed of the joint’s movement. Set a value above zero to allow the joint to “dampen” oscillations which would otherwise carry on indefinitely. | |
| Linear Limit | Set a limit on the joint’s linear movement (i.e., movement over distance rather than rotation), specified as a distance from the joint’s origin. | |
| Limit | The distance in world units from the origin to the limit. | |
| Bounciness | Set a bounce force to apply to the object to push it back when it reaches the limit distance. | |
| Contact DistanceA joint limit property that sets the minimum distance tolerance between the joint position and the limit at which the limit will be enforced. More info See in Glossary |
The minimum distance tolerance between the joint position and the limit to enforce the limit. A high tolerance means the limit is less likely to be violated when the object is moving fast. However, this requires the limit to be taken into account by the physics simulation more often and reduces performance slightly. | |
| Angular X Limit Spring | Apply a spring torque to rotate the object back when it goes past the limit angle of the joint. | |
| Spring | The spring torque. Set this value to zero to make the limit impassable. Set a value other than zero to make the limit elastic. | |
| Damper | The reduction of the spring torque in proportion to the speed of the joint’s rotation. Set a value above zero to allow the joint to “dampen” oscillations which would otherwise carry on indefinitely. | |
| Low Angular X Limit | Lower limit on the joint’s rotation around the x-axis, specified as an angle from the joint’s original rotation. | |
| Limit | The limit angle. | |
| Bounciness | Set a bounce torque to apply to the object when its rotation reaches the limit angle. | |
| Contact Distance | The minimum angular tolerance (between the joint angle and the limit) at which the limit will be enforced. A high tolerance violates the limit less often when the object is moving fast. However, this requires the physics simulation to take into account the limit more often and reduces performance slightly. | |
| High Angular XLimit | This is similar to the Low Angular X Limit property described above but it determines the upper angular limit of the joint’s rotation rather than the lower limit. | |
| Angular YZ Limit Spring | This is similar to the Angular X Limit Spring described above but applies to rotation around both the Y and Z axes. | |
| Angular Y Limit | This is similar to the Angular X Limit property described above but applies the limit to the y-axis and regards both the upper and lower angular limits as the same. | |
| Angular Z Limit | This is similar to the Angular X Limit property described above but applies the limit to the z-axis and regards both the upper and lower angular limits as the same. | |
| Target Position | The target position that the joint’s drive force moves to. | |
| Target Velocity | The desired velocity that the joint moves to the Target Position under the drive force. | |
| XDrive | Set the force that Unity uses to rotate the joint around its local x-axis by the Position Spring and Position Damper drive torques. The Maximum Force parameter limits the force. This property is only available if the Rotation Drive Mode property is set to X & YZ. For more information, see Drive force section below. | |
| Position Spring | The spring torque that Unity uses to rotate the joint from its current position towards its target position. | |
| Position Damper | Reduces the amount of spring torque in proportion to the difference between the joint’s current velocity and its target velocity. This reduces the speed of the joint’s movement. Set a value above zero to allow the joint to dampen oscillations which would otherwise carry on indefinitely. | |
| Maximum Force | Limits the amount of force that the drive can apply. To make the drive apply the force that it’s calculated, set this to a high value that the drive is unlikely to calculate. | |
| YDrive | This is similar to the X Drive described above but applies to the joint’s y-axis. | |
| ZDrive | This is similar to the X Drive described above but applies to the joint’s z-axis. | |
| Target Rotation | The orientation that the joint’s rotational drive rotates towards, specified as a quaternionUnity’s standard way of representing rotations as data. When writing code that deals with rotations, you should usually use the Quaternion class and its methods. More info See in Glossary. The target rotation is relative to the body that the Joint is attached to, unless the Swap Bodies parameter is set, in which case it’s relative to the connected body’s anchor. |
|
| Target Angular Velocity | The angular velocity that the joint’s rotational drive aims to achieve. The property is specified as a vector. The vector’s length specifies the rotational speed and whose direction defines the axis of rotation. | |
| Rotation Drive Mode | Set how Unity applies drive force to the object to rotate it to the target orientation. Set the mode to X and YZ, to apply the torque around the axes as specified by the Angular X/YZ Drive properties described below. If you use Slerp mode then the Slerp Drive properties determine the drive torque. | |
| Angular X Drive | This specifies how the drive torque rotates the joint around its local x-axis. This property is only available if the Rotation Drive Mode property described above is set to X & YZ. For more information, see Drive force section below. | |
| Position Spring | The spring torque that Unity uses to rotate the joint from its current position towards its target position. | |
| Position Damper | Reduces the amount of spring torque in proportion to the difference between the joint’s current velocity and its target velocity. This reduces the speed of the joint’s movement. Set a value above zero to allow the joint to dampen oscillations which would otherwise carry on indefinitely. | |
| Maximum Force | Limits the amount of force that the drive can apply. To make the drive apply the force that it’s calculated, set this to a high value that the drive is unlikely to calculate. | |
| Angular YZDrive | This is similar to the Angular X Drive described above but applies to both the joint’s Y and Z axes. | |
| Slerp Drive | This specifies how the drive torque rotates the joint around all local axes. The property is only available if the Rotation Drive Mode property described above is set to Slerp. For more information, see Slerp Drive section below. | |
| Position Spring | The spring torque that Unity uses to rotate the joint from its current position towards its target position. | |
| Position Damper | Reduces the amount of spring torque in proportion to the difference between the joint’s current velocity and its target velocity. This reduces the speed of the joint’s movement. Set a value above zero to allow the joint to dampen oscillations which would otherwise carry on indefinitely. | |
| Maximum Force | Limits the amount of force that the drive can apply. To make the drive apply the force that it’s calculated, set this to a high value that the drive is unlikely to calculate. | |
| Projection Mode | This defines how the joint snaps back to its constraints when it unexpectedly moves beyond them, because the physics engineA system that simulates aspects of physical systems so that objects can accelerate correctly and be affected by collisions, gravity and other forces. More info See in Glossary is unable to reconcile the current combination of forces within the simulation. The options are None and Position and Rotation. |
|
| Projection Distance | The distance the joint must move beyond its constraints before the physics engine attempts to snap it back to an acceptable position. | |
| Projection Angle | The angle the joint must rotate beyond its constraints before the physics engine attempts to snap it back to an acceptable position. | |
| Configured in World Space | Enable this property to calculate the values set by the various target and drive properties in world space instead of the object’s local space. | |
| Swap Bodies | Enable this property to swap the order in which the physics engine processes the Rigidbodies involved in the joint. This results in different joint motion but has no impact on Rigidbodies and anchors. | |
| Break Force | If a force larger than this value pushes the joint beyond its constraints then the joint is permanently “broken” and deleted. Break Torque only breaks a joint when its axes are Limited or Locked (see Constraining movement section below). | |
| Break Torque | If a torque larger than this value rotates the joint beyond its constraints then the joint is permanently “broken” and deleted. Break Force can break a joint regardless of whether its axes are Free, Limited or Locked (see Constraining movement section below). | |
| Enable Collision | Enable this property to let the object with the joint collide with the object it is connected to. If this is disabled, the joint and object will pass through each other. | |
| Enable Preprocessing | If preprocessing is disabled then certain “impossible” configurations of the joint are kept more stable rather than drifting wildly out of control. | |
| Mass Scale | The scale to apply to the inverted mass and inertia tensor of the Rigidbody, ranging from 0.00001 to infinity. This is useful when the joint connects two Rigidbodies of largely varying mass. The physics solver produces better results when the connected Rigidbodies have a similar mass. When your connected Rigidbodies vary in mass, use this property with the Connect Mass Scale property to apply fake masses to make them roughly equal to each other. This produces a high-quality and stable simulation, but reduces the physical behaviour of the Rigidbodies. | |
| Connected Mass Scale | The scale to apply to the inverted mass and inertia tensor of the connected Rigidbody, ranging from 0.00001 to infinity. | |
Details
Like the other joints, you can use the Configurable Joint to restrict the movement of an object but you can also use it to drive it to a target velocity or position with forces. Because there are a lot of configuration options,you may need to experiment with them to get the joint to behave exactly the way you want.
Constraining movement
You can constrain both the translational movement and rotation on each joint axis independently using the X, Y, Z Motion and X, Y, Z Rotation properties. Enable Configured In World Space to constrain movements to the world axes rather than the object’s local axes. Each of these properties can be set to Locked, Limited or Free:
- A Locked axis restricts all movement, so the joint cannot move at all. For example, an object locked in the world y-axis cannot move up or down.
- A Limited axis allows free movement between predefined limits, as explained below. For example, a gun turret might be given a restricted arc of fire by limiting its Y rotation to a specific angular range.
- A Free axis allows any movement.
You can limit translational movement using the Linear Limit property, which defines the maximum distance the joint can move from its point of origin (measured along each axis separately). For example, you can constrain the puck for an air hockey table by locking the joint in the y-axis (in world space), leaving it free in the z-axis and setting the limit for the x-axis to fit the width of the table; the puck is then constrained to stay within the playing area.
You can also limit rotation using the Angular Limit properties. Unlike the linear limit, you can specify different limit values for each axis with this property. You can also define separate upper and lower limits on the angle of rotation for the x-axis; the other two axes use the same angle either side of the original rotation. For example, you can construct a “teeter table” by using a flat plane with a joint constrained to allow slight tilting in the X and Z directions while leaving the Y rotation locked.
Bounciness and springs
By default, a joint stops moving when it runs into its limit. However, an inelastic collision like this is rare in the real world and so it is useful to add some feeling of bounce to a constrained joint. To make the constrained object bounce back after it hits its limit, use the Bounciness property of the linear and angular limits. Most collisionsA collision occurs when the physics engine detects that the colliders of two GameObjects make contact or overlap, when at least one has a Rigidbody component and is in motion. More info
See in Glossary look more natural with a small amount of bounciness but you can also set this property higher to simulate unusually bouncy boundaries like the cushions of a pool table.
To soften the joint limits even more, use the spring properties: Linear Limit Spring for translation and Angular X/YZ Limit Spring for rotation. If you set the Spring property to a value above zero, the joint does not abruptly stop moving when it hits a limit, but is drawn back to the limit position by a spring force. The strength of the force is determined by the Spring value. By default, the spring is perfectly elastic and will catapult the joint back in the opposite direction to the collision.
You can use the Damper property to reduce the elasticity and return the joint to the limit more gently. For example, you can use a spring jointA joint type that connects two Rigidbody components together but allows the distance between them to change as though they were connected by a spring. More info
See in Glossary to create a lever that you can pull to the left or right, but then it springs back to an upright position. If the springs are perfectly elastic then the lever will oscillate back and forth around the centre point after it is released. However, if you add enough damping then the spring will rapidly settle down to the neutral position.
Drive forces
Not only can a joint react to the movements of object it is attached to, but it can also actively apply drive forces to set the object in motion. Some joints need to keep the object moving at a constant speed, such as a rotary motor turning a fan blade. Use the Target Velocity and Target Angular Velocity properties to set your desired velocity for such joints.
You might need to use joints that move their object towards a particular position in space,or a particular orientation. Use the Target Position and Target Rotation properties to set this functionality. For example, to implement a forklift, mount the forks on a configurable joint and then set the target height to raise them from a script.
With the target set, the X, Y, Z Drive and Angular X/YZ Drive (or alternatively Slerp Drive) properties specify the force to use to push the joint toward it. The Drives’ Mode property selects whether the joint should seek a target position, velocity or both. The Position Spring and Position Damper work in the same way as for the joint limits when they seek a target position. In velocity mode, the spring force depends on the “distance” between the current velocity and the target velocity; the damper helps the velocity to settle at the chosen value rather than oscillating endlessly around it. For example, the formula for the XDrive force is:
force = PositionSpring * (target position - position) + PositionDamper * (targetVelocity - velocity)
So, the force grows proportional to the difference between the current value and the target value, and reduces by the damper proportional to the difference between the current velocity and the target one. Unity applies the force to both positional and rotational drives.
The Maximum Force property is a final refinement that prevents the force applied by the spring from exceeding a limit value regardless of how far the joint is from its target. This prevents a joint that you stretch far from its target from rapidly snapping the object back in an uncontrolled way.
When you use any drive force (except for Slerp Drive, described below), the joint applies the force to the object separately in each axis. For example, you can implement a spacecraft that has a high forward flying speed but a relatively low speed in sideways steering motion.
Slerp Drive
Unlike the other drive modes that apply forces in separate axes, the Slerp Drive uses the quaternion’s spherical interpolation or “slerp” functionality to reorient the joint. Rather than isolating individual axes, the slerp process finds the minimum total rotation that takes the object from the current orientation to the target, and applies it on all axes as necessary. Slerp drive is slightly easier to configure but you cannot specify different drive forces for the X and Y/Z axes.
To enable Slerp drive, change the Rotation Drive Mode property from X and YZ to Slerp. A joint can use either the Angular X/YZ Drive values or the Slerp Drive values, but not both.
- 2019–05–23 Page amended