Tutorial · Fundamentos de scripting

Tutorial de TweenService: mover, girar e fazer parts sumirem

Um tween muda uma propriedade suavemente do valor atual até um objetivo ao longo do tempo: uma plataforma desliza, uma gema gira, uma parede some. O TweenService faz os passos intermediários por você, então você nunca precisa escrever um loop que empurra uma part a cada frame. Este guia cobre as três linhas que todo tween precisa, o que cada configuração do TweenInfo faz, mover, girar e fazer parts sumirem, loops, esperar um tween terminar e o truque para animar um Model inteiro.

Atualizado em 12 de novembro de 20266 min de leituraEscrito por

Resumo

Pegue o serviço com game:GetService("TweenService"), descreva o movimento com TweenInfo.new(time, easingStyle, easingDirection), depois chame TweenService:Create(part, info, { Position = goal }) e dê :Play() no tween que ele devolve. Qualquer propriedade number, Vector3, CFrame, Color3, UDim2 ou parecida pode receber tween. Use tween.Completed:Wait() para esperar ele terminar, e dê ao TweenInfo uma contagem de repetição -1 com reverses ligado para um loop de ida e volta.

  • Faça o tween da part no servidor quando todos os jogadores devem ver; no cliente para efeitos que só aquele jogador precisa.
  • Ancore as parts que recebem tween, senão a física briga com o tween.
  • Um Model não tem Position nem CFrame para animar: faça o tween de um NumberValue e mova o model com PivotTo.
Nesta página
  1. Como funciona
  2. 1. TweenInfo
  3. 2. Girar e sumir
  4. 3. Loops
  5. 4. Models
  6. Servidor ou cliente
  7. Erros comuns
  8. Com o RoCode
  9. Perguntas frequentes
  10. Fontes e leitura extra

As três linhas que todo tween precisa

Insira uma Part no Workspace, marque Anchored, depois passe o mouse sobre ela, clique em + e insira um Script. Este sobe a part 10 studs em 2 segundos:

Script em uma Part do Workspace chamado Rise
-- Script dentro de uma Part.
local TweenService = game:GetService("TweenService")

local part = script.Parent :: BasePart

local info = TweenInfo.new(2) -- 2 segundos, easing padrão
local goal = { Position = part.Position + Vector3.new(0, 10, 0) }

local tween = TweenService:Create(part, info, goal)
tween:Play()

O objetivo é uma tabela com nomes de propriedades e os valores em que elas devem terminar. Você pode animar várias propriedades de uma vez: { Position = ..., Transparency = 1, Color = Color3.fromRGB(255, 0, 0) }. O tween começa dos valores que existirem quando você chamar Play, então você só informa o final.

O que pode e o que não pode receber tween
TipoFaz tween suave?Exemplos
numberSimTransparency, Reflectance, o Value de um NumberValue
Vector3, CFrameSimPosition, Size, CFrame, Orientation
Color3SimColor
UDim2, Vector2SimSize e Position de GUI
boolean, EnumItemTroca no finalCanCollide, Material
string, InstanceNãoDá o erro cannot be tweened due to type mismatch (em inglês)

Passo 1: Todas as configurações do TweenInfo

O TweenInfo.new recebe até seis valores, nesta ordem. Você pode deixar de fora os do final.

TweenInfo.new(time, style, direction, repeatCount, reverses, delayTime)
ValorPadrãoO que faz
time1Segundos de uma execução.
easingStyleQuadO formato do movimento: Linear (velocidade constante), Sine, Quad, Cubic, Back (passa do ponto), Bounce, Elastic, Exponential.
easingDirectionOutOut começa rápido e desacelera; In começa devagar; InOut faz os dois.
repeatCount0Execuções extras depois da primeira. -1 repete para sempre.
reversesfalseVolta ao início depois de cada execução.
delayTime0Segundos de espera antes de começar.
Script em uma Part do Workspace chamado Platform
-- Script dentro de uma Part chamada Platform.
-- Desliza 12 studs para lá e para cá para sempre, suavizando nas duas pontas.
local TweenService = game:GetService("TweenService")

local platform = script.Parent :: BasePart

local info = TweenInfo.new(
	3, -- segundos em cada sentido
	Enum.EasingStyle.Sine,
	Enum.EasingDirection.InOut,
	-1, -- repete para sempre
	true -- volta a cada vez
)

TweenService:Create(platform, info, { Position = platform.Position + Vector3.new(12, 0, 0) }):Play()

Para uma plataforma que deve carregar os jogadores em cima dela, uma part ancorada com tween se move por baixo deles mas não os leva junto. O guia de plataforma móvel (em inglês) cobre esse caso.

Passo 2: Girar, redimensionar e fazer sumir

Para girar, faça o tween do CFrame até o CFrame atual vezes uma rotação. Animar a Orientation também funciona, mas o CFrame mantém a part no lugar enquanto ela gira. Aqui uma parede some e encolhe quando o script roda, e depois é removida quando o tween termina:

Script em uma Part do Workspace chamado FadingWall
-- Script dentro de uma Part chamada FadingWall.
local TweenService = game:GetService("TweenService")

local wall = script.Parent :: BasePart

-- gira um quarto de volta em torno do eixo para cima da própria part em 1 segundo
local turn = TweenService:Create(wall, TweenInfo.new(1), {
	CFrame = wall.CFrame * CFrame.Angles(0, math.rad(90), 0),
})
turn:Play()
turn.Completed:Wait() -- só continua quando ele terminar

-- depois some e encolhe ao mesmo tempo
local fade = TweenService:Create(wall, TweenInfo.new(0.8, Enum.EasingStyle.Quad, Enum.EasingDirection.In), {
	Transparency = 1,
	Size = wall.Size * 0.2,
})
fade:Play()
fade.Completed:Wait()
wall:Destroy()

O Completed dispara com um PlaybackState: Completed quando chegou ao objetivo, ou Cancelled quando tween:Cancel() o parou. Não espere o Completed de um tween que repete para sempre: ele nunca termina.

Passo 3: Um item que flutua e gira

Dois tweens em loop em propriedades diferentes rodam lado a lado. Fazer um tween de 360 graus inteiros com CFrame não faz nada, porque o início e o fim são a mesma rotação, então o giro anima um NumberValue de 0 a 360 e define o CFrame a partir dele. Coloque este Script dentro de uma part ancorada:

Script em uma Part do Workspace chamado FloatingGem
-- Script dentro de uma Part chamada Gem. Flutua para cima e para baixo e gira para sempre.
local TweenService = game:GetService("TweenService")

local FLOAT_HEIGHT = 1.5 -- studs acima de onde você a colocou
local FLOAT_SECONDS = 1.2 -- em cada sentido
local SPIN_SECONDS = 3 -- uma volta completa

local gem = script.Parent :: BasePart
gem.Anchored = true
local baseCFrame = gem.CFrame

local height = Instance.new("NumberValue")
local angle = Instance.new("NumberValue")

local function apply()
	gem.CFrame = baseCFrame * CFrame.new(0, height.Value, 0) * CFrame.Angles(0, math.rad(angle.Value), 0)
end
height.Changed:Connect(apply)
angle.Changed:Connect(apply)

TweenService:Create(height, TweenInfo.new(FLOAT_SECONDS, Enum.EasingStyle.Sine, Enum.EasingDirection.InOut, -1, true), {
	Value = FLOAT_HEIGHT,
}):Play()

TweenService:Create(angle, TweenInfo.new(SPIN_SECONDS, Enum.EasingStyle.Linear, Enum.EasingDirection.In, -1), {
	Value = 360,
}):Play()

O giro usa easing Linear para girar em velocidade constante, e recomeça em 0 a cada loop, que é o mesmo ângulo que 360, então não há pulo. O guia de coletar moedas (em inglês) coloca itens assim em um jogo.

Passo 4: Faça o tween de um Model inteiro

Um Model não tem propriedade Position nem CFrame, então TweenService:Create(model, ...) não tem o que mover. No lugar, faça o tween de um NumberValue de 0 a 1 e mova o model com PivotTo, que move todas as parts dentro dele juntas:

Script em um Model do Workspace chamado Elevator
-- Script dentro de um Model chamado Elevator.
-- Move o model inteiro 20 studs para cima e de volta, todas as parts juntas.
local TweenService = game:GetService("TweenService")

local elevator = script.Parent :: Model
local startPivot = elevator:GetPivot()
local endPivot = startPivot * CFrame.new(0, 20, 0)

local progress = Instance.new("NumberValue")
progress.Changed:Connect(function(alpha: number)
	elevator:PivotTo(startPivot:Lerp(endPivot, alpha))
end)

local info = TweenInfo.new(4, Enum.EasingStyle.Quad, Enum.EasingDirection.InOut, -1, true, 2)
TweenService:Create(progress, info, { Value = 1 }):Play()

Ancore todas as parts do model. O 2 no final do TweenInfo é a espera antes de cada execução, então o elevador espera no alto e embaixo. O guia de portas (em inglês) usa o mesmo padrão para abrir portas feitas de várias parts.

Servidor ou cliente?

Um tween tocado em um Script de servidor muda a part no servidor, e os valores novos são replicados para todos os jogadores, então todo mundo vê. Um tween em um LocalScript muda a part só na tela daquele jogador.

Onde tocar um tween
Toque emQuandoExemplo
Um Script de servidorA mudança importa para o jogo ou para todo mundo.Portas, obstáculos que se movem, uma ponte que abre
Um LocalScriptSó este jogador deve ver, ou é um efeito puramente visual.Um item sumindo para o jogador que o pegou, UI

A replicação envia atualizações muitas vezes por segundo, então tweens no servidor parecem suaves para a maioria dos jogadores, mas tweens muito rápidos ou muitos tweens no servidor podem parecer menos suaves em conexões lentas. Para muito movimento decorativo (centenas de moedas girando), toque os tweens em um LocalScript em cada cliente.

Erros comuns e como resolver

Abra a janela Output (menu Window, depois Output) antes de apertar Play.

A part não se move

Confira se você chamou :Play() no tween, se o nome da propriedade do objetivo está escrito exatamente certo (Position, não position), e se é um Script em um lugar onde scripts rodam (dentro de uma part no Workspace, ou no ServerScriptService).

A part cai ou treme durante o tween

Ela não está ancorada, então a gravidade e as colisões brigam com o tween. Marque Anchored.

TweenService:Create property cannot be tweened due to type mismatch

O valor do objetivo é do tipo errado, por exemplo um number para uma propriedade Vector3. Veja a página do erro (em inglês).

Unable to cast to Dictionary ou Unable to cast value to Object

Os argumentos estão na ordem errada ou são do tipo errado. É sempre Create(instance, tweenInfo, goalTable). Veja Unable to cast value to Object (em inglês).

Crie com o RoCode

Se você prefere não escrever tweens à mão, o RoCode pode construí-los no jogo que você tem aberto. O RoCode é um agente de IA independente para Roblox Studio, não feito pela Roblox: você descreve a mudança em um chat na web, e o plugin dele para o Studio cria os scripts no seu Explorer, então não há código para colar.

Você digita

Faça o model da ponte no Workspace deslizar 15 studs para o lado quando a rodada começar, usando um tween de NumberValue e PivotTo, e faça as parts vermelhas da barreira sumirem em 1 segundo ao mesmo tempo.

O RoCode faz
  • Pode achar as parts e os models que você quer dizer com Search Game antes de escrever qualquer coisa
  • Escreve o Script com Create Script e é instruído a compilá-lo com Check Script
  • Cria um ponto de desfazer antes e depois de cada lote de mudanças, então Ctrl+Z volta um lote de cada vez

Com o plugin 3.9 ou mais recente, o RoCode pode rodar um teste curto e ler os erros, mas movimento é mais fácil de avaliar com os seus próprios olhos, então aperte Play e veja. Como o RoCode se conecta ao Studio.

Perguntas frequentes

Como usar o TweenService no Roblox?

Pegue o serviço, crie um TweenInfo, chame TweenService:Create(object, info, { Property = goal }) e dê :Play() no resultado. A primeira seção tem um exemplo de três linhas.

Como fazer um tween repetir para sempre?

Passe -1 como quarto valor do TweenInfo.new (repeatCount), e true como quinto se ele deve ir e voltar.

Como esperar um tween terminar?

Chame tween.Completed:Wait() depois de tween:Play(), ou conecte uma função ao tween.Completed.

Dá para fazer tween de um Model?

Não diretamente. Faça o tween de um NumberValue de 0 a 1 e chame model:PivotTo(start:Lerp(goal, value)) quando ele mudar, como no Passo 4.

Como parar um tween?

Chame tween:Cancel() para parar e deixar a part onde está, ou tween:Pause() para continuar depois com Play().

Fontes e leitura extra

Como o código foi verificado: todo script desta página passa no verificador de tipos estrito do Luau com as definições da API do Roblox (luau-lsp, 12 de novembro de 2026). A verificação de tipos pega APIs com nome errado e tipos incorretos, não a lógica do jogo, então teste no Studio antes de publicar.

Teste o RoCode no seu próprio jogo.

Créditos grátis todo dia, sem cartão. Instale o plugin, descreva o recurso e confira o que aparece no Studio.