Vide bindings for Ripple spring animation
npm install @rbxts/vide-rippleRipple is a simple, lightweight, and easy-to-use Roblox library for creating simple transitions and animations. It is inspired by react-spring and aims to provide an imperative API for general use.
Ripple is available on NPM and can be installed with the following commands:
``bash`
npm install @rbxts/ripple
yarn add @rbxts/ripple
pnpm add @rbxts/ripple
`toml`Wally
Ripple = "littensy/ripple@version"
The following data types are supported for animation:
| Data type | Converted type |
| -------------------------- | --------------------------------------------------------------- |
| number | [number] |[vector]
| vector | |[vector]
| Vector2 | |[vector]
| Vector3 | |[vector]
| Color3 | (Oklab) |[vector]
| UDim | |[vector, number]
| UDim2 | |[vector, vector, vector, vector]
| CFrame | |[vector, number]
| Rect | |Map
| Map |
---
createSpring creates a spring object starting at the given value.
`lua
local spring = createSpring(0, {
tension = 170,
friction = 26,
start = true,
})
spring:setGoal(1)
spring:onChange(print) --> number, deltaTime
`
Try the react-spring visualizer →
#### Parameters
- initialValue: The value that the spring should start with.options
- optional : The physical properties of the spring.
#### Options
| Option | Type | Description |
| ---------------- | --------- | ---------------------------------------------------------------------------------------------- |
| tension[^1] | number | Influences the number of bounces in the animation. Defaults to 170. |number
| friction[^1] | | Influences the level of spring in the animation. Defaults to 26. |number
| mass[^1] | | Influences the speed of the spring and height of the bounce. Defaults to 1. |number
| frequency[^2] | | How quickly the spring responds to changes. |number
| dampingRatio[^2] | | Dictates how the spring slows down. |number
| precision | | The distance to the goal before the spring is considered idle. Defaults to 0.001. |number
| restVelocity | | The smallest velocity before the spring is considered idle. Derived from precision by default. |T
| position | | Set the position of the spring. |T
| velocity | | Set the velocity of the spring. |T
| impulse | | Add to the velocity of the spring. |boolean
| start | | Connect to Heartbeat while animating. Defaults to false. |
[^1]: Tension, friction, and mass are not compatible with frequency or damping ratio.
[^2]: Frequency and damping ratio are not compatible with tension, friction, or mass.
#### Returns
createSpring returns a spring object.
---
createTween creates a tween object starting at the given value.
`lua
local tween = createTween(0, {
easing = "quadOut",
duration = 1,
start = true,
})
tween:setGoal(1)
tween:onChange(print) --> number, deltaTime
`
#### Parameters
- initialValue: The value that the spring should start with.options
- optional : The properties of the tween.
#### Options
| Option | Type | Description |
| -------- | --------- | -------------------------------------------------------------- |
| easing | Easing | The easing function to use for animation. |number
| duration | | Duration of one repetition of the tween, in seconds. |number
| repeats | | Number of times the tween repeats. |boolean
| reverses | | Reverse directions when repeating. |T
| position | | Continue the rest of the tween from this position. |boolean
| start | | Connect to Heartbeat while animating. Defaults to false. |
#### Easing functions
| | | |
| ------------- | -------------- | ---------------- |
| "linear" | "instant" | "smoothstep" |"sineIn"
| | "sineOut" | "sineInOut" |"backIn"
| | "backOut" | "backInOut" |"quadIn"
| | "quadOut" | "quadInOut" |"quartIn"
| | "quartOut" | "quartInOut" |"quintIn"
| | "quintOut" | "quintInOut" |"bounceIn"
| | "bounceOut" | "bounceInOut" |"elasticIn"
| | "elasticOut" | "elasticInOut" |"expoIn"
| | "expoOut" | "expoInOut" |"circIn"
| | "circOut" | "circInOut" |"cubicIn"
| | "cubicOut" | "cubicInOut" |
See examples of easing functions →
#### Returns
createTween returns a tween object.
---
createMotion creates an animation that switches between a spring and a tween.
`lua
local motion = createMotion(0, {
spring = { tension = 170, friction = 26 },
tween = { easing = "quadOut", duration = 1 },
start = true,
})
motion:onChange(print) --> number, deltaTime
motion:tween(1)
task.wait(1)
motion:spring(0)
`
> [!WARNING]
>
> This creates both a spring and a tween object, which can be wasteful if your animation uses only one or the other.
>
> Use createSpring or createTween if you do not need to switch animation types.
#### Parameters
- initialValue: The value that the spring and tween should start with.options
- optional : The properties of the spring or tween.
#### Options
| Option | Type | Description |
| ------ | ------------------ | ------------------------------------------------------------ |
| spring | SpringOptions | The spring options to use for spring animations. |TweenOptions
| tween | | The tween options to use for tween animations. |boolean
| start | | Connect to Heartbeat while animating. Defaults to false. |
#### Returns
createMotion` returns a motion object that controls a spring and a tween.
---
Ripple is licensed under the MIT License.
