Tween API
Tween API is an easy-to-use API for ROBLOX that will help you write interpolation code faster and with more style. The API is easy to learn and use.
Insert
Before using the API, you need to insert the ModuleScript into your ROBLOX game. To do so, take the free model of the ModuleScript on ROBLOX and insert it into your game. Put it into the correct service for your needs. For instance, if both the server and clients are using the API, place it under ReplicatedStorage. If only the server is using it, place it under ServerScriptService.
Creating a new Tween object
local Tween = require(game.ReplicatedStorage.Tween)
local tween = Tween.new()
There are also three optional constructor parameters that you can use when creating a new Tween object:
local tween = Tween.new(Number duration, String easingFunction, Function callback)
local tween = Tween.new(0.5, "InOutExpo", function(ratio)
print(ratio)
end)
Methods
VOID tween:Start(Boolean doStep)
Starts a tween process. Note that only 1 process can run at a time. If a process
is already running, an error will be thrown. Use the IsRunning to
check if there is a process running already. If you must run more than one at a
time, then create another tween object. You can use the Clone method
to do this quickly.
VOID tween:Stop()
Stops the current tween process. If no process is running, this method will do nothing.
VOID tween:Run([Function secondaryCallback])
Run through the entire tween process. Internally, this method will invoke Start and
then continue to invoke Step until the elapsed time has hit the duration, or until
the Stop method is invoked. Optionally, a 'secondaryCallback' function can be provided,
which will be called alongside any other current callback function.
Note: This method runs in the background on another thread, meaning that it does not yield. If
you need to know when the process is complete, use the Finish event.
Number ratio, Boolean isFinished tween:Step()
Runs a single step in the tween process. If no process is running, this method will do nothing.
If used explicitly, the Start method must be called first. The only reason you would
need to use this is if you are binding the tween process to your own animation sequence loop. Otherwise,
it is recommended to just use Run, which will call this method internally.
The function returns the result of the easing function at the elapsed time based on the duration.
Boolean tween:IsRunning()
Returns true if a tween process is running, and false otherwise.
Tween tween:Clone()
Returns a clone of the current tween object.
Warning: This also copies over the same callback function. If you don't want it to use the
same callback function, you must explicitly change this using the SetCallback method.
VOID tween:SetDuration(Number duration)
Set the duration (in seconds) for the interpolation.
Number tween:GetDuration()
Get the currently-set duration for the tween object.
VOID tween:SetEasingFunction(String easingFunctionName)
Set the easing function to be used. The easing function must be one of the available functions listed at the bottom of this documentation. This is not case-sensitive.
String tween:GetEasingFunction()
Returns the name of the currently-set easing function.
VOID tween:SetCallback(Function callback)
Set the callback of the tween object. The callback will be fired any time that the Step method is invoked during the duration of a tween process. Note that the Run method invokes Step internally, and therefore uses this callback as well. If the option 'doStep' parameter is used on the Start method, it too will invoke Step and therefore use the callback.
Function tween:GetCallback()
Returns the current callback function.
Events
tween.Begin(Number startTime)
Fires when the Start method has been called. Note that the Run method invokes the Start method internally, and so will also trigger this event.
tween.Begin:connect(function(startTime)
print("Tween process began at " .. startTime)
end)
tween.Begin:wait()tween.Finish(Number endTime)
Fires when the Stop method has been called. Note that the Step method will automatically call Stop if the elapsed time has matched or gone over the duration. Also note that the Run method calls Step internally, therefore will also trigger this event once complete.
tween.Finish:connect(function(endTime)
print("Tween process finished at " .. endTime)
end)
tween.Finish:wait()