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 are mostly useful for animations requiring a numerical property to be interpolated over a range of values. The name tween comes from in-betweening, an animation technique where you specify keyframes and the computer interpolates the frames that appear between them. Animating something with a Tween is called tweening.

Tween is more suited than AnimationPlayer for animations where you don't know the final values in advance. For example, interpolating a dynamically-chosen camera zoom value is best done with a Tween; it would be difficult to do the same thing with an AnimationPlayer node. Tweens are also more light-weight than AnimationPlayer, so they are very much suited for simple animations or general tasks that don't require visual tweaking provided by the editor. They can be used in a "fire-and-forget" manner for some logic that normally would be done by code. You can e.g. make something shoot periodically by using a looped CallbackTweener with a delay.

A Tween can be created by using either SceneTree.create_tween() or Node.create_tween(). Tweens created manually (i.e. by using Tween.new()) are invalid and can't be used for tweening values.

A tween animation is created by adding Tweeners to the Tween object, using tween_property(), tween_interval(), tween_callback(), tween_method(), tween_subtween(), or tween_await():

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)

This sequence will make the $Sprite node turn red, then shrink, before finally calling Node.queue_free() to free the sprite. Tweeners are executed one after another by default. This behavior can be changed using parallel() and set_parallel().

When a Tweener is created with one of the tween_* methods, a chained method call can be used to tweak the properties of this Tweener. For example, if you want to set a different transition type in the above example, you can use 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)

Most of the Tween methods can be chained this way too. In the following example the Tween is bound to the running script's node and a default transition is set for its 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)

Another interesting use for Tweens is animating arbitrary sets of objects:

GDScriptC#

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

In the example above, all children of a node are moved one after another to position (0, 0).

You should avoid using more than one Tween per object's property. If two or more tweens animate one property at the same time, the last one created will take priority and assign the final value. If you want to interrupt and restart an animation, consider assigning the Tween to a variable:

GDScriptC#

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

Some Tweeners use transitions and eases. The first accepts a TransitionType constant, and refers to the way the timing of the animation is handled (see easings.net for some examples). The second accepts an EaseType constant, and controls where the trans_type is applied to the interpolation (in the beginning, the end, or both). If you don't know which transition and easing to pick, you can try different TransitionType constants with EASE_IN_OUT, and use the one that looks best.

Tween easing and transition types cheatsheet

Note: Tweens are not designed to be reused and trying to do so results in an undefined behavior. Create a new Tween for each animation and every time you replay an animation from start. Keep in mind that Tweens start immediately, so only create a Tween when you want to start animating.

Note: The tween is processed after all of the nodes in the current frame, i.e. node's Node._process() method would be called before the tween (or Node._physics_process() depending on the value passed to set_process_mode()).

Методы

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

Tween будет обрабатываться независимо от того, приостановлено ли SceneTree.

---

enum TransitionType: 🔗

TransitionType TRANS_LINEAR = 0

Анимация интерполируется линейно.

TransitionType TRANS_SINE = 1

Анимация интерполируется с использованием синусоидальной функции.

TransitionType TRANS_QUINT = 2

Анимация интерполируется с помощью функции пятой степени.

TransitionType TRANS_QUART = 3

Анимация интерполируется с помощью функции четвертой степени.

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, поэтому они запускаются независимо от анимированных узлов. Когда вы связываете Node с Tween, Tween остановит анимацию, когда объект не находится внутри дерева, и Tween будет автоматически завершен, когда связанный объект будет освобожден. Также TWEEN_PAUSE_BOUND сделает поведение паузы зависимым от связанного узла.

Для более короткого способа создания и привязки Tween вы можете использовать Node.create_tween().

---

Tween chain() 🔗

Используется для связывания двух Tweener после вызова set_parallel() с true.

GDScriptC#

var tween = create_tween().set_parallel(true)
tween.tween_property(...)
tween.tween_property(...) # Будет работать параллельно с предыдущим.
tween.chain().tween_property(...) # Будет запущен после завершения двух вышеуказанных действий.

---

bool custom_step(delta: float) 🔗

Обрабатывает Tween по заданному значению delta в секундах. Это в основном полезно для ручного управления, когда Tween приостановлен. Его также можно использовать для немедленного завершения анимации Tween, установив delta больше, чем вся продолжительность анимации Tween.

Возвращает true, если Tween все еще имеет Tweener, которые не были завершены.

---

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 🔗

Returns true if any Tweener has been added to the Tween and the Tween is valid. Useful when tweeners are added dynamically and the tween can end up empty. Killing an empty tween before it starts will prevent errors.

---

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, уничтожения или при создании с помощью 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(...)

Все Tween-ы в примере будут запущены одновременно.

Вы можете сделать Tween параллельным по умолчанию, используя set_parallel().

---

void pause() 🔗

Приостанавливает tween. Анимацию можно возобновить с помощью play().

Примечание: Если Tween приостановлен и не привязан ни к одному узлу, он будет существовать бесконечно, пока не будет запущен вручную или не станет недействительным. Если вы потеряете ссылку на такой Tween, вы можете восстановить его с помощью SceneTree.get_processed_tweens().

---

void play() 🔗

Возобновляет приостановленный или остановленный Tween.

---

Tween set_ease(ease: EaseType) 🔗

Sets the default ease type for PropertyTweeners and MethodTweeners appended after this method.

Before this method is called, the default ease type is 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) 🔗

Устанавливает количество повторений последовательности tween, т. е. set_loops(2) запустит анимацию дважды.

Вызов этого метода без аргументов заставит Tween работать бесконечно, пока он не будет убит с помощью kill(), связанный узел Tween не будет освобожден или все анимированные объекты не будут освобождены (что делает дальнейшую анимацию невозможной).

Предупреждение: Обязательно всегда добавляйте некоторую длительность/задержку при использовании бесконечных циклов. Чтобы предотвратить зависание игры, циклические анимации с нулевой длительностью (например, один CallbackTweener без задержки) останавливаются после небольшого количества циклов, что может привести к неожиданным результатам. Если время жизни Tween зависит от какого-либо узла, всегда используйте bind_node().

---

Tween set_parallel(parallel: bool = true) 🔗

Если parallel равен true, то Tweener, добавленный после этого метода, по умолчанию будет выполняться одновременно, а не последовательно.

Примечание: Как и в случае с parallel(), tweener, добавленный непосредственно перед этим методом, также будет частью параллельного шага.

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

Масштабирует скорость tweening. Это влияет на все 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() 🔗

Останавливает tweening и сбрасывает Tween в его начальное состояние. Это не удалит никакие добавленные Tweener.

Примечание: Это не сбрасывает цели PropertyTweener к их значениям, когда Tween был запущен впервые.

var tween = create_tween()

# Будет изменяться от 0 до 500 за 1 секунду.
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 секунду,
# таким образом, с половинной скоростью, чем раньше.
tween.stop()
tween.play()

Примечание: Если Tween остановлен и не привязан ни к одному узлу, он будет существовать бесконечно, пока не будет запущен вручную или не станет недействительным. Если вы потеряете ссылку на такой Tween, вы можете восстановить его с помощью SceneTree.get_processed_tweens().

---

AwaitTweener tween_await(signal: Signal) 🔗

Creates and appends an AwaitTweener. This method can be used to await a signal to be emitted and create asynchronous animations or cutscenes.

The animation will not progress to the next step until the awaited signal is emitted or the connection becomes invalid (e.g. as a result of freeing the target object). If you know that the emission may not happen, use AwaitTweener.set_timeout().

Note: The awaited signal should be emitted during the step when AwaitTweener is active.

Example: An object launches itself and explodes upon collision or after 4 seconds.

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

Example: A character walks to a specific point, says some lines and walks back when the player closes the message box.

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

Note: If you are awaiting a signal from a callback called in the same Tween, make sure the signal is emitted after the await starts. If it can't be reasonably guaranteed, you can await and emit in the same step:

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

---

CallbackTweener tween_callback(callback: Callable) 🔗

Создает и добавляет CallbackTweener. Этот метод можно использовать для вызова произвольного метода в любом объекте. Используйте Callable.bind() для привязки дополнительных аргументов для вызова.

Пример: Объект, который продолжает стрелять каждую секунду:

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. Этот метод можно использовать для создания задержек в анимации tween, как альтернативу использованию задержки в других Tween или когда нет анимации (в этом случае Tween действует как таймер). time — это длина интервала в секундах.

Пример: Создание интервала при выполнении кода:

GDScriptC#

# ... какой-то код
await 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(). Он вызывает метод с течением времени с tween-значением, предоставленным в качестве аргумента. Значение tween-значение между from и to в течение времени, указанного duration в секундах. Используйте Callable.bind(), чтобы привязать дополнительные аргументы для вызова. Вы можете использовать MethodTweener.set_ease() и MethodTweener.set_trans(), чтобы настроить смягчение и переход значения или MethodTweener.set_delay(), чтобы задержать tween-значение.

Пример: Заставить 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.0).set_delay(1.0)

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

---

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

Создает и добавляет PropertyTweener. Этот метод делает промежуток между property object между начальным значением и 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, чтобы увидеть, как можно дополнительно настроить анимацию.

Примечание: Вы можете найти правильное имя свойства, наведя курсор на свойство в Инспекторе. Вы также можете указать компоненты свойства напрямую, используя "property:component" (например, 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, что позволяет создавать более сложные и компонуемые последовательности.

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

# Родительский tween выполнит subtween как один из своих шагов.
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 застрянет на шаге subtween; для получения дополнительной информации см. документацию по этим методам.

Примечание: Режимы паузы и обработки, установленные set_pause_mode() и set_process_mode() в subtween, будут переопределены настройками родительского Tween.