---

PhysX Constraint Reference

---

Overview

---

A constraint is basically another name for a joint. It allows you to connect two rigid bodies together, and also apply limits or forces. Unreal Engine 3 has a very flexible and data-driven constraint system that allows designers to make many different types of joint simple by changing some options. The engine has a few default joint types (ball-and-socket, hinge, prismatic) but they only differ in their settings. You should feel free to start with any joint type and experiment with making your own configurations.

Shared and per-instance settings

The settings are divided into two parts - those that are shared by all instances of a particular joint, and those that are unique to each instance. Something like a joint limit will be the same for all instances of a joint for example, but various motor settings may be different on each one. Shared properties are stored in the RB_ConstraintSetup object, whereas per-instance properties are stored in the RB_ConstraintInstance object. In PhAT you can toggle between these with a joint selected by pressing the 'I' key on your keyboard (or pressing the 'i' button on the tool bar).

Stiffness And Damping

At several places in the constraint you can set a 'stiffness' and 'damping' parameter to control the behavior of a spring. You can think of these settings in the context of a car suspension setup which is made from a spring and an oil piston. The spring controls how much force is generated to bring the object back to its default or equilibrium position, and the damping is like the oil that acts to damp any motion. If you have some stiffness but no damping, then the motion will oscillate back and forth and never come to rest. If you set your damping very high, it can take a long time to reach its equilibrium.

RB_ConstraintSetup

---

General Settings

• ConstraintBone1 - In a PhysicsAsset, the name of the first bone that the joint should connect.
• ConstraintBone2 - In a PhysicsAsset, the name of the second bone that the joint should connect.

Linear Settings

There are three LinearSetup structures - one for X, Y and Z directions. Each have the following settings:

• bLimited - If there is a limit on this degree of freedom. If false, linear movement is not limited at all.
• LimitSize - If bLimited is true, how much movement is allowed in this direction. Set this to zero to completely lock this degree of freedom.

Note that linear limits are actually spherical - so if a direction is not limited to zero ('locked') then it will use the max of the three LimitSize values. So if X was 0, Y was 10 and Z was 20, it would be limited to a circle of radius 20 on the YZ plane. If X was 0, Y was 0 and Z was 20, it would be limited to a line along Z which went from +20 to -20.

• bLinearLimitSoft - By default the linear limits are 'hard'. If you set this to true they are treated as springy instead and you can 'push' into them.
• LinearLimitStiffness - If bLinearLimitSoft is true, this controls the stiffness of the limit spring.
• LinearLimitDamping - If bLinearLimitSoft is true, this controls the damping of the limit spring.
• bLinearBreakable - If true, this joint can be broken by applying a linear force to it (basically pulling the joint apart).
• LinearBreakThreshold - If bLinearBreakable is true, this is the force that is needed to break the joint.

Angular Settings

The angular part of a joint is specified in terms of 'swing' and 'twist'. You can think of swing as a cone around the X axis, and twist as rotation around that axis. In UE3 the cone limit is specified by two angles, so can be an elliptical cone.

• bSwingLimited - If true, the angle between the two bodies is limited to a cone.
• bTwistLimited - If true, the twist between the two bodies is limited.
• bSwingLimitSoft - By default the swing cone limit is 'hard'. If this is set to true it is springy instead and can be pushed into.
• bTwistLimitSoft - By default the twist limit is 'hard'. If this is set to true it is springy instead and can be pushed into.
• Swing1LimitAngle - Defines one dimension of the swing limit cone in degrees.
• Swing2LimitAngle - Defines the other dimension of the swing limit cone in degrees.
• TwistLimitAngle - Defines the amount of twist that is allowed between the two constrained bodies.
• SwingLimitStiffness - If bSwingLimitSoft is true, this controls the stiffness of the cone.
• SwingLimitDamping - If bSwingLimitSoft is true, this controls the damping of the cone.
• TwistLimitStiffness - If bTwistLimitSoft is true, this controls the stiffness of the twist limit.
• TwistLimitDamping - If bTwistLimitSoft is true, this controls the damping of the twist limit.
• bAngularBreakable - If true, this joint can be broken by applying a torque to it (basically twisting the joint apart).
• AngularBreakThreshold - If bAngularBreakable is true, this is the torque required to break this joint.

Pulley Settings

A pulley is a special kind of joint that acts like a point on one body is connected by a rope to a point on the other, and that rope also passes through 2 points in space. When using this kind of joint, most other joint settings will have no effect.

• bIsPulley - If true, this joint will be treated as a pulley type.
• bMaintainMinDistance - If true, no 'slack' is allowed in the 'ropes' and they are treated a bit like rods instead, so you can push up on one object and the other will be pushed down.
• PulleyRatio - The gear ratio on the pulley. If its not 1.0, pulling on one side will result in less movement on the other, but with more force.

RB_ConstraintInstance

---

Velocity And Position Drive

Unreal Engine 3 provides two ways to drive a joint - Position and Velocity drive. Position drive acts like a spring, where the joint will attempt to reach a given position using the stiffness and damping properties you specify. Velocity drive is like a motor, where you specify the velocity you desire and a maximum force that may be applied to achieve it.

Linear Settings

• bLinearXPositionDrive - Enable position drive on the linear X axis.
• bLinearXVelocityDrive - Enable velocity drive on the linear X axis.
• bLinearYPositionDrive - Enable position drive on the linear Y axis.
• bLinearYVelocityDrive - Enable velocity drive on the linear Y axis.
• bLinearZPositionDrive - Enable position drive on the linear Z axis.
• bLinearZVelocityDrive - Enable velocity drive on the linear Z axis.
• LinearPositionTarget - If linear position drive is enabled, this is the target relative position that the joint will try to achieve.
• LinearVelocityTarget - If linear velocity drive is enabled, this is the target relative linear velocity that the joint will try to achieve.
• LinearDriveSpring - If linear position drive is enabled, this is the stiffness of the drive spring.
• LinearDriveDamping - If linear position drive is enabled, this is the damping of the drive spring.
• LinearDriveForceLimit - If linear velocity drive is enabled, this is the maximum force that will be applied to attain LinearVelocityTarget.

Angular Settings

• bSwingPositionDrive - Enable position drive on the swing axes.
• bSwingVelocityDrive - Enable velocity drive on the swing axes.
• bTwistPositionDrive - Enable position drive around the twist axis.
• bTwistVelocityDrive - Enable velocity drive around the twist axis.
• bAngularSlerpDrive - Advanced option. Specifies the method that is used for applying drive to the joint.
• AngularPositionTarget - If angular position drive is enabled, this is the target relative quaternion that the joint will try to achieve.
• AngularVelocityTarget - If angular velocity drive is enabled, this is the target relative angular velocity that the joint will try to achieve.
• AngularDriveSpring - If angular position drive is enabled, this is the stiffness of the drive spring.
• AngularDriveDamping - If angular position drive is enabled, this is the damping of the drive spring.
• AngularDriveForceLimit - If angular velocity drive is enabled, this is the maximum torque that will be applied to attain AngularVelocityTarget.

Examples

---

Ball And Socket

A ball-and-socket joint is simply a joint that has all its linear parts locked and all its angular parts free.

Hinge

A hinge is like a ball-and-socket in that all its linear parts are locked, but its swing parts are also locked, so it can only rotate around its twist axis.

Prismatic

A prismatic joint has 2 out of its 3 linear degrees of freedom locked, and also has all its angular degrees of freedom locked. This allows is to slide down a 'rail' but cannot rotate at all.

Joint Friction

You can simulate joint friction using the drive settings. Turn on velocity drive with a target velocity of zero, and use the LinearDriveForceLimit and AngularDriveForceLimit settings to control how strongly the joint will resist motion.

Punch bag

You could simulate something like a punch-bag (a ball on the top of a vertical pole that can be knocked around) with a joint by first creating a ball-and-socket joint. Then turn on swing position drive and adjust the AngularDriveSpring and AngularDriveDamping until it springs nicely around the upright position when pushed. You could turn on swing limits as well to ensure that it cannot bend over too far.

Downloads

---

• Download the PhysX constraints example.