PhysicsJoint
A joint is used to constrain bodies to the world or to each other in various ways. A joint is automatically destroyed when either body it is attached to is destroyed. A joint cannot exist unattached from a body.
Read time 5 minutesLast updated 13 days ago
Definition
- Type: Struct
- Namespace: Unity.U2D.Physics
- Assembly: UnityEngine.PhysicsCore2DModule
- Implements: IEquatable<PhysicsJoint>
public readonly struct PhysicsJoint : IEquatable<PhysicsJoint>
Remarks
Connect or constrain two bodies by creating a joint between them. For example, create a fixed joint to weld two bodies together, or a distance joint to keep them a set distance apart. Use joints to simulate real-world mechanical behaviors like a spring or a hinge. All joints let you set the anchor points on the bodies they connect, and limits on the force and torque they apply. Create two PhysicsBody objects, create a definition object for the joint type you want, for example PhysicsDistanceJointDefinition, then pass the definition into PhysicsWorld.CreateJoint. If you destroy a body, Unity also destroys any joints connected to it.
Additional Resources: PhysicsJoint.JointType, PhysicsDistanceJointDefinition
Examples
// Use a fixed distance joint to create a fixed point that a large circle swings from.using UnityEngine;using Unity.U2D.Physics;public class CreateJointExample : MonoBehaviour{ public PhysicsDistanceJointDefinition jointDefinition = new PhysicsDistanceJointDefinition(); void Awake() { PhysicsWorld world = PhysicsWorld.defaultWorld; // Create a static fixed body. PhysicsBodyDefinition bodyDefinition1 = new PhysicsBodyDefinition { type = PhysicsBody.BodyType.Static, position = new Vector2(-5f, 0f), }; PhysicsBody object1 = world.CreateBody(bodyDefinition1); // Create a large circle below the fixed body. PhysicsBodyDefinition bodyDefinition2 = new PhysicsBodyDefinition { type = PhysicsBody.BodyType.Dynamic, position = new Vector2(5f, 0f), }; PhysicsBody object2 = world.CreateBody(bodyDefinition2); object2.CreateShape(new CircleGeometry { radius = 3f }); // Add the bodies to the joint definition. jointDefinition.bodyA = object1; jointDefinition.bodyB = object2; // Add the joint to the world. world.CreateJoint(jointDefinition); }}
Constructors
Constructor | Description |
|---|---|
| PhysicsJoint(Unity.U2D.Physics.PhysicsHandle) | Create a joint from a physics handle. |
Properties
Property | Description |
|---|---|
| bodyA | The first body the joint constrains. |
| bodyB | The second body the joint constrains. |
| callbackTarget | Get/Set the Object object that event callbacks for this joint will be sent to. Care should be taken with any Object assigned as a callback target that isn't a Object as this assignment will not in itself keep the object alive and can be garbage collected. To avoid this, you should have at least a single reference to the object in your code. To remove the object assigned here, set the callback target to NULL. |
| collideConnected | Whether the shapes on the pair of bodies can come into contact. |
| currentAngularSeparationError | Get the current angular separation error for this joint, in degrees. This does not consider admissible movement. |
| currentConstraintForce | Get the current constraint force used by the joint, usually in newtons. |
| currentConstraintTorque | Get the current constraint torque used by the joint, usually in newton-meters. |
| currentLinearSeparationError | Get the current linear separation error for this joint, usually in meters. This does not consider admissible movement. |
| drawScale | Controls the scaling of the joint drawing. Not all joints have scalable elements but those that do will use this scaling. |
| drawTarget | Controls which Unity editor views this joint is drawn into. |
| forceThreshold | The force threshold beyond which a joint event will be produced. |
| isOwned | Get if the joint is owned. See PhysicsJoint.SetOwner. |
| isValid | Checks if the joint is valid. |
| jointType | Gets the joint type. See PhysicsJoint.JointType. |
| localAnchorA | The local anchor frame constraint relative to bodyA's origin. |
| localAnchorB | The local anchor frame constraint relative to bodyB's origin. |
| owner | The owner object associated with this joint, or NULL if no owner has been specified. This is a convenience property that returns the same value as PhysicsJoint.GetOwner. |
| ownerUserData | Get PhysicsUserData that can be used for any purpose, typically by the owner only. |
| physicsHandle | Get the physics handle. |
| selectedDrawing | Controls whether this joint is drawn individually when the world is drawn. |
| torqueThreshold | The torque threshold beyond which a joint event will be produced. |
| tuningDamping | Controls the joint stiffness damping, non-dimensional. Use 1 for critical damping. |
| tuningFrequency | Controls the joint stiffness frequency, in cycles per second. |
| userData | Get/Set PhysicsUserData that can be used for any purpose. The physics system doesn't use this data, it is entirely for custom use. |
| world | Get the world the body is attached to. |
| worldDrawing | Controls whether this joint is automatically drawn when the world is drawn. |
Methods
Method | Description |
|---|---|
| Destroy | Destroy the joint. If the object is owned with PhysicsJoint.SetOwner then you must provide the owner key it returned. Failing to do so will return a warning and the joint will not be destroyed. |
| Draw | Draw this joint's current state once, as custom drawing. |
| GetOwner | Get the owner object associated with this joint as specified using PhysicsJoint.SetOwner. |
| SetOwner | Set the owner object using the specified owner key. You can only set the owner once, multiple attempts will produce a warning. This call does not bind the lifetime of the specified owner object, it is simply a reference. It is also valid to not specify an owner object (NULL) to simply gain an owner key however it can be useful, if simply for debugging purposes and discovery, to know which object is the owner. |
| SetOwnerUserData | Set PhysicsUserData that can be used for any purpose, typically by the owner only. |
| WakeBodies | Wake the pair of bodies the joint is constraining. |
Static Methods
Method | Description |
|---|---|
| CreateJoint | Create a PhysicsDistanceJoint in the world. See PhysicsDistanceJoint.Create. |
| DestroyBatch | Destroy a batch of joints. Owned joints will produce a warning and will not be destroyed (see PhysicsJoint.SetOwner). Any invalid joints will be ignored. |
| SetOwner | Set the owner object using the specified owner key. You can only set the owner once, multiple attempts will produce a warning. This call does not bind the lifetime of the specified owner object, it is simply a reference. Whilst it is valid to not specify an owner object (NULL), it is recommended for debugging purposes. |
| SetOwnerUserData | Set PhysicsUserData on a batch of joints that can be used for any purpose, typically by the owner only. The joints and userDatas spans must be the same length; joints[n] receives userDatas[n]. |
| SetSelectedDrawing | Set the selected drawing state on a batch of joints. |
| SetUserData | Set PhysicsUserData on a batch of joints that can be used for any purpose. The joints and userDatas spans must be the same length; joints[n] receives userDatas[n]. |
Enums
Enum | Description |
|---|---|
| PhysicsJoint.JointType | The type of joint. |