A streamlined Roblox animation utility that simplifies the use of springs, tweens, and splines on object properties.

Types

SpringInfo

A dictionary of spring properties such as {s = 10, d = 0.5}. Can be constructed using any keys that you could use to create a Spring object. Possible keys:

Initial = Initial | i
Speed = Speed | s
Damper = Damper | d
Target = Target | t
Velocity = Velocity | v
Position = Position | Value | p
Clock = Clock

AnimChain

An object that listens for the end of a tween/spring animation and then fires any connected :AndThen() callbacks. :AndThen() always returns the same AnimChain object, so you can chain as many callbacks together as you want.

TweenInfo

TweenInfo can be passed to the tweening functions as either a TweenInfo object or a dictionary of the desired parameters. Keys are either the TweenInfo parameter name or shortened versions:

Time = Time | t
EasingStyle = EasingStyle | Style | s
EasingDirection = EasingDirection | Direction | d
RepeatCount = RepeatCount | Repeat | rc
Reverses = Reverses | Reverse | r
DelayTime = DelayTime | Delay | dt

Tweens

AnimNation tweens support all properties that are supported by TweenService, as well as tweening Models by CFrame and tweening NumberSequence/ColorSequence values (given that the target sequence has the same number of keypoints).

---

.tween(object: Instance, tweenInfo: TweenInfo | {}, properties: {[string]: any}, waitToKill: boolean?): AnimChain

Asynchronously performs a tween on the given object. Parameters are identical to TweenService:Create(), with the addition of waitToKill, which will make the operation synchronous (yielding) if true. :AndThen() can be used to link another function that will be called when the tween completes.

---

.tweenFromAlpha(object: Instance, tweenInfo: TweenInfo | {}, properties: {[string]: any}, alpha: number, waitToKill: boolean?): AnimChain

Asynchronously performs a tween on the given object, starting from the specified alpha percentage. Otherwise identical to AnimNation.tween. Currently supports number, Vector2, Vector3, CFrame, Color3, UDim2, UDim and any other type that supports scalar multiplication/addition.

NOTE: Currently supports tweening Models by CFrame, but does not yet support tweening NumberSequence/ColorSequence values. Using .getTweenFromInstance() will also not return a Tween if using this function. This is due to the backend being a custom solution since Roblox doesn't natively support skipping around in Tween objects :)

---

.getTweenFromInstance(object: Instance): Tween?

Returns the last tween played on the given object, or nil if none exists.

Springs

AnimNation springs support the following types: number, Vector2, Vector3, UDim, UDim2, CFrame, and Color3. These are natively supported by the provided Spring class as well.

---

.impulse(object: Instance, springInfo: SpringInfo, properties: {[string]: any}, waitToKill: boolean?): AnimChain

Asynchronously performs a spring impulse on the given object. The optional waitToKill flag will make the operation synchronous (yielding) if true. :AndThen() can be used on this function's return value to link another function that will be called when the spring completes (reaches epsilon).

---

.target(object: Instance, springInfo: SpringInfo, properties: {[string]: any}, waitToKill: boolean?)

Asynchronously uses a spring to transition the given object's properties to the specified values. The optional waitToKill flag will make the operation synchronous (yielding) if true.

NOTE: No AnimChain is currently returned to enable :AndThen() behavior. I plan to add support for this in a future update.

---

.bind(springs: {Spring}, label: string, callback: (positions: {Springable}, velocities: {Springable}) -> ())

Binds a callback function to the given springs' positions and velocities. Can be used to create more complex and constant interactions with spring values than just a quick impulse or target.

---

.unbind(spring: Spring, label: string)

Unbinds the callback associated with the specified label from updates.

---

.createSpring(springInfo: SpringInfo, name: string?): Spring

Creates a new spring with the given properties and maps it to the specified name, if provided. An initial value can be provided in the SpringInfo table. Aliases: .register()

---

.getSpring(name: string): Spring?

Returns the spring with the given name. If none exists, it will return nil with a warning, or an error depending on the set ERROR_POLICY. Aliases: .inquire()

Splines

AnimNation splines are used in animation for interpolating between a series of points in a smoothed curving fashion.

---

.getSpline(name: string): Spline?

Returns the Spline with the given name. If none exists, it will return nil with a warning, or an error depending on the set ERROR_POLICY.

---

.createSpline(controlPoints: {CFrame}, name: string?): Spline

Creates a new Spline from the given control points. This should be a table of CFrame values with at least 4 entries.

---

.slerpTweenFromAlpha(object: Instance, tweenInfo: TweenInfo | {}, spline: Spline | {CFrame}, alignment: ("Track" | "Nodes")?, alpha: number?, waitToKill: boolean?): AnimChain

Asynchronously performs tween-based spherical interpolation on the given object, starting from the specified alpha percentage. Parameters are similar to AnimNation.tweenFromAlpha(), with the addition of alignment which determines whether the object being tweened is aligned to the track orientation or the nodes' orientations. A spline argument is also required, which can be supplied as previously constructed spline object or an array of points to create a new one from. :AndThen() can be used to link a callback function when the tween completes. Currently supports number, Vector2, Vector3, UDim, UDim2, CFrame, Color3 and any other type that supports scalar multiplication/addition.