Spring

Getting it

local Spring = Engine:GetPackage("Spring")

Overview

A spring moves its Position towards its Target like a damped spring would: it accelerates, slows down near the target and, depending on the damper, may overshoot and wobble. Change the target at any time and the spring reacts smoothly from wherever it is, keeping its current velocity. That makes springs ideal for things that follow input, such as cameras, cursors, hover effects or a health bar.

Springs are evaluated analytically from the time since the last change. There is no per-frame update to call; reading Position at any moment gives the exact value.

local Spring = Engine:GetPackage("Spring")

local scale = Spring.new(0, { speed = 18, damper = 0.6 })
local unbind = scale:Bind(panel.UIScale, "Scale")

openButton.Activated:Connect(function()
	scale.Target = 1
end)

closeButton.Activated:Connect(function()
	scale.Target = 0
end)

Speed and damper

Constructors

new

Spring.new(initial: SpringValue, config: { speed: number?, damper: number? }?, clock: (() -> number)?): Spring

A spring at rest at initial. The type of initial (number, Vector2, Vector3 or CFrame) fixes the spring's Kind. Speed and damper default to the configuration values.

Presets

Spring.FromPreset(name: string, initial: SpringValue, clock?): Spring
Spring.Gentle(initial), Spring.Wobbly(initial), Spring.Stiff(initial), Spring.Slow(initial), Spring.Bouncy(initial)

Ready-made speed and damper pairs. Their values come from the configuration.

Spring members

Impulse

spring:Impulse(velocity: SpringValue)

Adds velocity, like hitting the spring. For CFrame springs pass a Vector3 (linear velocity only).

-- Camera shake on landing
cameraOffset:Impulse(Vector3.new(0, -12, 0))

SkipToTarget / Stop

spring:SkipToTarget()
spring:Stop()

SkipToTarget jumps straight to the target and stops. Stop freezes the spring where it is right now by making its current position the new target.

Bind

spring:Bind(instance: Instance, property: string): () -> ()

Writes Position to instance[property] every frame. Returns a function that stops the binding; it also stops when the instance is destroyed.

Extrapolate

spring:Extrapolate(seconds: number): SpringValue

Where the spring will be after seconds if nothing changes.

IsSettled / TimeToSettle

spring:IsSettled(threshold: number?): boolean
spring:TimeToSettle(threshold: number?): number

Whether the distance to the target is below threshold, and how many seconds until it will be.

Clone

spring:Clone(): Spring

A new spring with the same state that moves on independently.

Spring groups

Spring.Group(initial: { [string]: SpringValue }, config: { [string]: SpringConfig }?, clock?): SpringGroup

Several named springs that you drive together, for example position, size and transparency of one frame.

local card = Spring.Group({
	Position = UDim2.fromScale(0.5, 0.6).Y.Scale,
	Transparency = 1,
})

card:SetTarget({ Position = 0.5, Transparency = 0 })

Configuration

Types

export type SpringValue = number | Vector2 | Vector3 | CFrame
export type SpringConfig = { speed: number?, damper: number? }
export type Spring
export type SpringGroup