{"id":"kiy4ku/spr","name":"spr","scope":"kiy4ku","platform":"roblox","description":"Spr is a high-performance and user-friendly motion library for Roblox based on springs.","version":"2.1.0","latest":"2.1.0","versions":["2.1.0"],"license":"MIT","licenseRating":"safe","licenseCaveats":[],"licenseVerified":true,"dependencies":{},"integrity":"ff705df9ddb1f5ae8d791ccfd362033d19b03a73aebbe3f03986a8d0db4cab17","likes":0,"downloads":0,"install":"forest install kiy4ku/spr","url":"https://forest.dev/p/roblox/kiy4ku/spr","files":"https://api.forest.dev/ai/package/roblox/kiy4ku/spr/files","readme":"# ☄️ spr\r\n\r\nSprings are powerful approach for describing fluid, physically-based animation.<br/>\r\n**spr** is a high-performance and user-friendly motion library for Roblox based on springs.\r\n\r\nAnimations are a single line of code:\r\n\r\n```lua\r\nspr.target(part, springDamping, springFrequency, { CFrame = CFrame.new(0, 10, 0) })\r\n```\r\n\r\n## Features\r\n#### A small, easy-to-use API\r\n- spr is easy enough for designers and learning programmers to understand.\r\n- spr only needs a target value and motion parameters. It handles all other aspects of animation automatically.\r\n\r\n#### Easy-to-tune motion\r\n- Motion is defined by *frequency* and *damping ratio*.\r\n- Frequency and damping ratio are easy to visualize without running the game. Tuning usually only takes one try.\r\n\r\n#### A robust spring model\r\n- spr's robust analytical motion solver handles a wide variety of spring parameters that cause other spring solvers to fail.\r\n- 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.\r\n\r\n#### Tight integration with Roblox datatypes\r\n- spr animates directly over Roblox properties without additional layers of indirection.\r\n- spr performs runtime type checking, providing stronger typing than Roblox instance property setters.\r\n- spr knows how to animate in the ideal space for each datatype.\r\n    - For example, spr will automatically animate [Color3](https://developer.roblox.com/en-us/api-reference/datatype/Color3) values in perceptually-uniform [CIELUV space.](https://en.wikipedia.org/wiki/CIELUV)\r\n\r\n## API\r\n\r\n### `spr.target`\r\n```lua\r\nspr.target(\r\n   obj: Instance,\r\n   dampingRatio: number,\r\n   undampedFrequency: number,\r\n   targetProperties: {[string]: any})\r\n```\r\n\r\nAnimates the given properties towardes the target values.\r\n\r\n### `spr.completed`\r\n```lua\r\nspr.completed(obj: Instance, callback: ()->())\r\n```\r\n\r\nRegisters a callback function that will be called the next time the instance stops animating. The callback is only called once.\r\nThis is useful for tracking instance lifetime, such as destroying a part when it becomes invisible.\r\n\r\n### `spr.stop`\r\n```lua\r\nspr.stop(obj: Instance, property: string?)\r\n```\r\n\r\nStops animations for a particular property.\r\nIf a property is not specified, all properties belonging to the instance will stop animating.\r\n\r\n## Spring fundamentals\r\n\r\nDamping ratio and undamped frequency are the two properties describing a spring's motion.\r\n\r\n- [Damping ratio](https://en.wikipedia.org/wiki/Damping_ratio) describes shape\r\n- [Undamped frequency](https://ocw.mit.edu/courses/mathematics/18-03-differential-equations-spring-2010/readings/supp_notes/MIT18_03S10_chapter_13.pdf) describes speed\r\n\r\n### Damping ratio\r\n- **Damping ratio < 1** overshoots and converges on the target. This is called underdamping.\r\n- **Damping ratio = 1** converges on the target without overshooting. This is called critical damping.\r\n- **Damping ratio > 1** converges on the target without overshooting, but slower. This is called overdamping.\r\n\r\nCritical damping is recommended as the most visually neutral option with no overshoot.\r\nUnderdamping is recommended for animations that need extra pop.\r\n\r\nDamping ratio and frequency can be [visualized here.](https://www.desmos.com/calculator/rzvw27ljh9)\r\n\r\n## Type support\r\n\r\nspr supports a subset of Roblox and native Luau types for which interpolation makes sense.\r\nCurrently, those are:\r\n\r\n- `boolean`\r\n- `CFrame`\r\n- `Color3`\r\n- `ColorSequence`\r\n- `number`\r\n- `NumberRange`\r\n- `UDim`\r\n- `UDim2`\r\n- `Vector2`\r\n- `Vector3`\r\n\r\n## Setup\r\n\r\nspr is a single-module library.\r\n\r\n1. Paste the source of [spr.lua](https://raw.githubusercontent.com/Fraktality/spr/master/spr.lua) into a new ModuleScript\r\n2. Require the ModuleScript with `local spr = require(<path to spr>)`\r\n3. Follow the below code examples to get started with the API.\r\n\r\nDocumentation on how to use ModuleScripts can be found [here.](https://developer.roblox.com/en-us/api-reference/class/ModuleScript)\r\n\r\n## Examples\r\n\r\n### `spr.target`\r\n\r\n```lua\r\n-- damping ratio 1 (critically damped), frequency 1\r\n-- frame slowly moves to the middle of the screen without overshooting\r\nspr.target(frame, 1, 1, {\r\n    Position = UDim2.fromScale(0.5, 0.5)\r\n})\r\n```\r\n\r\n```lua\r\n-- damping ratio 0.6 (underdamped), frequency 4\r\n-- frame quickly moves to the middle of the screen, overshoots, and wobbles around the target\r\nspr.target(frame, 0.6, 4, {\r\n    Position = UDim2.fromScale(0.5, 0.5)\r\n})\r\n```\r\n\r\n### `spr.completed`\r\n\r\n```lua\r\nspr.target(workspace.Part, 1, 1, {Transparency = 1})\r\nspr.completed(workspace.Part, function() workspace.Part:Destroy() end)\r\n```\r\n\r\n### `spr.stop`\r\n\r\n```lua\r\nspr.target(frame, 0.6, 1, {\r\n    Position = UDim2.fromScale(1, 1)\r\n})\r\n-- spr is now animating frame.Position\r\n\r\ntask.wait(1)\r\n\r\nspr.stop(frame, \"Position\")\r\n-- spr is no longer animating frame.Position\r\n```\r\n\r\n\r\n```lua\r\nspr.target(frame, 0.6, 1, {\r\n    Position = UDim2.fromScale(1, 1),\r\n    Size = UDim2.fromScale(0.5, 0.5)\r\n})\r\n-- spr is now animating Position and Size\r\n\r\ntask.wait(1)\r\n\r\nspr.stop(frame)\r\n-- spr is no longer animating Position or Size\r\n```\r\n","readmeTruncated":false}