SpringConstraint

Show Deprecated

A SpringConstraint applies a force to its Attachments based on spring and damper behavior. Assuming the constraint has SpringConstraint.Stiffness, it will apply forces based on how far apart the attachments are. If the attachments are further apart than the constraint's SpringConstraint.FreeLength, the attachments will be forced together. If they are closer than the SpringConstraint.FreeLength, the attachments will be forced apart. In addition, if SpringConstraint.Damping is set, there will be a damping component to the applied force that scales with the velocity of the attachments.

This constraint, along with a CylindricalConstraint, is ideal for building vehicle suspension.

Note that if this constraint attaches one part (A) to another part (B) that is anchored or connected to an anchored part (Z), part A will not be locally simulated when interacting with a player.

Calculating SpringConstraint Force

The following helper function exhibits how the force of a SpringConstraint is calculated based on various properties of the constraint and its attachments.


1local function getSpringForce(spring)
2 if not spring:IsA("SpringConstraint") then
3 warn(spring .. " is not a spring constraint!")
4 return
5 end
6
7 local currentLength = spring.CurrentLength
8 local freeLength = spring.FreeLength
9 if (spring.LimitsEnabled) then
10 currentLength = math.clamp(currentLength, spring.MinLength, spring.MaxLength)
11 freeLength = math.clamp(freeLength, spring.MinLength, spring.MaxLength)
12 end
13 local springLength = currentLength - freeLength
14
15 local axis = spring.Attachment0.WorldPosition - spring.Attachment1.WorldPosition
16 if axis.Magnitude > 0 then
17 axis = axis.Unit
18 end
19 local effectiveVelocity = spring.Attachment0.Parent.Velocity - spring.Attachment1.Parent.Velocity
20
21 -- https://en.wikipedia.org/wiki/Harmonic_oscillator
22 -- f = -k * x - c * dx/dt + fext
23 -- Gravity may not be all of the external forces; friction may affect this, but it's harder to account for
24 local forceExternal = Vector3.new(0, -workspace.Gravity, 0)
25 local force = -spring.Stiffness * springLength - spring.Damping * axis:Dot(effectiveVelocity) + axis:Dot(forceExternal)
26
27 force = math.clamp(force, -spring.MaxForce, spring.MaxForce)
28 return force
29end
30

Code Samples

Calculating SpringConstraint Force

1local function getSpringForce(spring)
2 if not spring:IsA("SpringConstraint") then
3 warn(spring .. " is not a spring constraint!")
4 return
5 end
6
7 local currentLength = spring.CurrentLength
8 local freeLength = spring.FreeLength
9 if spring.LimitsEnabled then
10 currentLength = math.clamp(currentLength, spring.MinLength, spring.MaxLength)
11 freeLength = math.clamp(freeLength, spring.MinLength, spring.MaxLength)
12 end
13 local springLength = currentLength - freeLength
14
15 local axis = spring.Attachment0.WorldPosition - spring.Attachment1.WorldPosition
16 if axis.Magnitude > 0 then
17 axis = axis.Unit
18 end
19 local effectiveVelocity = spring.Attachment0.Parent.Velocity - spring.Attachment1.Parent.Velocity
20
21 -- https://en.wikipedia.org/wiki/Harmonic_oscillator
22 -- f = k * x - c * dx/dt + fext
23 -- Gravity may not be all of the external forces; friction may affect this, but it's harder to account for
24 local forceExternal = Vector3.new(0, -workspace.Gravity, 0)
25 local force = spring.Stiffness * springLength
26 - spring.Damping * axis:Dot(effectiveVelocity)
27 + axis:Dot(forceExternal)
28
29 force = math.clamp(force, -spring.MaxForce, spring.MaxForce)
30 return force
31end
32
33local spring = script.Parent
34print(getSpringForce(spring))

Summary

Properties

The number of coils visualized on the SpringConstraint. This can only be set between 0 and 8.

The current distance between the SpringConstant’s Attachment.

READ ONLY
NOT REPLICATED

Damping constant for the SpringConstraint. Multiplied to the velocity of the constraint’s Attachment to reduce the spring force applied.

Natural resting length of the spring.

Sets whether the SpringConstraint enforces a minimum and maximum length.

The maximum force the SpringConstraint can apply on its Attachment.

The maximum separation the SpringConstraint will allow if SpringConstraint.LimitsEnabled is true.

The minimum separation the SpringConstraint will allow if SpringConstraint.LimitsEnabled is true.

The visualized radius of the spring's coils.

The strength of the spring. The higher this value the more force will be applied when the attachments are separated a different length than the SpringConstraint.FreeLength.

The visualized thickness of the spring's coils.

Events

Methods

Properties

Coils

The number of coils visualized on the SpringConstraint. This can only be set between 0 and 8.

CurrentLength

Read Only
Not Replicated

The current distance between the SpringConstraint's Attachment.

Damping

Damping constant for the SpringConstraint. Multiplied to the velocity of the constraint's Attachment to reduce the spring force applied.

FreeLength

Natural resting length of the spring.

LimitsEnabled

Sets whether the SpringConstraint enforces a minimum and maximum length. If the SpringConstraint's Attachment reach these limits, they will simply stop moving apart from one another without restitution. If you need restitution or elasticity at the ends of the range of motion, you can combine a SpringConstraint with another constraint that allows restitution at the end of its range, such as a PrismaticConstraint or RopeConstraint.

MaxForce

The maximum force the SpringConstraint can apply on its Attachment. Some spring systems can give rise to forces that grow fast leading to instability. In such cases it is recommended to set MaxForce to a reasonable value.

MaxLength

The maximum separation the SpringConstraint will allow if SpringConstraint.LimitsEnabled is true.

MinLength

The minimum separation the SpringConstraint will allow if SpringConstraint.LimitsEnabled is true.

Radius

The visualized radius of the spring's coils.

Stiffness

The strength of the spring. The higher this value the more force will be applied when the attachments are separated a different length than the SpringConstraint.FreeLength.

Thickness

The visualized thickness of the spring's coils.

Events

Methods