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"。若動畫庫鍵值為空字串（預設庫），則省略斜線只寫動畫鍵值。

與 Tween 相比，AnimationPlayer 更適合處理時序複雜的動畫；若你偏好使用動畫軌編輯器而非程式碼，也可以選擇 AnimationPlayer。

動畫目標屬性的更新發生於處理影格階段。

教學

屬性

StringName	assigned_animation
StringName	autoplay	`&""`
StringName	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
Array[StringName]	get_queue()
NodePath	get_root() const
float	get_section_end_time() const
float	get_section_start_time() const
bool	has_section() const
bool	is_animation_active() 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(anim_name: StringName) 🔗

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

屬性說明

StringName assigned_animation 🔗

void set_assigned_animation(value: StringName)
StringName get_assigned_animation()

若正在播放則為目前動畫鍵值，否則為上一次播放的動畫鍵值。設定此屬性會更換動畫，但除非已在播放，否則不會自動開始。另見 current_animation。

StringName autoplay = &"" 🔗

void set_autoplay(value: StringName)
StringName get_autoplay()

場景載入時要播放的動畫鍵名。

StringName current_animation = &"" 🔗

void set_current_animation(value: StringName)
StringName 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.

回傳用來更新動畫的處理通知類型。

Array[StringName] 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_animation_active() const 🔗

Returns true if the an animation is currently active. An animation is active if it was played by calling play() and was not finished yet, or was stopped by calling stop().

This can be used to check whether an animation is currently paused or stopped.

var is_paused = not is_playing() and is_animation_active()
var is_stopped = not is_playing() and not is_animation_active()

bool is_playing() const 🔗

若動畫正在播放（即使 speed_scale 或 custom_speed 為 0），則回傳 true。

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 的動畫。

此方法相當於使用 custom_speed = -1.0、from_end = true 呼叫 play()，詳情請參考該方法說明。

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 的區段。

此方法等同於以 custom_speed = -1.0 且 from_end = true 呼叫 play_section()，詳情請參閱其說明。

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 結束。

此方法等同於以 custom_speed = -1.0 與 from_end = true 呼叫 play_section_with_markers()，詳情請參閱其說明。

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，動畫狀態不會在畫面上更新。

注意： 方法／音訊／動畫播放軌不會由此方法處理。