Up to date

This page is up to date for Godot 4.2. If you still find outdated information, please open an issue.

AnimationMixer¶

继承： Node < Object

派生： AnimationPlayer, AnimationTree

AnimationPlayer 和 AnimationTree 的基类。

描述¶

AnimationPlayer 和 AnimationTree 的基类，用于管理动画列表。同时还提供了用于播放和混合的常用属性和方法。

在扩展后的类中实例化播放信息数据后，就会由 AnimationMixer 负责处理混合。

属性¶

bool	active	`true`
int	audio_max_polyphony	`32`
AnimationCallbackModeMethod	callback_mode_method	`0`
AnimationCallbackModeProcess	callback_mode_process	`1`
bool	deterministic	`false`
bool	reset_on_save	`true`
NodePath	root_motion_track	`NodePath("")`
NodePath	root_node	`NodePath("..")`

方法¶

Variant	_post_process_key_value ( Animation animation, int track, Variant value, Object object, int object_idx ) virtual const
Error	add_animation_library ( StringName name, AnimationLibrary library )
void	advance ( float delta )
void	clear_caches ( )
StringName	find_animation ( Animation animation ) const
StringName	find_animation_library ( Animation animation ) const
Animation	get_animation ( StringName name ) const
AnimationLibrary	get_animation_library ( StringName name ) const
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 ( StringName name ) const
bool	has_animation_library ( StringName name ) const
void	remove_animation_library ( StringName name )
void	rename_animation_library ( StringName name, StringName newname )

信号¶

animation_finished ( StringName anim_name )

动画播放结束时通知。

注意：如果动画正在循环播放，则不会发出此信号。

animation_libraries_updated ( )

当动画库发生更改时发出通知。

animation_list_changed ( )

当动画列表发生更改时发出通知。

animation_started ( StringName anim_name )

当动画开始播放时发出通知。

caches_cleared ( )

当缓存被清除时通知，可以是自动清除，也可以是通过 clear_caches 手动清除。

mixer_updated ( )

仅用于编辑器。当属性已完成更新进而更新动画播放编辑器中的虚拟 AnimationPlayer 时发出通知。

枚举¶

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

在动画中达到时立即进行方法调用。

属性说明¶

bool active = true

void set_active ( bool value )
bool is_active ( )

如果 true 时，AnimationMixer 将执行逻辑处理。

int audio_max_polyphony = 32

void set_audio_max_polyphony ( int value )
int get_audio_max_polyphony ( )

每个指定的 AudioStreamPlayer 可能同时发出的声音的数量。

例如，如果该值为 32 并且动画有两个音轨，则分配的两个 AudioStreamPlayer 可以同时播放最多 32 个声音。

AnimationCallbackModeMethod callback_mode_method = 0

void set_callback_mode_method ( AnimationCallbackModeMethod value )
AnimationCallbackModeMethod get_callback_mode_method ( )

方法调用轨道所使用的调用模式。

AnimationCallbackModeProcess callback_mode_process = 1

void set_callback_mode_process ( AnimationCallbackModeProcess value )
AnimationCallbackModeProcess get_callback_mode_process ( )

更新动画的过程通知。

bool deterministic = false

void set_deterministic ( bool value )
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，且结果将等于取值为 0.5 的 AnimationNodeBlend2。

bool reset_on_save = true

void set_reset_on_save_enabled ( bool value )
bool is_reset_on_save_enabled ( )

由编辑器使用。如果设置为 true，场景将被保存，并应用重置动画（带有键 "RESET" 的动画）的效果，就好像它已被定位到时间 0 一样，编辑器保留场景在保存之前的值。

这使得在编辑器中预览和编辑动画更加方便，因为对场景的更改，只要在重置动画中被设置，就不会被保存。

NodePath root_motion_track = NodePath("")

void set_root_motion_track ( NodePath value )
NodePath get_root_motion_track ( )

用于根部运动的动画轨道的路径。路径必须是指向节点的场景树有效路径，必须从将实现动画的节点的父节点开始指定。要指定控件属性或骨骼的轨道，请在路径后附加其名称，用 ":" 隔开。例如，"character/skeleton:ankle" 或 "character/mesh:transform/local"。

如果轨道的类型是 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 ( NodePath value )
NodePath get_root_node ( )

节点路径引用将从其运行的节点。

方法说明¶

Variant _post_process_key_value ( Animation animation, int track, Variant value, Object object, int object_idx ) virtual const

虚函数，用于播放期间在获取关键帧之后的处理。

Error add_animation_library ( StringName name, AnimationLibrary library )

将 library 添加到该动画播放器的键 name 下。

void advance ( float delta )

手动将动画前进指定的时间（单位为秒）。

void clear_caches ( )

AnimationMixer 会缓存动画节点。如果一个节点消失，它可能不会注意到；clear_caches 能够强制它再次更新缓存。

StringName find_animation ( Animation animation ) const

返回 animation 的键；如果未找到，则返回一个空的 StringName。

StringName find_animation_library ( Animation animation ) const

返回包含 animation 的 AnimationLibrary 的键；如果找不到，则返回一个空的 StringName。

Animation get_animation ( StringName name ) const

返回带有键 name 的 Animation。如果动画不存在，则返回 null 并记录错误。

AnimationLibrary get_animation_library ( StringName name ) const

返回第一个键为 name 的 AnimationLibrary，如果没有找到则返回 null。

要获得 AnimationPlayer 的全局动画库，请使用 get_animation_library("")。

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：

var current_rotation: Quaternion

func _process(delta):
    if Input.is_action_just_pressed("animate"):
        current_rotation = get_quaternion()
        state_machine.travel("Animate")
    var velocity: Vector3 = current_rotation * animation_tree.get_root_motion_position() / delta
    set_velocity(velocity)
    move_and_slide()

通过将其与 get_root_motion_position_accumulator 结合使用，你可以更正确地应用根运动位置来考虑节点的旋转。

func _process(delta):
    if Input.is_action_just_pressed("animate"):
        state_machine.travel("Animate")
    set_quaternion(get_quaternion() * animation_tree.get_root_motion_rotation())
    var velocity: Vector3 = (animation_tree.get_root_motion_rotation_accumulator().inverse() * 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) 时，它们相差的值可以这样求出：

var prev_root_motion_rotation_accumulator: Quaternion

func _process(delta):
    if Input.is_action_just_pressed("animate"):
        state_machine.travel("Animate")
    var current_root_motion_rotation_accumulator: Quaternion = animation_tree.get_root_motion_Quaternion_accumulator()
    var difference: Quaternion = prev_root_motion_rotation_accumulator.inverse() * current_root_motion_rotation_accumulator
    prev_root_motion_rotation_accumulator = current_root_motion_rotation_accumulator
    transform.basis *= difference

然而，当一个动画循环时，可能会得到一个意料之外的变化，所以这个只在一些简单情况下才有用。

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 ( StringName name ) const

如果该 AnimationPlayer 使用键 name 存储 Animation，则返回 true。

bool has_animation_library ( StringName name ) const

如果该 AnimationPlayer 使用键 name 存储 AnimationLibrary，则返回 true。

void remove_animation_library ( StringName name )

移除与键 name 关联的 AnimationLibrary。

void rename_animation_library ( StringName name, StringName newname )

将与键 name 关联的 AnimationLibrary 移动到键 newname。