{"id":"eldonwilliams/spr","name":"spr","scope":"eldonwilliams","platform":"roblox","description":"Spr module as a wally package w/ added support for ","version":"0.2.1","latest":"0.2.1","versions":["0.1.0","0.1.1","0.2.0","0.2.1"],"license":"MIT","licenseRating":"safe","licenseCaveats":["License identified from the packaged LICENSE file; the manifest declared none."],"licenseVerified":true,"dependencies":{},"integrity":"3ff71d8bfdbb069dca440fec98baf39e02fc17fb052ec5f42e8f7f40b23a3b6a","likes":0,"downloads":0,"install":"forest install eldonwilliams/spr","url":"https://forest.dev/p/roblox/eldonwilliams/spr","files":"https://api.forest.dev/ai/package/roblox/eldonwilliams/spr/files","readme":"# ☄️ spr\r\nSprings are a simple and powerful model for describing physically-based motion.\r\n**spr** is a small spring-based UI animation library.\r\n\r\n## Features\r\n#### A small API\r\n- You should be able to animate anything by giving spr a target value and a set of animation parameters.\r\n- You should not have to memorize new datatypes or more than a few API calls.\r\n\r\n#### Easy-to-tune motion\r\n- You should be able to know how an animation will look without running the game.\r\n- Motion is defined by frequency and damping ratio, which are easy to understand and visualize.\r\n\r\n#### A robust, analytical spring model\r\n- You should never be able to accidentally pass the spring solver values that will cause numerical instability or explosion.\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## 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.\r\nUnderdamping is recommended for animations that need to \"pop.\"\r\n\r\nDamping ratio and frequency can be [visualized here.](https://www.desmos.com/calculator/rzvw27ljh9)\r\n\r\n## API\r\n\r\n### spr.target\r\n```lua\r\nspr.target(\r\n   Instance obj,\r\n   number dampingRatio,\r\n   number undampedFrequency,\r\n   table<string, Variant> targetProperties)\r\n```\r\n\r\nAnimates the given properties towardes the target values, given damping ratio and frequency values.\r\n\r\n#### Examples\r\n\r\n```lua\r\n-- damping ratio 1 (critically damped), frequency 4\r\n-- frame quickly moves to the middle of the screen without overshooting\r\nspr.target(frame, 1, 4, {\r\n    Position = UDim2.fromScale(0.5, 0.5)\r\n})\r\n```\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```lua\r\n-- damping ratio 0.6 (underdamped), frequency 1\r\n-- frame slowly moves to the middle of the screen, overshoots, and wobbles around the target\r\nspr.target(frame, 0.6, 1, {\r\n    Position = UDim2.fromScale(0.5, 0.5)\r\n})\r\n```\r\n\r\n### spr.stop\r\n```lua\r\nspr.stop(\r\n   Instance obj[,\r\n   string property])\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#### Examples\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\nwait(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\nwait(1)\r\n\r\nspr.stop(frame)\r\n-- spr is no longer animating Position or Size\r\n```\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 above 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### wally\r\n\r\n1. Setup a wally project, you can find information about that [here](https://github.com/upliftgames/wally).\r\n2. Add ``Spr = \"eldonwilliams/spr@^0.1.0\"`` to your `wally.toml` file\r\n3. Run ``wally install`` and you should be good to go!\r\n\r\n### roblox-ts\r\n\r\nroblox-ts bindings for spr can be installed [here.](https://www.npmjs.com/package/@rbxts/spr)\r\n\r\n","readmeTruncated":false}