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

FieldWhat it does
Connected BodyThe other body it holds. None holds this one to the world.
Enable CollisionWhether the two bodies still collide with each other. Off at first.
Auto Configure Connected AnchorMakes the connected anchor where the anchor is, as the joint is made, and writes it into Connected Anchor.
AnchorWhere it holds its own body, in its entity's own units.
Connected AnchorWhere it holds the other body, in that entity's own units, or in the world's when there is none.
Break ForceThe force it breaks at, in newtons. Infinity, the default, never breaks.
Break TorqueThe 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.

FieldWhat it does
AxisWhat it turns about, in its entity's own units. Up (0, 1, 0) at first, for a door.
MotorOff, Speed or Target; see Motors.
Motor SpeedHow fast the motor turns it, in degrees a second, counter-clockwise looking down the axis.
Target AngleThe angle the motor turns it to and holds, in degrees from where it was made, within its limits.
Motor FrequencyHow stiffly the motor holds it at its target, in bounces a second. 2 at first.
Motor Damping RatioHow the motor's bounce at its target dies away: 0 never, 1 at once. 1 at first.
Max Motor TorqueThe most torque the motor turns it with, in newton meters. 10,000 at first.
Use LimitsWhether it stops turning past Lower Angle and Upper Angle.
Lower AngleThe least it turns, in degrees from where it was made: from −180 to 0.
Upper AngleThe 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.

FieldWhat it does
AxisWhich way it slides, in its entity's own units. Along X at first.
MotorOff, Speed or Target; see Motors.
Motor SpeedHow fast the motor drives it along its axis, in meters a second.
Target PositionWhere the motor drives it to and holds it, in meters from where it was made.
Motor FrequencyHow stiffly the motor holds it at its target, in bounces a second. 2 at first.
Motor Damping RatioHow the motor's bounce at its target dies away: 0 never, 1 at once. 1 at first.
Max Motor ForceThe most force the motor drives it with, in newtons. 10,000 at first.
Use LimitsWhether it stops sliding past Lower Translation and Upper Translation.
Lower TranslationThe least it slides, in meters from where it was made: 0 or less.
Upper TranslationThe 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.

FieldWhat it does
Auto Configure DistanceMakes the distance how far apart the anchors are as the joint is made, and writes it into Distance. On at first.
DistanceHow far apart the anchors are kept, in meters.
Max Distance OnlyLets 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.

FieldWhat it does
Auto Configure DistanceMakes the distance how far apart the anchors are as the joint is made. On at first.
DistanceHow far apart the spring pulls the anchors, in meters.
Damping RatioHow the spring's bounce dies away: 0 never, 1 at once. 0 at first.
FrequencyHow 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.

FieldWhat it does
AxisAlong the limb, in its own units: what it twists about, and the middle of the cone it swings in. Up at first.
Swing AxisAcross the limb, in its own units: the way it swings as far as Swing Angle. Along X at first.
Swing AngleHow far it swings toward Swing Axis and away, in degrees. 45 at first.
Swing Angle AcrossHow far it swings square to Swing Axis, either way, in degrees. 45 at first.
Lower TwistThe least it twists about its axis, in degrees from the twist it was made at. −30 at first.
Upper TwistThe 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