In animation, tweening is the process of generating intermediate frames between two key points in a sequence. When designing a user interface, you can use tweening to transition a GuiObject smoothly from one state to another, such as:
- Smoothly increasing the size of a button when a user selects it.
- Sliding UI menus in and out from the screen edges.
- Gradually animating a health bar between two widths when a user receives a health boost.
Single-Property Tweens
Position
To tween the position of a GuiObject:
- Set the AnchorPoint for the object.
- Pass a TweenInfo and the target position to TweenService:Create().
- Play the tween with Tween:Play().
The following code snippet moves an ImageLabel within a ScreenGui to the exact center of the screen:
UI Tween - Position
local TweenService = game:GetService("TweenService")local Players = game:GetService("Players")local PlayerGui = Players.LocalPlayer:WaitForChild("PlayerGui")local ScreenGui = PlayerGui:WaitForChild("ScreenGui")local object = ScreenGui:WaitForChild("ImageLabel")object.AnchorPoint = Vector2.new(0.5, 0.5)local targetPosition = UDim2.new(0.5, 0, 0.5, 0)local tweenInfo = TweenInfo.new(2)local tween = TweenService:Create(object, tweenInfo, {Position = targetPosition})tween:Play()
Size
To tween the size of a GuiObject:
- Attach a UIAspectRatioConstraint to the object to maintain its designed aspect ratio when tweening.
- Pass a TweenInfo and the target size to TweenService:Create().
- Play the tween with Tween:Play().
The following code snippet scales an ImageLabel within a ScreenGui to 40% of the screen width or height (whichever is smaller) from the object's center anchor point:
UI Tween - Size
local TweenService = game:GetService("TweenService")local Players = game:GetService("Players")local PlayerGui = Players.LocalPlayer:WaitForChild("PlayerGui")local ScreenGui = PlayerGui:WaitForChild("ScreenGui")local object = ScreenGui:WaitForChild("ImageLabel")object.AnchorPoint = Vector2.new(0.5, 0.5)local aspectRatioConstraint = Instance.new("UIAspectRatioConstraint")aspectRatioConstraint.Parent = objectlocal targetSize = UDim2.new(0.4, 0, 0.4, 0)local tweenInfo = TweenInfo.new(2)local tween = TweenService:Create(object, tweenInfo, {Size = targetSize})tween:Play()
Rotation
To tween the rotation of a GuiObject:
- Set the AnchorPoint for the object to rotate around.
- Determine the target Rotation for the object.
- Pass a TweenInfo and the target rotation to TweenService:Create().
- Play the tween with Tween:Play().
UI Tween - Size
local TweenService = game:GetService("TweenService")local Players = game:GetService("Players")local PlayerGui = Players.LocalPlayer:WaitForChild("PlayerGui")local ScreenGui = PlayerGui:WaitForChild("ScreenGui")local object = ScreenGui:WaitForChild("ImageLabel")object.AnchorPoint = Vector2.new(0.5, 0.5)local targetRotation = 45local tweenInfo = TweenInfo.new(2)local tween = TweenService:Create(object, tweenInfo, {Rotation = targetRotation})tween:Play()
Transparency
Multiple properties control UI transparency, depending on the object type. You can tween each of these properties individually or combined through a multi-property tween. Alternatively, you can tween an object's overall transparency by placing it inside a CanvasGroup and tweening the group's GroupTransparency.
UI Tween - Image Transparency
local TweenService = game:GetService("TweenService")local Players = game:GetService("Players")local PlayerGui = Players.LocalPlayer:WaitForChild("PlayerGui")local ScreenGui = PlayerGui:WaitForChild("ScreenGui")local object = ScreenGui:WaitForChild("ImageLabel")local targetTransparency = 0.8local tweenInfo = TweenInfo.new(2)local tween = TweenService:Create(object, tweenInfo, {ImageTransparency = targetTransparency})tween:Play()
UI Tween - Canvas Group Transparency
local TweenService = game:GetService("TweenService")local Players = game:GetService("Players")local PlayerGui = Players.LocalPlayer:WaitForChild("PlayerGui")local ScreenGui = PlayerGui:WaitForChild("ScreenGui")local canvasGroup = ScreenGui:WaitForChild("CanvasGroup")local targetTransparency = 0.8local tweenInfo = TweenInfo.new(2)local tween = TweenService:Create(canvasGroup, tweenInfo, {GroupTransparency = targetTransparency})tween:Play()
Color
Multiple properties control UI color, depending on the object type. You can tween each of these properties individually or combined through a multi-property tween. Alternatively, you can tween an object's overall color by placing it inside a CanvasGroup and tweening the group's GroupColor3.
UI Tween - Image Color
local TweenService = game:GetService("TweenService")local Players = game:GetService("Players")local PlayerGui = Players.LocalPlayer:WaitForChild("PlayerGui")local ScreenGui = PlayerGui:WaitForChild("ScreenGui")local object = ScreenGui:WaitForChild("ImageLabel")local targetColor = Color3.fromRGB(255, 0, 0)local tweenInfo = TweenInfo.new(2)local tween = TweenService:Create(object, tweenInfo, {ImageColor3 = targetColor})tween:Play()
UI Tween - Canvas Group Color
local TweenService = game:GetService("TweenService")local Players = game:GetService("Players")local PlayerGui = Players.LocalPlayer:WaitForChild("PlayerGui")local ScreenGui = PlayerGui:WaitForChild("ScreenGui")local canvasGroup = ScreenGui:WaitForChild("CanvasGroup")local targetColor = Color3.fromRGB(255, 0, 0)local tweenInfo = TweenInfo.new(2)local tween = TweenService:Create(canvasGroup, tweenInfo, {GroupColor3 = targetColor})tween:Play()
Stroke
Multiple properties control UI borders, depending on the object type.
Alternatively, you can apply a UIStroke child and tween its thickness, color, and/or transparency.
UI Object | Properties |
---|---|
UIStroke | Color, Thickness, Transparency |
UI Tween - UIStroke Color & Thickness
local TweenService = game:GetService("TweenService")local Players = game:GetService("Players")local PlayerGui = Players.LocalPlayer:WaitForChild("PlayerGui")local ScreenGui = PlayerGui:WaitForChild("ScreenGui")local object = ScreenGui:WaitForChild("TextLabel")local stroke = Instance.new("UIStroke")stroke.Color = Color3.fromRGB(255, 255, 255)stroke.Thickness = 5stroke.Parent = objectlocal targetColor = Color3.fromRGB(255, 0, 0)local targetThickness = 10local tweenInfo = TweenInfo.new(2)local tween = TweenService:Create(stroke, tweenInfo, {Color = targetColor, Thickness = targetThickness})tween:Play()
Multi-Property Tweens
You can combine any of the single-property tweens into more complex tweens by passing multiple target properties to TweenService:Create(), for example position + rotation or size + transparency.
UI Tween - Position & Rotation
local TweenService = game:GetService("TweenService")local Players = game:GetService("Players")local PlayerGui = Players.LocalPlayer:WaitForChild("PlayerGui")local ScreenGui = PlayerGui:WaitForChild("ScreenGui")local object = ScreenGui:WaitForChild("ImageLabel")object.AnchorPoint = Vector2.new(0.5, 0.5)local targetPosition = UDim2.new(0.5, 0, 0.5, 0)local targetRotation = 45local tweenInfo = TweenInfo.new(2)local tween = TweenService:Create(object, tweenInfo, {Position = targetPosition, Rotation = targetRotation})tween:Play()
UI Tween - Size & Transparency
local TweenService = game:GetService("TweenService")local Players = game:GetService("Players")local PlayerGui = Players.LocalPlayer:WaitForChild("PlayerGui")local ScreenGui = PlayerGui:WaitForChild("ScreenGui")local object = ScreenGui:WaitForChild("ImageLabel")object.AnchorPoint = Vector2.new(0.5, 0.5)local aspectRatioConstraint = Instance.new("UIAspectRatioConstraint")aspectRatioConstraint.Parent = objectlocal targetSize = UDim2.new(0.4, 0, 0.4, 0)local targetTransparency = 0.8local tweenInfo = TweenInfo.new(2)local tween = TweenService:Create(object, tweenInfo, {Size = targetSize, ImageTransparency = targetTransparency})tween:Play()
Tween Sequences
You can chain UI animations to occur one after another by playing subsequent tweens upon the previous tween's Completed event. For example, the following script moves an object to the center of the screen, then rotates it by 45°.
UI Tween Sequence
local TweenService = game:GetService("TweenService")
local Players = game:GetService("Players")
local PlayerGui = Players.LocalPlayer:WaitForChild("PlayerGui")
local ScreenGui = PlayerGui:WaitForChild("ScreenGui")
local object = ScreenGui:WaitForChild("ImageLabel")
object.AnchorPoint = Vector2.new(0.5, 0.5)
local targetPosition = UDim2.new(0.5, 0, 0.5, 0)
local targetRotation = 45
local tweenInfo = TweenInfo.new(2)
local positionTween = TweenService:Create(object, tweenInfo, {Position = targetPosition})
local rotationTween = TweenService:Create(object, tweenInfo, {Rotation = targetRotation})
-- Initially play position tween
positionTween:Play()
-- Play rotation tween upon completion of position tween
positionTween.Completed:Connect(function()
rotationTween:Play()
end)
Easing Options
Using the easing options of TweenInfo, you can control the easing style and direction of UI animations.
Style
Enum.EasingStyle sets the rate of interpolation from start to end. By default, easing style is set to Enum.EasingStyle.Quad.
Style | Description |
---|---|
Linear | Moves at a constant speed. |
Sine | Speed is determined by a sine wave for a gentle easing motion. |
Quad | Similar to Sine but with a slightly sharper curve based on quadratic interpolation. |
Cubic | Similar to Quad but with a slightly sharper curve based on cubic interpolation. |
Quart | Similar to Cubic but with an even sharper curve based on quartic interpolation. |
Quint | Similar to Quart but with an even sharper curve based on quintic interpolation. |
Exponential | The sharpest curve based on exponential interpolation. |
Circular | Follows a circular arc, such that acceleration is more sudden and deceleration more gradual versus Quint or Exponential. |
Back | Slightly overshoots the target, then backs into place. |
Bounce | Bounces backwards multiple times after reaching the target, before eventually settling. |
Elastic | Moves as if attached to a rubber band, overshooting the target several times. |
Easing Style - Cubic
local tweenInfo = TweenInfo.new(2, Enum.EasingStyle.Cubic)local tween = TweenService:Create(object, tweenInfo, {Rotation = 45})
Direction
Enum.EasingDirection defines how the easing style interpolation applies to an object, with a default of Out. Note that a tween with Linear easing style is not affected, as linear interpolation is constant from start to end.
Direction | Description |
---|---|
In | The easing style applies in a forward direction. |
Out | The easing style applies in a reverse direction. |
InOut | The easing style applies forward for the first half and in reverse for the second half. |
Easing Direction - InOut
local tweenInfo = TweenInfo.new(2, Enum.EasingStyle.Cubic, Enum.EasingDirection.InOut)local tween = TweenService:Create(object, tweenInfo, {Rotation = 45})
Animating Text
You can easily enhance text-based UI, such as cutscene banners, player instructions, and prompts, with animated effects.
Typewriter Effect
The "typewriter" effect is ideal for TextLabels that tell a story, output NPC conversations, etc.
Create a new ModuleScript within ReplicatedStorage.
Rename the new script AnimateUI.
Paste the following code into the script:
ModuleScript - AnimateUIlocal LocalizationService = game:GetService("LocalizationService")local Players = game:GetService("Players")local SOURCE_LOCALE = "en"local translator = nillocal AnimateUI = {}function AnimateUI.loadTranslator()pcall(function()translator = LocalizationService:GetTranslatorForPlayerAsync(Players.LocalPlayer)end)if not translator thenpcall(function()translator = LocalizationService:GetTranslatorForLocaleAsync(SOURCE_LOCALE)end)endendfunction AnimateUI.typeWrite(guiObject, text, delayBetweenChars)guiObject.Visible = trueguiObject.AutoLocalize = falselocal displayText = text-- Translate text if possibleif translator thendisplayText = translator:Translate(guiObject, text)end-- Replace line break tags so grapheme loop will not miss those charactersdisplayText = displayText:gsub("<br%s*/>", "\n")-- Remove RichText tags since char-by-char animation will break the tagsdisplayText = displayText:gsub("<[^<>]->", "")-- Set translated/modified text on parentguiObject.Text = displayTextlocal index = 0for first, last in utf8.graphemes(displayText) doindex += 1guiObject.MaxVisibleGraphemes = indextask.wait(delayBetweenChars)endendreturn AnimateUICreate a TextLabel in a suitable location, such as within a ScreenGui parented to StarterGui.
Insert a new LocalScript as a direct child of the label and paste in the following code. Note that each message is output by calling AnimateUI.typeWrite() with parameters for the parent object, the string to output, and the delay between characters.
LocalScriptlocal ReplicatedStorage = game:GetService("ReplicatedStorage")local AnimateUI = require(ReplicatedStorage:WaitForChild("AnimateUI"))local label = script.Parent-- Load translator if game is localized--AnimateUI.loadTranslator()local message1 = [[Beyond this door is the<br /><font size="46" color="rgb(255,50,25)">Great Zorgoth...</font> <font size="40">🗡</font>]]AnimateUI.typeWrite(label, message1, 0.05)task.wait(1)local message2 = [[...who rules this dungeon <font color="rgb(255,200,50)">unchallenged!</font> <font size="30">😈</font>]]AnimateUI.typeWrite(label, message2, 0.05)