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

AnimationMixer

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

Успадковано від: AnimationPlayer, AnimationTree

Базовий клас для AnimationPlayer і AnimationTree.

Опис

Базовий клас для AnimationPlayer і AnimationTree для керування списками анімації. Він також має загальні властивості та методи для відтворення та змішування.

Після створення екземпляра даних інформації про відтворення в розширеному класі змішування обробляється AnimationMixer.

Посібники

Властивості

bool

active

true

int

audio_max_polyphony

32

AnimationCallbackModeDiscrete

callback_mode_discrete

1

AnimationCallbackModeMethod

callback_mode_method

0

AnimationCallbackModeProcess

callback_mode_process

1

bool

deterministic

false

bool

reset_on_save

true

bool

root_motion_local

false

NodePath

root_motion_track

NodePath("")

NodePath

root_node

NodePath("..")

Методи

Variant

_post_process_key_value(animation: Animation, track: int, value: Variant, object_id: int, object_sub_idx: int) virtual const

Error

add_animation_library(name: StringName, library: AnimationLibrary)

void

advance(delta: float)

void

capture(name: StringName, duration: float, trans_type: TransitionType = 0, ease_type: EaseType = 0)

void

clear_caches()

StringName

find_animation(animation: Animation) const

StringName

find_animation_library(animation: Animation) const

Animation

get_animation(name: StringName) const

AnimationLibrary

get_animation_library(name: StringName) const

Array[StringName]

get_animation_library_list() const

PackedStringArray

get_animation_list() const

Vector3

get_root_motion_position() const

Vector3

get_root_motion_position_accumulator() const

Quaternion

get_root_motion_rotation() const

Quaternion

get_root_motion_rotation_accumulator() const

Vector3

get_root_motion_scale() const

Vector3

get_root_motion_scale_accumulator() const

bool

has_animation(name: StringName) const

bool

has_animation_library(name: StringName) const

void

remove_animation_library(name: StringName)

void

rename_animation_library(name: StringName, newname: StringName)

Сигнали

animation_finished(anim_name: StringName) 🔗

Сповіщає про завершення відтворення анімації.

Примітка: Цей сигнал не випромінюється, якщо анімація зациклена.

animation_libraries_updated() 🔗

Сповіщає про зміни в бібліотеках анімації.

animation_list_changed() 🔗

Сповіщає про зміну списку анімацій.

animation_started(anim_name: StringName) 🔗

Сповіщає про початок відтворення анімації.

Примітка: Цей сигнал не випромінюється, якщо анімація відтворюється зациклено.

caches_cleared() 🔗

Сповіщає про очищення кешів, автоматично або вручну, за допомогою clear_caches().

mixer_applied() 🔗

Повідомляє, коли результат змішування застосовано до цільових об’єктів.

mixer_updated() 🔗

Повідомляє про оновлення процесу, пов’язаного з властивостями.

Переліки

enum AnimationCallbackModeProcess: 🔗

AnimationCallbackModeProcess ANIMATION_CALLBACK_MODE_PROCESS_PHYSICS = 0

Анімація процесу під час кадрів фізики (див. Node.NOTIFICATION_INTERNAL_PHYSICS_PROCESS). Це особливо корисно під час анімації фізичних тіл.

AnimationCallbackModeProcess ANIMATION_CALLBACK_MODE_PROCESS_IDLE = 1

Анімація процесу під час кадрів процесу (див. Node.NOTIFICATION_INTERNAL_PROCESS).

AnimationCallbackModeProcess ANIMATION_CALLBACK_MODE_PROCESS_MANUAL = 2

Не обробляти анімацію. Використовуйте advance(), щоб обробити анімацію вручну.

enum AnimationCallbackModeMethod: 🔗

AnimationCallbackModeMethod ANIMATION_CALLBACK_MODE_METHOD_DEFERRED = 0

Пакетні виклики методів під час процесу анімації, а потім виклики після обробки подій. Це дозволяє уникнути помилок, пов'язаних з видаленням вузлів або модифікацією AnimationPlayer під час відтворення.

AnimationCallbackModeMethod ANIMATION_CALLBACK_MODE_METHOD_IMMEDIATE = 1

Виклики методом робляться одразу після його досягнення в анімації.

enum AnimationCallbackModeDiscrete: 🔗

AnimationCallbackModeDiscrete ANIMATION_CALLBACK_MODE_DISCRETE_DOMINANT = 0

Значення доріжки Animation.UPDATE_DISCRETE має перевагу під час змішування значень доріжки Animation.UPDATE_CONTINUOUS або Animation.UPDATE_CAPTURE і значень доріжки Animation.UPDATE_DISCRETE.

AnimationCallbackModeDiscrete ANIMATION_CALLBACK_MODE_DISCRETE_RECESSIVE = 1

Значення доріжки Animation.UPDATE_CONTINUOUS або Animation.UPDATE_CAPTURE має перевагу під час змішування значень доріжки Animation.UPDATE_CONTINUOUS або Animation.UPDATE_CAPTURE і значень доріжки Animation.UPDATE_DISCRETE. Це типова поведінка для AnimationPlayer.

AnimationCallbackModeDiscrete ANIMATION_CALLBACK_MODE_DISCRETE_FORCE_CONTINUOUS = 2

Завжди обробляйте значення доріжки Animation.UPDATE_DISCRETE як Animation.UPDATE_CONTINUOUS із Animation.INTERPOLATION_NEAREST. Це стандартна поведінка для AnimationTree.

Якщо трек значень має неінтерполюємі значення типу ключа, вона внутрішньо перетворюється для використання ANIMATION_CALLBACK_MODE_DISCRETE_RECESSIVE із Animation.UPDATE_DISCRETE.

Список типів, що не підлягають інтерполяції:

@GlobalScope.TYPE_BOOL і @GlobalScope.TYPE_INT розглядаються як @GlobalScope.TYPE_FLOAT під час змішування та округлюються під час отримання результату.

Те ж саме для масивів і векторів з ними, наприклад @GlobalScope.TYPE_PACKED_INT32_ARRAY або @GlobalScope.TYPE_VECTOR2I, вони обробляються як @GlobalScope.TYPE_PACKED_FLOAT32_ARRAY або @GlobalScope.TYPE_VECTOR2. Також зауважте, що для масивів розмір також інтерполюється.

@GlobalScope.TYPE_STRING і @GlobalScope.TYPE_STRING_NAME інтерполюються між кодами символів і довжиною, але зауважте, що існує різниця в алгоритмі між інтерполяцією між ключами та інтерполяцією шляхом змішування.

Описи властивостей

bool active = true 🔗

  • void set_active(value: bool)

  • bool is_active()

Якщо true, AnimationMixer оброблятиме.

int audio_max_polyphony = 32 🔗

  • void set_audio_max_polyphony(value: int)

  • int get_audio_max_polyphony()

Кількість можливих одночасних звуків для кожного з призначених AudioStreamPlayers.

Наприклад, якщо це значення дорівнює 32 і анімація має дві звукові доріжки, два призначені AudioStreamPlayer можуть відтворювати одночасно до 32 голосів кожен.

AnimationCallbackModeDiscrete callback_mode_discrete = 1 🔗

Зазвичай для доріжок можна встановити значення Animation.UPDATE_DISCRETE для нечастого оновлення, як правило, під час використання найближчої інтерполяції.

Однак під час змішування з Animation.UPDATE_CONTINUOUS враховуються кілька результатів. callback_mode_discrete вказує це явно. Дивіться також AnimationCallbackModeDiscrete.

Щоб результати змішування мали гарний вигляд, рекомендується встановити це значення на ANIMATION_CALLBACK_MODE_DISCRETE_FORCE_CONTINUOUS для оновлення кожного кадра під час змішування. Існують інші значення для сумісності, і вони підходять, якщо немає змішування, але інакше можуть виникнути артефакти.

AnimationCallbackModeMethod callback_mode_method = 0 🔗

Режим виклику, який використовується для треків "Метод виклику".

AnimationCallbackModeProcess callback_mode_process = 1 🔗

Сповіщення про процес, в якому потрібно оновити анімацію.

bool deterministic = false 🔗

  • void set_deterministic(value: bool)

  • bool is_deterministic()

Якщо true, змішування використовує детермінований алгоритм. Загальна вага не нормалізується, а результат накопичується з початковим значенням (0 або анімація "RESET", якщо є).

Це означає, що якщо загальна кількість змішування становить 0,0, результат дорівнює анімації "RESET".

Якщо кількість доріжок між змішаними анімаціями різна, анімація з відсутньою доріжкою розглядається так, ніби вона мала початкове значення.

Якщо false, суміш не використовує детермінований алгоритм. Загальна вага нормалізується і завжди 1.0. Якщо кількість доріжок між змішаними анімаціями різна, нічого не буде зроблено щодо анімації, у якій відсутня доріжка.

Примітка. У AnimationTree змішування з AnimationNodeAdd2, AnimationNodeAdd3, AnimationNodeSub2 або вагою, більшою за 1.0, може призвести до несподіваних результатів.

Наприклад, якщо AnimationNodeAdd2 поєднує два вузли з кількістю 1.0, тоді загальна вага буде 2.0, але вона буде нормалізована, щоб зробити загальну кількість 1.0 і результат дорівнюватиме AnimationNodeBlend2 із значенням 0,5.

bool reset_on_save = true 🔗

  • void set_reset_on_save_enabled(value: bool)

  • bool is_reset_on_save_enabled()

Цей параметр використовується редактором. Якщо встановлено значення true, сцену буде збережено з ефектами анімації скидання (анімація з ключем "RESET"), застосованими так, ніби її було створено в момент часу 0, при цьому редактор збереже значення, які сцена мала перед збереженням.

Це робить зручнішим попередній перегляд і редагування анімації у редакторі, оскільки зміни у сцені не будуть збережені, доки вони встановлені в анімації скидання.

bool root_motion_local = false 🔗

  • void set_root_motion_local(value: bool)

  • bool is_root_motion_local()

Якщо true, значення get_root_motion_position() витягується як значення локального перекладу перед змішуванням. Іншими словами, це трактується так, ніби переклад виконується після обертання.

NodePath root_motion_track = NodePath("") 🔗

  • void set_root_motion_track(value: NodePath)

  • NodePath get_root_motion_track()

Шлях до доріжки анімації, яка використовується для основного руху. Шляхи мають бути дійсними шляхами дерева сцен до вузла та мають бути вказані, починаючи з батьківського вузла вузла, який відтворюватиме анімацію. root_motion_track використовує той самий формат, що й Animation.track_set_path(), але зауважте, що потрібно вказати кістку.

Якщо трек має тип Animation.TYPE_POSITION_3D, Animation.TYPE_ROTATION_3D або Animation.TYPE_SCALE_3D, трансформація буде візуально скасована, а анімація залишиться на місці. Дивіться також get_root_motion_position(), get_root_motion_rotation(), get_root_motion_scale() і RootMotionView.

NodePath root_node = NodePath("..") 🔗

  • void set_root_node(value: NodePath)

  • NodePath get_root_node()

Вузол, з якого буде проходити посилання на шлях вузла.

Описи методів

Variant _post_process_key_value(animation: Animation, track: int, value: Variant, object_id: int, object_sub_idx: int) virtual const 🔗

Віртуальна функція обробки після отримання ключа під час відтворення.

Error add_animation_library(name: StringName, library: AnimationLibrary) 🔗

Додає library до програвача анімації під ключ name.

AnimationMixer за замовчуванням має глобальну бібліотеку з порожнім рядком як ключ. Щоб додати анімацію до глобальної бібліотеки:

var global_library = mixer.get_animation_library("")
global_library.add_animation("назва_анімації", ресурс_анімації)

void advance(delta: float) 🔗

Вручну перемотайте анімацію на вказаний час (у секундах).

void capture(name: StringName, duration: float, trans_type: TransitionType = 0, ease_type: EaseType = 0) 🔗

Якщо доріжка анімації, визначена name, має опцію Animation.UPDATE_CAPTURE, зберігає поточні значення об’єктів, указаних шляхом доріжки, як кеш. Якщо вже є захоплений кеш, старий кеш відкидається.

Після цього він буде інтерполювати з поточним результатом змішування анімації під час процесу відтворення протягом часу, визначеного параметром duration, працюючи як крос-фейд.

Ви можете вказати trans_type як криву для інтерполяції. Для кращих результатів може бути доцільно вказати Tween.TRANS_LINEAR для випадків, коли перша клавіша доріжки починається з ненульового значення або коли значення ключа не змінюється, і Tween.TRANS_QUAD для випадків де значення ключа змінюється лінійно.

void clear_caches() 🔗

AnimationMixer кешує анімовані вузли. Він може не помітити, якщо вузол зникне. clear_caches() змушує його знову оновити кеш.

StringName find_animation(animation: Animation) const 🔗

Повертає ключ animation або порожній StringName, якщо його не знайдено.

StringName find_animation_library(animation: Animation) const 🔗

Повертає ключ до бібліотеки AnimationLibrary, яка містить animation або порожній рядок StringName, якщо його не знайдено.

Animation get_animation(name: StringName) const 🔗

Повертає Animation за ключем name. Якщо анімації не існує, повертається null і реєструється помилка.

AnimationLibrary get_animation_library(name: StringName) const 🔗

Повертає першу AnimationLibrary з ключем name або null, якщо не знайдено.

Щоб отримати глобальну бібліотеку анімації AnimationMixer, використовуйте get_animation_library("").

Array[StringName] get_animation_library_list() const 🔗

Повертає список збережених ключів бібліотеки.

PackedStringArray get_animation_list() const 🔗

Повертає список збережених ключів анімації.

Vector3 get_root_motion_position() const 🔗

Отримайте дельту руху позиції за допомогою root_motion_track як Vector3, який можна використовувати деінде.

Якщо root_motion_track не є шляхом до треку типу Animation.TYPE_POSITION_3D, повертає Vector3(0, 0, 0).

Дивіться також root_motion_track і RootMotionView.

Найпростіший приклад — застосування позиції до CharacterBody3D:

змінна current_rotation

func _process(delta):
    if Input.is_action_just_pressed("animate"):
        current_rotation = get_quaternion()
        state_machine.travel("Анімувати")
    var velocity = current_rotation * animation_tree.get_root_motion_position() / delta
    set_velocity(velocity)
    move_and_slide()

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

func _process(delta):
    if Input.is_action_just_pressed("animate"):
        state_machine.travel("Анімувати")
    set_quaternion(get_quaternion() * animation_tree.get_root_motion_rotation())
    var velocity = (animation_tree.get_root_motion_rotation_accumulator().inverse() * get_quaternion()) * animation_tree.get_root_motion_position() / delta
    set_velocity(velocity)
    move_and_slide()

Якщо root_motion_local має значення true, повертає попередньо помножене значення перекладу з інвертованим обертанням.

У цьому випадку код можна записати наступним чином:

func _process(delta):
    if Input.is_action_just_pressed("animate"):
        state_machine.travel("Анімувати")
    set_quaternion(get_quaternion() * animation_tree.get_root_motion_rotation())
    var velocity = get_quaternion() * animation_tree.get_root_motion_position() / delta
    set_velocity(velocity)
    move_and_slide()

Vector3 get_root_motion_position_accumulator() const 🔗

Отримує змішане значення доріжок переміщення з root_motion_track як Vector3, який можна десь використати.

Це корисно у випадках, коли ви хочете зберегти початкові значення ключів анімації.

Наприклад, якщо у попередньому кадрі відтворюється анімація з одним ключем Vector3(0, 0, 0), а у наступному кадрі відтворюється анімація з одним ключем Vector3(1, 0, 1) то різницю можна обчислити наступним чином:

var prev_root_motion_position_accumulator: Vector3

func _process(delta):
    if Input.is_action_just_pressed("animate"):
        state_machine.travel("Animate")
    var current_root_motion_position_accumulator: Vector3 = animation_tree.get_root_motion_position_accumulator()
    var difference: Vector3 = current_root_motion_position_accumulator - prev_root_motion_position_accumulator
    prev_root_motion_position_accumulator = current_root_motion_position_accumulator
    transform.origin += difference

Однак, якщо анімація зациклена, може відбутися ненавмисна дискретна зміна, тому це корисно лише для деяких простих випадків використання.

Quaternion get_root_motion_rotation() const 🔗

Отримати дельту обертання з root_motion_track як Quaternion який можна десь використати.

Якщо root_motion_track не є шляхом до типу доріжку Animation.TYPE_ROTATION_3D, повертає Quaternion(0, 0, 0, 1).

Дивіться також root_motion_track і RootMotionView.

Найпростішим прикладом є застосування обертання до CharacterBody3D:

func _process(delta):
    if Input.is_action_just_pressed("animate"):
        state_machine.travel("Animate")
    set_quaternion(get_quaternion() * animation_tree.get_root_motion_rotation())

Quaternion get_root_motion_rotation_accumulator() const 🔗

Отримайте змішане значення доріжок обертання за допомогою root_motion_track як Quaternion, який можна використовувати деінде.

Це необхідно для правильного застосування положення руху кореня з урахуванням обертання. Дивіться також get_root_motion_position().

Крім того, це корисно у випадках, коли потрібно дотримуватися початкових ключових значень анімації.

Наприклад, якщо в попередньому кадрі відтворюється анімація лише з одним ключем Quaternion(0, 0, 0, 1), а потім анімація лише з одним ключем Quaternion(0, 0,707, 0, 0,707) відтворюється в наступному кадрі, різницю можна обчислити наступним чином:

   [gdscript]
   var prev_root_motion_rotation_accumulator:

   func _process(delta):
        if Input.is_action_just_pressed("animate"):
            state_machine.travel("Анімувати")
        var current_root_motion_rotation_accumulator: Quaternion = animation_tree.get_root_motion_rotation_accumulator()
        змінна різниця: Quaternion = prev_root_motion_rotation_accumulator.inverse() * current_root_motion_rotation_accumulator
        prev_root_motion_rotation_accumulator = current_root_motion_rotation_accumulator
        transform.basis *= Basis(difference)
   [/gdscript][/codeblocks]

Однак, якщо анімація повторюється, може статися ненавмисна дискретна зміна, тому це корисно лише для деяких простих випадків використання.

Vector3 get_root_motion_scale() const 🔗

Отримує дельту маштабування з root_motion_track як Vector3 який можна десь використати.

Якщо root_motion_track не є шляхом до доріжки типу Animation.TYPE_SCALE_3D, повертає Vector3(0, 0, 0).

Дивіться також root_motion_track і RootMotionView.

Найпростішим прикладом є застосування масштабування до CharacterBody3D:

var current_scale: Vector3 = Vector3(1, 1, 1)
var scale_accum: Vector3 = Vector3(1, 1, 1)

func _process(delta):
    if Input.is_action_just_pressed("animate"):
        current_scale = get_scale()
        scale_accum = Vector3(1, 1, 1)
        state_machine.travel("Animate")
    scale_accum += animation_tree.get_root_motion_scale()
    set_scale(current_scale * scale_accum)

Vector3 get_root_motion_scale_accumulator() const 🔗

Отримує змішане значення доріжок масштабування з root_motion_track як Vector3 який можна десь використати.

Наприклад, якщо у попередньому кадрі відтворено анімацію з ключем Vector3(1, 1, 1), а в наступному з ключем Vector3(2, 2, 2), то різницю можна вирахувати наступним чином:

var prev_root_motion_scale_accumulator: Vector3

func _process(delta):
    if Input.is_action_just_pressed("animate"):
        state_machine.travel("Animate")
    var current_root_motion_scale_accumulator: Vector3 = animation_tree.get_root_motion_scale_accumulator()
    var difference: Vector3 = current_root_motion_scale_accumulator - prev_root_motion_scale_accumulator
    prev_root_motion_scale_accumulator = current_root_motion_scale_accumulator
    transform.basis = transform.basis.scaled(difference)

Однак, якщо анімація зациклена, може статися ненавмисна дискретна зміна, тому це корисно лише для деяких простих випадків використання.

bool has_animation(name: StringName) const 🔗

Повертає true, якщо AnimationMixer зберігає Animation із ключем name.

bool has_animation_library(name: StringName) const 🔗

Повертає true, якщо AnimationMixer зберігає Animation із ключем name.

void remove_animation_library(name: StringName) 🔗

Видаляє AnimationLibrary, пов'язану з ключем name.

void rename_animation_library(name: StringName, newname: StringName) 🔗

Переміщує AnimationLibrary, пов'язану з ключем name, до ключа newname.