TweenBase
The base class for in-between interpolation handlers.
Summary
Properties
PlaybackState describes the current stage for the Tween animation. A description of each state can be found on the page for the PlaybackState enum. It can be manipulated through other Tween functions, like Play.
Events
The Completed event of a Tween fires when the tween finishes playing. This will happen either when the tween naturally finishes playing, or if it is stopped with TweenBase:Cancel().
Methods
The Cancel function halts playback of its Tween and resets the tween variables. If TweenBase:Play() is called again the Tween's properties will resume interpolating towards their destination but, as the tween variables have been reset, take the full length of the animation to do so.
The Pause function halts playback of its Tween. If you call `Class.TweenBase.Play again, the tween resumes playback from the moment it was paused.
The Play function starts the playback of its Tween. Note that if a tween has already begun calling Play will have no effect unless the tween has finished or has been stopped (either by TweenBase:Cancel() or TweenBase:Pause()).
Properties
PlaybackState
Read only property that shows the current playback PlaybackState of the Tween. PlaybackState is an Enum type variable with the following possible values.
- Delayed - The tween is waiting to repeat due to the DelayTime property of the Tween's TweenInfo
- Playing - The tween is playing normally
- Paused - The tween has been paused
- Completed - The tween has completed successfully
- Cancelled - The tween has been cancelled
Events
Completed
The Completed event of a Tween fires when the tween finishes playing. This will happen either when the tween naturally finishes playing, or if it is stopped with TweenBase:Cancel().
A function connected to this event will be passed the PlaybackState of the tween when it finished to give indication about why the tween ended. If the tween finishes naturally the status will be Completed, if cancelled then the state will be Cancelled. Note that calling TweenBase:Pause() will not fire the Completed event.
Code Samples
1local Players = game:GetService("Players")
2local TweenService = game:GetService("TweenService")
3
4local SLOW_DURATION = 10
5
6local function slowCharacter(humanoid)
7 local goal = {}
8 goal.WalkSpeed = 0
9
10 local tweenInfo = TweenInfo.new(SLOW_DURATION)
11
12 local tweenSpeed = TweenService:Create(humanoid, tweenInfo, goal)
13
14 tweenSpeed:Play()
15
16 return tweenSpeed
17end
18
19local function onCharacterAdded(character)
20 local humanoid = character:WaitForChild("Humanoid")
21 local initialSpeed = humanoid.WalkSpeed
22 local tweenSpeed = slowCharacter(humanoid)
23 tweenSpeed.Completed:Wait()
24 humanoid.WalkSpeed = initialSpeed
25end
26
27local function onPlayerAdded(player)
28 player.CharacterAdded:Connect(onCharacterAdded)
29end
30
31Players.PlayerAdded:Connect(onPlayerAdded)1local TweenService = game:GetService("TweenService")
2
3local part = Instance.new("Part")
4part.Position = Vector3.new(0, 50, 0)
5part.Anchored = true
6part.Parent = workspace
7
8local goal = {}
9goal.Position = Vector3.new(0, 0, 0)
10
11local tweenInfo = TweenInfo.new(3)
12
13local tween = TweenService:Create(part, tweenInfo, goal)
14
15local function onTweenCompleted(playbackState)
16 if playbackState == Enum.PlaybackState.Completed then
17 local explosion = Instance.new("Explosion")
18 explosion.Position = part.Position
19 explosion.Parent = workspace
20 part:Destroy()
21 task.delay(2, function()
22 if explosion then
23 explosion:Destroy()
24 end
25 end)
26 end
27end
28
29tween.Completed:Connect(onTweenCompleted)
30
31tween:Play()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()Methods
Cancel
The Cancel function halts playback of its Tween and resets the tween variables. If TweenBase:Play() is called again the Tween's properties will resume interpolating towards their destination but, as the tween variables have been reset, take the full length of the animation to do so.
Only the tween variables are reset, not the properties being changed by the tween. This means if you cancel a tween half way through its animation the properties will not reset to their original values. Where Cancel differs from TweenBase:Pause() is that once resumed, it will take the full duration of the tween to complete the animation.
Returns
Code Samples
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 goal = {}
9goal.Position = Vector3.new(0, 50, 0)
10
11local tweenInfo = TweenInfo.new(5)
12
13local tween = TweenService:Create(part, tweenInfo, goal)
14
15tween:Play()
16task.wait(2.5)
17tween:Cancel()
18
19local playTick = tick()
20tween:Play()
21
22tween.Completed:Wait()
23
24local timeTaken = tick() - playTick
25print("Tween took " .. tostring(timeTaken) .. " secs to complete")
26
27-- The tween will take 5 seconds to complete as the tween variables have been reset by tween:Cancel()Pause
The Pause function halts playback of its Tween. However the progress variables of the tween isn't reset. When you call TweenBase:Play(), the tween resumes playback from the moment it was paused.
If you want to reset the progress variables of the tween, use TweenBase:Cancel(). A tween paused halfway through its animation takes half of its duration to complete when resumed.
Returns
Code Samples
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()Play
The Play function starts the playback of its Tween. Note that if a tween has already begun calling Play will have no effect unless the tween has finished or has been stopped (either by TweenBase:Cancel() or TweenBase:Pause()).
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).
Returns
Code Samples
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()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()