Configurable Joint
Reference Manual > Components > Physics Components > Configurable Joint

Configurable Joint

Configurable Joints are extremely customizable. They expose all joint-related properties of PhysX, so they are capable of creating behaviors similar to all other joint types.


Properties of the Configurable Joint

Details

There are two primary functions that the Configurable Joint can perform: movement/rotation restriction and movement/rotation acceleration. These functions depend on a number of inter-dependent properties. It may require some experimentation to create the exact behavior you're trying to achieve. We'll now give you an overview of the Joint's functionality to make your experimentation as simple as possible.

Movement/Rotation Restriction

You specify restriction per axis and per motion type. XMotion, YMotion, and ZMotion allow you to define translation along that axis. Angular XMotion, Angular YMotion, and Angular ZMotion allow you to define rotation around that axis. Each one of these properties can be set to Free (unrestricted), Limited (restricted based on limits you can define), or Locked (restricted to zero movement).

Limiting Motion

When you have any of the "Motion" properties set to Limited, you can define the limitations of movement for that axis. You do this by changing the values of one of the "Limit" properties.

For translation of movement (non-angular), the Linear Limit property will define the maximum distance the object can move from its origin. Translation on any "Motion" properties set to Limited will be restricted according to Linear Limit->Limit. Think of this Limit property as setting a border around the axis for the object.

Bouncyness, Spring, and Damper will define the behavior of the object when it reaches the Limit on any of the Limited "Motion" axes. If all of these values are set to 0, the object will instantly stop moving when it reaches the border. Bouncyness will make the object bounce back away from the border. Spring and Damper will use springing forces to pull the object back to the border. This will soften the border, so the object will be able to pass through the border and be pulled back instead of stopping immediately.

Limiting Rotation

Limiting rotation works almost the same as limiting motion. The difference is that the three "Angular Motion" properties all correspond to different "Angular Limit" properties. Translation restriction along all 3 axes are defined by the Linear Limit property, and rotation restriction along each of the 3 axes is defined by a separate "Angular Limit" property per axis.

Angular XMotion limitation is the most robust, as you can define a Low Angular XLimit and a High Angular XLimit. Therefore if you want to define a low rotation limit of -35 degrees and a high rotation limit of 180 degrees, you can do this. For the Y and Z axes, the low and high rotation limits will be identical, set together by the Limit property of Angular YLimit or Angular ZLimit.

The same rules about object behavior at the rotation limits from the Limiting Motion section applies here.

Movement/Rotation Acceleration

You specify object movement or rotation in terms of moving the object toward a particular position/rotation, or velocity/angular velocity. This system works by defining the "Target" value you want to move toward, and using a "Drive" to provide acceleration which will move the object toward that target. Each "Drive" has a Mode, which you use to define which "Target" the object is moving toward.

Translation Acceleration

The XDrive, YDrive, and ZDrive properties are what start the object moving along that axis. Each Drive's Mode will define whether the object should be moving toward the Target Position or Target Velocity or both. For example, when XDrive's mode is set to Position, then the object will try to move to the value of Target Position->X.

When a Drive is using Position in its Mode, its Position Spring value will define how the object is moved toward the Target Position. Similarly, when a Drive is using Velocity in its Mode, its Maximum Force value will define how the object is accelerated to the Target Velocity.

Rotation Acceleration

Rotation acceleration properties: Angular XDrive, Angular YZDrive, and Slerp Drive function the same way as the translation Drives. There is one substantial difference. Slerp Drive behaves differently from the Angular Drive functionality. Therefore you can choose to use either both Angular Drives or Slerp Drive by choosing one from the Rotation Drive Mode. You cannot use both at once.

Properties

AnchorThe point where the center of the joint is defined. All physics-based simulation will use this point as the center in calculations
AxisThe local axis that will define the object's natural rotation based on physics simulation
Secondary AxisThe axis that will be used if the Axis is set to (0,0,0)
XMotionAllow movement along the X axis to be Free, completely Locked, or Limited according to Linear Limit
YMotionAllow movement along the Y axis to be Free, completely Locked, or Limited according to Linear Limit
ZMotionAllow movement along the Z axis to be Free, completely Locked, or Limited according to Linear Limit
Angular XMotionAllow rotation around the X axis to be Free, completely Locked, or Limited according to Low and High Angular XLimit
Angular YMotionAllow rotation around the Y axis to be Free, completely Locked, or Limited according to Angular YLimit
Angular ZMotionAllow rotation around the Z axis to be Free, completely Locked, or Limited according to Angular ZLimit
Linear LimitBoundary defining movement restriction, based on distance from the joint's origin
LimitThe distance in units from the origin to the wall of the boundary
BouncynessAmount of bounce-back force applied to the object when it reaches the Limit
SpringStrength of force applied to move the object back to the Limit. Any value other than 0 will implicitly soften the boundary
DamperResistance strength against the Spring
Low Angular XLimitBoundary defining lower rotation restriction, based on delta from original rotation
LimitThe rotation in degrees that the object's rotation should not drop below
BouncynessAmount of bounce-back torque applied to the object when its rotation reaches the Limit
SpringStrength of force applied to move the object back to the Limit. Any value other than 0 will implicitly soften the boundary
DamperResistance strength against the Spring
High Angular XLimitBoundary defining upper rotation restriction, based on delta from original rotation.
LimitThe rotation in degrees that the object's rotation should not exceed
BouncynessAmount of bounce-back torque applied to the object when its rotation reaches the Limit
SpringStrength of force applied to move the object back to the Limit. Any value other than 0 will implicitly soften the boundary
DamperResistance strength against the Spring
Angular YLimitBoundary defining rotation restriction, based on delta from original rotation
LimitThe rotation in degrees that the object's rotation should not exceed
BouncynessAmount of bounce-back torque applied to the object when its rotation reaches the Limit
SpringStrength of torque applied to move the object back to the Limit. Any value other than 0 will implicitly soften the boundary
DamperResistance strength against the Spring
Angular ZLimitBoundary defining rotation restriction, based on delta from original rotation
LimitThe rotation in degrees that the object's rotation should not exceed
BouncynessAmount of bounce-back torque applied to the object when its rotation reaches the Limit
SpringStrength of force applied to move the object back to the Limit. Any value other than 0 will implicitly soften the boundary
DamperResistance strength against the Spring
Target PositionThe desired position that the joint should move into
Target VelocityThe desired velocity that the joint should move along
XDriveDefinition of how the joint's movement will behave along its local X axis
ModeSet the following properties to be dependent on Target Position, Target Velocity, or both
Position SpringStrength of a rubber-band pull toward the defined direction. Only used if Mode includes Position
Position DamperResistance strength against the Position Spring. Only used if Mode includes Position
Maximum ForceAmount of strength applied to push the object toward the defined direction. Only used if Mode includes Velocity
YDriveDefinition of how the joint's movement will behave along its local Y axis
ModeSet the following properties to be dependent on Target Position, Target Velocity, or both
Position SpringStrength of a rubber-band pull toward the defined direction. Only used if Mode includes Position.
Position DamperResistance strength against the Position Spring. Only used if Mode includes Position.
Maximum ForceAmount of strength applied to push the object toward the defined direction. Only used if Mode includes Velocity.
ZDriveDefinition of how the joint's movement will behave along its local Z axis
ModeSet the following properties to be dependent on Target Position, Target Velocity, or both.
Position SpringStrength of a rubber-band pull toward the defined direction. Only used if Mode includes Position
Position DamperResistance strength against the Position Spring. Only used if Mode includes Position
Maximum ForceAmount of strength applied to push the object toward the defined direction. Only used if Mode includes Velocity
Target RotationThis is a Quaternion. It defines the desired rotation that the joint should rotate into
Target Angular VelocityThis is a Vector3. It defines the desired angular velocity that the joint should rotate into
Rotation Drive ModeControl the object's rotation with either X & YZ or Slerp Drive by itself
Angular XDriveDefinition of how the joint's rotation will behave around its local X axis. Only used if Rotation Drive Mode is Swing & Twist
ModeSet the following properties to be dependent on Target Rotation, Target Angular Velocity, or both
Position SpringStrength of a rubber-band pull toward the defined direction. Only used if Mode includes Position
Position DamperResistance strength against the Position Spring. Only used if Mode includes Position
Maximum ForceAmount of strength applied to push the object toward the defined direction. Only used if Mode includes Velocity.
Angular YZDriveDefinition of how the joint's rotation will behave around its local Y and Z axes. Only used if Rotation Drive Mode is Swing & Twist
ModeSet the following properties to be dependent on Target Rotation, Target Angular Velocity, or both
Position SpringStrength of a rubber-band pull toward the defined direction. Only used if Mode includes Position
Position DamperResistance strength against the Position Spring. Only used if Mode includes Position
Maximum ForceAmount of strength applied to push the object toward the defined direction. Only used if Mode includes Velocity
Slerp DriveDefinition of how the joint's rotation will behave around all local axes. Only used if Rotation Drive Mode is Slerp Only
ModeSet the following properties to be dependent on Target Rotation, Target Angular Velocity, or both
Position SpringStrength of a rubber-band pull toward the defined direction. Only used if Mode includes Position
Position DamperResistance strength against the Position Spring. Only used if Mode includes Position
Maximum ForceAmount of strength applied to push the object toward the defined direction. Only used if Mode includes Velocity
Projection ModeProperties to track to snap the object back to its constrained position when it drifts off too much
Projection DistanceDistance from the Connected Body that must be exceeded before the object snaps back to an acceptable position
Projection AngleDifference in angle from the Connected Body that must be exceeded before the object snaps back to an acceptable position
Congfigure in World SpaceIf enabled, all Target values will be calculated in World Space instead of the object's Local Space
Break ForceApplied Force values above this number will cause the joint to be destroyed
Break TorqueApplied Torque values above this number will cause the joint to be destroyed