教程 · 脚本基础

Roblox TweenService:移动、旋转和隐藏零件

补间(tween)会在给定时间内把一个属性从当前值平滑地变到目标值:平台滑动、宝石旋转、墙壁淡出。TweenService 会自己计算中间的每一步,所以你不需要写一个每帧移动零件的循环。本教程包括:每个补间都离不开的三行代码,TweenInfo 每个设置的作用,零件的移动、旋转和淡出,循环,等待补间结束,以及补间整个模型(Model)的技巧。

更新于 2026年11月20日阅读约 3 分钟作者

要点

用 game:GetService("TweenService") 获取服务,用 TweenInfo.new(time, easingStyle, easingDirection) 描述运动,然后调用 TweenService:Create(part, info, { Position = goal }),再对得到的补间调用 :Play()。任何 number、Vector3、CFrame、Color3、UDim2 等类型的属性都可以补间。要等待结束,使用 tween.Completed:Wait();要让它无限地来回运动,在 TweenInfo 中把重复次数设为 -1 并开启 reverses。

  • 当所有玩家都应该看到零件变化时,在服务端补间;当效果只给这个玩家看时,在客户端补间。
  • 把要补间的零件设为锚固(Anchored),否则物理会干扰补间。
  • Model 没有可以补间的 Position 或 CFrame:补间一个 NumberValue,再通过 PivotTo 移动模型。
本页内容
  1. 工作原理
  2. 1. TweenInfo
  3. 2. 旋转和淡出
  4. 3. 循环
  5. 4. 模型
  6. 服务端还是客户端
  7. Common errors
  8. 用 RoCode
  9. 常见问题
  10. 参考资料

每个补间都需要的三行代码

在 Workspace 中插入一个 Part,勾选 Anchored,然后把鼠标悬停在它上面,点击 + 并插入一个 Script。这个脚本在 2 秒内把零件升高 10 格(stud):

Script 位置: Workspace 中的零件 名称: Rise
-- 零件里的 Script。
local TweenService = game:GetService("TweenService")

local part = script.Parent :: BasePart

local info = TweenInfo.new(2) -- 2 秒,默认缓动
local goal = { Position = part.Position + Vector3.new(0, 10, 0) }

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

目标是一张表,由属性名和它们最终要达到的值组成。可以同时补间多个属性:{ Position = ..., Transparency = 1, Color = Color3.fromRGB(255, 0, 0) }。补间从调用 Play 那一刻的值开始,所以你永远只需要设定终点。

哪些可以补间,哪些不行
类型能平滑补间吗?示例
number能Transparency、Reflectance、NumberValue 的 Value
Vector3, CFrame能Position、Size、CFrame、Orientation
Color3能Color
UDim2, Vector2能GUI 的 Size 和 Position
boolean, EnumItem在结束时切换CanCollide、Material
string, Instance不能会报错 cannot be tweened due to type mismatch

第 1 步:TweenInfo 的所有设置

TweenInfo.new 按以下顺序最多接受六个值。后面的值可以省略。

TweenInfo.new(time, style, direction, repeatCount, reverses, delayTime)
值默认作用
time1播放一次所需的秒数。
easingStyleQuad运动的形态:Linear(匀速)、Sine、Quad、Cubic、Back(会冲过头)、Bounce、Elastic、Exponential。
easingDirectionOutOut 开始快然后减速;In 开始慢;InOut 两者兼有。
repeatCount0第一次播放后再重复多少次。-1 表示无限重复。
reversesfalse每次播放后是否返回起点。
delayTime0开始前等待的秒数。
Script 位置: Workspace 中的零件 名称: Platform
-- 名为 Platform 的零件里的 Script。
-- 无限地来回移动 12 格,两端都平滑过渡。
local TweenService = game:GetService("TweenService")

local platform = script.Parent :: BasePart

local info = TweenInfo.new(
	3, -- 每个方向的秒数
	Enum.EasingStyle.Sine,
	Enum.EasingDirection.InOut,
	-1, -- 无限重复
	true -- 每次都返回
)

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

如果平台需要载着站在上面的玩家,请注意:用补间移动的锚固零件会在他们脚下移动,但不会带着他们走。这种情况在 移动平台教程 中有讲解。

第 2 步:旋转、缩放和淡出

要旋转零件,把 CFrame 补间到当前 CFrame 乘以一个旋转。补间 Orientation 也可以,但用 CFrame 时零件会原地旋转。这里的墙在脚本运行时先旋转,然后淡出并缩小,补间结束后被删除:

Script 位置: Workspace 中的零件 名称: FadingWall
-- 名为 FadingWall 的零件里的 Script。
local TweenService = game:GetService("TweenService")

local wall = script.Parent :: BasePart

-- 在 1 秒内绕自身竖直轴旋转四分之一圈
local turn = TweenService:Create(wall, TweenInfo.new(1), {
	CFrame = wall.CFrame * CFrame.Angles(0, math.rad(90), 0),
})
turn:Play()
turn.Completed:Wait() -- 等旋转结束后才继续

-- 然后同时淡出并缩小
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()

Completed 触发时会带上 PlaybackState:补间到达目标时是 Completed,被 tween:Cancel() 停止时是 Cancelled。不要等待一个无限重复的补间的 Completed:它永远不会结束。

第 3 步:漂浮并旋转的物品

两个作用于不同属性的循环补间会同时运行。通过 CFrame 补间完整的 360 度旋转不会有任何效果,因为起点和终点是同一个旋转,所以旋转部分补间一个从 0 到 360 的 NumberValue,并据此设置 CFrame。把这个 Script 放进一个锚固的零件:

Script 位置: Workspace 中的零件 名称: FloatingGem
-- 名为 Gem 的零件里的 Script。无限地上下漂浮并旋转。
local TweenService = game:GetService("TweenService")

local FLOAT_HEIGHT = 1.5 -- 比你放置它的位置高出的格数
local FLOAT_SECONDS = 1.2 -- 每个方向
local SPIN_SECONDS = 3 -- 转一整圈

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

旋转使用 Linear 缓动,所以转速恒定,而且每个循环都从 0 重新开始,0 和 360 是同一个角度,所以不会有跳动。收集金币教程 会把这类物品做进游戏里。

第 4 步:补间整个模型

Model 没有 Position 或 CFrame 属性,所以 TweenService:Create(model, ...) 没有东西可移动。改为补间一个从 0 到 1 的 NumberValue,并通过 PivotTo 移动模型,它会把模型里的所有零件一起移动:

Script 位置: Workspace 中的模型 名称: Elevator
-- 名为 Elevator 的模型里的 Script。
-- 把整个模型向上移动 20 格再返回,所有零件一起移动。
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()

把模型的所有零件都设为锚固。TweenInfo 最后的 2 是每次播放前的延迟,所以电梯会在顶部和底部停留。门的教程 用同样的方法打开由多个零件组成的门。

服务端还是客户端?

在服务端 Script 中运行的补间会在服务器上改变零件,新的值会复制给所有玩家,所以每个人都能看到。LocalScript 中的补间只会在这个玩家的屏幕上改变零件。

在哪里运行补间
运行位置什么时候示例
服务端 Script这个变化对游戏或对所有人都重要。门、移动的障碍、展开的桥
LocalScript只有这个玩家需要看到,或者纯粹是视觉效果。只在捡起它的玩家那里淡出的物品、UI

复制每秒会发送很多次更新,所以服务端补间对大多数玩家来说是平滑的,但非常快或数量非常多的服务端补间在慢速网络上可能看起来不够平滑。对于大量装饰性的运动(数百枚旋转的金币),请在每个客户端的 LocalScript 中运行补间。

常见错误与解决办法

点击 Play 之前先打开 Output 窗口(Window 菜单,然后选 Output)。

零件完全不动

检查你是否对补间调用了 :Play(),目标中的属性名是否拼写准确(是 Position 而不是 position),以及它是否是放在脚本会运行的位置的 Script(Workspace 中的零件里或 ServerScriptService 中)。

补间时零件掉落或抖动

它没有锚固,所以重力和碰撞会干扰补间。勾选 Anchored。

TweenService:Create property cannot be tweened due to type mismatch

目标值的类型不对,例如给 Vector3 类型的属性传了一个数字。请看 错误页面(英文)。

Unable to cast to Dictionary 或 Unable to cast value to Object

参数顺序或类型不对。顺序永远是 Create(instance, tweenInfo, goalTable)。请看 Unable to cast value to Object(英文)。

用 RoCode 来做

如果不想手动写补间,RoCode 可以在你打开的场景里把它们搭好。RoCode 是独立的 Roblox Studio AI 代理,并非 Roblox 出品:你在网页聊天里描述改动,它的 Studio 插件就会在你的 Explorer 中创建脚本,所以不需要粘贴代码。

你输入

回合开始时,通过补间 NumberValue 和 PivotTo,让 Workspace 中的桥模型向旁边移开 15 格,同时在 1 秒内让红色的障碍零件淡出。

RoCode 的操作
  • 可以在写任何东西之前用 Search Game 找到需要的零件和模型
  • 用 Create Script 编写 Script,并被要求用 Check Script 检查能否编译
  • 在每批改动前后设置撤销点,所以按 Ctrl+Z 一次回退一批

使用插件 3.9 及以上时,RoCode 可以运行简短的试玩测试并读取错误,但运动效果最容易用自己的眼睛判断,所以请点击 Play 看一看。RoCode 如何连接到 Studio。

常见问题

Roblox 里 TweenService 怎么用?

获取服务,创建 TweenInfo,调用 TweenService:Create(object, info, { Property = goal }),再对结果调用 :Play()。第一部分有一个三行代码的示例。

怎么让补间无限循环?

把 -1 作为 TweenInfo.new 的第四个值(repeatCount)传入;如果需要来回运动,第五个值传 true。

怎么等待补间结束?

在 tween:Play() 之后调用 tween.Completed:Wait(),或者把一个函数连接到 tween.Completed。

Model 能补间吗?

不能直接补间。补间一个从 0 到 1 的 NumberValue,每次变化时调用 model:PivotTo(start:Lerp(goal, value)),就像第 4 步那样。

怎么停止补间?

调用 tween:Cancel() 停止它并让零件留在当前位置,或者调用 tween:Pause(),之后再用 Play() 继续。

参考资料

代码如何验证:本页的所有脚本都已用 Roblox API 类型定义(luau-lsp,2026年11月20日)通过 Luau strict 类型检查。类型检查能发现 API 名称写错和类型不匹配,但发现不了游戏逻辑上的错误。发布前请务必在 Studio 中测试。

在你自己的游戏里试试 RoCode。

每天有免费额度,无需绑定银行卡。安装插件,描述你想要的功能,然后看看它在 Studio 里做了什么。