Tween

Overview

Tween is used to smoothly and naturally change the properties of an object. By using Tween, various properties such as the object’s position, rotation, and size can be animated, adding immersive and rich visual effects to the game.

Features

• Tweens excel in both code simplicity and performance, helping to easily implement various effects.

• Tweens support various Easing styles, providing smooth and natural animations.

• Tweens are processed internally in an efficient manner, and their performance overhead is lower compared to frame-by-frame updates.

• Tweens automatically terminate once completed, and subsequent tasks can be easily handled in the Completed event.

Components

• TweenService: The service used to create and manage tweens.

• TweenInfo: An object that defines how the tween behaves, including settings for duration, direction, and repeat count.

• TweenGoals: Defines the property values to be changed by the tween.

How to Use

1. Creating a Tween

You can define the behavior of a tween animation, such as its duration, easing style, and repeat count, using the TweenInfo.new function.

The properties to which the animation will be applied, such as the object’s position or rotation, are set in the TweenGoals table.

local TweenService = game:GetService("TweenService")
local Part = script.Parent

-- Setting Tween information
local TweenInfoData = TweenInfo.new(
    2,                        -- Easing duration (seconds)
    Enum.EasingStyle.Linear,  -- Easing style
    Enum.EasingDirection.Out, -- Easing direction
    0,                        -- Number of repetitions (-1 for infinite) 
    false,                    -- Whether to reverse
    0                         -- Wait time
)

-- Properties to be changed with the tween
local TweenGoals = 
{
    Position = Vector3.new(-400, 50, -350)
}

local Tween = TweenService:Create(Part, TweenInfoData, TweenGoals)

2. Setting Properties to Be Changed With the Tween

The functionality of the tween varies depending on the properties set in the TweenGoals.

DataType	Usage Example
CFrame	CFrame
Vector3	Position, Orientation, Size
Color3	Color
number	Transparency
bool	CanCollide
UDim2	Position, Size

3. Running the Tween

You can create a tween by passing the target object, the pre-configured TweenInfo, and TweenGoals to the TweenService:Create function. Once the tween is created, it can be executed using the Play function.

local TweenService = game:GetService("TweenService")
local Part = script.Parent

-- Setting Tween information
local TweenInfoData = TweenInfo.new(
    2,                        -- Easing duration (seconds)
    Enum.EasingStyle.Linear,  -- Easing style
    Enum.EasingDirection.Out, -- Easing direction
    0,                        -- Number of repetitions (-1 for infinite) 
    false,                    -- Whether to reverse
    0                         -- Wait time
)

-- Properties to be changed with the tween
local TweenGoals = 
{
    Position = Vector3.new(-400, 50, -350)
}

local Tween = TweenService:Create(Part, TweenInfoData, TweenGoals)

Tween:Play()

4. Controlling the Tween Execution

A tween that is running can be paused using the Pause function.

...
Tween:Pause() -- Pause
wait(2)​
Tween:Play()  -- Resume

The Cancel function can be used to cancel a running tween.

...
Tween:Cancel()

5. Handling Events After the Tween Ends

The Completed event can be used to handle actions after a tween finishes executing.

local TweenService = game:GetService("TweenService")
local Part = script.Parent

-- Setting Tween information
local TweenInfoData = TweenInfo.new(
    2,                        -- Easing duration (seconds)
    Enum.EasingStyle.Linear,  -- Easing style
    Enum.EasingDirection.Out, -- Easing direction
    0,                        -- Number of repetitions (-1 for infinite) 
    false,                    -- Whether to reverse
    0                         -- Wait time
)

-- Properties to be changed with the tween
local TweenGoals = 
{
    Position = Vector3.new(-400, 50, -350)
}

local Tween = TweenService:Create(Part, TweenInfoData, TweenGoals)

local function OnCompleted(playbackState)
    print("Tween Complete!", playbackState)
end
Tween.Completed:Connect(OnCompleted)

Tween:Play()

EasingStyle

EasingDirection