Features
TweenGroups: "Group multiple Tweens in an object and call their respective methods"
Preloading: "Preload tweens with any fps to play them or get the interpolating values"
GC: "Tweens are stored on a table for use, as long as the Instance or Tween are referenced"
Signals: "GetPropertyChangedSignal() and Completed are supported"
Attributes: "Cancel or block tweens when a specified attribute is set"
AutoWait: "Auto-yield for groups when a Tween method is called until every Tween is iterated"
Alpha: "Play with a given alpha or set the instance to that point"
Easy to use: "Can replace regular Tweens easily"
Source Code
Find it in the asset store: Download
GitHub: GitHub - Dungoler/SharpTween: Extended Tweening Library
Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted.
This library aims to extend the functionality of the TweenService with features such as groups, attribute-based observation (canceling/blocking playback), preloading, alpha operations such as setting an Instance to an alpha, etc., while also being easy to implement in existing code.
Benchmarks
All benchmarks have been realized with the following specs:
- GPU: AMD Radeon RX 6600
- CPU: AMD Ryzen 5 5600G
Some method times may not be easily read, so keep in mind that the time shown is the â50%â value found on the method info.
Playback
Preloading with a framerate of 60
10,000 iterations
1,250 iterations
As you can see in the benchmarks above, SharpTweenâs Create and TweenServiceâs are identical in performance. Preloading may be a heavy task in terms of resources; however, it only needs to be done once (unless you explicitly override the old preloaded values).
CustomTween creation
10,000 iterations
1,250
Extended functionality comes at the cost of more memory consumption, hence the longer creation time on SharpTweenâs behalf.
SharpTween
Custom types:
- CustomTweenGroup
- CustomTween
Obtained via the Init constructor of the module. It consists of three methods:
| Method Name | Parameters | Description |
|---|---|---|
| Create | instance: Instance, twinfo: TweenInfo, propertyTable: {[string]: any} | This constructor creates a new CustomTween |
| GetValue | number | Returns a new alpha value for interpolating using the given alpha value, Enum.EasingStyle, and Enum.EasingDirection. The provided alpha value will be clamped between 0 and 1. |
| SetDefaultGroup | CustomTweenGroup | Sets the default group that CustomTweens will be assigned to when created. |
And finally, two properties:
| Property Name | Type | Description |
|---|---|---|
| new | () â CustomTweenGroup | Constructor that creates a new CustomTween group. |
| NewCustomTween | LemonSignal.Signal<CustomTween> | Signal fired when a CustomTween is created. |
CustomTweens
A CustomTween refers to those objects created with SharpTween:Create(...).
Being the most characteristical object provided by this module, they are loaded with useful methods. Here is a list of all the unique ones:
| Method Name | Parameters | Description |
|---|---|---|
| PlayPreloaded | newProgress: number?, goalProgress: number? | Plays from preloaded frames. Play() and PlayPreloaded() have no effect until the tween is stopped or canceled. Preload() should be called before executing. No tween object is used. |
| Preload | fps: number?, overrides: boolean? | Builds frames using the current instance values (not the initial stored properties). Preloading with a different fps parameter replaces the old one. |
| SetInstanceToAlpha | alpha: number | Immediately set the instance properties to a specific alpha using preloaded frames. |
| AdjustTime | newTime: number | Replace the current Tween with a copy using a different Time. If currently playing, the new Tween will start playing. |
| AdjustDelayTime | delayTime: number | Replace the current Tween with a copy using a different DelayTime. If currently playing, the new Tween will start playing after the given delay. |
| GetReverse | Returns a new CustomTween with initial properties and goals reversed (end->start) Note: this does not fully âresetâ the instance; it only provides a tween that animates back over the set of tweening properties. | |
| GetAlpha | Returns two values: â Alpha: the eased alpha of the Tween obtained with the TweenInfo easing parameters.â Progress: the progress of the Tween (0..1).This does not reflect PlayPreloaded() progress (PreloadedAlpha property does). |
|
| SetAlpha | alpha: number | Adjusts the Tweenâs time such that the given alpha corresponds to the new starting point. The alpha is always relative to the original TweenInfo.Time.The CustomTween has to be preloaded after the function is called to be affected. alpha is normalized (0..1). |
| RandomizeProperties | percentage: number | Randomizes the Tweening properties with the given percentage. The percentage is always relative to the default goals. |
| AdjustMultiplier | newMultiplier: number? | Sets the Tweening Speed Multiplier to the given number, relative to the original TweenInfo.Time. The multiplier is persistent, and will keep multiplying even when calling CustomTween methods that modify the Tweening time such as AdjustTime() or SetAlpha(). Default multiplier is 1 |
| GetPropertyTable | Returns the passed property table when creating the CustomTween. |
CustomTweens also posess some regular Tween methods, events & properties. The included are:
- Methods:
- Play
- Pause
- Cancel
- Clone
- GetPropertyChangedSignal
- Events:
- Completed
- Properties:
- PlaybackState
- Instance
- TweenInfo
Non-shared methods
These methods are not inherited by CustomTweenGroups as it would make room for ambigous code. Here is a list of all of them:
| Method Name | Parameters | Description |
|---|---|---|
| GetPropertyChangedSignal | property: string | Works just like the regular GetPropertyChangedSignal(). Returns a new signal that fires when the given property changes. |
| GetProgressSignal | progress: number | This method returns a new signal that fires when the progress is reached. Utilized for both preloaded and regular playback. progress is normalized (0..1). |
| StartObservingAttribute | string | |
| StopObservingAttribute | string |
Properties
| Property Name | Type | Description |
|---|---|---|
| _createdTween | Tween | The internal Tween used by the CustomTween. |
| observerSignals | {[string]: Trove.Trove} | The internal Troves used for each observation. |
| observedAttributes | {string} | |
| newAttributeSignal | LemonSignal.Signal<string> | Signal that is fired when an attribute starts being observated. |
| frames | number | Total amount of frames stored for preloaded playback. |
| fps | number | Fps used to get the last frames. |
| isPreloadedRunning | boolean | |
| PreloadedAlpha | number | Alpha of the preloaded playback. |
| PreloadedProgress | number | Preloaded progress ranging from 0 to 1 |
| PreloadedPlayed | LemonSignal.Signal | Signal that is fired when preloaded playback is played. |
| InitialTweenInfo | TweenInfo | TweenInfo that is given at the CustomTweenâs creation. Should not be modified directly. |
| Bezier | (alpha: number) â ()? | Custom bezier used for preloading. Overrides the CustomTweenâs TweenInfo.EasingStyle and TweenInfo.EasingDirection. |
CustomTweenGroups
A CustomTweenGroup or CustomTween group is an object that makes handling and implementing CustomTweens a breeze. It consists of five convenient methods:
| Method Name | Parameters | Description |
|---|---|---|
| Add | CustomTween | Adds a CustomTween to the group. |
| Remove | CustomTween | Remove a CustomTween from the group if it exists in it. |
| WaitTweens | Wait for all CustomTweens to execute the ongoing function requested by the group (if any). | |
| NewObserver | attribute: string | Starts an observer on every CustomTween member of the group. |
| RemoveObserver | attribute: string | Removes an observer on every CustomTween member of the group, if observed. |
Properties
| Property Name | Type | Description |
|---|---|---|
| AutoWait | boolean | Determines if yielding occurs. |
| isIterating | boolean | Indicates whether an iteration is ongoing. |
| observedAttributes | {string} | List of attributes the group is observing. |
Groups can request some methods upon every CustomTween member. These methods are CustomTween methods that will be called on the members if the group calls them. For example, calling Play() on the group calls Play() on every member. The methods are the following; detailed info can be found in the CustomTween documentation:
- PlayPreloaded
- Preload
- AdjustTime
- GetReverse
- GetAlpha
- SetAlpha
- RandomizeProperties
- AdjustMultiplier
- AdjustTime
- Play
- Pause
- Cancel
- Clone
By default, requesting a method does not yield the current thread to avoid interrupting scripts that shouldnât be interrupted. Thatâs where WaitTweens and AutoWait come in.
-
WaitTweens (method) is very useful if you want to make sure every method you call on the group is replicated upon every CustomTween member. It yields the current thread until every member returns the value obtained with the method requested by the group.
-
AutoWait (property) determines if yielding should occur when any method is requested.
Examples
Creating a CustomTween
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local SharpTween = require(ReplicatedStorage.SharpTween).Init()
local Frame = Instance.new("Frame")
local twinfo = TweenInfo.new(1)
local goal = {Position = UDim2.fromScale(1, 1)}
local newTween = SharpTween:Create(Frame, twinfo, goal)
Playing a CustomTween
newTween:Play()
-- or --
newTween:Preload()
newTween:PlayPreloaded()
task.wait(1)
-- will work, no need to preload twice
newTween:PlayPreloaded(0.1, 0.5)
-- the tweening will start at 0.1
-- and stop when the progress hits 0.5
Calling PlayPreloaded() when the CustomTween is already playing has no effect, just like a regular Tween. Setting a goalProgress as seen in the example (0.5) will fire the Completed Event after the progress is hit.
Preloading with a specific framerate
newTween:Preload(120)
newTween:PlayPreloaded()
task.wait(1)
newTween:Preload(75, true) -- overwrite preloaded frames
newTween:PlayPreloaded()
Setting the instance to a given point in the interpolation
local Frame = Instance.new("Frame")
local twinfo = TweenInfo.new(1, Enum.EasingStyle.Linear, Enum.EasingDirection.InOut)
local goal = {Position = UDim2.fromScale(1, 1)}
local newTween = SharpTween:Create(Frame, twinfo, goal)
newTween:Preload()
print(Frame.Position)
-- output: {0, 0}, {0, 0}
newTween:SetInstanceToAlpha(0.5)
print(Frame.Position)
-- output: {0.5, 0}, {0.5, 0}
Preloading is optional, if not preloaded, it will do it automatically. However, it is recommended to avoid lag.
Randomizing properties
newTween:SetInstanceToAlpha(1)
print(Frame.Position)
-- output: {1, 0}, {1, 0}
newTween:RandomizeProperties(10) -- randomize the properties up to a 10%
newTween:Preload(nil, true) -- Default fps, overwrite preloaded frames
newTween:SetInstanceToAlpha(1)
print(newTween)
-- output in this case: {1.01728737, 0}, {1.05772877, 0}
Play reverse
local reverseTween = newTween:GetReverse()
newTween:Play()
task.wait(1)
print(Frame.Position)
-- output: {1, 0}, {1, 0}
reverseTween:Play()
task.wait(1)
print(Frame.Position)
-- output: {0, 0}, {0, 0}
Play preloaded reverse
newTween:Play()
task.wait(1)
print(Frame.Position)
-- output: {1, 0}, {1, 0}
-- update the initial properties as they're the goal for the
-- reverse, if not, it would remain in {0, 0}, {0, 0} (The position where it was created).
newTween:UpdateInitialProperties()
local reverseTween = newTween:GetReverse()
reverseTween:Preload()
reverseTween:PlayPreloaded()
task.wait(1)
print(Frame.Position)
-- output: {0, 0}, {0, 0}
SetAlpha() usage example
-- Goal: Start the tween from a given alpha
local ALPHA = 0.8
newTween:SetInstanceToAlpha(ALPHA) -- sets the instance to that point
newTween:SetAlpha(ALPHA) -- adjusts the time with the given alpha
newTween:Play()
SetDefaultGroup() usage example
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local SharpTween = require(ReplicatedStorage.SharpTween).Init()
local Frame = Instance.new("Frame")
local TextLabel = Instance.new("TextLabel")
local twinfo = TweenInfo.new(1)
local Group = SharpTween.new()
SharpTween:SetDefaultGroup(group)
Group:NewObserver("Blue")
local newTween1 = SharpTween:Create(Frame, twinfo, {Position = UDim2.fromScale(1, 1)})
local newTween2 = SharpTween:Create(TextLabel, twinfo, {Size = UDim2.fromScale(0, 1)})
-- both CustomTweens will be added to the group automatically and will
-- listen to the attribute "Blue"
SharpTween:SetDefaultGroup(nil)
local newTween3 = SharpTween:Create(TextLabel, twinfo, {Size = UDim2.fromScale(0, 1)})
-- will not be added to the group automatically.
[ADDED] AdjustMultiplier() usage example
local CustomTween = SharpTween:Create(Frame2, twinfo, {Position = UDim2.fromScale(0.9, Frame2.Position.Y.Scale)})
CustomTween:AdjustMultiplier(2)
CustomTween:Play()
The Speed Multiplier can be changed while the CustomTween is playing! Works best in pair with PlayPreloaded(), as the easing isnât reset.
[ADDED] Bezier curves usage example
local CustomTween = SharpTween:Create(Frame2, twinfo, {Position = UDim2.fromScale(0.9, Frame2.Position.Y.Scale)})
-- cuadratic curve in this case
CustomTween.Bezier = SharpTween.NewBezier({
{x=0, y=0},
{x=0.5, y=1},
{x=1, y=1},
})
CustomTween:Preload(120)
-- PlayPreloaded() as inserting bezier curves in regular Tweens is not possible
CustomTween:PlayPreloaded()
No limit on the amount of elements in the table!
AutoWait property usage example
Group.AutoWait = true
Group:Play() -- Yields the script until Play() is called upon every group member
Group:Cancel() -- should not cause any issue. Yields too
Without AutoWait, the function WaitTweens() should be called after Play() to avoid issues.
[2.0.0+] Progress signal usage example
local Frame = Instance.new("Frame")
local twinfo = TweenInfo.new(1, Enum.EasingStyle.Cubic, Enum.EasingDirection.Out)
local goal = {Position = UDim2.fromScale(1, 1)}
local newTween = SharpTween:Create(Frame, twinfo, goal)
newwTween:Preload()
newTween:GetProgressSignal(0.4):Connect(function()
print(newTween:GetAlpha())
print(newTween.PreloadedAlpha)
print(newTween.PreloadedProgress)
end)
newTween:Play()
--[[ output:
~0.784, ~0.4,
0
0
]]
newTween.Completed:Wait()
newTween:PlayPreloaded()
--[[ output:
1, 1
~0.784
0.4
]]
Update registry
1.0.1
- Fixed a minor bug where changing the Instance property of a CustomTween would not have an effect.
1.1.0
-
Fixed preloaded playback being sped up or slowed down when the preloaded frame rate didnât match the userâs frames.
-
Setting an observed attribute to a CustomTween now cancels instead of just blocking.
-
Added the CustomTween property:
PreloadedProgress number 0
- Changed the GetAlpha CustomTween method to return two values:
- PreloadedAlpha
- PreloadedProgress
-
PreloadedAlpha now reflects the actual alpha rather than the progress.
-
Added a CustomTween method:
GetPropertyTable(self: self) {[string]: any}
"Gets the property goals table"
1.2.0
- Added Bezier curves functionality as suggested by @romefalls
1.3.0
-
Added Speed Multiplier functionality as suggested by @thekingmarz
-
Fixed a bug where a CustomTween could not be played right after the Completed Event of another CustomTween due to race conditions.
-
Slightly changed the SetInstanceToAlpha function to not accept nil as the alpha parameter and convert it to 0.
-
PlayPreloaded() alpha parameter renamed to newProgress
-
Added a goalProgress parameter to the PlayPreloaded function, which determines the point at which the tweening will end.
1.3.1
- Fixed an issue where some CustomTweenGroup methods would not pass self to the âStartObservingAttributeâ CustomTween method.
1.4.0
- Fixed an issue where the Completed event would not pass the Enum.PlaybackState parameter
- Added the GetValue method from TweenService
2.0.0
- PlayPreloaded() playback now works correctly for preloaded frames under the userâs frame rate.
- Added a GetProgressSignal method for CustomTweens.
- Renamed the isParsing CustomTweenGroup property to isIterating.
