Configurable joints in-depth documentation / tutorial / for dummies

[Miffeltoffel]

So, I’ve been wanting to use the configurable joints for a vehicle suspension model, but the documentation didn’t really answer the questions I had.

While https://www.3dbuzz.com/training/view/unity-fundamentals/physics/13-configurable-joint
answered some and was a great platform to start from, it still required a bit of fiddling before I was able to use them with satisfactory results, plotting down what I learned as I went.

So, having had great use of this forum and all the answers here I thought I’d give back and share what I’ve found. If someone spots any error in my logic or has anything to add, please feel free to tell me, I definitely do not consider myself above error. So, here’s what I found:

Naming convention:
Spring – The actual spring script
Spring object – The object that contains the spring script
Attached object – The other object that the spring is connected to

AFAIK the springs are modelled using Hookes law, F = -kx -dv, where F is the resulting force, k is the spring stiffness, x is displacement, d is dampening coefficient and v is the velocity. Both displacement and velocity is that of the spring object relative the attached object.

Axis/Secondary axis – Defines the primary/secondary axis of the spring coordinate system. If we set this to [0,1,0] for example, the spring main axis is in the spring objects Y-direction. This affects most settings. For example, the X motion setting then applies to the spring objects Y-direction.

Configured in world space – Everything should be defined in world space instead.

Swap bodies – This makes the joint behave as if the script was added to the attached object rather than the spring object.

Break Force/Torque – If the Force/Torque specified here is exceeded, the configurable joint is removed from the object.

Enable collision – Should the bodies in each end of the spring be able to collide?

Enable preprocessing – This reduces the accuracy of the joint simulation but is very useful when some degrees of freedom are removed (some motions are set to ‘Locked’), because PhysX can then ignore some calculations.

Anchor – This defines where the spring is attached. Defined in the spring object coordinate system.

Connected anchor – Where on the connected body the spring is connected. This is defined in the attached objects coordinate system, as opposed to the anchor.

X/Y/Z Motion - Defines how the spring should behave linearly in the spring coordinate system.
Free – Can move every which way
Limited – Obeys the restrictions under ”Linear limit”
Locked – Cannot move in the specified direction

Angular X/Y/Z motion – Defines how the spring can rotate around the specified spring axes.
Free – Can rotate every which way
Limited – Obeys the restrictions under ”Angular limit” - note that this is divide into X and YZ. X is the primary axis, hence it will have more options.
Locked – Cannot rotate about the specified axis.

Linear Limit Spring – Define the spring end points behaviour.
Defines end-position behaviour. If Spring/Damper = 0 the spring is forcably stopped in the end position (sort of when you hit the bottom of the dampers on your car when hitting a speed bump at high velocities, there is a hard shock).
Spring (-kx): Equivalent to spring stiffness that decides how much it should oscillate around the end point
Damper (-dv): Equivalent to damping coefficient that decides how much oscillation around end point is damped.

Linear Limit – Define the spring end points.
Limit: Defines how many Units the spring can be stretched/compressed.
Bounciness: Equivalent to energy conservation at the end points.
0 = all energy dissipated when end position is reached (like a lead ball dropped),
1 = all energy conserved when end position is reached (like a bouncing ball)
Contact distance: How far away from the current position the joint looks to see if we are close to the limit. If this is =0 there is no prediction which is faster but may become jittery since we have no prediction.

Angular X limit spring – Defines how the spring should behave around the end-position of the allowed rotation.
Spring (-kx): Equivalent to spring stiffness that decides how much it should oscillate around the end point
Damper (-dv): Equivalent to damping coefficient that decides how much oscillation around end point is damped.

Low/High angular X & Y/Z limit – Defines the lower/upper boundary of the rotation. Note that X is independent and YZ have to be specified together.
Limit: Defines how many degrees (NOT RADIANS) the spring can be stretched/compressed radially.
Bounciness: Equivalent to energy conservation at the end points. 0 = all energy dissipated when end position is reached (like hitting a brick wall), 1 = all energy conserved when end position is reached (like hitting a rubber surface)
Contact distance: How far away from the current position the joint looks to see if we are close to the limit. If this is =0 there is no prediction which is faster but may become jittery since we have no prediction.

Target position – Set the position in spring space where the end point of the joint should aim to be (the rest position of the spring). Creates a distance in the direction of the primary axis from the anchor to the connected anchor. Example: Setting this to [1,0,0] will move the spring object to [-1,0,0] relative the connected anchor (in the spring coordinate system).

Target velocity – Set the contant velocity the spring should try to achieve in spring space.

X/Y/Z Drive – Defines what method we use to control the spring. All defined in spring space.
Position: Uses Position Spring (Spring stiffness) – equivalent to the kx-term
Velocity: Uses Position Damper (Damping coefficient) – equivalent to dv-term
Position and velocity: Uses both terms, complete Hooke’s law.

X/Y/Z Drive - Defines behaviour around the mid-position of the spring.

Projection mode – This is a ”Last resort” kind of solution if the spring violates the limits too badly. This has nothing to do with physics and is used only to make sure that things do not explode and go haywire.
Position and Rotation: If the joint goes above/below the allowed limits it will automatically snap back to the limit.
Projection distance: How much above/below the linear limit does it have to be before we snap back?
Projection Angle: How many degrees above/below the angular limit does it have to be before we snap back?

Hope this helps someone with this very powerful (but slightly underdocumented) feature!

[emugod]

I’m not positive but it seems like the Axis settings are used to define different axes, relative to the default of the objects local axes. If you leave them (0,0,0) you will have everything working in the objects local space.

[emugod]

Just discovered; The object is not treated as a static collider once at its limit. If you’re pushing against it with a kinematic rigidbody, it will ignore the limit and keep moving, rather than having your kinematic pass into and through it.

[domilab]

Thank you so much for this post. I’ve also noticed that the documentation is poor at best and the video was helpful but not enough. Maybe you could provide some insight where I’m still confused.

Is it possible to use this joint to pull things together? I’m guessing this would involve the linear limit/spring and bounciness. Say I had an anchor point 100 units away. I want the object to be pulled to within 4 units and stop. Is this possible with this joint? I tried something similar with the spring joint but my results are never what I expect.

Edit: Could the drive be used to maintain the speed on how fast it’s pulled back? If I wanted a constantly velocity, is that possible?

[Static-Dynamo]

The documentation on the configurable joint is really bad and is making things much more difficult than they have to be. I’ve been trying to figure out how to set projection mode via script and have had no luck. Anyone know how to do this? The documentation doesn’t give any explanation on if it’s even possible. I’ve had success setting everything else I need for my behavior via script, except for this one part.

[electric_jesus]

It seems like Target Angular Velocity and Target Rotation of a ConfigurableJoint are measured in the opposite directions. At the same time Target Velocity and Target Position are both measured in the same direction. It just blows my mind.
Tested with Unity 5.3.8 and Unity 5.4.3.

[anthonov]

@electric_jesus

It seems like Target Angular Velocity and Target Rotation of a ConfigurableJoint are measured in the opposite directions. At the same time Target Velocity and Target Position are both measured in the same direction. It just blows my mind.
Tested with Unity 5.3.8 and Unity 5.4.3.

Yes, same for me, i can’t understand why its not a priority in unity team to improve and (better)explain these basic tools.

[thieum]

Working with joints has always been a mess because of poor documentation, for years now.
My guess is Unity devs can’t really make things better since all this belongs to Nvidia PhysX engine.
In addition to @Miffeltoffel excellent guidelines, there are extra infos and explanations on Nvidia website :
http://docs.nvidia.com/gameworks/content/gameworkslibrary/physx/guide/Manual/Joints.html

[adhochero]

@Miffeltoffel

So, I’ve been wanting to use the configurable joints for a vehicle suspension model, but the documentation didn’t really answer the questions I had.

While https://www.3dbuzz.com/training/view/unity-fundamentals/physics/13-configurable-joint
answered some and was a great platform to start from, it still required a bit of fiddling before I was able to use them with satisfactory results, plotting down what I learned as I went.

So, having had great use of this forum and all the answers here I thought I’d give back and share what I’ve found. If someone spots any error in my logic or has anything to add, please feel free to tell me, I definitely do not consider myself above error. So, here’s what I found:

Naming convention:
Spring – The actual spring script
Spring object – The object that contains the spring script
Attached object – The other object that the spring is connected to

AFAIK the springs are modelled using Hookes law, F = -kx -dv, where F is the resulting force, k is the spring stiffness, x is displacement, d is dampening coefficient and v is the velocity. Both displacement and velocity is that of the spring object relative the attached object.

Axis/Secondary axis – Defines the primary/secondary axis of the spring coordinate system. If we set this to [0,1,0] for example, the spring main axis is in the spring objects Y-direction. This affects most settings. For example, the X motion setting then applies to the spring objects Y-direction.

Configured in world space – Everything should be defined in world space instead.

Swap bodies – This makes the joint behave as if the script was added to the attached object rather than the spring object.

Break Force/Torque – If the Force/Torque specified here is exceeded, the configurable joint is removed from the object.

Enable collision – Should the bodies in each end of the spring be able to collide?

Enable preprocessing – This reduces the accuracy of the joint simulation but is very useful when some degrees of freedom are removed (some motions are set to ‘Locked’), because PhysX can then ignore some calculations.

Anchor – This defines where the spring is attached. Defined in the spring object coordinate system.

Connected anchor – Where on the connected body the spring is connected. This is defined in the attached objects coordinate system, as opposed to the anchor.

X/Y/Z Motion - Defines how the spring should behave linearly in the spring coordinate system.
Free – Can move every which way
Limited – Obeys the restrictions under ”Linear limit”
Locked – Cannot move in the specified direction

Angular X/Y/Z motion – Defines how the spring can rotate around the specified spring axes.
Free – Can rotate every which way
Limited – Obeys the restrictions under ”Angular limit” - note that this is divide into X and YZ. X is the primary axis, hence it will have more options.
Locked – Cannot rotate about the specified axis.

Linear Limit Spring – Define the spring end points behaviour.
Defines end-position behaviour. If Spring/Damper = 0 the spring is forcably stopped in the end position (sort of when you hit the bottom of the dampers on your car when hitting a speed bump at high velocities, there is a hard shock).
Spring (-kx): Equivalent to spring stiffness that decides how much it should oscillate around the end point
Damper (-dv): Equivalent to damping coefficient that decides how much oscillation around end point is damped.

Linear Limit – Define the spring end points.
Limit: Defines how many Units the spring can be stretched/compressed.
Bounciness: Equivalent to energy conservation at the end points.
0 = all energy dissipated when end position is reached (like a lead ball dropped),
1 = all energy conserved when end position is reached (like a bouncing ball)
Contact distance: How far away from the current position the joint looks to see if we are close to the limit. If this is =0 there is no prediction which is faster but may become jittery since we have no prediction.

Angular X limit spring – Defines how the spring should behave around the end-position of the allowed rotation.
Spring (-kx): Equivalent to spring stiffness that decides how much it should oscillate around the end point
Damper (-dv): Equivalent to damping coefficient that decides how much oscillation around end point is damped.

Low/High angular X & Y/Z limit – Defines the lower/upper boundary of the rotation. Note that X is independent and YZ have to be specified together.
Limit: Defines how many degrees (NOT RADIANS) the spring can be stretched/compressed radially.
Bounciness: Equivalent to energy conservation at the end points. 0 = all energy dissipated when end position is reached (like hitting a brick wall), 1 = all energy conserved when end position is reached (like hitting a rubber surface)
Contact distance: How far away from the current position the joint looks to see if we are close to the limit. If this is =0 there is no prediction which is faster but may become jittery since we have no prediction.

Target position – Set the position in spring space where the end point of the joint should aim to be (the rest position of the spring). Creates a distance in the direction of the primary axis from the anchor to the connected anchor. Example: Setting this to [1,0,0] will move the spring object to [-1,0,0] relative the connected anchor (in the spring coordinate system).

Target velocity – Set the contant velocity the spring should try to achieve in spring space.

X/Y/Z Drive – Defines what method we use to control the spring. All defined in spring space.
Position: Uses Position Spring (Spring stiffness) – equivalent to the kx-term
Velocity: Uses Position Damper (Damping coefficient) – equivalent to dv-term
Position and velocity: Uses both terms, complete Hooke’s law.

X/Y/Z Drive - Defines behaviour around the mid-position of the spring.

Projection mode – This is a ”Last resort” kind of solution if the spring violates the limits too badly. This has nothing to do with physics and is used only to make sure that things do not explode and go haywire.
Position and Rotation: If the joint goes above/below the allowed limits it will automatically snap back to the limit.
Projection distance: How much above/below the linear limit does it have to be before we snap back?
Projection Angle: How many degrees above/below the angular limit does it have to be before we snap back?

Hope this helps someone with this very powerful (but slightly underdocumented) feature!

I have a question about the option “Mode” for the x,y,z Drives, mine dosent have Mode

[Sword111_1]

Hi maybe someone can help me, with a configerable joint problem that ivhttps://youtu.be/PJ50zboeds8e been battling with for weeks?Works ok with a hinge joint but i need the full range or colliding movement ! Would anyone know how to get the point to sping back into line? Tried evey sort of tweek … something simple im missing but dont know what ! Thanks Hugo

- YouTube

- YouTube

- YouTube

[T0rp3d0]

@Miffeltoffel

So, I’ve been wanting to use the configurable joints for a vehicle suspension model, but the documentation didn’t really answer the questions I had.

While https://www.3dbuzz.com/training/view/unity-fundamentals/physics/13-configurable-joint
answered some and was a great platform to start from, it still required a bit of fiddling before I was able to use them with satisfactory results, plotting down what I learned as I went.

So, having had great use of this forum and all the answers here I thought I’d give back and share what I’ve found. If someone spots any error in my logic or has anything to add, please feel free to tell me, I definitely do not consider myself above error. So, here’s what I found:

Naming convention:
Spring – The actual spring script
Spring object – The object that contains the spring script
Attached object – The other object that the spring is connected to

AFAIK the springs are modelled using Hookes law, F = -kx -dv, where F is the resulting force, k is the spring stiffness, x is displacement, d is dampening coefficient and v is the velocity. Both displacement and velocity is that of the spring object relative the attached object.

Axis/Secondary axis – Defines the primary/secondary axis of the spring coordinate system. If we set this to [0,1,0] for example, the spring main axis is in the spring objects Y-direction. This affects most settings. For example, the X motion setting then applies to the spring objects Y-direction.

Configured in world space – Everything should be defined in world space instead.

Swap bodies – This makes the joint behave as if the script was added to the attached object rather than the spring object.

Break Force/Torque – If the Force/Torque specified here is exceeded, the configurable joint is removed from the object.

Enable collision – Should the bodies in each end of the spring be able to collide?

Enable preprocessing – This reduces the accuracy of the joint simulation but is very useful when some degrees of freedom are removed (some motions are set to ‘Locked’), because PhysX can then ignore some calculations.

Anchor – This defines where the spring is attached. Defined in the spring object coordinate system.

Connected anchor – Where on the connected body the spring is connected. This is defined in the attached objects coordinate system, as opposed to the anchor.

X/Y/Z Motion - Defines how the spring should behave linearly in the spring coordinate system.
Free – Can move every which way
Limited – Obeys the restrictions under ”Linear limit”
Locked – Cannot move in the specified direction

Angular X/Y/Z motion – Defines how the spring can rotate around the specified spring axes.
Free – Can rotate every which way
Limited – Obeys the restrictions under ”Angular limit” - note that this is divide into X and YZ. X is the primary axis, hence it will have more options.
Locked – Cannot rotate about the specified axis.

Linear Limit Spring – Define the spring end points behaviour.
Defines end-position behaviour. If Spring/Damper = 0 the spring is forcably stopped in the end position (sort of when you hit the bottom of the dampers on your car when hitting a speed bump at high velocities, there is a hard shock).
Spring (-kx): Equivalent to spring stiffness that decides how much it should oscillate around the end point
Damper (-dv): Equivalent to damping coefficient that decides how much oscillation around end point is damped.

Linear Limit – Define the spring end points.
Limit: Defines how many Units the spring can be stretched/compressed.
Bounciness: Equivalent to energy conservation at the end points.
0 = all energy dissipated when end position is reached (like a lead ball dropped),
1 = all energy conserved when end position is reached (like a bouncing ball)
Contact distance: How far away from the current position the joint looks to see if we are close to the limit. If this is =0 there is no prediction which is faster but may become jittery since we have no prediction.

Angular X limit spring – Defines how the spring should behave around the end-position of the allowed rotation.
Spring (-kx): Equivalent to spring stiffness that decides how much it should oscillate around the end point
Damper (-dv): Equivalent to damping coefficient that decides how much oscillation around end point is damped.

Low/High angular X & Y/Z limit – Defines the lower/upper boundary of the rotation. Note that X is independent and YZ have to be specified together.
Limit: Defines how many degrees (NOT RADIANS) the spring can be stretched/compressed radially.
Bounciness: Equivalent to energy conservation at the end points. 0 = all energy dissipated when end position is reached (like hitting a brick wall), 1 = all energy conserved when end position is reached (like hitting a rubber surface)
Contact distance: How far away from the current position the joint looks to see if we are close to the limit. If this is =0 there is no prediction which is faster but may become jittery since we have no prediction.

Target position – Set the position in spring space where the end point of the joint should aim to be (the rest position of the spring). Creates a distance in the direction of the primary axis from the anchor to the connected anchor. Example: Setting this to [1,0,0] will move the spring object to [-1,0,0] relative the connected anchor (in the spring coordinate system).

Target velocity – Set the contant velocity the spring should try to achieve in spring space.

X/Y/Z Drive – Defines what method we use to control the spring. All defined in spring space.
Position: Uses Position Spring (Spring stiffness) – equivalent to the kx-term
Velocity: Uses Position Damper (Damping coefficient) – equivalent to dv-term
Position and velocity: Uses both terms, complete Hooke’s law.

X/Y/Z Drive - Defines behaviour around the mid-position of the spring.

Projection mode – This is a ”Last resort” kind of solution if the spring violates the limits too badly. This has nothing to do with physics and is used only to make sure that things do not explode and go haywire.
Position and Rotation: If the joint goes above/below the allowed limits it will automatically snap back to the limit.
Projection distance: How much above/below the linear limit does it have to be before we snap back?
Projection Angle: How many degrees above/below the angular limit does it have to be before we snap back?

Hope this helps someone with this very powerful (but slightly underdocumented) feature!

So may i assume the ‘spring’ will exist between the ‘Anchor’ and ‘Connected Anchor’? Such that all physical movement of the spring depends on your careful placement of ‘Anchor’ and ‘Connected anchor’?

[Wattosan]

It would be nice to have linear min and max limits as well for each axis.
Also to have min and max angular limits for other axis as well other than the X axis.

[vladimir_tikhonov]

Check out this gide I’ve just published, it covers most of ConfigurableJoint’s functionality - Luna Tech Series: A Deep Dive into Unity Configurable Joints | Luna Labs

[thieum]

@vladimir_tikhonov

Check out this gide I’ve just published, it covers most of ConfigurableJoint’s functionality - https://medium.com/luna-labs-ltd/luna-tech-series-a-deep-dive-into-unity-configurable-joints-96c49138b9b7

Really good explanation! Thumb up for your effort!
Just one extra advise : when a joint is set, rotating the joint transform won’t result in rotating the whole piece, but only the rigidbody. It can be confusing.

[czbo]

I am trying to understand the joints and how the physics work in Unity, and I found something strange happens when spring damping is too high. The amount of downward distance due to gravity is affected by mass of rigidbody and spring constant, but somehow if damping is too high, the rigidbody’s final position seems to be higher than you would expect. See the video of a comparison I made:

Unity 3D physics damping compare

you can see when spring constant is 100 and damping is 100, the final position of the 4th cube in the chain is abnormally high and similar to the 3rd cube. In real life you would expect the distance between each cube to be about the same, as shown in the case when damping is 10 instead.

I am guessing this has something to do with the calculation of force in the damping term -dv where if d is too large, then you end up overcompensating for the downward force of gravity and the velocity gets to zero before it settles to the correct final position?

[kloogens]

I have a conference call with Unity in the next two days. I am going to complain about this until someone promises something will be done about it. This is unacceptable.

[GF-Huang]

Any progress?

An error occurred: Body is too short (minimum is 20 characters)