Tween

Успадковує: RefCounted < Object

Легкий об'єкт, який використовується для універсальної анімації через скрипт, використовуючи Tweeners.

Опис

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

Tween більше підходить, ніж AnimationPlayer, для анімацій, де кінцеві значення заздалегідь не відомі. Наприклад, інтерполяцію динамічно вибраного значення масштабування камери найкраще виконувати за допомогою вузла Tween; було б важко зробити те саме з вузлом AnimationPlayer. Твінз також легші, ніж AnimationPlayer, тому вони дуже підходять для простих анімацій або загальних завдань, які не потребують візуального налаштування, що надається редактором. Їх можна використовувати за принципом "запустив і забув" для певної логіки, яка зазвичай виконується кодом. Наприклад, ви можете змусити щось періодично зніматися, використовуючи зациклений CallbackTweener із затримкою.

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

Анімація 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 на кожну властивість об'єкта. Якщо два або більше 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() буде викликаний перед tween (або 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

Анімація переповнена хінтовою (до потужності 5) функцією.

TransitionType TRANS_QUART = 3

Анімація переповнена за допомогою квартичного (до потужності 4) функції.

TransitionType TRANS_QUAD = 4

Анімація переповнена квадроциклом (до потужності 2) функції.

TransitionType TRANS_EXPO = 5

Анімація переповнена за допомогою параметра (до потужності х).

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. Tweens обробляються безпосередньо 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.new(). Invalid Tweens не може Tweeners Додатки.

void kill() 🔗

Визначте всі операції та недійсні дії Подивитися.

Tween parallel() 🔗

Змушує наступний Tweener працювати паралельно з попереднім.

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

Усі Tweener у прикладі запускатимуться одночасно.

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

void pause() 🔗

Запобігає товщині. Анімація можна відновити за допомогою 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) 🔗

Налаштовує кількість разів послідовність віджиму буде повторюватися, тобто set_loops(2) запустить анімацію двічі.

Зателефонувавши цей метод без аргументів, виконайте Tween нескінченно, доки він загинув з вбивства(), вузол Tween звільняється, або всі анімовані об'єкти були звільнені (що робить подальшу анімацію неможливо).

Попередження: Переконайтеся, що завжди додають деяку тривалість / витримку при використанні нескінченних петель. Щоб запобігти заморожуванню гри, 0-duration петлі анімація (наприклад, єдиний 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()

# Зміниться від 0 до 500 протягом 1 секунди.
position.x = 0,0
tween.tween_property(self, "position:x", 500, 1.0)

# Коли таймер закінчиться, буде (приблизно) 250.
очікувати 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() для прив'язки додаткових аргументів для виклику.

Приклад: Об'єкт, який продовжує стріляти кожну 1 секунду:

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, як альтернативу використанню затримки в інших Tweener, або коли анімація відсутня (у цьому випадку 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()Він викликає метод з часом, передаючи змінене значення як аргумент. Значення змінюється між from та to протягом часу, заданого duration, у секундах. Використання Callable.bind() щоб прив’язати додаткові аргументи до виклику. Ви можете використовувати MethodTweener.set_ease() та MethodTweener.set_trans() для налаштування згладжування та переходу значення або MethodTweener.set_delay() для затримки твінінгу.

Приклад: Змусити 3D-об'єкт виглядати з однієї точки в іншу:

var tween = create_tween()
tween.tween_method(look_at.bind(Vector3.UP), Vector3(-1, 0, -1), Vector3(1, 0, -1), 1.0) # The look_at() method takes up vector as second argument.

Приклад: Встановлення тексту 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)

# Батьківський анімаційний проміжок виконає підпроміжок як один із своїх кроків.
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)

Примітка: ** Методи :ref:`pause()<class_Tween_method_pause>`, :ref:`stop()<class_Tween_method_stop>` і :ref:`set_loops()<class_Tween_method_set_loops>` можуть призвести до того, що батьківський **Tween застрягне на кроці subtween; дивіться документацію для цих методів для отримання додаткової інформації.

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