AnimationPlayer
繼承： AnimationMixer < Node < Object
用於動畫播放的節點。
說明
動畫播放器用於一般目的的動畫播放。它包含一個 AnimationLibrary 資源字典以及動畫轉場的自訂混合時間。
某些方法與屬性會用單一鍵值直接參照動畫，此鍵值格式為「動畫庫鍵值/動畫鍵值」，例如 "movement/run"。若動畫庫鍵值為空字串（預設庫），則省略斜線只寫動畫鍵值。
與 Tween 相比，AnimationPlayer 更適合處理時序複雜的動畫；若你偏好使用動畫軌編輯器而非程式碼，也可以選擇 AnimationPlayer。
動畫目標屬性的更新發生於處理影格階段。
教學
屬性
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
方法
animation_get_next(animation_from: StringName) const |
|
void |
animation_set_next(animation_from: StringName, animation_to: StringName) |
void |
|
get_blend_time(animation_from: StringName, animation_to: StringName) const |
|
get_method_call_mode() const |
|
get_playing_speed() const |
|
get_process_callback() const |
|
get_root() const |
|
get_section_end_time() const |
|
get_section_start_time() const |
|
has_section() const |
|
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 |
|
void |
seek(seconds: float, update: bool = false, update_only: bool = false) |
void |
set_blend_time(animation_from: StringName, animation_to: StringName, sec: float) |
void |
|
void |
|
void |
|
void |
set_section(start_time: float = -1, end_time: float = -1) |
void |
set_section_with_markers(start_marker: StringName = &"", end_marker: StringName = &"") |
void |
訊號
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.
屬性說明
若正在播放則為目前動畫鍵值，否則為上一次播放的動畫鍵值。設定此屬性會更換動畫，但除非已在播放，否則不會自動開始。另見 current_animation。
場景載入時要播放的動畫鍵名。
String 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 🔗
若為 true 且引擎以 Movie Maker 模式運行（見 MovieWriter），當此 AnimationPlayer 播放完動畫後會立刻呼叫 SceneTree.quit() 結束引擎，並輸出訊息。
注意： 該行為遵循 AnimationMixer.animation_finished 的邏輯，若動畫設為循環則不會退出引擎。
bool playback_auto_capture = true 🔗
若為 true，播放前會自動執行 AnimationMixer.capture()。等同於以預設參數呼叫 play_with_capture()，而非 play()。
注意： 僅當動畫包含捕捉軌道時才會進行捕捉插值。另見 Animation.UPDATE_CAPTURE。
float playback_auto_capture_duration = -1.0 🔗
另見 play_with_capture() 與 AnimationMixer.capture()。
若 playback_auto_capture_duration 為負值，時長將設為目前位置到第一個關鍵影格的區間。
EaseType playback_auto_capture_ease_type = 0 🔗
捕捉插值所使用的緩和型式。另見 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 🔗
動畫混合的預設時間，範圍 0–4096，精度 0.01。
速度倍率。值為 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() 🔗
回傳目前排程中等待播放的動畫鍵值清單。
已棄用： Use AnimationMixer.root_node instead.
回傳節點路徑引用的起始節點。
float get_section_end_time() const 🔗
回傳目前播放區段的結束時間。
float get_section_start_time() const 🔗
回傳目前播放區段的開始時間。
若目前有區段動畫在播放則回傳 true。
若動畫正在播放（即使 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) 🔗
此方法可提供比 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，動畫狀態不會在畫面上更新。
注意： 方法／音訊／動畫播放軌不會由此方法處理。