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.


local function getSpringForce(spring)
if not spring:IsA("SpringConstraint") then
warn(spring .. " is not a spring constraint!")
return
end
local currentLength = spring.CurrentLength
local freeLength = spring.FreeLength
if (spring.LimitsEnabled) then
currentLength = math.clamp(currentLength, spring.MinLength, spring.MaxLength)
freeLength = math.clamp(freeLength, spring.MinLength, spring.MaxLength)
end
local springLength = currentLength - freeLength
local axis = spring.Attachment0.WorldPosition - spring.Attachment1.WorldPosition
if axis.Magnitude > 0 then
axis = axis.Unit
end
local effectiveVelocity = spring.Attachment0.Parent.Velocity - spring.Attachment1.Parent.Velocity
-- https://en.wikipedia.org/wiki/Harmonic_oscillator
-- f = -k * x - c * dx/dt + fext
-- Gravity may not be all of the external forces; friction may affect this, but it's harder to account for
local forceExternal = Vector3.new(0, -workspace.Gravity, 0)
local force = -spring.Stiffness * springLength - spring.Damping * axis:Dot(effectiveVelocity) + axis:Dot(forceExternal)
force = math.clamp(force, -spring.MaxForce, spring.MaxForce)
return force
end

Code Samples

Calculating SpringConstraint Force

local function getSpringForce(spring)
if not spring:IsA("SpringConstraint") then
warn(spring .. " is not a spring constraint!")
return
end
local currentLength = spring.CurrentLength
local freeLength = spring.FreeLength
if spring.LimitsEnabled then
currentLength = math.clamp(currentLength, spring.MinLength, spring.MaxLength)
freeLength = math.clamp(freeLength, spring.MinLength, spring.MaxLength)
end
local springLength = currentLength - freeLength
local axis = spring.Attachment0.WorldPosition - spring.Attachment1.WorldPosition
if axis.Magnitude > 0 then
axis = axis.Unit
end
local effectiveVelocity = spring.Attachment0.Parent.Velocity - spring.Attachment1.Parent.Velocity
-- https://en.wikipedia.org/wiki/Harmonic_oscillator
-- f = k * x - c * dx/dt + fext
-- Gravity may not be all of the external forces; friction may affect this, but it's harder to account for
local forceExternal = Vector3.new(0, -workspace.Gravity, 0)
local force = spring.Stiffness * springLength
- spring.Damping * axis:Dot(effectiveVelocity)
+ axis:Dot(forceExternal)
force = math.clamp(force, -spring.MaxForce, spring.MaxForce)
return force
end
local spring = script.Parent
print(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.

Methods

Events

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.

Methods

Events