Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

Tween

继承： RefCounted < Object

通过脚本进行通用动画的轻量级对象，使用 Tweener。

描述

补间动画（Tweens）主要用于那些需要在一定数值范围内对数字属性进行插值的动画。Tween（补间）这个名字来源于 in-betweening（中间画），这是一种动画技术：你只需要指定关键帧，电脑就会自动计算并补全它们之间的那些过渡帧。使用 Tween 来制作动画的过程，就被称为“补间动画（tweening）”。

当动画的最终数值无法提前预知时，Tween 比 AnimationPlayer 更加适用。例如，动态插值一个随机选定的摄像机缩放值，用 Tween 来实现是最好的；但如果想用 AnimationPlayer 节点做同样的事情，就会非常困难。此外，Tweens 比 AnimationPlayer 更加轻量级，因此非常适合制作那些不需要编辑器进行可视化微调的简单动画或通用任务。对于一些通常需要用代码来处理的逻辑，你也可以用“发射后不管（fire-and-forget）”的方式来使用它们。比如，你可以使用一个带延迟的循环 CallbackTweener，来让某个物体周期性地发射子弹。

你可以通过调用 SceneTree.create_tween() 或 Node.create_tween() 来创建一个 Tween。如果是手动创建的 Tween（比如直接使用 Tween.new()），它是无效的，无法用来对数值进行补间动画。

你可以通过调用 tween_property、tween_interval、tween_callback、tween_method、tween_subtween 或 tween_await 这些方法，向 Tween 对象中添加 Tweener，从而创建出一个补间动画:

GDScriptC#

var tween = get_tree().create_tween()
tween.tween_property($Sprite, "modulate", Color.RED, 1.0)
tween.tween_property($Sprite, "scale", Vector2(), 1.0)
tween.tween_callback($Sprite.queue_free)

这个序列会让 $Sprite 节点先变成红色，然后缩小，最后调用 Node.queue_free() 来释放（销毁）这个精灵。默认情况下，Tweener 是一个接一个按顺序执行的。不过，你也可以使用 parallel() 和 set_parallel() 来改变这种（串行）行为。

当使用 tween_* 系列方法创建出一个 Tweener 后，你可以使用链式方法调用来微调这个 Tweener 的各项属性。例如，如果你想改变上面示例中的过渡类型（transition type），就可以使用 set_trans() 方法：

GDScriptC#

var tween = get_tree().create_tween()
tween.tween_property($Sprite, "modulate", Color.RED, 1.0).set_trans(Tween.TRANS_SINE)
tween.tween_property($Sprite, "scale", Vector2(), 1.0).set_trans(Tween.TRANS_BOUNCE)
tween.tween_callback($Sprite.queue_free)

大多数 Tween 的方法也可以这样进行链式调用。在下面的例子中，这个 Tween 被绑定到了当前运行脚本所在的节点上，并且为它的 Tweeners 设置了一个默认的过渡效果：

GDScriptC#

var tween = get_tree().create_tween().bind_node(self).set_trans(Tween.TRANS_ELASTIC)
tween.tween_property($Sprite, "modulate", Color.RED, 1.0)
tween.tween_property($Sprite, "scale", Vector2(), 1.0)
tween.tween_callback($Sprite.queue_free)

Tween 的另一个有趣用法是，对任意一组对象进行动画处理：

GDScriptC#

var tween = create_tween()
for sprite in get_children():
    tween.tween_property(sprite, "position", Vector2(0, 0), 1.0)

在上面的例子中，某个节点的所有子节点会被依次移动到 (0, 0) 的位置。

你应该避免对同一个对象的属性使用多个 Tween。如果两个或更多的补间动画同时控制同一个属性，最后创建的那个会获得优先权，并决定该属性的最终值。如果你想中断并重新开始一个动画，可以考虑将 Tween 赋值给一个变量：

GDScriptC#

var tween
func animate():
    if tween:
        tween.kill() #中断（或取消）上一次的动画。
    tween = create_tween()

部分 Tweener（补间器）会用到过渡（transitions）和缓动（eases）。前者接受一个 TransitionType 常量，它决定了动画的时间节奏处理方式（你可以访问 easings.net 查看一些具体的效果示例）。后者接受一个 EaseType 常量，它控制着 trans_type（过渡类型）在插值过程中的应用位置（是应用在开头、结尾，还是两头都应用）。如果你不知道该选哪种过渡和缓动效果，可以尝试搭配不同的 TransitionType 常量与 EASE_IN_OUT 一起使用，然后从中挑一个视觉效果最棒的。

Tween easing and transition types cheatsheet

注意： Tween 并不是为了重复使用而设计的，强行复用会导致不可预期的行为。每次制作动画，以及每次想要从头重播动画时，都应该创建一个新的 Tween。请记住，Tween 在创建后会立刻开始运行，所以只有当你真正准备开始播放动画时，再去创建它。

注意： Tween 是在当前帧的所有节点处理之后才被执行的。也就是说，节点的 Node._process() 方法会在 Tween 之前被调用（或者如果是根据 set_process_mode() 传入的值来决定的话，那就是 Node._physics_process() 会在 Tween 之前被调用）。

方法

Tween	bind_node(node: Node)
Tween	chain()
bool	custom_step(delta: float)
int	get_loops_left() const
float	get_total_elapsed_time() const
bool	has_tweeners() const
Variant	interpolate_value(initial_value: Variant, delta_value: Variant, elapsed_time: float, duration: float, trans_type: TransitionType, ease_type: EaseType) static
bool	is_running()
bool	is_valid()
void	kill()
Tween	parallel()
void	pause()
void	play()
Tween	set_ease(ease: EaseType)
Tween	set_ignore_time_scale(ignore: bool = true)
Tween	set_loops(loops: int = 0)
Tween	set_parallel(parallel: bool = true)
Tween	set_pause_mode(mode: TweenPauseMode)
Tween	set_process_mode(mode: TweenProcessMode)
Tween	set_speed_scale(speed: float)
Tween	set_trans(trans: TransitionType)
void	stop()
AwaitTweener	tween_await(signal: Signal)
CallbackTweener	tween_callback(callback: Callable)
IntervalTweener	tween_interval(time: float)
MethodTweener	tween_method(method: Callable, from: Variant, to: Variant, duration: float)
PropertyTweener	tween_property(object: Object, property: NodePath, final_val: Variant, duration: float)
SubtweenTweener	tween_subtween(subtween: Tween)

---

信号

finished() 🔗

该 Tween 完成所有补间时发出。该 Tween 设为无限循环时不会发出（见 set_loops()）。

---

loop_finished(loop_count: int) 🔗

完成一次循环时触发（见 set_loops()），会提供该循环的索引号。这个信号不会在最后一次循环后触发，这种情况请使用 finished 代替。

---

step_finished(idx: int) 🔗

完成该 Tween 的一步完成后触发，会提供这一步的索引号。一步指的是单个 Tweener 或一组并行执行的 Tweener。

---

枚举

enum TweenProcessMode: 🔗

TweenProcessMode TWEEN_PROCESS_PHYSICS = 0

该 Tween 在每个物理帧之后进行更新（见 Node._physics_process()）。

TweenProcessMode TWEEN_PROCESS_IDLE = 1

该 Tween 在每个处理帧之后进行更新（见 Node._process()）。

---

enum TweenPauseMode: 🔗

TweenPauseMode TWEEN_PAUSE_BOUND = 0

如果该 Tween 绑定了节点，它将在该节点可以处理时进行处理（见 Node.process_mode）。否则与 TWEEN_PAUSE_STOP 相同。

TweenPauseMode TWEEN_PAUSE_STOP = 1

如果 SceneTree 被暂停，则该 Tween 也会暂停。

TweenPauseMode TWEEN_PAUSE_PROCESS = 2

无论 SceneTree 是否被暂停，该 Tween 都会处理。

---

enum TransitionType: 🔗

TransitionType TRANS_LINEAR = 0

动画是线性插值的。

TransitionType TRANS_SINE = 1

动画使用正弦函数进行插值。

TransitionType TRANS_QUINT = 2

动画使用五次（5 次方）函数进行插值。

TransitionType TRANS_QUART = 3

动画使用四次（4 次方）函数进行插值。

TransitionType TRANS_QUAD = 4

动画使用二次（2 次方）函数进行插值。

TransitionType TRANS_EXPO = 5

动画使用指数（x 次方）函数进行插值。

TransitionType TRANS_ELASTIC = 6

动画弹性插值，在边缘摆动。

TransitionType TRANS_CUBIC = 7

动画使用三次（3 次方）函数进行插值。

TransitionType TRANS_CIRC = 8

动画使用平方根的函数进行插值。

TransitionType TRANS_BOUNCE = 9

动画通过在末尾弹跳插值。

TransitionType TRANS_BACK = 10

动画在末端回放插值。

TransitionType TRANS_SPRING = 11

动画像朝着末尾的弹簧一样插值。

---

enum EaseType: 🔗

EaseType EASE_IN = 0

插值开始缓慢，并加速接近结束。

EaseType EASE_OUT = 1

插值开始快速，接近结束时减慢。

EaseType EASE_IN_OUT = 2

EASE_IN 和 EASE_OUT 的组合。两端的插值最慢。

EaseType EASE_OUT_IN = 3

EASE_IN 和 EASE_OUT 的组合。两端的插值最快。

---

方法说明

Tween bind_node(node: Node) 🔗

将这个 Tween 绑定到给定的 node 上。Tween 是由 SceneTree 直接处理的，所以不依赖被动画的节点运行。将该 Tween 绑定到某个 Node 后，该对象不在树中时该 Tween 就会暂停动画，绑定对象被释放时该 Tween 会被自动销毁。另外，TWEEN_PAUSE_BOUND 会让暂停行为依赖于绑定的节点。

使用 Node.create_tween() 来创建并绑定 Tween 更简单。

---

Tween chain() 🔗

用于在使用 true 调用 set_parallel() 后，将两个 Tweener 串联。

GDScriptC#

var tween = create_tween().set_parallel(true)
tween.tween_property(...)
tween.tween_property(...) # 会和上一条并行执行。
tween.chain().tween_property(...) # 会在前两条完成后执行。

---

bool custom_step(delta: float) 🔗

使用给定的增量 delta 处理该 Tween，单位为秒。主要用于在该 Tween 暂停时进行手动控制。通过将 delta 设置为大于 Tween 动画总时长的值，也可以立即结束该 Tween 的动画。

如果该 Tween 仍然有未完成的 Tweener，则返回 true。

---

int get_loops_left() const 🔗

返回该 Tween 所剩的循环数（见 set_loops()）。返回 -1 表示 Tween 无限循环，返回 0 表示 Tween 已结束。

---

float get_total_elapsed_time() const 🔗

返回该 Tween 已进行动画的总时长（即自开始以来经过的时间，不计算暂停等时间），单位为秒。时长会受到 set_speed_scale() 影响，stop() 会将其重置为 0。

注意：由于时长是由帧的增量时间累计而来的，该 Tween 完成动画后所返回的时长会比 Tween 的实际时长略大。

---

bool has_tweeners() const 🔗

如果已向 Tween 添加了任意 Tweener 且该 Tween 有效，则返回 true。当动态添加补间器且补间序列最终可能为空时，此方法非常有用。在空补间开始前将其终止，可避免报错。

---

Variant interpolate_value(initial_value: Variant, delta_value: Variant, elapsed_time: float, duration: float, trans_type: TransitionType, ease_type: EaseType) static 🔗

不想使用 Tween 进行动画时，可以使用这个方法进行手动插值。与 @GlobalScope.lerp() 类似，但支持自定义过渡和缓动。

initial_value 为插值的起始值。

delta_value 为插值的变化值，即等于 final_value - initial_value。

elapsed_time 为插值开始后所经过的秒数，用于控制插值的位置。例如，等于 duration 的一半时，插值后的值位于初始值和最终值的一半。这个值也可以比 duration 大或者比 0 小，此时会进行外插。

duration 为插值的总时长。

注意：如果 duration 等于 0，那么无论提供的 elapsed_time 为多少，该方法返回的始终是最终值。

---

bool is_running() 🔗

返回该 Tween 目前是否正在执行，即未暂停且未完成。

---

bool is_valid() 🔗

返回该 Tween 是否有效。有效的 Tween 是由场景树包含的 Tween（即 SceneTree.get_processed_tweens() 返回的数组中包含这个 Tween）。Tween 失效的情况有：补间完成、被销毁、使用 Tween.new() 创建。无效的 Tween 不能追加 Tweener。

---

void kill() 🔗

中止所有补间操作，并使该 Tween 无效。

---

Tween parallel() 🔗

让下一个 Tweener 与上一个并行执行。

GDScriptC#

var tween = create_tween()
tween.tween_property(...)
tween.parallel().tween_property(...)
tween.parallel().tween_property(...)

该示例中的所有 Tweener 都会同时执行。

你可以通过使用 set_parallel() 让该 Tween 默认并行。

---

void pause() 🔗

暂停该补间。可以使用 play() 恢复动画。

注意：如果一个 Tween 被暂停并且没有被绑定到任何节点，它将无限期地存在，直到手动启动或失效。如果丢失了对这种 Tween 的引用，可以使用 SceneTree.get_processed_tweens() 检索它。

---

void play() 🔗

恢复已暂停或已停止的 Tween。

---

Tween set_ease(ease: EaseType) 🔗

设置在此方法之后添加的 PropertyTweener（属性补间器）和 MethodTweener（方法补间器）的默认缓动类型。

在调用此方法之前，默认的缓动类型是 EASE_IN_OUT。

GDScriptC#

var tween = create_tween()
tween.tween_property(self, "position", Vector2(300, 0), 0.5) # Uses EASE_IN_OUT.
tween.set_ease(Tween.EASE_IN)
tween.tween_property(self, "rotation_degrees", 45.0, 0.5) # Uses EASE_IN.

---

Tween set_ignore_time_scale(ignore: bool = true) 🔗

如果 ignore 为 true，则该补间动画会忽略 Engine.time_scale，随实际流逝的时间更新。所有 Tweener 和对应的延迟都会受到影响。默认值为 false。

---

Tween set_loops(loops: int = 0) 🔗

这只该补间序列的重复次数，即 set_loops(2) 会让动画执行两次。

调用这个方法时如果不带参数，那么该 Tween 会无限执行，直到被 kill() 销毁、该 Tween 绑定的节点被释放或者所有进行动画的对象都被释放（无法再进行任何动画）。

警告：使用无限循环时请一定要加入一些时长/延迟。为了防止游戏冻结，0 时长的循环动画（例如单个不带延迟的 CallbackTweener）会在循环若干次后停止，造成出乎预料的结果。如果 Tween 的生命期依赖于某个节点，请一定使用 bind_node()。

---

Tween set_parallel(parallel: bool = true) 🔗

如果 parallel 为 true，则后续追加的 Tweener 默认就是同时运行的，否则默认依次运行。

注意：与 parallel() 类似，在这个方法前添加的那一个补间器也是并行步骤的一部分。

tween.tween_property(self, "position", Vector2(300, 0), 0.5)
tween.set_parallel()
tween.tween_property(self, "modulate", Color.GREEN, 0.5) # 与位置补间器一同运行。

---

Tween set_pause_mode(mode: TweenPauseMode) 🔗

决定该 Tween 在 SceneTree 暂停时的行为。

默认值为 TWEEN_PAUSE_BOUND。

---

Tween set_process_mode(mode: TweenProcessMode) 🔗

决定该 Tween 应当在处理帧（见 Node._process()）还是物理帧（见 Node._physics_process()）执行。

默认值为 TWEEN_PROCESS_IDLE。

---

Tween set_speed_scale(speed: float) 🔗

补间的速度缩放。影响所有 Tweener 及其延迟。

---

Tween set_trans(trans: TransitionType) 🔗

设置在该方法之后追加的 PropertyTweener 和 MethodTweener 的默认过渡类型。

调用该方法前的默认过渡类型为 TRANS_LINEAR。

var tween = create_tween()
tween.tween_property(self, "position", Vector2(300, 0), 0.5) # 使用 TRANS_LINEAR。
tween.set_trans(Tween.TRANS_SINE)
tween.tween_property(self, "rotation_degrees", 45.0, 0.5) # 使用 TRANS_SINE。

---

void stop() 🔗

停止补间动画并将 Tween 重置为初始状态，不会移除已追加的 Tweener。

注意：该方法不会将 PropertyTweener 的目标重置为 Tween 首次开始时的值。

var tween = create_tween()

# 将在 1 秒内从 0 移动到 500。
position.x = 0.0
tween.tween_property(self, "position:x", 500, 1.0)

# 计时器结束时（大概）在 250。
await get_tree().create_timer(0.5).timeout

# 现在将在 1 秒内从（大概）250 移动到 500，
# 因此速度为原先的一半。
tween.stop()
tween.play()

注意：如果 Tween 被停止且未与任何节点绑定，则会无限存续下去，直到手动启动或手动废除。如果你丢失了对这种 Tween 的引用，则可以通过 SceneTree.get_processed_tweens() 来获取。

---

AwaitTweener tween_await(signal: Signal) 🔗

创建并追加一个 AwaitTweener。该方法可用于等待信号发出，以创建异步动画或过场动画。

在等待的信号发出或连接失效（例如因目标对象被释放）之前，动画不会进入下一步。如果预计信号可能不会发出，请使用 AwaitTweener.set_timeout()。

注意： 等待的信号应在 AwaitTweener 处于活动状态的步骤期间发出。

示例： 一个对象发射自身，并在碰撞时或 4 秒后爆炸。

var tween = create_tween()
tween.tween_callback(launch)
tween.tween_await(collided).set_timeout(4.0)
tween.tween_callback(explode)

示例： 一个角色走到指定位置，说出几行台词，当玩家关闭消息框时再走回去。

var tween = create_tween()
tween.tween_callback(walk_to.bind(600.0))
tween.tween_await(destination_reached)
tween.tween_callback(say_dialogue.bind("Good day, sir!"))
tween.tween_await(dialogue_closed)
tween.tween_callback(walk_to.bind(0.0))

注意： 如果你正在等待一个在同一个 Tween 中调用的回调函数发出的信号，请确保该信号是在等待（await）开始 之后 才发出的。如果无法合理地保证这一点，你可以将等待和发出信号放在同一个步骤中进行：

var tween = create_tween()
tween.tween_await(signal)
tween.parallel().tween_callback(method_that_emits_signal)

---

CallbackTweener tween_callback(callback: Callable) 🔗

创建并追加一个 CallbackTweener。这个方法可用于调用任意对象的任意方法。请使用 Callable.bind() 绑定额外的调用参数。

示例：总是每隔 1 秒射击一次的对象：

GDScriptC#

var tween = get_tree().create_tween().set_loops()
tween.tween_callback(shoot).set_delay(1.0)

示例：将精灵变红然后变蓝，带有 2 秒延迟：

GDScriptC#

var tween = get_tree().create_tween()
tween.tween_callback($Sprite.set_modulate.bind(Color.RED)).set_delay(2)
tween.tween_callback($Sprite.set_modulate.bind(Color.BLUE)).set_delay(2)

---

IntervalTweener tween_interval(time: float) 🔗

创建并追加一个 IntervalTweener。这个方法可用于在补间动画中创建延迟，可以替代在其他 Tweener 中使用延迟，或无动画的情况（此时 Tween 充当计时器的角色）。time 为间隔时间，单位为秒。

示例：创建代码执行的间隔：

GDScriptC#

# ... 一些代码
yield(create_tween().tween_interval(2), "finished")
# ... 更多代码

示例：创建每隔几秒就来回移动并跳跃的对象：

GDScriptC#

var tween = create_tween().set_loops()
tween.tween_property($Sprite, "position:x", 200.0, 1.0).as_relative()
tween.tween_callback(jump)
tween.tween_interval(2)
tween.tween_property($Sprite, "position:x", -200.0, 1.0).as_relative()
tween.tween_callback(jump)
tween.tween_interval(2)

---

MethodTweener tween_method(method: Callable, from: Variant, to: Variant, duration: float) 🔗

创建并追加一个 MethodTweener。这个方法与 tween_callback() 和 tween_property() 的组合类似，会使用补间后的值作为参数去持续调用某个方法。该值是从 from 到 to 进行补间的，时长为 duration 秒。请使用 Callable.bind() 绑定额外的调用参数。你可以使用 MethodTweener.set_ease() 和 MethodTweener.set_trans() 来调整该值的缓动和过渡，可以使用 MethodTweener.set_delay() 来延迟补间。

示例：让 3D 对象面向另一个点：

GDScriptC#

var tween = create_tween()
tween.tween_method(look_at.bind(Vector3.UP), Vector3(-1, 0, -1), Vector3(1, 0, -1), 1.0) # look_at() 方法的第二个参数接受的是上向量。

示例：在一段延迟后，使用中间方法来设置 Label 的文本：

GDScriptC#

func _ready():
    var tween = create_tween()
    tween.tween_method(set_label_text, 0, 10, 1).set_delay(1)

func set_label_text(value: int):
    $Label.text = "Counting " + str(value)

---

PropertyTweener tween_property(object: Object, property: NodePath, final_val: Variant, duration: float) 🔗

创建并追加一个 PropertyTweener。这个方法会将 object 对象的 property 属性在初始值和最终值 final_val 之间进行补间，持续时间为 duration 秒。初始值默认为该 PropertyTweener 启动时该属性的值。

GDScriptC#

var tween = create_tween()
tween.tween_property($Sprite, "position", Vector2(100, 200), 1.0)
tween.tween_property($Sprite, "position", Vector2(200, 300), 1.0)

会将该精灵移动到 (100, 200) 然后再移动到 (200, 300)。如果你使用了 PropertyTweener.from() 或 PropertyTweener.from_current()，那么起始位置就会被给定的值所覆盖。更多调整项请参阅 PropertyTweener 中的其他方法。

注意：鼠标悬停在检查器中的属性上即可查看正确的属性名称。你还可以用 "属性:组件" 的形式提供属性中的组件（例如 position:x），这样就只会修改这个特定的组件。

示例：使用不同的过渡类型从同一位置开始移动两次：

GDScriptC#

var tween = create_tween()
tween.tween_property($Sprite, "position", Vector2.RIGHT * 300, 1.0).as_relative().set_trans(Tween.TRANS_SINE)
tween.tween_property($Sprite, "position", Vector2.RIGHT * 300, 1.0).as_relative().from_current().set_trans(Tween.TRANS_EXPO)

---

SubtweenTweener tween_subtween(subtween: Tween) 🔗

创建并追加 SubtweenTweener。该方法可用于将 subtween 嵌套至该 Tween 中，从而创建更复杂、方便合成的动画序列。

# 子补间动画会旋转该对象。
var subtween = create_tween()
subtween.tween_property(self, "rotation_degrees", 45.0, 1.0)
subtween.tween_property(self, "rotation_degrees", 0.0, 1.0)

# 父补间动画会将子补间动画作为单一步骤执行。
var tween = create_tween()
tween.tween_property(self, "position:x", 500, 3.0)
tween.tween_subtween(subtween)
tween.tween_property(self, "position:x", 300, 2.0)

注意：pause()、stop()、set_loops() 等方法可能导致父 Tween 卡在子补间动画步骤；详见对应方法的文档。

注意：使用 set_pause_mode() 和 set_process_mode() 对 subtween 设置的暂停模式和处理模式会被父 Tween 的设置覆盖。