Constraints

In the physics engine, Constraints are used to simulate connections between objects, such as rods, strings, springs, or ragdolls.

Constraints depend on Rigidbody. If the node does not have a rigidbody component, the engine will automatically add a rigidbody component when adding constraints.

Note: The current constraint only works if the physics engine is selected as Bullet, PhysX or Cannon.js.

HingeConstraint

Hinge constraints constrain the motion of connected objects to a certain axis. This constraint is useful in situations such as simulating the hinge of a door or the rotation of a motor.

HingeConstraint

PropertiesDescription
AttachedBodyThe rigid body to which the constraint is attached, that is, the rigid body component under the same node where the current constraint is located
ConnectedBodyGets or sets the rigid body to which the constraint is connected, null means it is linked to a static body
EnableCollisionGets or sets whether collision is enabled between two bodies connected by a constraint
PivotAConstrain the relative position of a joint in the local space of its own rigid body
PivotBConstrain the relative position of the joint in the local space of the connected rigid body
AxisThe axis that constrains constraint rotation in local space

physics-hinge

Please refer to HingeConstraint API for the hinge constraint interface.

PointToPointConstraint

A point-to-point constraint is a simple composite constraint that connects two objects, or one object, to a point in the coordinate system. The connected objects can be freely rotated with respect to each other while sharing a common connection point.

point-to-point constraint

PropertiesDescription
AttachedBodyThe rigid body to which the constraint is attached, that is, the rigid body component under the same node where the current constraint is located
ConnectedBodyGets or sets the rigid body to which the constraint is connected, null means it is linked to a static body
EnableCollisionGets or sets whether collision is enabled between two bodies connected by a constraint
PivotAConstrain the relative position of a joint in the local space of its own rigid body
PivotBConstrain the relative position of the joint in the local space of the connected rigid body

physics-p2p

For point-to-point constraint interface, please refer to PointToPointConstraint API.

FixedConstraint

A fixed constraint is the simplest constraint, it locks the relative position and rotation of two rigid bodies. The connected objects are not allowed to move relatively to each other.

FixedConstraint

PropertiesDescription
AttachedBodyThe rigid body to which the constraint is attached, that is, the rigid body component under the same node where the current constraint is located
ConnectedBodyGets or sets the rigid body to which the constraint is connected, null means it is linked to a static body
EnableCollisionGets or sets whether collision is enabled between two bodies connected by a constraint
BreakForceGets or sets the maximum force that can be applied to the constraint before it breaks
BreakTorqueGets or sets the maximum torque that can be applied to the constraint before it breaks

physics-fixed

For fixed constraint interface, please refer to FixedConstraint API.

Configurable constraint

Configurable constraints are one of the most comprehensive constraints in physics engines, including various commonly used constraint types in game engines. Through configuration, control can be applied to each of the six degrees of freedom, and nearly all commonly used special constraints in physics engines can be achieved by setting constraint parameters in different directions. Different degrees of freedom can have different constraint modes, such as free, limited, and locked. Free means no constraints are applied, limit means the range and process of the rigid body’s motion are limited, and locked means the connected rigid bodies must be relatively stationary. For example, setting the constraint mode of all six degrees of freedom to locked is equivalent to using a fixed constraint to restrict the rigid body. In limit mode, the motion of the rigid body can be restricted to a certain extent, such as limiting the movement of that degree of freedom within a certain range. For the rigid body in limit mode, when it reaches the boundary of the restricted range, it will bounce back. At this time, the rebound strength can be adjusted by setting different rebound coefficients, and the elasticity of the constraint can be achieved by adjusting the parameters of the soft constraint, applying a certain amount of resistance to the motion, etc.

Rigid bodies connected by configurable constraints can produce the desired relative motion driven by the motor. After the motor is enabled, the rigid body will move to the specified relative position or gradually accelerate to the specified relative velocity and maintain motion. The motor has two different modes, servo mode and normal mode. In servo mode, the driver will make the rigid body move to the specified position or angle and stop after reaching the target position or angle. In normal mode, the driver will gradually accelerate the rigid body to achieve the specified linear velocity or angular velocity, and then maintain that velocity. Another adjustable parameter is the maximum driving force of the driver, which determines how fast the rigid body can accelerate towards the specified target position and velocity. When the maximum driving force is large, it will be difficult for external interference to change the relative motion state between rigid bodies.

physics-configurable-main | Properties | Description | | :— | :— | | AttachedBody | The rigid body to which the constraint is attached, that is, the rigid body component under the same node where the current constraint is located | | ConnectedBody | Gets or sets the rigid body to which the constraint is connected, null means it is linked to a static body | | EnableCollision | Gets or sets whether collision is enabled between two bodies connected by a constraint | | Axis | Gets or sets the principle axis of the constraint | | SecondaryAxis | Gets or sets the secondary axis of the constraint (orthogonal to the principle axis) | | PivotA | The relative position of the joint in the local space of its own rigid body | | PivotB | The relative position of the joint in the local space of the connected rigid body | | AutoPivotB | Automatically derivate the pivotB from the pivotA and the relative transform between the two rigid bodies | | BreakForce | Gets or sets the maximum force that can be applied to the constraint before it breaks | | BreakTorque | Gets or sets the maximum torque that can be applied to the constraint before it breaks | | LinearLimitSettings | Gets or sets the linear limit settings | | AngularLimitSettings | Gets or sets the angular limit settings | | LinearDriverSettings | Gets or sets the linear motor settings | | AngularDriverSettings | Gets or sets the angular motor settings |

Example: When the main axis of the constraint is set to the y-axis of the attached rigid body, and the secondary axis is set to the x-axis of the attached rigid body, the coordinate of the constraint is shown in the figure below. | local coordinate of the attached body | linear coordinate of the joint | angular coordinate of the joint | | :— | :— | :— | | configurable-constraint-axis-config | constraint-coordinate | constraint-angular-coordinate |

Linear limit settings

physics-configurable-linear-limit | Properties | Description | | :— | :— | | XMotion | Gets or sets the constraint mode of the x-axis | | YMotion | Gets or sets the constraint mode of the y-axis | | ZMotion | Gets or sets the constraint mode of the z-axis | | Upper | Gets or sets the upper limit of the linear limit | | Lower | Gets or sets the lower limit of the linear limit | | Restitution | Gets or sets the restitution of the constraint | | Enable Soft Constraint | Gets or sets whether to enable soft constraint | | Damping | Gets or sets the damping of the constraint | | Stiffness | Gets or sets the stiffness of the constraint |

Angular limit settings

physics-configurable-angular-limit

PropertiesDescription
Twist MotionGets or sets the constraint mode of the twist axis
Swing Motion1Gets or sets the constraint mode of the swing y axis
Swing Motion2Gets or sets the constraint mode of the swing z axis
Twist ExtentGets or sets the limit angle along the twist axis
Swing Extent1Gets or sets the limit angle along the swing y axis
Swing Extent2Gets or sets the limit angle along the swing z axis
Twist RestitutionGets or sets the restitution of the twist constraint
Swing RestitutionGets or sets the restitution of the swing constraint
Enable Soft Constraint TwistGets or sets whether to enable soft constraint for twist
Twist DampingGets or sets the damping of the twist constraint
Twist StiffnessGets or sets the stiffness of the twist constraint
Enable Soft Constraint SwingGets or sets whether to enable soft constraint for swing
Swing DampingGets or sets the damping of the swing constraint
Swing StiffnessGets or sets the stiffness of the swing constraint

Linear driver settings

physics-configurable-linear-driver

PropertiesDescription
XDriveGets or sets the driver mode along the x axis
YDriveGets or sets the driver mode along the y axis
ZDriveGets or sets the driver mode along the z axis
target PositionGets or sets the target position
Target VelocityGets or sets the target velocity
StrengthGets or sets the maximum driving force

Angular driver settings

physics-configurable-angular-driver

PropertiesDescription
Twist DriveGets or sets the driver mode along the twist axis
Swing Drive1Gets or sets the driver mode along the swing y axis
Swing Drive2Gets or sets the driver mode along the swing z axis
target OrientationGets or sets the target angle
Target velocityGets or sets the target angular velocity
StrengthGets or sets the maximum driving force

Drive Mode

Both linear and angular motors can have their drive modes adjusted by sub-axis, there are 3 drive modes:

  • DISABLED: Disabled mode, in which the corresponding split-axis is not affected by the motor driving force or torque.
  • SERVO: Attempts to move/rotate to a specified position/angle.

    • Linear motors: The Drive attributes of X, Y and Z correspond to the three parameters of the Target Position.

      servo.png

      For example, if XDrive is SERVO and the X component of Target Position is 10, then the constraint will try to move to 10.

    • Angle motors: Twist Drive, Swig Drive1, Swig Drive2 correspond to the three parameters of Target Orientation respectively

  • INDUCTION: drive the constraint to the specified speed/angular velocity.

    • Linear motors: The Drive attributes of X, Y, and Z correspond to the three parameters of Target Velocity respectively

      The Drive attribute for X, Y, and Z corresponds to the three parameters of Target Velocity.

      induction.png

      For example, if XDrive is INDUCTION and the X component of Target Velocity is 10, then the constraint will try to move its velocity to 10.

    • Angle motors: Twist Drive, Swig Drive1, Swig Drive2 correspond to the three parameters of Target Velocity.

For configurable constraint interface, please refer to ConfigurableConstraint API.