Skip to main content

Springer

Springer is a class that allows you to animate values using a spring physics model. The values you can animate are numbers, Vector2, and Vector3. You can set the target value, frequency, and damping to customize the spring. You can also listen to the onStep SpringerSignal to get the current value of the spring. When the spring reaches the target value, the onComplete SpringerSignal will be fired.

Here is an example of how to use the Springer class to animate a number from 0 to 1:

local springer = Springer.new(0, 5, .2)
springer:SetTarget(1, 10, .8)
springer.onStep:Connect(function(value)
	print(value)
end)
springer.onComplete:Connect(function()
	print("Springer completed")
end)

Here is an example of how to use the Springer class to animate a Vector3 from (0, 10, 0) to (5, 15, 8) in 1 second:

local springer = Springer.new(Vector3.new(0, 10, 0), 5, .2)
springer:SetTarget(Vector3.new(5, 15, 8), 10, .8)
springer.onStep:Connect(function(value)
	print(value)
end)
springer.onComplete:Connect(function()
	print("Springer completed")
end)

The springer class when begin animating immediately on the next frame if you pass the initial goal value. Here is an example of how to use the Springer class to animate a number from 0 to 1 in 1 second immediately: 

local springer = Springer.new(0, 5, .2, 1)
springer.onStep:Connect(function(value)
	print(value)
end)
NOTE
- When you call the `SetTarget` method, the spring will start animating towards the target value.
- If you set any of the properties directly, the spring animation will override them.
- Setting isActive to false will stop the spring animation.(It will then not call the onComplete signal)
- Setting isActive to true will NOT start the spring animation. You need to call the SetTarget method to start the animation.
- Setting the properties directly will not animate the spring.

Types​

Springer​

</>
interface Springer {
value: number | Vector2 | Vector3--

The current value of the spring.

velocity: number | Vector2 | Vector3--

The current velocity of the spring.

target: number | Vector2 | Vector3--

The target value of the spring.

frequency: number--

The frequency of the spring.

damping: number--

The damping of the spring.

springType: string--

The type of the spring value.

isActive: boolean--

Whether the spring is active or not.

onComplete: SpringerSignal--

The signal that fires when the spring reaches the target value.

onStep: SpringerSignal--

The signal that fires every frame with the current value of the spring.

}

SpringerSignal​

</>
interface SpringerSignal {
new: SpringerSignal--

Creates a new SpringerSignal instance.

Connect: (
self: SpringerSignal,
handler: (...any) → ()
) → Connection--

Connects a function to the signal.

Fire: (
self: SpringerSignal,
...any
) → ()--

Fires the signal with the given arguments.

Wait: (self: SpringerSignal) → ...any--

Yields the current thread until the signal is fired.

}

Properties​

onComplete​

Event
</>
Springer.onComplete: SpringerSignal

Fired when the spring reaches the target value, and is no longer animating.

local springer = Springer.new(0, 5, .2)
springer:SetTarget(1, 10, .8)
springer.onComplete:Connect(function()
	print("Springer completed")
end)

onStep​

Event
</>
Springer.onStep: SpringerSignal

Fired every frame with the current value of the spring. (RenderStepped for client, Heartbeat for server) 

local springer = Springer.new(0, 5, .2)
springer:SetTarget(1, 10, .8)
springer.onStep:Connect(function(value)
	print(value)
end)

Functions​

SetTarget​

</>
Springer.SetTarget(
self: Springer,
newTarget: number | Vector2 | Vector3,--

The target value of the spring.

frequency: number?,--

The frequency of the spring.

damping: number?--

The damping of the spring.

) → Springer--

The Springer instance.

Springer:SetTarget(newTarget: number | Vector2 | Vector3, frequency: number?, damping: number?): Springer

Sets the target value of the spring. The spring will start animating towards the target value. You can also set the frequency and damping of the spring. If the frequency and damping are not provided, the spring will use the default values of 1.

Here is an example of how to use the SetTarget method to bounce between two values every 3 seconds:

local springer = Springer.new(0, 4, .3)
local switch = true
while true do
	task.wait(3)
	if switch then
		springer:SetTarget(1, 6, .5)
	else
		springer:SetTarget(0, 2, .2)
	end
	switch = not switch
end

new​

</>
Springer.new(
initialValue: number | Vector2 | Vector3,
frequency: number?,
damping: number?,
initialGoal: (number | Vector2 | Vector3)?
) → Springer--

The Springer instance.

constructs a new Springer instance.

NOTE
The .new method is a constructor and should be called with a colon from the Springer ModuleScript.
Springer instances themselves, will not contain the .new method.
Show raw api
{
    "functions": [
        {
            "name": "SetTarget",
            "desc": "Springer:SetTarget(newTarget: number | Vector2 | Vector3, frequency: number?, damping: number?): Springer\n\nSets the target value of the spring. The spring will start animating towards the target value.\nYou can also set the frequency and damping of the spring.\nIf the frequency and damping are not provided, the spring will use the default values of 1.\n\nHere is an example of how to use the SetTarget method to bounce between two values every 3 seconds:\n```lua\nlocal springer = Springer.new(0, 4, .3)\nlocal switch = true\nwhile true do\n\ttask.wait(3)\n\tif switch then\n\t\tspringer:SetTarget(1, 6, .5)\n\telse\n\t\tspringer:SetTarget(0, 2, .2)\n\tend\n\tswitch = not switch\nend\n```",
            "params": [
                {
                    "name": "self",
                    "desc": "",
                    "lua_type": "Springer"
                },
                {
                    "name": "newTarget",
                    "desc": "The target value of the spring.",
                    "lua_type": "number | Vector2 | Vector3"
                },
                {
                    "name": "frequency",
                    "desc": "The frequency of the spring.",
                    "lua_type": "number?"
                },
                {
                    "name": "damping",
                    "desc": "The damping of the spring.",
                    "lua_type": "number?"
                }
            ],
            "returns": [
                {
                    "desc": "The Springer instance.",
                    "lua_type": "Springer"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 260,
                "path": "libraries/springer/Source/init.lua"
            }
        },
        {
            "name": "new",
            "desc": "constructs a new Springer instance.\n\n:::note\n\tThe .new method is a constructor and should be called with a colon from the Springer ModuleScript.\n\tSpringer instances themselves, will not contain the .new method.\n:::",
            "params": [
                {
                    "name": "initialValue",
                    "desc": "",
                    "lua_type": "number | Vector2 | Vector3"
                },
                {
                    "name": "frequency",
                    "desc": "",
                    "lua_type": "number?"
                },
                {
                    "name": "damping",
                    "desc": "",
                    "lua_type": "number?"
                },
                {
                    "name": "initialGoal",
                    "desc": "",
                    "lua_type": "(number | Vector2 | Vector3)?\n"
                }
            ],
            "returns": [
                {
                    "desc": "The Springer instance.",
                    "lua_type": "Springer"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 315,
                "path": "libraries/springer/Source/init.lua"
            }
        }
    ],
    "properties": [
        {
            "name": "onComplete",
            "desc": "Fired when the spring reaches the target value, and is no longer animating.\n\n```lua\nlocal springer = Springer.new(0, 5, .2)\nspringer:SetTarget(1, 10, .8)\nspringer.onComplete:Connect(function()\n\tprint(\"Springer completed\")\nend)\n```",
            "lua_type": "SpringerSignal",
            "tags": [
                "Event"
            ],
            "source": {
                "line": 48,
                "path": "libraries/springer/Source/init.lua"
            }
        },
        {
            "name": "onStep",
            "desc": "Fired every frame with the current value of the spring.\n(RenderStepped for client, Heartbeat for server) \n\n```lua\nlocal springer = Springer.new(0, 5, .2)\nspringer:SetTarget(1, 10, .8)\nspringer.onStep:Connect(function(value)\n\tprint(value)\nend)\n```",
            "lua_type": "SpringerSignal",
            "tags": [
                "Event"
            ],
            "source": {
                "line": 65,
                "path": "libraries/springer/Source/init.lua"
            }
        }
    ],
    "types": [
        {
            "name": "Springer",
            "desc": "",
            "fields": [
                {
                    "name": "value",
                    "lua_type": "number | Vector2 | Vector3",
                    "desc": "The current value of the spring."
                },
                {
                    "name": "velocity",
                    "lua_type": "number | Vector2 | Vector3",
                    "desc": "The current velocity of the spring."
                },
                {
                    "name": "target",
                    "lua_type": "number | Vector2 | Vector3",
                    "desc": "The target value of the spring."
                },
                {
                    "name": "frequency",
                    "lua_type": "number",
                    "desc": "The frequency of the spring."
                },
                {
                    "name": "damping",
                    "lua_type": "number",
                    "desc": "The damping of the spring."
                },
                {
                    "name": "springType",
                    "lua_type": "string",
                    "desc": "The type of the spring value."
                },
                {
                    "name": "isActive",
                    "lua_type": "boolean",
                    "desc": "Whether the spring is active or not."
                },
                {
                    "name": "onComplete",
                    "lua_type": "SpringerSignal",
                    "desc": "The signal that fires when the spring reaches the target value."
                },
                {
                    "name": "onStep",
                    "lua_type": "SpringerSignal",
                    "desc": "The signal that fires every frame with the current value of the spring."
                }
            ],
            "source": {
                "line": 23,
                "path": "libraries/springer/Source/init.lua"
            }
        },
        {
            "name": "SpringerSignal",
            "desc": "",
            "fields": [
                {
                    "name": "new",
                    "lua_type": "SpringerSignal",
                    "desc": "Creates a new SpringerSignal instance."
                },
                {
                    "name": "Connect",
                    "lua_type": "(self: SpringerSignal, handler: (...any) -> ()) -> Connection",
                    "desc": "Connects a function to the signal."
                },
                {
                    "name": "Fire",
                    "lua_type": "(self: SpringerSignal, ...any) -> ()",
                    "desc": "Fires the signal with the given arguments."
                },
                {
                    "name": "Wait",
                    "lua_type": "(self: SpringerSignal) -> ...any",
                    "desc": "Yields the current thread until the signal is fired."
                }
            ],
            "source": {
                "line": 32,
                "path": "libraries/springer/Source/init.lua"
            }
        }
    ],
    "name": "Springer",
    "desc": "- Wally Package: [Springer](https://wally.run/package/naxious/springer)\n\nSpringer is a class that allows you to animate values using a spring physics model.\nThe values you can animate are numbers, Vector2, and Vector3.\nYou can set the target value, frequency, and damping to customize the spring.\nYou can also listen to the `onStep` SpringerSignal to get the current value of the spring.\nWhen the spring reaches the target value, the `onComplete` SpringerSignal will be fired.\n\nHere is an example of how to use the Springer class to animate a number from 0 to 1:\n```lua\nlocal springer = Springer.new(0, 5, .2)\nspringer:SetTarget(1, 10, .8)\nspringer.onStep:Connect(function(value)\n\tprint(value)\nend)\nspringer.onComplete:Connect(function()\n\tprint(\"Springer completed\")\nend)\n```\n\nHere is an example of how to use the Springer class to animate a Vector3 from (0, 10, 0) to (5, 15, 8) in 1 second:\n```lua\nlocal springer = Springer.new(Vector3.new(0, 10, 0), 5, .2)\nspringer:SetTarget(Vector3.new(5, 15, 8), 10, .8)\nspringer.onStep:Connect(function(value)\n\tprint(value)\nend)\nspringer.onComplete:Connect(function()\n\tprint(\"Springer completed\")\nend)\n```\n\nThe springer class when begin animating immediately on the next frame if you pass the initial goal value.\nHere is an example of how to use the Springer class to animate a number from 0 to 1 in 1 second immediately:\n```lua\nlocal springer = Springer.new(0, 5, .2, 1)\nspringer.onStep:Connect(function(value)\n\tprint(value)\nend)\n```\n\n:::note\n\t- When you call the `SetTarget` method, the spring will start animating towards the target value.\n\t- If you set any of the properties directly, the spring animation will override them.\n\t- Setting isActive to false will stop the spring animation.(It will then not call the onComplete signal)\n\t- Setting isActive to true will NOT start the spring animation. You need to call the SetTarget method to start the animation.\n\t- Setting the properties directly will not animate the spring.\n:::",
    "source": {
        "line": 138,
        "path": "libraries/springer/Source/init.lua"
    }
}