Struct PhysicsJoint

A set of constraints on the relative motion of a PhysicsConstrainedBodyPair. Most joint types can be described with a single instance, but complex setups like ragdoll joints require more than one instance to stabilize. In these cases, you should associate multiple joints using PhysicsJointCompanion.

Implements
IComponentData
IQueryTypeParameter
Inherited Members
Namespace: Unity.Physics
Assembly: Unity.Physics.dll
Syntax
public struct PhysicsJoint : IComponentData, IQueryTypeParameter

Properties

BodyAFromJoint

The anchor point and orientation in the space of the first body.

Declaration
[CreateProperty]
public BodyFrame BodyAFromJoint { get; set; }
Property Value
Type Description
BodyFrame

The body from joint.

BodyBFromJoint

The target point and orientation in the space of the second body.

Declaration
[CreateProperty]
public BodyFrame BodyBFromJoint { get; set; }
Property Value
Type Description
BodyFrame

The body b from joint.

this[int]

Access to Constraint atom with provided index.

Declaration
public Constraint this[int constraintIndex] { get; set; }
Parameters
Type Name Description
int constraintIndex

Index of the constraint atom.
Property Value
Type Description
Constraint

JointType

An optional property to provide a hint about what behavior the underlying constraints represent. Use it in conjunction with convenience setters in JointComponentExtensions to modify constraints. Its value is set when you use a factory method to construct a new PhysicsJoint instance, but it has no effect on joint behavior. See also.

Declaration
[CreateProperty]
public JointType JointType { get; set; }
Property Value
Type Description
JointType

The type of the joint.
See Also

Version

A counter to keep track of changes to the joint's definition. Use it with back-ends like Havok that cache information about the joint if its properties have not changed.

Declaration
[CreateProperty]
public byte Version { get; }
Property Value
Type Description
byte

The version.

Methods

CreateAngularVelocityMotor(BodyFrame, BodyFrame, float, float)

Create a AngularVelocityMotor joint. This is an angular motor that will spin around an axis at the specified constant target velocity.

Declaration
public static PhysicsJoint CreateAngularVelocityMotor(BodyFrame bodyAFromJoint, BodyFrame bodyBFromJoint, float targetVelocity, float maxImpulseOfMotor = Infinity)
Parameters
Type Name Description
BodyFrame bodyAFromJoint

Specifies the pivot point and axis of rotation in the space of body A. This is the body that has the motor. The BodyFrame parameters should be set as follows: The Position should be set to the pivot position. The Pivot Position is an offset from the center of the body with the motor (bodyA). The Axis is the axis that bodyA will pivot about. Value must be normalized. The Perpendicular Axis must be perpendicular to Axis. Value must be normalized.
BodyFrame bodyBFromJoint

Specifies the pivot point and axis of rotation in the space of bodyB. This is the Connected Body. If no body is connected, then bodyB is the World and data should be in world-space. It is recommended to 'Auto Set Connected' this body to bodyA such that they share a pivot point (code is not supported for this not to be enabled) and should be calculated using the following transformation: RigidTransform bFromA = math.mul(math.inverse(worldFromB), worldFromA). The BodyFrame parameters should be set as follows: The Position should be calculated as math.transform(bFromA, PivotPosition); where PivotPosition is the translation in bodyAFromJoint. This is the position of the Pivot relative to the Connected Body. The Axis should be calculated as math.mul(bFromA.rot, axis), where axis is the Axis of bodyAFromJoint. This is the translation of the Axis relative to the Connected Body. Value must be normalized. The Perpendicular Axis should be calculated as perpendicular to Axis (for bodyB). Value must be normalized.
float targetVelocity

The target angular velocity around Joint's Axis, in radians/s.
float maxImpulseOfMotor

The magnitude of the max impulse that a motor constraint can exert in a single step. This is a motor specific usage that does not represent the impulse threshold to break the motor.
Returns
Type Description
PhysicsJoint

A Constraint.

CreateBallAndSocket(float3, float3)

Create a BallAndSocket joint.

Declaration
public static PhysicsJoint CreateBallAndSocket(float3 anchorA, float3 anchorB)
Parameters
Type Name Description
float3 anchorA

Specifies the anchor point in the space of body A.
float3 anchorB

Specifies the target point in the space of body B.
Returns
Type Description
PhysicsJoint

The new ball and socket joint.

CreateFixed(BodyFrame, BodyFrame)

Create a Fixed joint.

Declaration
public static PhysicsJoint CreateFixed(BodyFrame bodyAFromJoint, BodyFrame bodyBFromJoint)
Parameters
Type Name Description
BodyFrame bodyAFromJoint

Specifies a reference point and orientation in the space of body A.
BodyFrame bodyBFromJoint

Specifies a target point and orientation in the space of body B.
Returns
Type Description
PhysicsJoint

The new fixed joint.

CreateHinge(BodyFrame, BodyFrame)

Create a Hinge joint.

Declaration
public static PhysicsJoint CreateHinge(BodyFrame bodyAFromJoint, BodyFrame bodyBFromJoint)
Parameters
Type Name Description
BodyFrame bodyAFromJoint

Specifies the anchor point and axis of rotation in the space of body A.
BodyFrame bodyBFromJoint

Specifies the target point and axis of alignment in the space of body B.
Returns
Type Description
PhysicsJoint

The new hinge joint.

CreateLimitedDOF(RigidTransform, bool3, bool3)

Create a LimitedDegreeOfFreedom joint.

Declaration
public static PhysicsJoint CreateLimitedDOF(RigidTransform offset, bool3 linearLocks, bool3 angularLocks)
Parameters
Type Name Description
RigidTransform offset

Specifies a target point and orientation in the space of body B.
bool3 linearLocks

Specifies which linear axes are constrained.
bool3 angularLocks

Specifies which angular axes are constrained.
Returns
Type Description
PhysicsJoint

The new limited degree of freedom.

CreateLimitedDistance(float3, float3, FloatRange)

Create a LimitedDistance joint.

Declaration
public static PhysicsJoint CreateLimitedDistance(float3 anchorA, float3 anchorB, Math.FloatRange distanceRange)
Parameters
Type Name Description
float3 anchorA

Specifies the anchor point in the space of body A.
float3 anchorB

Specifies the target point in the space of body B.
Math.FloatRange distanceRange

The minimum required distance and maximum possible distance between the two anchor points.
Returns
Type Description
PhysicsJoint

The new limited distance joint.

CreateLimitedDistance(float3, float3, FloatRange, float3, float, float)

Create a LimitedDistance joint.

Declaration
public static PhysicsJoint CreateLimitedDistance(float3 anchorA, float3 anchorB, Math.FloatRange distanceRange, float3 impulseEventThreshold, float springFrequency = 74341.31, float dampingRatio = 2530.126)
Parameters
Type Name Description
float3 anchorA

Specifies the anchor point in the space of body A.
float3 anchorB

Specifies the target point in the space of body B.
Math.FloatRange distanceRange

The minimum required distance and maximum possible distance between the two anchor points.
float3 impulseEventThreshold

The minimum impulse needed to receive an impulse event for this joint.
float springFrequency

The spring frequency used to relax this joint.
float dampingRatio

The damping ratio used to relax this joint.
Returns
Type Description
PhysicsJoint

The new limited distance joint.

CreateLimitedHinge(BodyFrame, BodyFrame, FloatRange)

Create a LimitedHinge joint.

Declaration
public static PhysicsJoint CreateLimitedHinge(BodyFrame bodyAFromJoint, BodyFrame bodyBFromJoint, Math.FloatRange angularRange)
Parameters
Type Name Description
BodyFrame bodyAFromJoint

Specifies the anchor point, axis of rotation, and rest orientation in the space of body A.
BodyFrame bodyBFromJoint

Specifies the target point, axis of alignment, and reference orientation in the space of body B.
Math.FloatRange angularRange

The minimum required and maximum possible angle of rotation about the aligned axes.
Returns
Type Description
PhysicsJoint

The new limited hinge joint.

CreateLinearVelocityMotor(BodyFrame, BodyFrame, float, float)

Create a LinearVelocityMotor joint. This is a motorized prismatic joint type that will drive to a constant target relative velocity, in a specified direction.

Declaration
public static PhysicsJoint CreateLinearVelocityMotor(BodyFrame bodyAFromJoint, BodyFrame bodyBFromJoint, float target, float maxImpulseOfMotor = Infinity)
Parameters
Type Name Description
BodyFrame bodyAFromJoint

Specifies the anchor point and axis of rotation in the space of bodyA. This is the body that has the motor. The BodyFrame parameters should be set as follows: The Position should be set to the anchor position. The Anchor Position is an offset from the center of the body with the motor (bodyA), representing the anchor point of translation. The Axis is the normalized direction of the motor rotated relative to the orientation of bodyA. Value must be normalized. The Perpendicular Axis should be calculated as perpendicular to Axis. Value must be normalized.
BodyFrame bodyBFromJoint

Specifies the pivot point and axis of alignment in the space of bodyB. This is the Connected Body. If no body is connected, then bodyB is the World and data should be in world-space. It is recommended to 'Auto Set Connected' this body to bodyA such that they share a pivot point (code is not supported for this not to be enabled) and should be calculated using the following transformation: RigidTransform bFromA = math.mul(math.inverse(worldFromB), worldFromA). The BodyFrame parameters should be set as follows: The Position should be calculated as math.transform(bFromA, AnchorPosition); where AnchorPosition is the translation in bodyAFromJoint. This is the position of the Anchor relative to the Connected Body. The Axis should be calculated as math.mul(bFromA.rot, axis), where axis is the Axis of bodyAFromJoint. This is the translation of the Axis relative to the Connected Body. Value must be normalized. The Perpendicular Axis should be calculated as perpendicular to Axis (for bodyB). Value must be normalized.
float target

The target velocity, in m/s. The motor will drive the bodies to this relative speed, along the Joint's Axis.
float maxImpulseOfMotor

The magnitude of the max impulse that a motor constraint can exert in a single step. This is a motor specific usage that does not represent the impulse threshold to break the motor.
Returns
Type Description
PhysicsJoint

A Constraint.

CreatePositionMotor(BodyFrame, BodyFrame, float, float)

Create a PositionMotor joint. This is a motorized prismatic joint that drives bodies toward the specified relative target position, along one axis.

Declaration
public static PhysicsJoint CreatePositionMotor(BodyFrame bodyAFromJoint, BodyFrame bodyBFromJoint, float target, float maxImpulseOfMotor = Infinity)
Parameters
Type Name Description
BodyFrame bodyAFromJoint

Specifies the anchor point and axis of translation of bodyA. This is the body that has the motor. The BodyFrame parameters should be set as follows: The Position should be set to the anchor position. The Anchor Position is an offset from the center of the body with the motor (bodyA), and represents the anchor point of translation. The Axis is the normalized direction of the motor rotated relative to the orientation of bodyA. Value must be normalized. The Perpendicular Axis must be perpendicular to Axis. Value must be normalized.
BodyFrame bodyBFromJoint

Specifies the pivot point and axis of alignment in the space of bodyB. This is the Connected Body. If no body is connected, then bodyB is the World and data should be in world-space. It is recommended to 'Auto Set Connected' this body to bodyA such that they share a pivot point (code is not supported for this not to be enabled) and should be calculated using the following transformation: RigidTransform bFromA = math.mul(math.inverse(worldFromB), worldFromA). The BodyFrame parameters should be set as follows: The Position should be calculated as math.transform(bFromA, AnchorPosition); where AnchorPosition is the translation in bodyAFromJoint. This is the position of the Anchor relative to the Connected Body. The Axis should be calculated as math.mul(bFromA.rot, axis), where axis is the Axis of bodyAFromJoint. This is the translation of the Axis relative to the Connected Body. Value must be normalized. The Perpendicular Axis should be calculated as perpendicular to Axis (for bodyB). Value must be normalized.
float target

The target distance between the bodies' anchor points, along the Joint's Axis. This is the position the motor will be driving towards.
float maxImpulseOfMotor

The magnitude of the max impulse that a motor constraint can exert in a single step. This is a motor specific usage that does not represent the impulse threshold to break the motor.
Returns
Type Description
PhysicsJoint

A Constraint.

CreatePrismatic(BodyFrame, BodyFrame, FloatRange)

Create a Prismatic joint.

Declaration
public static PhysicsJoint CreatePrismatic(BodyFrame bodyAFromJoint, BodyFrame bodyBFromJoint, Math.FloatRange distanceOnAxis)
Parameters
Type Name Description
BodyFrame bodyAFromJoint

Specifies the anchor point and axis of rotation in the space of body A.
BodyFrame bodyBFromJoint

Specifies the target point and axis of alignment in the space of body B.
Math.FloatRange distanceOnAxis

The minimum required and maximum possible distance between the two anchor points along their aligned axes.
Returns
Type Description
PhysicsJoint

A Constraint.

CreateRagdoll(BodyFrame, BodyFrame, float, FloatRange, FloatRange, out PhysicsJoint, out PhysicsJoint)

Create a RagdollPrimaryCone and RagdollPerpendicularCone joint suitable for multi-axial joints on characters. The primary axis of the joined bodies can rotate within a range of motion defined by the maximum cone angle, minus the intersection with a pair of cones along the perpendicular axis. The bodies may also twist about the primary axis within this range.

Declaration
public static void CreateRagdoll(BodyFrame bodyAFromJoint, BodyFrame bodyBFromJoint, float maxConeAngle, Math.FloatRange angularPlaneRange, Math.FloatRange angularTwistRange, out PhysicsJoint primaryConeAndTwist, out PhysicsJoint perpendicularCone)
Parameters
Type Name Description
BodyFrame bodyAFromJoint

Specifies the anchor point, axis of rotation, and rest orientation in the space of body A.
BodyFrame bodyBFromJoint

Specifies the target point, axis of alignment, and reference orientation in the space of body B.
float maxConeAngle

Half angle of the primary cone, which defines the maximum possible range of motion in which the primary axis is restricted. This value is clamped to the range (-pi, pi).
Math.FloatRange angularPlaneRange

The range of angular motion defining the cones perpendicular to the primary cone, between which the primary axis may swing. This range may be asymmetrical, and is clamped to the range (-pi/2, pi/2)./param>
Math.FloatRange angularTwistRange

The range of angular motion for twisting around the primary axis within the region defined by the primary and perpendicular cones. This range is usually symmetrical, and is clamped to the range (-pi, pi).
PhysicsJoint primaryConeAndTwist

[out] The joint defining the maximum conical range of the primary axis and the angular range of motion about it.
PhysicsJoint perpendicularCone

[out] The joint defining the conic sections about the perpendicular axis to subtract from the primary cone.

CreateRotationalMotor(BodyFrame, BodyFrame, float, float)

Create a RotationalMotor joint. This is an angular motor that will drive towards the specified target angle, about an axis.

Declaration
public static PhysicsJoint CreateRotationalMotor(BodyFrame bodyAFromJoint, BodyFrame bodyBFromJoint, float target, float maxImpulseOfMotor = Infinity)
Parameters
Type Name Description
BodyFrame bodyAFromJoint

Specifies the pivot point and axis of rotation in the space of body A. This is the body that has the motor. The BodyFrame parameters should be set as follows: The Position should be set to the pivot position. The Pivot Position is an offset from the center of the body with the motor (bodyA). The Axis is the axis that bodyA will pivot about. Value must be normalized. The Perpendicular Axis must be perpendicular to Axis. Value must be normalized.
BodyFrame bodyBFromJoint

Specifies the pivot point and axis of alignment in the space of bodyB. This is the Connected Body. If no body is connected, then bodyB is the World and data should be in world-space. It is recommended to 'Auto Set Connected' this body to bodyA such that they share a pivot point (code is not supported for this not to be enabled) and should be calculated using the following transformation: RigidTransform bFromA = math.mul(math.inverse(worldFromB), worldFromA). The BodyFrame parameters should be set as follows: The Position should be calculated as math.transform(bFromA, PivotPosition); where PivotPosition is the translation in bodyAFromJoint. This is the position of the Pivot relative to the Connected Body. The Axis should be calculated as math.mul(bFromA.rot, axis), where axis is the Axis of bodyAFromJoint. This is the translation of the Axis relative to the Connected Body. Value must be normalized. The Perpendicular Axis should be calculated as perpendicular to Axis (for bodyB). Value must be normalized.
float target

The target rotation around Joint's Axis, in radians.
float maxImpulseOfMotor

The magnitude of the max impulse that a motor constraint can exert in a single step. This is a motor specific usage that does not represent the impulse threshold to break the motor.
Returns
Type Description
PhysicsJoint

A Constraint.

GetConstraintCount()

Get number of Constraint atoms in this joint.

Declaration
public int GetConstraintCount()
Returns
Type Description
int

Number of constraint atoms in this joint.

GetConstraints()

Get the sequence of Constraint atoms to apply between the two bodies.

Declaration
public FixedList512Bytes<Constraint> GetConstraints()
Returns
Type Description
FixedList512Bytes<Constraint>

The constraints.

SetConstraints(FixedList512Bytes<Constraint>)

Set the sequence of Constraints to apply between the two bodies.

Declaration
public void SetConstraints(FixedList512Bytes<Constraint> constraints)
Parameters
Type Name Description
FixedList512Bytes<Constraint> constraints

A sequence of Constraints to apply in order.

SetImpulseEventThresholdAllConstraints(float3)

Set the impulse event threshold for all eligible constraints (non-motorized ones) in this joint.

Declaration
public void SetImpulseEventThresholdAllConstraints(float3 impulseEventThreshold)
Parameters
Type Name Description
float3 impulseEventThreshold

Impulse event threshold.

SetImpulseEventThresholdAllConstraints(float3, float3)

Set the impulse event threshold for all eligible constraints (non-motorized ones) in this joint.

Declaration
public void SetImpulseEventThresholdAllConstraints(float3 impulseEventLinearThreshold, float3 impulseEventAngularThreshold)
Parameters
Type Name Description
float3 impulseEventLinearThreshold

Impulse event threshold for all linear constraints.
float3 impulseEventAngularThreshold

Impulse event threshold for all angular constraints.

SetImpulseEventThresholdSingleConstraint(int, float3)

Set the impulse event threshold of a constraint specified by constraint index. If a selected constraint is a motor, this function will have no effect.

Declaration
public void SetImpulseEventThresholdSingleConstraint(int constraintIndex, float3 impulseEventThreshold)
Parameters
Type Name Description
int constraintIndex

Constraint index (a value between 0 and 2).
float3 impulseEventThreshold

Impulse event threshold.

Implements

Unity.Entities.IComponentData
Unity.Entities.IQueryTypeParameter

Extension Methods