Small and fast motion library
Springs are powerful approach for describing fluid, physically-based animation.
spr is a high-performance and user-friendly motion library for Roblox based on springs.
Animations are a single line of code:
spr.target(part, springDamping, springFrequency, { CFrame = CFrame.new(0, 10, 0) })
spr.target
spr.target(
obj: Instance,
dampingRatio: number,
undampedFrequency: number,
targetProperties: {[string]: any})
Animates the given properties towardes the target values.
spr.completed
spr.completed(obj: Instance, callback: ()->())
Registers a callback function that will be called the next time the instance stops animating. The callback is only called once. This is useful for tracking instance lifetime, such as destroying a part when it becomes invisible.
spr.stop
spr.stop(obj: Instance, property: string?)
Stops animations for a particular property. If a property is not specified, all properties belonging to the instance will stop animating.
Damping ratio and undamped frequency are the two properties describing a spring's motion.
Critical damping is recommended as the most visually neutral option with no overshoot. Underdamping is recommended for animations that need extra pop.
Damping ratio and frequency can be visualized here.
spr supports a subset of Roblox and native Luau types for which interpolation makes sense. Currently, those are:
boolean
CFrame
Color3
ColorSequence
number
NumberRange
UDim
UDim2
Vector2
Vector3
spr is a single-module library.
local spr = require(<path to spr>)
Documentation on how to use ModuleScripts can be found here.
spr.target
-- damping ratio 1 (critically damped), frequency 1
-- frame slowly moves to the middle of the screen without overshooting
spr.target(frame, 1, 1, {
Position = UDim2.fromScale(0.5, 0.5)
})
-- damping ratio 0.6 (underdamped), frequency 4
-- frame quickly moves to the middle of the screen, overshoots, and wobbles around the target
spr.target(frame, 0.6, 4, {
Position = UDim2.fromScale(0.5, 0.5)
})
spr.completed
spr.target(workspace.Part, 1, 1, {Transparency = 1})
spr.completed(workspace.Part, function() workspace.Part:Destroy() end)
spr.stop
spr.target(frame, 0.6, 1, {
Position = UDim2.fromScale(1, 1)
})
-- spr is now animating frame.Position
task.wait(1)
spr.stop(frame, "Position")
-- spr is no longer animating frame.Position
spr.target(frame, 0.6, 1, {
Position = UDim2.fromScale(1, 1),
Size = UDim2.fromScale(0.5, 0.5)
})
-- spr is now animating Position and Size
task.wait(1)
spr.stop(frame)
-- spr is no longer animating Position or Size