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

AnimationPlayer

继承： AnimationMixer < Node < Object

用于播放动画的节点。

描述

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

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

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

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

教程

• 2D 精灵动画

• 动画教程索引

• 第三人称射击（TPS）演示

属性

String	assigned_animation
String	autoplay	""
String	current_animation	""
float	current_animation_length
float	current_animation_position
bool	movie_quit_on_finish	false
bool	playback_auto_capture	true
float	playback_auto_capture_duration	-1.0
EaseType	playback_auto_capture_ease_type	0
TransitionType	playback_auto_capture_transition_type	0
float	playback_default_blend_time	0.0
float	speed_scale	1.0

方法

StringName	animation_get_next(animation_from: StringName) const
void	animation_set_next(animation_from: StringName, animation_to: StringName)
void	clear_queue()
float	get_blend_time(animation_from: StringName, animation_to: StringName) const
AnimationMethodCallMode	get_method_call_mode() const
float	get_playing_speed() const
AnimationProcessCallback	get_process_callback() const
PackedStringArray	get_queue()
NodePath	get_root() const
float	get_section_end_time() const
float	get_section_start_time() const
bool	has_section() const
bool	is_playing() const
void	pause()
void	play(name: StringName = &"", custom_blend: float = -1, custom_speed: float = 1.0, from_end: bool = false)
void	play_backwards(name: StringName = &"", custom_blend: float = -1)
void	play_section(name: StringName = &"", start_time: float = -1, end_time: float = -1, custom_blend: float = -1, custom_speed: float = 1.0, from_end: bool = false)
void	play_section_backwards(name: StringName = &"", start_time: float = -1, end_time: float = -1, custom_blend: float = -1)
void	play_section_with_markers(name: StringName = &"", start_marker: StringName = &"", end_marker: StringName = &"", custom_blend: float = -1, custom_speed: float = 1.0, from_end: bool = false)
void	play_section_with_markers_backwards(name: StringName = &"", start_marker: StringName = &"", end_marker: StringName = &"", custom_blend: float = -1)
void	play_with_capture(name: StringName = &"", duration: float = -1.0, custom_blend: float = -1, custom_speed: float = 1.0, from_end: bool = false, trans_type: TransitionType = 0, ease_type: EaseType = 0)
void	queue(name: StringName)
void	reset_section()
void	seek(seconds: float, update: bool = false, update_only: bool = false)
void	set_blend_time(animation_from: StringName, animation_to: StringName, sec: float)
void	set_method_call_mode(mode: AnimationMethodCallMode)
void	set_process_callback(mode: AnimationProcessCallback)
void	set_root(path: NodePath)
void	set_section(start_time: float = -1, end_time: float = -1)
void	set_section_with_markers(start_marker: StringName = &"", end_marker: StringName = &"")
void	stop(keep_state: bool = false)

---

信号

animation_changed(old_name: StringName, new_name: StringName) 🔗

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

注意：通过 play() 或 AnimationTree 改变动画时，不会发出此信号。

---

current_animation_changed(name: String) 🔗

当 current_animation 更改时发出。

---

枚举

enum AnimationProcessCallback: 🔗

AnimationProcessCallback ANIMATION_PROCESS_PHYSICS = 0

已弃用： See AnimationMixer.ANIMATION_CALLBACK_MODE_PROCESS_PHYSICS.

AnimationProcessCallback ANIMATION_PROCESS_IDLE = 1

已弃用： See AnimationMixer.ANIMATION_CALLBACK_MODE_PROCESS_IDLE.

AnimationProcessCallback ANIMATION_PROCESS_MANUAL = 2

已弃用： See AnimationMixer.ANIMATION_CALLBACK_MODE_PROCESS_MANUAL.

---

enum AnimationMethodCallMode: 🔗

AnimationMethodCallMode ANIMATION_METHOD_CALL_DEFERRED = 0

已弃用： See AnimationMixer.ANIMATION_CALLBACK_MODE_METHOD_DEFERRED.

AnimationMethodCallMode ANIMATION_METHOD_CALL_IMMEDIATE = 1

已弃用： See AnimationMixer.ANIMATION_CALLBACK_MODE_METHOD_IMMEDIATE.

---

属性说明

String assigned_animation 🔗

• void set_assigned_animation(value: String)

• String get_assigned_animation()

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

---

String autoplay = "" 🔗

• void set_autoplay(value: String)

• String get_autoplay()

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

---

String current_animation = "" 🔗

• void set_current_animation(value: String)

• 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(value: bool)

• bool is_movie_quit_on_finish_enabled()

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

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

---

bool playback_auto_capture = true 🔗

• void set_auto_capture(value: bool)

• bool is_auto_capture()

如果为 true，则会在自动播放之前执行 AnimationMixer.capture()。这意味着只会使用默认参数执行 play_with_capture()，不会执行 play()。

注意：只有当动画包含捕获轨道时才会执行捕获插值。另见 Animation.UPDATE_CAPTURE。

---

float playback_auto_capture_duration = -1.0 🔗

• void set_auto_capture_duration(value: float)

• float get_auto_capture_duration()

另请参见play_with_capture()和AnimationMixer.capture()。

如果playback_auto_capture_duration为负值，则持续时间设置为当前位置和第一个关键点之间的间隔。

---

EaseType playback_auto_capture_ease_type = 0 🔗

• void set_auto_capture_ease_type(value: EaseType)

• EaseType get_auto_capture_ease_type()

捕获插值的缓动类型。另见 EaseType。

---

TransitionType playback_auto_capture_transition_type = 0 🔗

• void set_auto_capture_transition_type(value: TransitionType)

• TransitionType get_auto_capture_transition_type()

捕捉插值的过渡类型。另请参见TransitionType。

---

float playback_default_blend_time = 0.0 🔗

• void set_default_blend_time(value: float)

• float get_default_blend_time()

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

---

float speed_scale = 1.0 🔗

• void set_speed_scale(value: float)

• float get_speed_scale()

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

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

---

方法说明

StringName animation_get_next(animation_from: StringName) const 🔗

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

---

void animation_set_next(animation_from: StringName, animation_to: StringName) 🔗

当 animation_from 动画完成时，触发 animation_to 动画。

---

void clear_queue() 🔗

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

---

float get_blend_time(animation_from: StringName, animation_to: StringName) const 🔗

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

---

AnimationMethodCallMode get_method_call_mode() const 🔗

已弃用： Use AnimationMixer.callback_mode_method instead.

返回用于“方法调用”轨道的调用模式。

---

float get_playing_speed() const 🔗

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

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

---

AnimationProcessCallback get_process_callback() const 🔗

已弃用： Use AnimationMixer.callback_mode_process instead.

返回要更新动画的过程通知。

---

PackedStringArray get_queue() 🔗

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

---

NodePath get_root() const 🔗

已弃用： Use AnimationMixer.root_node instead.

返回节点路径引用将从其出发的节点。

---

float get_section_end_time() const 🔗

返回当前正在播放区域的结束时间点。

---

float get_section_start_time() const 🔗

返回当前正在播放区域的开始时间点。

---

bool has_section() const 🔗

如果正在播放动画中的某个区域，则返回 true。

---

bool is_playing() const 🔗

如果动画目前正在播放，则返回 true（即便 speed_scale 和/或 custom_speed 为 0）。

---

void pause() 🔗

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

另见 stop()。

---

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

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

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

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

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

---

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

倒放名称键为 name 的动画。

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

---

void play_section(name: StringName = &"", start_time: float = -1, end_time: float = -1, custom_blend: float = -1, custom_speed: float = 1.0, from_end: bool = false) 🔗

播放键名为 name 的动画中的指定区域，该区域的开始时间为 start_time、结束时间为 end_time。另见 play()。

将 start_time 设置为动画范围外的值表示使用动画的开头，将 end_time 设置为动画范围外的值表示使用动画的结尾。start_time 不能等于 end_time。

---

void play_section_backwards(name: StringName = &"", start_time: float = -1, end_time: float = -1, custom_blend: float = -1) 🔗

倒放键名为 name 的动画中的指定区域，该区域的开始时间为 start_time、结束时间为 end_time。

该方法是 play_section() 的简写，等价于 custom_speed = -1.0、from_end = true，详见其描述。

---

void play_section_with_markers(name: StringName = &"", start_marker: StringName = &"", end_marker: StringName = &"", custom_blend: float = -1, custom_speed: float = 1.0, from_end: bool = false) 🔗

播放键名为 name 的动画中的指定区域，该区域从 start_marker 标记开始、到 end_marker 标记结束。

如果开始标记为空，则区域从动画的开头开始。如果结束标记为空，则区域在动画的结尾结束。另见 play()。

---

void play_section_with_markers_backwards(name: StringName = &"", start_marker: StringName = &"", end_marker: StringName = &"", custom_blend: float = -1) 🔗

倒放键名为 name 的动画中的指定区域，该区域从 start_marker 标记开始、到 end_marker 标记结束。

该方法是 play_section_with_markers() 的简写，等价于 custom_speed = -1.0、from_end = true，详见其描述。

---

void play_with_capture(name: StringName = &"", duration: float = -1.0, custom_blend: float = -1, custom_speed: float = 1.0, from_end: bool = false, trans_type: TransitionType = 0, ease_type: EaseType = 0) 🔗

另见 AnimationMixer.capture()。

该方法提供的选项比 playback_auto_capture 更丰富。playback_auto_capture 为 false 时，该方法与下面这两行基本相同：

capture(name, duration, trans_type, ease_type)
play(name, custom_blend, custom_speed, from_end)

如果 name 为空，则指定的是 assigned_animation。

如果 duration 为负值，则持续时间是当前位置与第一个关键帧的间隔，from_end 为 true 时使用的则是当前位置与最后一个关键帧之间的间隔。

注意：duration 会考虑 speed_scale，但 custom_speed 不会考虑，因为捕获缓存会和混合结果进行插值，而混合结果可能包含多个动画。

---

void queue(name: StringName) 🔗

将动画加入队列，在当前动画和所有先前排队的动画完毕后播放。

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

---

void reset_section() 🔗

如果设置了区域则重置当前区域。

---

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

将动画寻道到时间点 seconds（单位为秒）。update 为 true 时会同时更新动画，否则会在处理时更新。当前帧和 seconds 之间的事件会被跳过。

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

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

---

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

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

---

void set_method_call_mode(mode: AnimationMethodCallMode) 🔗

已弃用： Use AnimationMixer.callback_mode_method instead.

设置用于“方法调用”轨道的调用模式。

---

void set_process_callback(mode: AnimationProcessCallback) 🔗

已弃用： Use AnimationMixer.callback_mode_process instead.

设置要更新动画的过程通知。

---

void set_root(path: NodePath) 🔗

已弃用： Use AnimationMixer.root_node instead.

设置节点路径引用将从哪个节点出发。

---

void set_section(start_time: float = -1, end_time: float = -1) 🔗

更改正在被播放的段落的起止时间。当前的回放位置将被限定在新段落范围内。参见play_section()。

---

void set_section_with_markers(start_marker: StringName = &"", end_marker: StringName = &"") 🔗

改变正在播放的段落的开始和结束标记。当前的回放位置将被固定到新段落中。参见play_section_with_markers()。

如果参数为空，段落将使用动画本身的起始或结束。如果两者都是空，那就意味着段落还没有设置。

---

void stop(keep_state: bool = false) 🔗

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

如果 keep_state 为 true，则动画状态不会在视觉上更新。

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