Engine
GuidesReferenceResourcesArtDesign

TweenBase

Show Deprecated
Not Creatable
Not Browsable

The base class for in-between interpolation handlers.

Summary

Properties

PlaybackState: PlaybackState

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.

READ ONLY
NOT REPLICATED

Methods

Cancel(): void  

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.

Pause(): void  

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.

Play(): void  

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()).

Events

Completed(playbackState: PlaybackState): RBXScriptSignal  

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().

Properties

PlaybackState

PlaybackState
Read Only
Not Replicated
Read Parallel

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

Code Samples

Tween PlaybackState
local TweenService = game:GetService("TweenService")



local part = Instance.new("Part")

part.Position = Vector3.new(0, 10, 0)

part.Anchored = true

part.Parent = workspace



local goal = {}

goal.Orientation = Vector3.new(0, 90, 0)



local tweenInfo = TweenInfo.new(1, Enum.EasingStyle.Quad, Enum.EasingDirection.InOut, 2, true, 0.5)



local tween = TweenService:Create(part, tweenInfo, goal)



local function onPlaybackChanged()

	print("Tween status has changed to:", tween.PlaybackState)

end



local playbackChanged = tween:GetPropertyChangedSignal("PlaybackState")

playbackChanged:Connect(onPlaybackChanged)



tween:Play()

Methods

Cancel

void

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

void

Code Samples

Tween Cancel
local TweenService = game:GetService("TweenService")



local part = Instance.new("Part")

part.Position = Vector3.new(0, 10, 0)

part.Anchored = true

part.Parent = workspace



local goal = {}

goal.Position = Vector3.new(0, 50, 0)



local tweenInfo = TweenInfo.new(5)



local tween = TweenService:Create(part, tweenInfo, goal)



tween:Play()

task.wait(2.5)

tween:Cancel()



local playTick = tick()

tween:Play()



tween.Completed:Wait()



local timeTaken = tick() - playTick

print("Tween took " .. tostring(timeTaken) .. " secs to complete")



-- The tween will take 5 seconds to complete as the tween variables have been reset by tween:Cancel()

Pause

void

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

void

Code Samples

Pausing a Tween
local TweenService = game:GetService("TweenService")



local part = Instance.new("Part")

part.Position = Vector3.new(0, 10, 0)

part.Anchored = true

part.BrickColor = BrickColor.new("Bright green")

part.Parent = workspace



local goal = {}

goal.Position = Vector3.new(50, 10, 0)



local tweenInfo = TweenInfo.new(10, Enum.EasingStyle.Linear)



local tween = TweenService:Create(part, tweenInfo, goal)



tween:Play()



task.wait(3)

part.BrickColor = BrickColor.new("Bright red")

tween:Pause()



task.wait(2)

part.BrickColor = BrickColor.new("Bright green")

tween:Play()

Play

void

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

void

Code Samples

Tween Creation
local TweenService = game:GetService("TweenService")



local part = Instance.new("Part")

part.Position = Vector3.new(0, 10, 0)

part.Color = Color3.new(1, 0, 0)

part.Anchored = true

part.Parent = game.Workspace



local goal = {}

goal.Position = Vector3.new(10, 10, 0)

goal.Color = Color3.new(0, 1, 0)



local tweenInfo = TweenInfo.new(5)



local tween = TweenService:Create(part, tweenInfo, goal)



tween:Play()
Tween Conflict
local TweenService = game:GetService("TweenService")



local part = Instance.new("Part")

part.Position = Vector3.new(0, 10, 0)

part.Anchored = true

part.Parent = game.Workspace



local tweenInfo = TweenInfo.new(5)



-- create two conflicting tweens (both trying to animate part.Position)

local tween1 = TweenService:Create(part, tweenInfo, { Position = Vector3.new(0, 10, 20) })

local tween2 = TweenService:Create(part, tweenInfo, { Position = Vector3.new(0, 30, 0) })



-- listen for their completion status

tween1.Completed:Connect(function(playbackState)

	print("tween1: " .. tostring(playbackState))

end)

tween2.Completed:Connect(function(playbackState)

	print("tween2: " .. tostring(playbackState))

end)



-- try to play them both

tween1:Play()

tween2:Play()

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.

Parameters

playbackState: PlaybackState

The PlaybackState of the tween upon completion.


Code Samples

Tween Completed
local Players = game:GetService("Players")

local TweenService = game:GetService("TweenService")



local SLOW_DURATION = 10



local function slowCharacter(humanoid)

	local goal = {}

	goal.WalkSpeed = 0



	local tweenInfo = TweenInfo.new(SLOW_DURATION)



	local tweenSpeed = TweenService:Create(humanoid, tweenInfo, goal)



	tweenSpeed:Play()



	return tweenSpeed

end



local function onCharacterAdded(character)

	local humanoid = character:WaitForChild("Humanoid")

	local initialSpeed = humanoid.WalkSpeed

	local tweenSpeed = slowCharacter(humanoid)

	tweenSpeed.Completed:Wait()

	humanoid.WalkSpeed = initialSpeed

end



local function onPlayerAdded(player)

	player.CharacterAdded:Connect(onCharacterAdded)

end



Players.PlayerAdded:Connect(onPlayerAdded)
Tween Conflict
local TweenService = game:GetService("TweenService")



local part = Instance.new("Part")

part.Position = Vector3.new(0, 10, 0)

part.Anchored = true

part.Parent = game.Workspace



local tweenInfo = TweenInfo.new(5)



-- create two conflicting tweens (both trying to animate part.Position)

local tween1 = TweenService:Create(part, tweenInfo, { Position = Vector3.new(0, 10, 20) })

local tween2 = TweenService:Create(part, tweenInfo, { Position = Vector3.new(0, 30, 0) })



-- listen for their completion status

tween1.Completed:Connect(function(playbackState)

	print("tween1: " .. tostring(playbackState))

end)

tween2.Completed:Connect(function(playbackState)

	print("tween2: " .. tostring(playbackState))

end)



-- try to play them both

tween1:Play()

tween2:Play()
Verifying a Tween has Completed
local TweenService = game:GetService("TweenService")



local part = Instance.new("Part")

part.Position = Vector3.new(0, 50, 0)

part.Anchored = true

part.Parent = workspace



local goal = {}

goal.Position = Vector3.new(0, 0, 0)



local tweenInfo = TweenInfo.new(3)



local tween = TweenService:Create(part, tweenInfo, goal)



local function onTweenCompleted(playbackState)

	if playbackState == Enum.PlaybackState.Completed then

		local explosion = Instance.new("Explosion")

		explosion.Position = part.Position

		explosion.Parent = workspace

		part:Destroy()

		task.delay(2, function()

			if explosion then

				explosion:Destroy()

			end

		end)

	end

end



tween.Completed:Connect(onTweenCompleted)



tween:Play()