TweenService

Show Deprecated
Not Creatable
Service

Tweens are used to interpolate the properties of instances. These can be used to create animations for various Roblox objects. Almost any numeric property can be tweened using TweenService. Note that only specific types of properties can be used with TweenService. The types of properties that can be tweened are:

TweenService's constructor function, TweenService:Create(), takes information about the animation and generates the Tween object which can be used to play the animation. Note that Tweens can animate multiple properties at the same time.

Details on how the interpolation of the tween is to be carried out are given in the tweenInfo parameter of TweenService:Create(). The TweenInfo data type includes a range of properties that can be used to achieve various styles of animation, including reversing and looping Tweens (see examples).

Multiple tweens can be played on the same object at the same time, but they must not be animating the same property. If two tweens attempt to modify the same property, the initial tween will be cancelled and overwritten by the most recent tween (see examples).

Although other methods exist for tweening objects, such as GuiObject:TweenSizeAndPosition(), TweenService allows multiple properties to be modified and for the animation to be paused and cancelled at any point.

Code Samples

Pausing a Tween

1local TweenService = game:GetService("TweenService")
2
3local part = Instance.new("Part")
4part.Position = Vector3.new(0, 10, 0)
5part.Anchored = true
6part.BrickColor = BrickColor.new("Bright green")
7part.Parent = workspace
8
9local goal = {}
10goal.Position = Vector3.new(50, 10, 0)
11
12local tweenInfo = TweenInfo.new(10, Enum.EasingStyle.Linear)
13
14local tween = TweenService:Create(part, tweenInfo, goal)
15
16tween:Play()
17
18task.wait(3)
19part.BrickColor = BrickColor.new("Bright red")
20tween:Pause()
21
22task.wait(2)
23part.BrickColor = BrickColor.new("Bright green")
24tween:Play()
Tween Creation

1local TweenService = game:GetService("TweenService")
2
3local part = Instance.new("Part")
4part.Position = Vector3.new(0, 10, 0)
5part.Color = Color3.new(1, 0, 0)
6part.Anchored = true
7part.Parent = game.Workspace
8
9local goal = {}
10goal.Position = Vector3.new(10, 10, 0)
11goal.Color = Color3.new(0, 1, 0)
12
13local tweenInfo = TweenInfo.new(5)
14
15local tween = TweenService:Create(part, tweenInfo, goal)
16
17tween:Play()
Looping a Tween

1local TweenService = game:GetService("TweenService")
2
3local part = Instance.new("Part")
4part.Position = Vector3.new(0, 10, 0)
5part.Anchored = true
6part.Parent = workspace
7
8local tweenInfo = TweenInfo.new(
9 2, -- Time
10 Enum.EasingStyle.Linear, -- EasingStyle
11 Enum.EasingDirection.Out, -- EasingDirection
12 -1, -- RepeatCount (when less than zero the tween will loop indefinitely)
13 true, -- Reverses (tween will reverse once reaching it's goal)
14 0 -- DelayTime
15)
16
17local tween = TweenService:Create(part, tweenInfo, { Position = Vector3.new(0, 30, 0) })
18
19tween:Play()
20task.wait(10)
21tween:Cancel() -- cancel the animation after 10 seconds
Tween an EnumItem

1local TweenService = game:GetService("TweenService")
2
3local part = Instance.new("Part")
4part.Shape = 0
5part.TopSurface = 0
6part.BottomSurface = 0
7part.Size = Vector3.new(1, 1, 1)
8part.Position = Vector3.new(0, 100, 0)
9part.Parent = workspace
10
11local info = TweenInfo.new(5)
12
13local propertyTable = {
14 Shape = 2,
15}
16
17TweenService:Create(part, info, propertyTable):Play()
Tween Conflict

1local TweenService = game:GetService("TweenService")
2
3local part = Instance.new("Part")
4part.Position = Vector3.new(0, 10, 0)
5part.Anchored = true
6part.Parent = game.Workspace
7
8local tweenInfo = TweenInfo.new(5)
9
10-- create two conflicting tweens (both trying to animate part.Position)
11local tween1 = TweenService:Create(part, tweenInfo, { Position = Vector3.new(0, 10, 20) })
12local tween2 = TweenService:Create(part, tweenInfo, { Position = Vector3.new(0, 30, 0) })
13
14-- listen for their completion status
15tween1.Completed:Connect(function(playbackState)
16 print("tween1: " .. tostring(playbackState))
17end)
18tween2.Completed:Connect(function(playbackState)
19 print("tween2: " .. tostring(playbackState))
20end)
21
22-- try to play them both
23tween1:Play()
24tween2:Play()

Summary

Properties

Events

Methods

Create(instance: Instance, tweenInfo: TweenInfo, propertyTable: table): Tween  

Creates a new Tween given the object whose properties are to be tweened, a TweenInfo and a dictionary of goal property values.

GetValue(alpha: number, easingStyle: EasingStyle, easingDirection: EasingDirection): number  

Calculates a new alpha given an EasingStyle and EasingDirection.

Properties

Events

Methods

Create

The Create function of TweenService creates a new Tween. The function takes three arguments: the object to tween, the TweenInfo to use, and a table containing the properties to tween and the values to tween to.

Tweens are used to interpolate the properties of instances. These can be used to create animations for various Roblox objects. Almost any numeric property can be tweened using TweenService.

The propertyTable parameter that is passed in needs to be a dictionary where the keys are the string names of the property (e.g. "Position", "Transparency", "Color", etc), and the value is the value the property needs to be at the end of the tween. Note that only specific types of properties can be used with TweenService, but multiple properties can be animated in the same tween. The types of properties that can be tweened are:

The Tween created using this function is unique to the object given as the instance parameter. To apply the same tween to another object, call this function again with the new object.

Details on how the interpolation of the tween is to be carried out are given in the TweenInfo parameter, such as reversing, looping and easing.

Parameters

instance: Instance

The Instance whose properties are to be tweened.

tweenInfo: TweenInfo

The TweenInfo to be used.

propertyTable: table

A dictionary of properties, and their target values, to be tweened.


Returns

Code Samples

Tween Creation

1local TweenService = game:GetService("TweenService")
2
3local part = Instance.new("Part")
4part.Position = Vector3.new(0, 10, 0)
5part.Color = Color3.new(1, 0, 0)
6part.Anchored = true
7part.Parent = game.Workspace
8
9local goal = {}
10goal.Position = Vector3.new(10, 10, 0)
11goal.Color = Color3.new(0, 1, 0)
12
13local tweenInfo = TweenInfo.new(5)
14
15local tween = TweenService:Create(part, tweenInfo, goal)
16
17tween:Play()
Looping a Tween

1local TweenService = game:GetService("TweenService")
2
3local part = Instance.new("Part")
4part.Position = Vector3.new(0, 10, 0)
5part.Anchored = true
6part.Parent = workspace
7
8local tweenInfo = TweenInfo.new(
9 2, -- Time
10 Enum.EasingStyle.Linear, -- EasingStyle
11 Enum.EasingDirection.Out, -- EasingDirection
12 -1, -- RepeatCount (when less than zero the tween will loop indefinitely)
13 true, -- Reverses (tween will reverse once reaching it's goal)
14 0 -- DelayTime
15)
16
17local tween = TweenService:Create(part, tweenInfo, { Position = Vector3.new(0, 30, 0) })
18
19tween:Play()
20task.wait(10)
21tween:Cancel() -- cancel the animation after 10 seconds

GetValue

Returns a new alpha value for interpolating using the given alpha value, EasingStyle, and EasingDirection.

The provided alpha value is clamped between 0 and 1.

Parameters

alpha: number

An interpolation value between 0 and 1.

easingStyle: EasingStyle

The easing style to use.

easingDirection: EasingDirection

The easing direction to use.


Returns

A new alpha value generated from the given easing style and direction.