spr
spr
Springs are a powerful way of describing physically based motion.
spr is an accessible library for creating beautiful UI animations from springs.
Fluid animations can be created in a single line of code with a simple syntax. Blending between animations is handled automatically in a physically-accurate way.
Driving Simulator uses spr extensively to handle over 500 unique animations.
Gallery
Features
A small API
- spr is easy to learn for non-programmers.
- You can animate anything by giving spr a target value and a set of animation parameters.
- You don’t have to memorize new datatypes or more than a few functions.
Easy-to-tune motion
- You should be able to know how an animation will look without running the game.
- Motion is defind by frequency and damping ratio, which are easy to understand and visualize.
An analytical spring solver
- The spr spring solver is extremely robust and provides protections from accidentally passing bad motion parameters.
- If spr is given a nonconverging set of motion parameters, it will throw a clear error describing what is wrong and how to fix it.
Tight integration with Roblox datatypes
- spr directly animates Roblox properties without additional layers of indirection.
- spr performs runtime type checking, providing stronger typing than Roblox instance property setters.
- spr knows how to animate in the ideal space for each datatype.
- spr will automatically animate Color3 values in perceptually-uniform CIELUV space.
Spring fundamentals
Damping ratio and frequency are the two properties defining a spring’s motion.
- Damping ratio describes shape
- Frequency describes speed
Damping ratio
- Damping ratio < 1 overshoots and converges on the target. This is called underdamping.
- Damping ratio = 1 converges on the target without overshooting. This is called critical damping.
- Damping ratio > 1 converges on the target without overshooting, but slower. This is called overdamping.
Critical damping is recommended as the most visually neutral option.
Underdamping is recommended for animations that need to “pop.”
Damping ratio and frequency can be visualized here.
Examples
-- damping ratio 1 (critically damped), frequency 0.5 (slow)
-- frame slowly moves to the middle of the screen without overshooting
spr.target(frame, 1, 0.5, {
Position = UDim2.fromScale(0.5, 0.5)
})
-- damping ratio 0.6 (underdamped), frequency 4 (fast)
-- frame quickly moves to the middle, overshoots, and wobbles before converging
spr.target(frame, 0.6, 4, {
Position = UDim2.fromScale(0.5, 0.5)
})
-- animate Position and Size
spr.target(frame, 0.6, 1, {
Position = UDim2.fromScale(1, 1),
Size = UDim2.fromScale(0.5, 0.5)
})
wait(1)
-- stop all animations on Frame
spr.stop(frame)
How to get
- Paste the source of spr.lua into a new ModuleScript.
- Require the ModuleScript with
local spr = require(<path to spr goes here>) - Follow the documentation to get started with the API.
Documentation on how to use ModuleScripts can be found here.
roblox-ts bindings for spr can be installed here.
Issues and bugs can be filed under GitHub issues.
