Tween

Наследует: RefCounted < Object

Легкий объект, используемый для универсальной анимации через скрипт с использованием Tweener.

Описание

Tween, в основном, полезны для анимаций, требующих интерполяции числового свойства по диапазону значений. Название tween происходит от in-betweening, техники анимации, при которой вы указываете ключевые кадры, а компьютер интерполирует кадры, которые появляются между ними. Анимация чего-либо с помощью Tween называется созданием промежуточных кадров.

Tween больше подходит, чем AnimationPlayer, для анимаций, где заранее неизвестны конечные значения. Например, интерполяцию динамически выбранного значения масштабирования камеры лучше всего осуществлять с помощью Tween; сделать то же самое с помощью узла AnimationPlayer будет сложно. Анимированные анимации также более легковесны, чем AnimationPlayer, поэтому они отлично подходят для простых анимаций или общих задач, не требующих визуальной настройки, предоставляемой редактором. Их можно использовать по принципу «запустил и забыл» для некоторой логики, которая обычно выполняется с помощью кода. Например, можно заставить что-то периодически стрелять, используя циклический CallbackTweener с задержкой.

Tween можно создать с помощью SceneTree.create_tween() или Node.create_tween(). Tween-ы, созданные вручную (т. е. с помощью Tween.new()), недействительны и не могут использоваться для значений tween.

Анимация перехода между кадрами создается путем добавления Tweener к объекту Tween с помощью tween_property(), tween_interval(), tween_callback() или tween_method():

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

Когда Tweener создается с помощью одного из методов tween_*, можно использовать цепочку вызовов методов для настройки свойств этого Tweener. Например, если вы хотите установить другой тип перехода в приведенном выше примере, вы можете использовать set_trans():

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 привязан к узлу работающего скрипта, а для его Tweener-ы установлены в переход по умолчанию:

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-ов — анимация произвольных наборов объектов:

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

В приведенном выше примере все дочерние элементы узла перемещаются один за другим в позицию (0, 0).

Следует избегать использования более одного Tween на одно свойство объекта. Если два или более tweens одновременно анимируют одно свойство, то последний созданный tween будет иметь приоритет и назначит окончательное значение. Если вы хотите прервать и возобновить анимацию, рассмотрите возможность назначения Tween переменной:

var tween
func animate():
    if tween:
        tween.kill() # Отменить предыдущую анимацию.
    tween = create_tween()

Некоторые Tweener-ы используют переходы и замедления. Первый принимает константу TransitionType и определяет способ обработки времени анимации (см. easings.net для некоторых примеров). Второй принимает константу EaseType и управляет тем, где trans_type применяется к интерполяции (в начале, в конце или в обоих случаях). Если вы не знаете, какой переход и замедление выбрать, вы можете попробовать разные константы TransitionType с EASE_IN_OUT и использовать ту, которая выглядит лучше всего.

Шпаргалка по типам анимации и переходов

Примечание: Tween-ы не предназначены для повторного использования, и попытка сделать это приводит к непредсказуемому поведению. Создавайте новый Tween для каждой анимации и каждый раз, когда вы воспроизводите анимацию с самого начала. Помните, что Tween-ы запускаются немедленно, поэтому создавайте Tween только тогда, когда хотите начать анимацию.

Примечание: Анимация обрабатывается после всех узлов в текущем кадре, т.е. метод узла Node._process() будет вызван до анимации (или Node._physics_process() в зависимости от значения, переданного в 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

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: 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.

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.

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 работать параллельно предыдущему.

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

Устанавливает тип плавности по умолчанию для PropertyTweener и MethodTweener, добавленных после этого метода.

Перед вызовом этого метода тип плавности по умолчанию — EASE_IN_OUT.

var tween = create_tween()
tween.tween_property(self, "position", Vector2(300, 0), 0.5) # Использует EASE_IN_OUT.
tween.set_ease(Tween.EASE_IN)
tween.tween_property(self, "rotation_degrees", 45.0, 0.5) # Использует 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().

CallbackTweener tween_callback(callback: Callable) 🔗

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

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

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

Пример: Окрашиваем спрайт в красный, а затем в синий цвет с задержкой в 2 секунды:

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 — это длина интервала в секундах.

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

# ... какой-то код
await create_tween().tween_interval(2).finished
# ... больше кода

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

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-объект смотреть из одной точки в другую:

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 с использованием промежуточного метода и после задержки:

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.

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), где это будет применяться только к этому конкретному компоненту.

Пример: Перемещение объекта дважды из одной и той же позиции с разными типами перехода:

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.