{"id":"mastrickdev/spring","name":"spring","scope":"mastrickdev","platform":"roblox","description":"Springs are powerful approach for describing fluid, physically-based animation. Spring is a high-performance and user-friendly motion library for Roblox based on springs.","version":"0.2.4","latest":"0.2.4","versions":["0.1.0","0.1.1","0.1.2","0.1.3","0.2.1","0.2.2","0.2.3","0.2.4"],"license":"MIT","licenseRating":"safe","licenseCaveats":["License identified from the packaged LICENSE file; the manifest declared none."],"licenseVerified":true,"dependencies":{"lukadev-0/typed-promise":{"version":"^4.0.2","alias":"Promise"}},"integrity":"0a94275c6d8c4fcae36fca5dffc2953c60a79ab456ebc94fa35cbf563a731403","likes":0,"downloads":0,"install":"forest install mastrickdev/spring","url":"https://forest.dev/p/roblox/mastrickdev/spring","files":"https://api.forest.dev/ai/package/roblox/mastrickdev/spring/files","readme":"# Spring\r\n\r\nSpring is an animation library for Roblox, which uses the method of harmonic response to create smooth and natural movements. Spring allows you to animate any property of any instance, using only two variables: **damping ratio** and **frequency**.\r\n\r\n## Wally Installation\r\n\r\nTo install with wally, insert it inside wally.toml [dependencies]\r\n\r\n```toml\r\nspring = \"mastrickdev/spring@0.2.3\"\r\n```\r\n\r\n## Usability\r\n\r\nTo use Spring, you need to first load the library:\r\n\r\n```lua\r\nlocal Spring = require(...)\r\n```\r\n\r\nThen, you can create an animation using the method `Spring.target`, which takes four arguments:\r\n\r\n- `instance`: the instance that you want to animate, such as a `BasePart`, a `GuiObject`, or a `Camera`.\r\n- `dampingRatio`: a number between 0 and 1 that describes the shape of the animation. The lower the value, the more the animation will oscillate and take longer to reach the target. The higher the value, the faster and smoother the animation will be. The recommended value is 1, which is called **critical damping**.\r\n- `frequency`: a positive number that describes the speed of the animation. The higher the value, the faster the animation will be. The recommended value is 1, which is called **natural frequency**.\r\n- `properties`: a table that contains the properties that you want to animate and the target values. For example, if you want to animate the position and orientation of a `BasePart`, you can use something like:\r\n\r\n```lua\r\nSpring.target(basePart, 0.75, 1, {  CFrame = CFrame.new(20, 20, 20) })\r\n```\r\n\r\nThe method `Spring.target` returns a `Promise`, which is an object that represents an asynchronous operation. You can use the method `:andThen` to execute a function when the animation finishes, or the method `:cancel` to cancel the animation and the `Promise`. For example, if you want to print a message when the animation is over, you can do something like:\r\n\r\n```lua\r\nSpring.target(basePart, 0.75, 1, { CFrame = CFrame.new(20, 20, 20) })\r\n    :andThen(function() print(\"Animation completed!\") end)\r\n```\r\n\r\nIf you want to cancel the animation before it finishes, you can do something like:\r\n\r\n```lua\r\nlocal promise = Spring.target(basePart, 0.75, 1, { CFrame = CFrame.new(20, 20, 20) })\r\n\r\n-- Some time later...\r\npromise:cancel()\r\n```\r\n\r\n## Fundamental concepts\r\n\r\nDamping ratio and frequency are the two properties that describe the motion of a spring.\r\n\r\n- **Damping ratio** describes the shape of the animation. The damping ratio is the ratio between the actual damping of the spring and the critical damping, which is the minimum required to avoid oscillations. The damping ratio can be classified into three types:\r\n\r\n    - **Underdamped** (damping ratio < 1): the animation exceeds the target value and converges to it with decreasing oscillations. This type of animation is recommended for situations that need more dynamism and energy.\r\n    - **Critically damped** (damping ratio = 1): the animation converges to the target value without exceeding it. This type of animation is recommended for situations that need more neutrality and smoothness.\r\n    - **Overdamped** (damping ratio > 1): the animation converges to the target value without exceeding it, but more slowly. This type of animation is recommended for situations that need more calm and control.\r\n\r\n- **Frequency** describes the speed of the animation. The frequency is the natural frequency of the spring, which is the rate of oscillation of the spring when there is no damping. The frequency can be adjusted to change the time that the animation takes to reach the target value.\r\n\r\nYou can visualize the effect of the damping ratio and the frequency on the animation using this [viewer](https://www.desmos.com/calculator/rzvw27ljh9).\r\n\r\n## Supported types\r\n\r\nSpring supports a subset of the native Roblox and Luau types for which interpolation makes sense. Currently, these are:\r\n\r\n- `boolean`: a logical value that can be `true` or `false`.\r\n- `CFrame`: a 4x4 matrix that represents the position and orientation of an object in 3D space.\r\n- `Color3`: a color represented by three components: red, green, and blue.\r\n- `ColorSequence`: a sequence of colors that can be used to interpolate between them.\r\n- `number`: a numerical value that can be integer or decimal.\r\n- `NumberRange`: a range of numbers that can be used to generate random numbers within it.\r\n- `UDim`: a relative dimension that can be used to position and size objects in the user interface.\r\n- `UDim2`: a relative dimension in two dimensions that can be used to position and size objects in the user interface.\r\n- `Vector2`: a two-dimensional vector that represents a direction or a position in the 2D plane.\r\n- `Vector3`: a three-dimensional vector that represents a direction or a position in the 3D space.\r\n","readmeTruncated":false}