@quenty/spring 2.2.0 → 3.0.1-canary.238.2c4d310.0

package/CHANGELOG.md

@@ -3,6 +3,25 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [3.0.1-canary.238.2c4d310.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/spring@3.0.0...@quenty/spring@3.0.1-canary.238.2c4d310.0) (2021-12-29)
+
+**Note:** Version bump only for package @quenty/spring
+
+
+
+
+
+# [3.0.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/spring@2.2.0...@quenty/spring@3.0.0) (2021-12-22)
+
+
+### Features
+
+* Add spring support for UDim2 and UDim and Vector2 ([d1763d7](https://github.com/Quenty/NevermoreEngine/commit/d1763d7cdc65ad5df4bbe38897cd9a446bb61bb1))
+
+
+
+
+
 # [2.2.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/spring@2.1.0...@quenty/spring@2.2.0) (2021-12-18)
 
 

package/README.md

@@ -1,10 +1,10 @@
 ## Spring
 <div align="center">
-  <a href="http://quenty.github.io/api/">
+  <a href="http://quenty.github.io/NevermoreEngine/">
     <img src="https://img.shields.io/badge/docs-website-green.svg" alt="Documentation" />
   </a>
   <a href="https://discord.gg/mhtGUS8">
-    <img src="https://img.shields.io/badge/discord-nevermore-blue.svg" alt="Discord" />
+    <img src="https://img.shields.io/discord/385151591524597761?color=5865F2&label=discord&logo=discord&logoColor=white" alt="Discord" />
   </a>
   <a href="https://github.com/Quenty/NevermoreEngine/actions">
     <img src="https://github.com/Quenty/NevermoreEngine/actions/workflows/build.yml/badge.svg" alt="Build and release status" />
@@ -19,40 +19,5 @@ upon index making this model good for lazy applications
 npm install @quenty/spring --save
 ```
 
-
-## API
-
-`Spring = Spring.new(number position)`
-	Creates a new spring in 1D
-`Spring = Spring.new(Vector3 position)`
-	Creates a new spring in 3D
-
-`Spring.Position`
-	Returns the current position
-`Spring.Velocity`
-	Returns the current velocity
-`Spring.Target`
-	Returns the target
-`Spring.Damper`
-	Returns the damper
-`Spring.Speed`
-	Returns the speed
-
-`Spring.Target = number/Vector3`
-	Sets the target
-`Spring.Position = number/Vector3`
-	Sets the position
-`Spring.Velocity = number/Vector3`
-	Sets the velocity
-`Spring.Damper = number [0, 1]`
-	Sets the spring damper, defaults to 1
-`Spring.Speed = number [0, infinity)`
-	Sets the spring speed, defaults to 1
-
-`Spring:TimeSkip(number DeltaTime)`
-	Instantly skips the spring forwards by that amount of now
-`Spring:Impulse(number/Vector3 velocity)`
-	Impulses the spring, increasing velocity by the amount given
-
 ## Visualization
 by Defaultio: https://www.desmos.com/calculator/hn2i9shxbz

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quenty/spring",
-  "version": "2.2.0",
+  "version": "3.0.1-canary.238.2c4d310.0",
   "description": "Spring implementation for Roblox",
   "keywords": [
     "Roblox",
@@ -29,7 +29,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@quenty/loader": "^3.1.1"
+    "@quenty/loader": "3.1.2-canary.238.2c4d310.0"
   },
-  "gitHead": "6eb398e9fb81191f0815885f807ab0cb3bb9bad1"
+  "gitHead": "2c4d310b84afd0570d89667dc5d4aa69a0ef304a"
 }

package/src/Shared/LinearValue.lua

@@ -1,11 +1,19 @@
----
--- @classmod LinearValue
--- @author Quenty
+--[=[
+	Represents a value that can operate in linear space
 
+	@class LinearValue
+]=]
 local LinearValue = {}
 LinearValue.ClassName = "LinearValue"
 LinearValue.__index = LinearValue
 
+--[=[
+	Constructs a new LinearValue object.
+
+	@param constructor (number ...) -> T
+	@param values ({ number })
+	@return LinearValue<T>
+]=]
 function LinearValue.new(constructor, values)
 	return setmetatable({
 		_constructor = constructor;
@@ -13,10 +21,21 @@ function LinearValue.new(constructor, values)
 	}, LinearValue)
 end
 
+--[=[
+	Returns whether or not a value is a LinearValue object.
+
+	@param value any -- A value to check
+	@return boolean -- True if a linear value, false otherwise
+]=]
 function LinearValue.isLinear(value)
 	return type(value) == "table" and getmetatable(value) == LinearValue
 end
 
+--[=[
+	Converts the value back to the base value
+
+	@return T
+]=]
 function LinearValue:ToBaseValue()
 	return self._constructor(unpack(self._values))
 end
@@ -57,6 +76,11 @@ local function operation(func)
 	end
 end
 
+--[=[
+	Returns the magnitude of the linear value.
+
+	@return number -- The magnitude of the linear value.
+]=]
 function LinearValue:GetMagnitude()
 	local dot = 0
 	for i=1, #self._values do
@@ -66,6 +90,13 @@ function LinearValue:GetMagnitude()
 	return math.sqrt(dot)
 end
 
+--[=[
+	Returns the magnitude of the linear value.
+
+	@prop magnitude number
+	@readonly
+	@within LinearValue
+]=]
 function LinearValue:__index(key)
 	if LinearValue[key] then
 		return LinearValue[key]
@@ -92,5 +123,23 @@ LinearValue.__div = operation(function(a, b)
 	return a / b
 end)
 
+function LinearValue:__eq(a, b)
+	if LinearValue.isLinear(a) and LinearValue.isLinear(b) then
+		if #a._values ~= #b._values then
+			return false
+		end
+
+		for i=1, #a._values do
+			if a._values[i] ~= b._values[i] then
+				return false
+			end
+		end
+
+		return true
+	else
+		return false
+	end
+end
+
 
 return LinearValue

package/src/Shared/Spring.lua

@@ -1,53 +1,51 @@
---[[
-class Spring
-
-Description:
-	A physical model of a spring, useful in many applications. Properties only evaluate
-	upon index making this model good for lazy applications
-
-API:
-	Spring = Spring.new(number position)
-		Creates a new spring in 1D
-	Spring = Spring.new(Vector3 position)
-		Creates a new spring in 3D
-
-	Spring.Position
-		Returns the current position
-	Spring.Velocity
-		Returns the current velocity
-	Spring.Target
-		Returns the target
-	Spring.Damper
-		Returns the damper
-	Spring.Speed
-		Returns the speed
-
-	Spring.Target = number/Vector3
-		Sets the target
-	Spring.Position = number/Vector3
-		Sets the position
-	Spring.Velocity = number/Vector3
-		Sets the velocity
-	Spring.Damper = number [-infinity, infinity]
-		Sets the spring damper, defaults to 1
-	Spring.Speed = number [0, infinity)
-		Sets the spring speed, defaults to 1
-
-	Spring:TimeSkip(number DeltaTime)
-		Instantly skips the spring forwards by that amount of now
-	Spring:Impulse(number/Vector3 velocity)
-		Impulses the spring, increasing velocity by the amount given
-
-Visualization (by Defaultio):
-	https://www.desmos.com/calculator/hn2i9shxbz
-]]
+--[=[
+	A physical model of a spring, useful in many applications.
+
+	A spring is an object that will compute based upon Hooke's law. Properties only evaluate
+	upon index making this model good for lazy applications.
+
+	```lua
+	local RunService = game:GetService("RunService")
+	local UserInputService = game:GetService("UserInputService")
+
+	local spring = Spring.new(Vector3.new(0, 0, 0))
 
+	RunService.RenderStepped:Connect(function()
+		if UserInputService:IsKeyDown(Enum.KeyCode.W) then
+			spring.Target = Vector3.new(0, 0, 1)
+		else
+			spring.Target = Vector3.new(0, 0, 0)
+		end
+
+		print(spring.Position) -- A smoothed out version of the input keycode W
+	end)
+	```
+
+	A good visualization can be fond here, provided by Defaultio:
+	https://www.desmos.com/calculator/hn2i9shxbz
 
+	@class Spring
+]=]
 local Spring = {}
 
---- Creates a new spring
--- @param initial A number or Vector3 (anything with * number and addition/subtraction defined)
--- @param[opt=os.clock] clock function to use to update spring
+--[=[
+	Constructs a new Spring at the position and target specified, of type T.
+
+	```lua
+	-- Linear spring
+	local linearSpring = Spring.new(0)
+
+	-- Vector2 spring
+	local vector2Spring = Spring.new(Vector2.new(0, 0))
+
+	-- Vector3 spring
+	local vector3Spring = Spring.new(Vector3.new(0, 0, 0))
+	```
+
+	@param initial T -- The initial parameter is a number or Vector3 (anything with * number and addition/subtraction).
+	@param clock? () -> number -- The clock function is option, and is used to update the spring
+	@return Spring<T>
+]=]
 function Spring.new(initial, clock)
 	local target = initial or 0
 	clock = clock or os.clock
@@ -62,14 +60,22 @@ function Spring.new(initial, clock)
 	}, Spring)
 end
 
---- Impulse the spring with a change in velocity
--- @param velocity The velocity to impulse with
+--[=[
+	Impulses the spring, increasing velocity by the amount given. This is useful to make something shake,
+	like a Mac password box failing.
+
+	@param velocity T -- The velocity to impulse with
+	@return ()
+]=]
 function Spring:Impulse(velocity)
 	self.Velocity = self.Velocity + velocity
 end
 
---- Skip forwards in now
--- @param delta now to skip forwards
+--[=[
+	Instantly skips the spring forwards by that amount time
+	@param delta number--  Time to skip forwards
+	@return ()
+]=]
 function Spring:TimeSkip(delta)
 	local now = self._clock()
 	local position, velocity = self:_positionVelocity(now+delta)
@@ -78,6 +84,87 @@ function Spring:TimeSkip(delta)
 	self._time0 = now
 end
 
+--[=[
+	The current position at the given clock time. Assigning the position will change the spring to have that position.
+
+	```lua
+	local spring = Spring.new(0)
+	print(spring.Position) --> 0
+	```
+
+	@prop Position T
+	@within Spring
+]=]
+--[=[
+	Alias for [Spring.Position](/api/Spring#Position)
+
+	@prop p T
+	@within Spring
+]=]
+--[=[
+	The current velocity. Assigning the velocity will change the spring to have that velocity.
+
+	```lua
+	local spring = Spring.new(0)
+	print(spring.Velocity) --> 0
+	```
+
+	@prop Velocity T
+	@within Spring
+]=]
+--[=[
+	Alias for [Spring.Velocity](/api/Spring#Velocity)
+
+	@prop v T
+	@within Spring
+]=]
+--[=[
+	The current target. Assigning the target will change the spring to have that target.
+
+	```lua
+	local spring = Spring.new(0)
+	print(spring.Target) --> 0
+	```
+
+	@prop Target T
+	@within Spring
+]=]
+--[=[
+	Alias for [Spring.Target](/api/Spring#Target)
+	@prop t T
+	@within Spring
+]=]
+--[=[
+	The current damper, defaults to 1. At 1 the spring is critically damped. At less than 1, it
+	will be underdamped, and thus, bounce, and at over 1, it will be critically damped.
+
+	@prop Damper number
+	@within Spring
+]=]
+--[=[
+	Alias for [Spring.Damper](/api/Spring#Damper)
+
+	@prop d number
+	@within Spring
+]=]
+--[=[
+	The speed, defaults to 1, but should be between [0, infinity)
+
+	@prop Speed number
+	@within Spring
+]=]
+--[=[
+	Alias for [Spring.Speed](/api/Spring#Speed)
+
+	@prop s number
+	@within Spring
+]=]
+--[=[
+	The current clock object to syncronize the spring against.
+
+	@prop Clock () -> number
+	@within Spring
+]=]
 function Spring:__index(index)
 	if Spring[index] then
 		return Spring[index]
@@ -181,4 +268,4 @@ function Spring:_positionVelocity(now)
 		b0*p0 + b1*p1 + b2*v0
 end
 
-return Spring
+return Spring

package/src/Shared/SpringUtils.lua

@@ -1,6 +1,7 @@
----
--- @module SpringUtils
--- @author Quenty
+--[=[
+	Utility functions that are related to the Spring object
+	@class SpringUtils
+]=]
 
 local EPSILON = 1e-6
 
@@ -9,6 +10,15 @@ local LinearValue = require("LinearValue")
 
 local SpringUtils = {}
 
+--[=[
+	Utility function that returns whether or not a spring is animating based upon
+	velocity and closeness to target, and as the second value, the value that should be
+	used.
+
+	@param spring Spring<T>
+	@param epsilon number? -- Optional epsilon
+	@return boolean, T
+]=]
 function SpringUtils.animating(spring, epsilon)
 	epsilon = epsilon or EPSILON
 
@@ -19,11 +29,14 @@ function SpringUtils.animating(spring, epsilon)
 	if type(target) == "number" then
 		animating = math.abs(spring.Position - spring.Target) > epsilon
 			or math.abs(spring.Velocity) > epsilon
-	elseif typeof(target) == "Vector3" or LinearValue.isLinear(target) then
-		animating = (spring.Position - spring.Target).magnitude > epsilon
-			or spring.Velocity.magnitude > epsilon
 	else
-		error("Unknown type")
+		local rbxtype = typeof(target)
+		if rbxtype == "Vector3" or rbxtype == "Vector2" or LinearValue.isLinear(target) then
+			animating = (spring.Position - spring.Target).magnitude > epsilon
+				or spring.Velocity.magnitude > epsilon
+		else
+			error("Unknown type")
+		end
 	end
 
 	if animating then
@@ -34,7 +47,14 @@ function SpringUtils.animating(spring, epsilon)
 	end
 end
 
--- Add to spring position to adjust for velocity of target. May have to set clock to time().
+--[=[
+	Add to spring position to adjust for velocity of target. May have to set clock to time().
+
+	@param velocity T
+	@param dampen number
+	@param speed number
+	@return T
+]=]
 function SpringUtils.getVelocityAdjustment(velocity, dampen, speed)
 	assert(velocity, "Bad velocity")
 	assert(dampen, "Bad dampen")
@@ -43,14 +63,31 @@ function SpringUtils.getVelocityAdjustment(velocity, dampen, speed)
 	return velocity*(2*dampen/speed)
 end
 
+--[=[
+	Converts an arbitrary value to a LinearValue if Roblox has not defined this value
+	for multiplication and addition.
+
+	@param value T
+	@return LinearValue<T> | T
+]=]
 function SpringUtils.toLinearIfNeeded(value)
 	if typeof(value) == "Color3" then
 		return LinearValue.new(Color3.new, {value.r, value.g, value.b})
+	elseif typeof(value) == "UDim2" then
+		return LinearValue.new(UDim2.new, {value.x.scale, value.x.offset, value.y.scale, value.y.offset})
+	elseif typeof(value) == "UDim" then
+		return LinearValue.new(UDim.new, {value.scale, value.offset})
 	else
 		return value
 	end
 end
 
+--[=[
+	Extracts the base value out of a packed linear value if needed.
+
+	@param value LinearValue<T> | any
+	@return T | any
+]=]
 function SpringUtils.fromLinearIfNeeded(value)
 	if LinearValue.isLinear(value) then
 		return value:ToBaseValue()