Up to date

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

AnimationPlayer

继承: AnimationMixer < Node < Object

用于播放动画的节点。

描述

动画播放器用于动画的通用播放。它包含 AnimationLibrary 资源的字典和动画过渡之间的自定义混合时间。

某些方法和属性使用单个键直接引用动画。这些键的格式为动画库的键,后跟正斜杠,然后是动画库内动画的键,例如 "movement/run"。如果动画库的键为空字符串(称为默认库),则省略正斜杠,与动画库使用相同的键。

AnimationPlayerTween 更适合用于复杂动画,例如不规则计时的动画。如果用动画轨道编辑器比用代码实现更方便,也可以优先于 Tween 使用。

更新动画的目标属性是在处理帧中进行的。

教程

属性

String

assigned_animation

String

autoplay

""

String

current_animation

""

float

current_animation_length

float

current_animation_position

bool

movie_quit_on_finish

false

float

playback_default_blend_time

0.0

float

speed_scale

1.0

方法

StringName

animation_get_next ( StringName animation_from ) const

void

animation_set_next ( StringName animation_from, StringName animation_to )

void

clear_queue ( )

float

get_blend_time ( StringName animation_from, StringName animation_to ) const

AnimationMethodCallMode

get_method_call_mode ( ) const

float

get_playing_speed ( ) const

AnimationProcessCallback

get_process_callback ( ) const

PackedStringArray

get_queue ( )

NodePath

get_root ( ) const

bool

is_playing ( ) const

void

pause ( )

void

play ( StringName name="", float custom_blend=-1, float custom_speed=1.0, bool from_end=false )

void

play_backwards ( StringName name="", float custom_blend=-1 )

void

queue ( StringName name )

void

seek ( float seconds, bool update=false, bool update_only=false )

void

set_blend_time ( StringName animation_from, StringName animation_to, float sec )

void

set_method_call_mode ( AnimationMethodCallMode mode )

void

set_process_callback ( AnimationProcessCallback mode )

void

set_root ( NodePath path )

void

stop ( bool keep_state=false )


信号

animation_changed ( StringName old_name, StringName new_name )

在前一个动画完成后,队列中的动画播放时发出。另见 queue

注意:通过 playAnimationTree 改变动画时,不会发出此信号。


current_animation_changed ( String name )

current_animation 更改时发出。


枚举

enum AnimationProcessCallback:

AnimationProcessCallback ANIMATION_PROCESS_PHYSICS = 0

用于向后兼容。见 AnimationMixer.ANIMATION_CALLBACK_MODE_PROCESS_PHYSICS

AnimationProcessCallback ANIMATION_PROCESS_IDLE = 1

用于向后兼容。见 AnimationMixer.ANIMATION_CALLBACK_MODE_PROCESS_IDLE

AnimationProcessCallback ANIMATION_PROCESS_MANUAL = 2

用于向后兼容。见 AnimationMixer.ANIMATION_CALLBACK_MODE_PROCESS_MANUAL


enum AnimationMethodCallMode:

AnimationMethodCallMode ANIMATION_METHOD_CALL_DEFERRED = 0

用于向后兼容。见 AnimationMixer.ANIMATION_CALLBACK_MODE_METHOD_DEFERRED

AnimationMethodCallMode ANIMATION_METHOD_CALL_IMMEDIATE = 1

用于向后兼容。见 AnimationMixer.ANIMATION_CALLBACK_MODE_METHOD_IMMEDIATE


属性说明

String assigned_animation

  • void set_assigned_animation ( String value )

  • String get_assigned_animation ( )

如果正在播放,则为当前动画的键,否则为上次播放的动画。设置后会改变动画,但除非已经播放,否则不会播放。另见 current_animation


String autoplay = ""

  • void set_autoplay ( String value )

  • String get_autoplay ( )

场景加载时要播放的动画名称。


String current_animation = ""

  • void set_current_animation ( String value )

  • String get_current_animation ( )

当前播放的动画的名称。如果没有动画正在播放,该属性的值是一个空字符串。改变这个值不会重新启动动画。关于播放动画的更多信息请参阅 play

注意:虽然这个属性会出现在检查器中,但它不是用来编辑的,也不会保存在场景中。该属性主要用于获取当前播放的动画,内部用于动画播放轨道。详情请参阅 Animation


float current_animation_length

  • float get_current_animation_length ( )

当前正在播放的动画的长度(以秒为单位)。


float current_animation_position

  • float get_current_animation_position ( )

当前播放的动画的位置(以秒为单位)。


bool movie_quit_on_finish = false

  • void set_movie_quit_on_finish_enabled ( bool value )

  • bool is_movie_quit_on_finish_enabled ( )

如果为 true,并且引擎在 Movie Maker 模式下运行(见 MovieWriter),则会在此 AnimationPlayer 中播放完动画后,立即使用 SceneTree.quit 退出引擎。当引擎因此而退出时,会打印一条消息。

注意:这与 AnimationMixer.animation_finished 信号遵循相同的逻辑,因此如果动画被设置为循环,它不会退出引擎。


float playback_default_blend_time = 0.0

  • void set_default_blend_time ( float value )

  • float get_default_blend_time ( )

混合动画的默认时间。范围从 0 到 4096,精度为 0.01。


float speed_scale = 1.0

  • void set_speed_scale ( float value )

  • float get_speed_scale ( )

速度缩放比。例如,如果该值为 1,则动画以正常速度播放。如果它是 0.5,那么它会半速播放。如果是 2,则会以双倍速度播放。

如果设置为负值,则动画反向播放。如果设置为0,则动画不会前进。


方法说明

StringName animation_get_next ( StringName animation_from ) const

返回在 animation_from 动画之后排队播放的动画的键。


void animation_set_next ( StringName animation_from, StringName animation_to )

animation_from 动画完成时,触发 animation_to 动画。


void clear_queue ( )

清除所有已排队、未播放的动画。


float get_blend_time ( StringName animation_from, StringName animation_to ) const

返回两个动画之间的混合时间(以秒为单位),由它们的键引用。


AnimationMethodCallMode get_method_call_mode ( ) const

用于向后兼容。见 AnimationCallbackModeMethod


float get_playing_speed ( ) const

返回当前动画的实际播放速度,未播放时则为 0。这个速度是 speed_scale 属性乘以调用 play 时指定的 custom_speed 参数。

如果当前动画是倒放的,则返回负值。


AnimationProcessCallback get_process_callback ( ) const

用于向后兼容。见 AnimationCallbackModeProcess


PackedStringArray get_queue ( )

返回当前排队播放的动画键列表。


NodePath get_root ( ) const

用于向后兼容。见 AnimationMixer.root_node


bool is_playing ( ) const

如果动画目前正在播放,则返回 true(即便 speed_scale 和/或 custom_speed0)。


void pause ( )

暂停当前播放的动画。current_animation_position 将被保留,调用 playplay_backwards 时,不带参数或使用与 assigned_animation 相同的动画名称,将恢复动画。

另见 stop


void play ( StringName name="", float custom_blend=-1, float custom_speed=1.0, bool from_end=false )

播放键名为 name 的动画。可以设置自定义混合时间和速度。

from_end 选项仅在切换到新的动画轨道,或在相同轨道的开始或结束时生效。它不影响在动画被中途暂停时恢复播放。如果 custom_speed 为负,且 from_endtrue,则动画将向后播放(相当于调用 play_backwards)。

AnimationPlayer 使用 assigned_animation 跟踪其当前或上次播放的动画。如果使用相同的动画 name 或没有 name 参数调用此方法,则分配的动画将在暂停时恢复播放。

注意:动画将在下次处理 AnimationPlayer 时更新。如果在调用该方法的同时更新了其他变量,则它们可能更新得太早。要立即执行更新,请调用 advance(0)


void play_backwards ( StringName name="", float custom_blend=-1 )

倒放名称键为 name 的动画。

这个方法是简写,等价于调用 play 时使用 custom_speed = -1.0from_end = true,所以更多信息请参阅其描述。


void queue ( StringName name )

将动画加入队列,在当前动画播放完毕后播放。

注意:如果当前正在播放循环动画,除非以某种方式停止循环动画,否则排队的动画将永远不会播放。


void seek ( float seconds, bool update=false, bool update_only=false )

将动画寻道到时间点 seconds(单位为秒)。updatetrue 时会同时更新动画,否则会在处理时更新。当前帧和 seconds 之间的事件会被跳过。

如果 update_only 为 true,则不会处理方法轨道、音频轨道、动画播放轨道。

注意:寻道至动画的末尾不会触发 AnimationMixer.animation_finished。如果想要跳过动画并触发该信号,请使用 AnimationMixer.advance


void set_blend_time ( StringName animation_from, StringName animation_to, float sec )

指定两个动画(由它们的键所引用)之间的混合时间(以秒为单位)。


void set_method_call_mode ( AnimationMethodCallMode mode )

用于向后兼容。见 AnimationCallbackModeMethod


void set_process_callback ( AnimationProcessCallback mode )

用于向后兼容。见 AnimationCallbackModeProcess


void set_root ( NodePath path )

用于向后兼容。见 AnimationMixer.root_node


void stop ( bool keep_state=false )

停止当前播放的动画。动画位置被重置为 0custom_speed 被重置为 1.0。另见 pause

如果 keep_statetrue,则动画状态不会在视觉上更新。

注意:方法/音频/动画播放轨道不会被该方法处理。