Manual
Manual
Joints
A joint holds two bodies together, or one body to the world: a door on its hinges, a drawer on its runners, a lamp on its chain, a limb on a ragdoll. This page covers the seven 3D joints, their anchors and motors, editing them in the Scene view, and joints that break.
What a joint holds
A joint is a component on an entity. It holds two bodies:
- its own body: the nearest Rigidbody 3D at or above its entity;
- the Connected Body: the body of the entity you drag from the Hierarchy into its Connected Body slot, an entity with a Rigidbody 3D or one under it. Left empty, the joint holds its body to the world.
Added in the editor, a joint brings a Rigidbody 3D to its entity when neither it nor anything above it has one. A joint never holds a character, and does nothing when both its bodies are the same.
A joint is made when the game starts playing, with the bodies where they are then. Its angles and distances count from there: a hinge starts at 0 degrees, a slider at 0 meters.
Fields every joint has
| Field | What it does |
|---|---|
| Connected Body | The other body it holds. None holds this one to the world. |
| Enable Collision | Whether the two bodies still collide with each other. Off at first. |
| Auto Configure Connected Anchor | Makes the connected anchor where the anchor is, as the joint is made, and writes it into Connected Anchor. |
| Anchor | Where it holds its own body, in its entity's own units. |
| Connected Anchor | Where it holds the other body, in that entity's own units, or in the world's when there is none. |
| Break Force | The force it breaks at, in newtons. Infinity, the default, never breaks. |
| Break Torque | The torque it breaks at, in newton meters. Infinity never breaks. |
Auto Configure Connected Anchor is on at first for every joint but the Distance Joint 3D and the Spring Joint 3D, so the two bodies are held where they are. With it off, you place Connected Anchor yourself.
Two bodies a joint holds pass through each other unless Enable Collision is on. Pairs your code asked not to meet with IgnoreCollision stay that way whatever the joint says.
Fixed Joint 3D
Holds the two bodies as they were, as if welded. It has only the fields every joint has. Use it to fix a part that can break off, such as a plank of a crate.
Ball Joint 3D
Holds the two bodies at one point, turning about it every way: a ball in its socket, a lamp on its chain. It has only the fields every joint has. A Ragdoll Joint 3D is a ball joint with limits.
Hinge Joint 3D
Holds the two bodies turning about one line: a door on its hinges, a wheel on its axle. The line goes through Anchor, along Axis, and turns with the entity.
| Field | What it does |
|---|---|
| Axis | What it turns about, in its entity's own units. Up (0, 1, 0) at first, for a door. |
| Motor | Off, Speed or Target; see Motors. |
| Motor Speed | How fast the motor turns it, in degrees a second, counter-clockwise looking down the axis. |
| Target Angle | The angle the motor turns it to and holds, in degrees from where it was made, within its limits. |
| Motor Frequency | How stiffly the motor holds it at its target, in bounces a second. 2 at first. |
| Motor Damping Ratio | How the motor's bounce at its target dies away: 0 never, 1 at once. 1 at first. |
| Max Motor Torque | The most torque the motor turns it with, in newton meters. 10,000 at first. |
| Use Limits | Whether it stops turning past Lower Angle and Upper Angle. |
| Lower Angle | The least it turns, in degrees from where it was made: from −180 to 0. |
| Upper Angle | The most it turns, in degrees from where it was made: from 0 to 180. 90 at first. |
Its angle is how far its own body has turned about the axis from the connected one, counter-clockwise looking down the axis, from where they were as it was made.
Slider Joint 3D
Holds the two bodies sliding along one line, kept at the turn they were made at: a drawer, a lift, a piston. The line goes through Anchor, along Axis.
| Field | What it does |
|---|---|
| Axis | Which way it slides, in its entity's own units. Along X at first. |
| Motor | Off, Speed or Target; see Motors. |
| Motor Speed | How fast the motor drives it along its axis, in meters a second. |
| Target Position | Where the motor drives it to and holds it, in meters from where it was made. |
| Motor Frequency | How stiffly the motor holds it at its target, in bounces a second. 2 at first. |
| Motor Damping Ratio | How the motor's bounce at its target dies away: 0 never, 1 at once. 1 at first. |
| Max Motor Force | The most force the motor drives it with, in newtons. 10,000 at first. |
| Use Limits | Whether it stops sliding past Lower Translation and Upper Translation. |
| Lower Translation | The least it slides, in meters from where it was made: 0 or less. |
| Upper Translation | The most it slides, in meters from where it was made: 0 or more. 1 at first. |
Distance Joint 3D
Keeps the two anchors a distance apart: a rod between them, or, with Max Distance Only, a rope that goes slack.
| Field | What it does |
|---|---|
| Auto Configure Distance | Makes the distance how far apart the anchors are as the joint is made, and writes it into Distance. On at first. |
| Distance | How far apart the anchors are kept, in meters. |
| Max Distance Only | Lets the bodies come nearer, as on a rope, and keeps them no further than Distance. |
Spring Joint 3D
Pulls the two anchors toward a distance apart, by a spring.
| Field | What it does |
|---|---|
| Auto Configure Distance | Makes the distance how far apart the anchors are as the joint is made. On at first. |
| Distance | How far apart the spring pulls the anchors, in meters. |
| Damping Ratio | How the spring's bounce dies away: 0 never, 1 at once. 0 at first. |
| Frequency | How stiff the spring is, in bounces a second. 1 at first. 0 is as stiff as a rod. |
Ragdoll Joint 3D
Holds a limb to what it hangs from, as a shoulder or a knee: at one point, swinging no further than a cone and twisting about itself within a range. Put it on the limb, with what it hangs from as its Connected Body.
| Field | What it does |
|---|---|
| Axis | Along the limb, in its own units: what it twists about, and the middle of the cone it swings in. Up at first. |
| Swing Axis | Across the limb, in its own units: the way it swings as far as Swing Angle. Along X at first. |
| Swing Angle | How far it swings toward Swing Axis and away, in degrees. 45 at first. |
| Swing Angle Across | How far it swings square to Swing Axis, either way, in degrees. 45 at first. |
| Lower Twist | The least it twists about its axis, in degrees from the twist it was made at. −30 at first. |
| Upper Twist | The most it twists about its axis, in degrees. 30 at first. |
The cone is about Axis as the joint was made, an ellipse that reaches Swing Angle one way and Swing Angle Across the other: an elbow swings far one way and hardly at all the other.
Motors
A hinge and a slider each have a motor, which Motor sets:
- Off: the joint moves only as it is pushed.
- Speed: drives it at Motor Speed, a spinning wheel or a conveyor.
- Target: drives it to Target Angle or Target Position and holds it there, as a spring of Motor Frequency and Motor Damping Ratio would: a door that swings open to 90 degrees, a robot's arm.
Either way, it pushes no harder than Max Motor Torque or Max Motor Force. Change a motor's fields from a system while the game plays, and the joint follows from the next step: set Target Angle to 0 to shut the door again.
Edit Joint
The Edit Joint button in a joint's section gives its anchors handles in the Scene view: one on Anchor, and one on Connected Anchor when Auto Configure Connected Anchor is off. Each is the Move tool's handle, its arrows and squares, with Shift for its middle; it turns as the Scene row's Local or Global says, and snaps as the Move tool does.
The joints of what is picked are drawn in light blue: a ball at each anchor and a line between them, a hinge's axis and, with limits, the arc it may turn through, a slider's line and, with limits, its ends, and a ragdoll joint's cone and twist. They are drawn from where the bodies are now, which is where they are as the game starts and the joint is made.
When a joint breaks
A joint breaks when it holds with more force than its Break Force or more torque than its Break Torque in a step. It is taken off its entity before the next step, and your code is told in Physics3D.JointsBroken:
Physics3D physics = context.Services.Get<Physics3D>();foreach (JointBroken3D broken in physics.JointsBroken){ // broken.Entity held broken.ConnectedBody (0 for the world) until it held broken.Force newtons. Log.Info($"The {broken.Joint} joint on {broken.Entity} broke at {broken.Force:0} N");}A fixed system sees the joints broken in its own step; a system of the frame sees those broken in every step since the frame before (see Which step a system sees).
In the Scripting API
- FixedJoint3D, BallJoint3D, HingeJoint3D, SliderJoint3D, DistanceJoint3D, SpringJoint3D and RagdollJoint3D: the joints.
- JointMotor3D: what a hinge's or a slider's motor does.
- JointBroken3D and Physics3D.JointsBroken: the joints that broke.
