Tween

继承： RefCounted < Object

通过脚本用于通用动画的轻量级对象，使用Tweeners。

描述

Tween主要用于需要在一系列值上插值数值属性的动画。tween这个名字来源于in-between，这是一种动画技术，您可以指定关键帧，计算机会插值出现在它们之间的帧。用Tween制作动画被称为推特。

Tween比AnimationPlayer更适合于那些你事先不知道最终值的动画。例如，插值动态选择的摄像机变焦值最好使用Tween；很难对AnimationPlayer节点执行相同的操作。Tween也比AnimationPlayer更轻量级，因此它们非常适合简单的动画或不需要编辑器提供视觉调整的一般任务。它们可以以“即发即弃”的方式用于某些通常由代码完成的逻辑。例如，您可以通过使用带有延迟的循环CallbackTweener来定期拍摄。

Tween可以通过以下方式创建SceneTree.create_tween()或Item.create_tween()。手动创建的Tween（即使用Tween.new()）无效，不能用于对值进行推特处理。

通过在tween对象中添加Tweener，使用tween_property()，tween_interval()，tween_callback()或tween_method()，来创建tween动画：

S3ScriptC#

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

此序列将使$Sprite节点变为红色，然后收缩，最后调用Item.queue_free()释放精灵。Tweener默认情况下是一个接一个执行的。可以使用以下命令更改此行为parallel()和set_parallel()。

当使用tween_*方法之一创建Tweener时，可以使用链式方法调用来调整此Tweener。例如，如果要在上例中设置不同的转换类型，可以使用set_trans()：

S3ScriptC#

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

大多数Tween方法也可以这样链接。在下面的示例中，Tween绑定到正在运行的脚本的节点，并为其设置默认转换Tweener:

S3ScriptC#

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

Tween的另一个有趣的用途是为任意对象集设置动画：

S3ScriptC#

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

在上面的示例中，节点的所有子节点都被逐个移动到位置（0, 0）。

应该避免对每个对象的属性使用多个Tween。如果两个或多个tween同时为一个属性设置动画，则最后创建的属性将具有优先级并指定最终值。如果要中断并重新启动动画，请考虑将Tween指定给变量：

S3ScriptC#

var tween
func animate():
    if tween:
        tween.kill() # Abort the previous animation.
    tween = create_tween()

一些Tweener会使用过渡和缓动。第一个接受一个TransitionType常量，指的是处理动画时间的方式。第二个接受一个EaseType常量，并控制trans_type应用于插值的位置（在开头、结尾或两者均有）。如果不知道该选择哪种过渡和缓动，可以尝试使用EASE_IN_OUT并配合不同TransitionType常量，并使用看起来最好的那个。

注意：Tween不是为重用而设计的，尝试这样做会导致未定义的行为。为每个动画创建一个新的Tween，并在每次从头回放动画时创建一个Tween。请记住，Tween会立即启动，因此只有在希望开始设置动画时才创建Tween。

注意： 该补间在当前帧中的所有节点之后进行处理，即节点的Item.Update()方法（或Item.FixedUpdate()，具体取决于传递给set_process_mode()的值）会在补间之前被调用。

方法

Tween	bind_node(node: Item)
Tween	chain()
bool	custom_step(delta: float)
int	get_loops_left() const
float	get_total_elapsed_time() 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()
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: ItemPath, 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) 🔗

当Tweener的一个步骤完成时发出，提供步骤索引。一个步骤是单个Tweener或一组Tweener并行运行。

---

枚举

enum TweenProcessMode: 🔗

TweenProcessMode TWEEN_PROCESS_PHYSICS = 0

Tween在每个物理帧后更新（参见Item.FixedUpdate()）。

TweenProcessMode TWEEN_PROCESS_IDLE = 1

Tween在每个进程帧之后更新（参见Item.Update()）。

---

enum TweenPauseMode: 🔗

TweenPauseMode TWEEN_PAUSE_BOUND = 0

如果Tween有一个绑定节点，它将在该节点可以处理时进行处理（参见Item.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: Item) 🔗

将此Tween与给定的node绑定。Tween直接由SceneTree处理，因此它们独立于动画节点运行。当您将Item与Tween绑定时，当对象不在树内时，Tween将停止动画，当绑定的对象被释放时，Tween将自动终止。此外，TWEEN_PAUSE_BOUND将使暂停行为依赖于绑定的节点。

对于创建和绑定Tween的更短方法，您可以使用Item.create_tween()。

---

Tween chain() 🔗

用于在使用 true 调用 set_parallel() 后链接两个 Tweener。

S3ScriptC#

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暂停时的手动控制非常有用。它也可以用于立即结束Tween动画，方法是将delta设置为长于Tween动画的整个持续时间。

如果Tween仍然有Tween尚未完成，则返回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持续时间。

---

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不能附加Tweeners。

---

void kill() 🔗

中止所有修剪操作并使Tween无效。

---

Tween parallel() 🔗

使下一个 Tweener 与前一个并行运行。

S3ScriptC#

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

示例中的所有 Tweener 都将同时运行。

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

---

void pause() 🔗

暂停调整。可以使用play()恢复动画。

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

---

void play() 🔗

恢复暂停或停止的Tween。

---

Tween set_ease(ease: EaseType) 🔗

设置在此方法之后附加的 PropertyTweener 和 MethodTweener 的默认缓动类型。

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

var tween = create_tween()
tween.tween_property(self, "position", Vector2(300, 0), 0.5) # 使用缓入缓出效果。
tween.set_ease(Tween.EASE_IN)
tween.tween_property(self, "rotation_degrees", 45.0, 0.5) # 使用缓入效果。

---

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) # Runs together with the position tweener.

---

Tween set_pause_mode(mode: TweenPauseMode) 🔗

确定SceneTree暂停时Tween的行为。检查TweenPauseMode的选项。

默认值为TWEEN_PAUSE_BOUND。

---

Tween set_process_mode(mode: TweenProcessMode) 🔗

确定Tween是否应该在进程帧（参见Item.Update()）或物理帧（参见Item.FixedUpdate()）之后运行。

默认值为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

# 现在将从（大约）250 增加到 500，这一过程将在 1 秒钟内完成。
# 现在将从（大约）250 增加到 500，这一过程将在 1 秒钟内完成，速度是之前的一半。
tween.stop()
tween.play()

注意： 如果一个补间动画（Tween）已停止且未绑定到任何节点，它将无限期存在，直到手动启动或失效。如果你丢失了对这样的补间动画的引用，可以使用 SceneTree.get_processed_tweens() 来检索它。

---

CallbackTweener tween_callback(callback: Callable) 🔗

创建并追加一个CallbackTweener。此方法可用于调用任何对象中的任意方法。使用Callable.bind()为调用绑定其他参数。

示例:每1秒持续射击的对象：

S3ScriptC#

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

示例:将一个精灵先变红，然后变蓝，延迟2秒：

S3ScriptC#

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 是间隔的时长，单位为秒。

Example:在代码执行中创建一个间隔：:

S3ScriptC#

# ... 一些代码
await create_tween().tween_interval(2).finished
# ... 更多代码

示例:创建一个来回移动并每隔几秒跳跃一次的对象:

S3ScriptC#

var tween = create_tween().set_loops()
tween.tween_property($Sprite, "position:x", 200.0, 1).as_relative()
tween.tween_callback(jump)
tween.tween_interval(2)
tween.tween_property($Sprite, "position:x", -200.0, 1).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() 来延迟补间动画。

Example:使一个 3D 对象从一个点看向另一个点： .. tabs:

.. code-tab:: s3script

   var tween = create_tween()
   tween.tween_method(look_at.bind(Vector3.UP), Vector3(-1, 0, -1), Vector3(1, 0, -1), 1) # look_at() 方法将向量作为第二个参数来使用。

.. code-tab:: csharp

   Tween tween = CreateTween();
   tween.TweenMethod(Callable.From((Vector3 target) => LookAt(target, Vector3.Up)), new Vector3(-1.0f, 0.0f, -1.0f), new Vector3(1.0f, 0.0f, -1.0f), 1.0f); // 使用 lambda 表达式来为调用操作绑定额外的参数。

示例：使用中间方法并在延迟后设置 Label 的文本：

S3ScriptC#

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: ItemPath, final_val: Variant, duration: float) 🔗

创建并追加一个 PropertyTweener。此方法在等于 duration（以秒为单位）的时间段内，在初始值和 final_val 之间对 object 的 property 进行补间。默认情况下，初始值是 PropertyTweener 开始补间时该属性的值。

S3ScriptC#

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

将精灵移动到位置 (100, 200)，然后再移动到 (200, 300)。如果你使用 PropertyTweener.from() 或 PropertyTweener.from_current()，起始位置将被给定的值覆盖。查看 PropertyTweener 中的其他方法，了解如何进一步调整补间动画。

注意：你可以通过将鼠标悬停在检查器中的属性上来找到正确的属性名称。你还可以通过使用"property:component"（例如position:x）直接提供属性的组件，这样它将只应用于该特定组件。

示例：从相同位置以不同过渡类型移动一个对象两次：

S3ScriptC#

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

---

SubtweenTweener tween_subtween(subtween: Tween) 🔗

创建并追加一个 SubtweenTweener。此方法可用于将 subtween 嵌套在此 Tween 中，从而能够创建更复杂且可组合的序列。

# Subtween 会旋转该物体。
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 卡在子补间步骤上；有关更多信息，请参阅这些方法的文档。

注意：由 [method 设置的暂停和处理模式。