:github_url: hide .. _class_AnimationPlayer: AnimationPlayer =============== **繼承：** :ref:`AnimationMixer` **<** :ref:`Node` **<** :ref:`Object` 用於動畫播放的節點。 .. rst-class:: classref-introduction-group 說明 ---- 動畫播放器用於一般目的的動畫播放。它包含一個 :ref:`AnimationLibrary` 資源字典以及動畫轉場的自訂混合時間。 某些方法與屬性會用單一鍵值直接參照動畫，此鍵值格式為「動畫庫鍵值/動畫鍵值」，例如 ``"movement/run"``\ 。若動畫庫鍵值為空字串（預設庫），則省略斜線只寫動畫鍵值。 與 :ref:`Tween` 相比，\ **AnimationPlayer** 更適合處理時序複雜的動畫；若你偏好使用動畫軌編輯器而非程式碼，也可以選擇 **AnimationPlayer**\ 。 動畫目標屬性的更新發生於處理影格階段。 .. rst-class:: classref-introduction-group 教學 ---- - :doc:`2D 精靈動畫 <../tutorials/2d/2d_sprite_animation>` - :doc:`動畫文件索引 <../tutorials/animation/index>` - `第三人稱射擊（TPS）示範 `__ .. rst-class:: classref-reftable-group 屬性 ---- .. table:: :widths: auto +--------------------------------------------------+--------------------------------------------------------------------------------------------------------------------+-----------+ | :ref:`StringName` | :ref:`assigned_animation` | | +--------------------------------------------------+--------------------------------------------------------------------------------------------------------------------+-----------+ | :ref:`StringName` | :ref:`autoplay` | ``&""`` | +--------------------------------------------------+--------------------------------------------------------------------------------------------------------------------+-----------+ | :ref:`StringName` | :ref:`current_animation` | ``&""`` | +--------------------------------------------------+--------------------------------------------------------------------------------------------------------------------+-----------+ | :ref:`float` | :ref:`current_animation_length` | | +--------------------------------------------------+--------------------------------------------------------------------------------------------------------------------+-----------+ | :ref:`float` | :ref:`current_animation_position` | | +--------------------------------------------------+--------------------------------------------------------------------------------------------------------------------+-----------+ | :ref:`bool` | :ref:`movie_quit_on_finish` | ``false`` | +--------------------------------------------------+--------------------------------------------------------------------------------------------------------------------+-----------+ | :ref:`bool` | :ref:`playback_auto_capture` | ``true`` | +--------------------------------------------------+--------------------------------------------------------------------------------------------------------------------+-----------+ | :ref:`float` | :ref:`playback_auto_capture_duration` | ``-1.0`` | +--------------------------------------------------+--------------------------------------------------------------------------------------------------------------------+-----------+ | :ref:`EaseType` | :ref:`playback_auto_capture_ease_type` | ``0`` | +--------------------------------------------------+--------------------------------------------------------------------------------------------------------------------+-----------+ | :ref:`TransitionType` | :ref:`playback_auto_capture_transition_type` | ``0`` | +--------------------------------------------------+--------------------------------------------------------------------------------------------------------------------+-----------+ | :ref:`float` | :ref:`playback_default_blend_time` | ``0.0`` | +--------------------------------------------------+--------------------------------------------------------------------------------------------------------------------+-----------+ | :ref:`float` | :ref:`speed_scale` | ``1.0`` | +--------------------------------------------------+--------------------------------------------------------------------------------------------------------------------+-----------+ .. rst-class:: classref-reftable-group 方法 ---- .. table:: :widths: auto +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`StringName` | :ref:`animation_get_next`\ (\ animation_from\: :ref:`StringName`\ ) |const| | +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |void| | :ref:`animation_set_next`\ (\ animation_from\: :ref:`StringName`, animation_to\: :ref:`StringName`\ ) | +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |void| | :ref:`clear_queue`\ (\ ) | +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`float` | :ref:`get_blend_time`\ (\ animation_from\: :ref:`StringName`, animation_to\: :ref:`StringName`\ ) |const| | +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`AnimationMethodCallMode` | :ref:`get_method_call_mode`\ (\ ) |const| | +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`float` | :ref:`get_playing_speed`\ (\ ) |const| | +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`AnimationProcessCallback` | :ref:`get_process_callback`\ (\ ) |const| | +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Array`\[:ref:`StringName`\] | :ref:`get_queue`\ (\ ) | +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`NodePath` | :ref:`get_root`\ (\ ) |const| | +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`float` | :ref:`get_section_end_time`\ (\ ) |const| | +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`float` | :ref:`get_section_start_time`\ (\ ) |const| | +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`has_section`\ (\ ) |const| | +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`is_animation_active`\ (\ ) |const| | +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`is_playing`\ (\ ) |const| | +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |void| | :ref:`pause`\ (\ ) | +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |void| | :ref:`play`\ (\ name\: :ref:`StringName` = &"", custom_blend\: :ref:`float` = -1, custom_speed\: :ref:`float` = 1.0, from_end\: :ref:`bool` = false\ ) | +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |void| | :ref:`play_backwards`\ (\ name\: :ref:`StringName` = &"", custom_blend\: :ref:`float` = -1\ ) | +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |void| | :ref:`play_section`\ (\ name\: :ref:`StringName` = &"", start_time\: :ref:`float` = -1, end_time\: :ref:`float` = -1, custom_blend\: :ref:`float` = -1, custom_speed\: :ref:`float` = 1.0, from_end\: :ref:`bool` = false\ ) | +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |void| | :ref:`play_section_backwards`\ (\ name\: :ref:`StringName` = &"", start_time\: :ref:`float` = -1, end_time\: :ref:`float` = -1, custom_blend\: :ref:`float` = -1\ ) | +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |void| | :ref:`play_section_with_markers`\ (\ name\: :ref:`StringName` = &"", start_marker\: :ref:`StringName` = &"", end_marker\: :ref:`StringName` = &"", custom_blend\: :ref:`float` = -1, custom_speed\: :ref:`float` = 1.0, from_end\: :ref:`bool` = false\ ) | +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |void| | :ref:`play_section_with_markers_backwards`\ (\ name\: :ref:`StringName` = &"", start_marker\: :ref:`StringName` = &"", end_marker\: :ref:`StringName` = &"", custom_blend\: :ref:`float` = -1\ ) | +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |void| | :ref:`play_with_capture`\ (\ name\: :ref:`StringName` = &"", duration\: :ref:`float` = -1.0, custom_blend\: :ref:`float` = -1, custom_speed\: :ref:`float` = 1.0, from_end\: :ref:`bool` = false, trans_type\: :ref:`TransitionType` = 0, ease_type\: :ref:`EaseType` = 0\ ) | +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |void| | :ref:`queue`\ (\ name\: :ref:`StringName`\ ) | +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |void| | :ref:`reset_section`\ (\ ) | +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |void| | :ref:`seek`\ (\ seconds\: :ref:`float`, update\: :ref:`bool` = false, update_only\: :ref:`bool` = false\ ) | +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |void| | :ref:`set_blend_time`\ (\ animation_from\: :ref:`StringName`, animation_to\: :ref:`StringName`, sec\: :ref:`float`\ ) | +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |void| | :ref:`set_method_call_mode`\ (\ mode\: :ref:`AnimationMethodCallMode`\ ) | +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |void| | :ref:`set_process_callback`\ (\ mode\: :ref:`AnimationProcessCallback`\ ) | +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |void| | :ref:`set_root`\ (\ path\: :ref:`NodePath`\ ) | +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |void| | :ref:`set_section`\ (\ start_time\: :ref:`float` = -1, end_time\: :ref:`float` = -1\ ) | +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |void| | :ref:`set_section_with_markers`\ (\ start_marker\: :ref:`StringName` = &"", end_marker\: :ref:`StringName` = &""\ ) | +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |void| | :ref:`stop`\ (\ keep_state\: :ref:`bool` = false\ ) | +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ .. rst-class:: classref-section-separator ---- .. rst-class:: classref-descriptions-group 訊號 ---- .. _class_AnimationPlayer_signal_animation_changed: .. rst-class:: classref-signal **animation_changed**\ (\ old_name\: :ref:`StringName`, new_name\: :ref:`StringName`\ ) :ref:`🔗` 當佇列中的動畫於上一段動畫播放完畢後開始播放時發出。另見 :ref:`queue()`\ 。 \ **注意：** 若透過 :ref:`play()` 或 :ref:`AnimationTree` 切換動畫時不會發出此訊號。 .. rst-class:: classref-item-separator ---- .. _class_AnimationPlayer_signal_current_animation_changed: .. rst-class:: classref-signal **current_animation_changed**\ (\ name\: :ref:`StringName`\ ) :ref:`🔗` 當 :ref:`current_animation` 變更時發出。 .. rst-class:: classref-section-separator ---- .. rst-class:: classref-descriptions-group 列舉 ---- .. _enum_AnimationPlayer_AnimationProcessCallback: .. rst-class:: classref-enumeration enum **AnimationProcessCallback**: :ref:`🔗` .. _class_AnimationPlayer_constant_ANIMATION_PROCESS_PHYSICS: .. rst-class:: classref-enumeration-constant :ref:`AnimationProcessCallback` **ANIMATION_PROCESS_PHYSICS** = ``0`` **已棄用：** See :ref:`AnimationMixer.ANIMATION_CALLBACK_MODE_PROCESS_PHYSICS`. .. _class_AnimationPlayer_constant_ANIMATION_PROCESS_IDLE: .. rst-class:: classref-enumeration-constant :ref:`AnimationProcessCallback` **ANIMATION_PROCESS_IDLE** = ``1`` **已棄用：** See :ref:`AnimationMixer.ANIMATION_CALLBACK_MODE_PROCESS_IDLE`. .. _class_AnimationPlayer_constant_ANIMATION_PROCESS_MANUAL: .. rst-class:: classref-enumeration-constant :ref:`AnimationProcessCallback` **ANIMATION_PROCESS_MANUAL** = ``2`` **已棄用：** See :ref:`AnimationMixer.ANIMATION_CALLBACK_MODE_PROCESS_MANUAL`. .. rst-class:: classref-item-separator ---- .. _enum_AnimationPlayer_AnimationMethodCallMode: .. rst-class:: classref-enumeration enum **AnimationMethodCallMode**: :ref:`🔗` .. _class_AnimationPlayer_constant_ANIMATION_METHOD_CALL_DEFERRED: .. rst-class:: classref-enumeration-constant :ref:`AnimationMethodCallMode` **ANIMATION_METHOD_CALL_DEFERRED** = ``0`` **已棄用：** See :ref:`AnimationMixer.ANIMATION_CALLBACK_MODE_METHOD_DEFERRED`. .. _class_AnimationPlayer_constant_ANIMATION_METHOD_CALL_IMMEDIATE: .. rst-class:: classref-enumeration-constant :ref:`AnimationMethodCallMode` **ANIMATION_METHOD_CALL_IMMEDIATE** = ``1`` **已棄用：** See :ref:`AnimationMixer.ANIMATION_CALLBACK_MODE_METHOD_IMMEDIATE`. .. rst-class:: classref-section-separator ---- .. rst-class:: classref-descriptions-group 屬性說明 -------- .. _class_AnimationPlayer_property_assigned_animation: .. rst-class:: classref-property :ref:`StringName` **assigned_animation** :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_assigned_animation**\ (\ value\: :ref:`StringName`\ ) - :ref:`StringName` **get_assigned_animation**\ (\ ) 若正在播放則為目前動畫鍵值，否則為上一次播放的動畫鍵值。設定此屬性會更換動畫，但除非已在播放，否則不會自動開始。另見 :ref:`current_animation`\ 。 .. rst-class:: classref-item-separator ---- .. _class_AnimationPlayer_property_autoplay: .. rst-class:: classref-property :ref:`StringName` **autoplay** = ``&""`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_autoplay**\ (\ value\: :ref:`StringName`\ ) - :ref:`StringName` **get_autoplay**\ (\ ) 場景載入時要播放的動畫鍵名。 .. rst-class:: classref-item-separator ---- .. _class_AnimationPlayer_property_current_animation: .. rst-class:: classref-property :ref:`StringName` **current_animation** = ``&""`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_current_animation**\ (\ value\: :ref:`StringName`\ ) - :ref:`StringName` **get_current_animation**\ (\ ) 目前正在播放的動畫鍵值。若未播放任何動畫，則為空字串。變更此值不會重新啟動動畫。更多播放方式請參閱 :ref:`play()`\ 。 \ **注意：** 雖然此屬性會出現在屬性檢視器中，但並非用於編輯，且不會存入場景檔。主要用途是取得當前播放的動畫，以及供動畫播放軌內部使用。詳見 :ref:`Animation`\ 。 .. rst-class:: classref-item-separator ---- .. _class_AnimationPlayer_property_current_animation_length: .. rst-class:: classref-property :ref:`float` **current_animation_length** :ref:`🔗` .. rst-class:: classref-property-setget - :ref:`float` **get_current_animation_length**\ (\ ) 目前播放動畫的長度（秒）。 .. rst-class:: classref-item-separator ---- .. _class_AnimationPlayer_property_current_animation_position: .. rst-class:: classref-property :ref:`float` **current_animation_position** :ref:`🔗` .. rst-class:: classref-property-setget - :ref:`float` **get_current_animation_position**\ (\ ) 目前播放動畫的位置（秒）。 .. rst-class:: classref-item-separator ---- .. _class_AnimationPlayer_property_movie_quit_on_finish: .. rst-class:: classref-property :ref:`bool` **movie_quit_on_finish** = ``false`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_movie_quit_on_finish_enabled**\ (\ value\: :ref:`bool`\ ) - :ref:`bool` **is_movie_quit_on_finish_enabled**\ (\ ) 若為 ``true`` 且引擎以 Movie Maker 模式運行（見 :ref:`MovieWriter`\ ），當此 **AnimationPlayer** 播放完動畫後會立刻呼叫 :ref:`SceneTree.quit()` 結束引擎，並輸出訊息。 \ **注意：** 該行為遵循 :ref:`AnimationMixer.animation_finished` 的邏輯，若動畫設為循環則不會退出引擎。 .. rst-class:: classref-item-separator ---- .. _class_AnimationPlayer_property_playback_auto_capture: .. rst-class:: classref-property :ref:`bool` **playback_auto_capture** = ``true`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_auto_capture**\ (\ value\: :ref:`bool`\ ) - :ref:`bool` **is_auto_capture**\ (\ ) 若為 ``true``\ ，播放前會自動執行 :ref:`AnimationMixer.capture()`\ 。等同於以預設參數呼叫 :ref:`play_with_capture()`\ ，而非 :ref:`play()`\ 。 \ **注意：** 僅當動畫包含捕捉軌道時才會進行捕捉插值。另見 :ref:`Animation.UPDATE_CAPTURE`\ 。 .. rst-class:: classref-item-separator ---- .. _class_AnimationPlayer_property_playback_auto_capture_duration: .. rst-class:: classref-property :ref:`float` **playback_auto_capture_duration** = ``-1.0`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_auto_capture_duration**\ (\ value\: :ref:`float`\ ) - :ref:`float` **get_auto_capture_duration**\ (\ ) 另見 :ref:`play_with_capture()` 與 :ref:`AnimationMixer.capture()`\ 。 若 :ref:`playback_auto_capture_duration` 為負值，時長將設為目前位置到第一個關鍵影格的區間。 .. rst-class:: classref-item-separator ---- .. _class_AnimationPlayer_property_playback_auto_capture_ease_type: .. rst-class:: classref-property :ref:`EaseType` **playback_auto_capture_ease_type** = ``0`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_auto_capture_ease_type**\ (\ value\: :ref:`EaseType`\ ) - :ref:`EaseType` **get_auto_capture_ease_type**\ (\ ) 捕捉插值所使用的緩和型式。另見 :ref:`EaseType`\ 。 .. rst-class:: classref-item-separator ---- .. _class_AnimationPlayer_property_playback_auto_capture_transition_type: .. rst-class:: classref-property :ref:`TransitionType` **playback_auto_capture_transition_type** = ``0`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_auto_capture_transition_type**\ (\ value\: :ref:`TransitionType`\ ) - :ref:`TransitionType` **get_auto_capture_transition_type**\ (\ ) 捕捉插值的轉換型式。另見 :ref:`TransitionType`\ 。 .. rst-class:: classref-item-separator ---- .. _class_AnimationPlayer_property_playback_default_blend_time: .. rst-class:: classref-property :ref:`float` **playback_default_blend_time** = ``0.0`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_default_blend_time**\ (\ value\: :ref:`float`\ ) - :ref:`float` **get_default_blend_time**\ (\ ) 動畫混合的預設時間，範圍 0–4096，精度 0.01。 .. rst-class:: classref-item-separator ---- .. _class_AnimationPlayer_property_speed_scale: .. rst-class:: classref-property :ref:`float` **speed_scale** = ``1.0`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_speed_scale**\ (\ value\: :ref:`float`\ ) - :ref:`float` **get_speed_scale**\ (\ ) 速度倍率。值為 ``1`` 時以正常速度播放；\ ``0.5`` 為半速；\ ``2`` 為兩倍速。 若為負值則反向播放；若為 ``0`` 則動畫停止推進。 .. rst-class:: classref-section-separator ---- .. rst-class:: classref-descriptions-group 方法說明 -------- .. _class_AnimationPlayer_method_animation_get_next: .. rst-class:: classref-method :ref:`StringName` **animation_get_next**\ (\ animation_from\: :ref:`StringName`\ ) |const| :ref:`🔗` 回傳排定在 ``animation_from`` 動畫之後播放的動畫鍵值。 .. rst-class:: classref-item-separator ---- .. _class_AnimationPlayer_method_animation_set_next: .. rst-class:: classref-method |void| **animation_set_next**\ (\ animation_from\: :ref:`StringName`, animation_to\: :ref:`StringName`\ ) :ref:`🔗` 當 ``animation_from`` 動畫播放完畢時觸發 ``animation_to`` 動畫。 .. rst-class:: classref-item-separator ---- .. _class_AnimationPlayer_method_clear_queue: .. rst-class:: classref-method |void| **clear_queue**\ (\ ) :ref:`🔗` 清除所有已排隊但尚未播放的動畫。 .. rst-class:: classref-item-separator ---- .. _class_AnimationPlayer_method_get_blend_time: .. rst-class:: classref-method :ref:`float` **get_blend_time**\ (\ animation_from\: :ref:`StringName`, animation_to\: :ref:`StringName`\ ) |const| :ref:`🔗` 回傳以鍵值指定的兩段動畫之間的混合時間（秒）。 .. rst-class:: classref-item-separator ---- .. _class_AnimationPlayer_method_get_method_call_mode: .. rst-class:: classref-method :ref:`AnimationMethodCallMode` **get_method_call_mode**\ (\ ) |const| :ref:`🔗` **已棄用：** Use :ref:`AnimationMixer.callback_mode_method` instead. 回傳「方法呼叫」軌道所使用的呼叫模式。 .. rst-class:: classref-item-separator ---- .. _class_AnimationPlayer_method_get_playing_speed: .. rst-class:: classref-method :ref:`float` **get_playing_speed**\ (\ ) |const| :ref:`🔗` 回傳目前動畫的實際播放速度，若未播放則為 ``0``\ 。此速度為 :ref:`speed_scale` 與呼叫 :ref:`play()` 時指定的 ``custom_speed`` 相乘所得。 若動畫以倒放方式播放，則回傳負值。 .. rst-class:: classref-item-separator ---- .. _class_AnimationPlayer_method_get_process_callback: .. rst-class:: classref-method :ref:`AnimationProcessCallback` **get_process_callback**\ (\ ) |const| :ref:`🔗` **已棄用：** Use :ref:`AnimationMixer.callback_mode_process` instead. 回傳用來更新動畫的處理通知類型。 .. rst-class:: classref-item-separator ---- .. _class_AnimationPlayer_method_get_queue: .. rst-class:: classref-method :ref:`Array`\[:ref:`StringName`\] **get_queue**\ (\ ) :ref:`🔗` 回傳目前排程中等待播放的動畫鍵值清單。 .. rst-class:: classref-item-separator ---- .. _class_AnimationPlayer_method_get_root: .. rst-class:: classref-method :ref:`NodePath` **get_root**\ (\ ) |const| :ref:`🔗` **已棄用：** Use :ref:`AnimationMixer.root_node` instead. 回傳節點路徑引用的起始節點。 .. rst-class:: classref-item-separator ---- .. _class_AnimationPlayer_method_get_section_end_time: .. rst-class:: classref-method :ref:`float` **get_section_end_time**\ (\ ) |const| :ref:`🔗` 回傳目前播放區段的結束時間。 .. rst-class:: classref-item-separator ---- .. _class_AnimationPlayer_method_get_section_start_time: .. rst-class:: classref-method :ref:`float` **get_section_start_time**\ (\ ) |const| :ref:`🔗` 回傳目前播放區段的開始時間。 .. rst-class:: classref-item-separator ---- .. _class_AnimationPlayer_method_has_section: .. rst-class:: classref-method :ref:`bool` **has_section**\ (\ ) |const| :ref:`🔗` 若目前有區段動畫在播放則回傳 ``true``\ 。 .. rst-class:: classref-item-separator ---- .. _class_AnimationPlayer_method_is_animation_active: .. rst-class:: classref-method :ref:`bool` **is_animation_active**\ (\ ) |const| :ref:`🔗` Returns ``true`` if the an animation is currently active. An animation is active if it was played by calling :ref:`play()` and was not finished yet, or was stopped by calling :ref:`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() .. rst-class:: classref-item-separator ---- .. _class_AnimationPlayer_method_is_playing: .. rst-class:: classref-method :ref:`bool` **is_playing**\ (\ ) |const| :ref:`🔗` 若動畫正在播放（即使 :ref:`speed_scale` 或 ``custom_speed`` 為 ``0``\ ），則回傳 ``true``\ 。 .. rst-class:: classref-item-separator ---- .. _class_AnimationPlayer_method_pause: .. rst-class:: classref-method |void| **pause**\ (\ ) :ref:`🔗` 暫停當前播放的動畫。\ :ref:`current_animation_position` 會被保留；呼叫 :ref:`play()` 或 :ref:`play_backwards()` 而不帶參數，或帶與 :ref:`assigned_animation` 相同的動畫名稱，即可繼續播放。 另見 :ref:`stop()`\ 。 .. rst-class:: classref-item-separator ---- .. _class_AnimationPlayer_method_play: .. rst-class:: classref-method |void| **play**\ (\ name\: :ref:`StringName` = &"", custom_blend\: :ref:`float` = -1, custom_speed\: :ref:`float` = 1.0, from_end\: :ref:`bool` = false\ ) :ref:`🔗` 播放鍵值為 ``name`` 的動畫，可自訂混合時間與播放速度。 \ ``from_end`` 僅影響切換到新動畫軌或同一軌起點／終點時；不影響在動畫中段暫停後再繼續播放。若 ``custom_speed`` 為負且 ``from_end`` 為 ``true``\ ，則動畫將倒放（等同於呼叫 :ref:`play_backwards()`\ ）。 \ **AnimationPlayer** 會以 :ref:`assigned_animation` 記錄目前或最後播放的動畫。如果此方法使用相同動畫 ``name``\ ，或未帶 ``name`` 參數呼叫，將會在暫停後繼續播放。 \ **注意：** 動畫會在下一次 **AnimationPlayer** 處理時更新。若同時修改其他變數，可能會過早執行。若需立即更新，請呼叫 ``advance(0)``\ 。 .. rst-class:: classref-item-separator ---- .. _class_AnimationPlayer_method_play_backwards: .. rst-class:: classref-method |void| **play_backwards**\ (\ name\: :ref:`StringName` = &"", custom_blend\: :ref:`float` = -1\ ) :ref:`🔗` 倒放鍵名為 ``name`` 的動畫。 此方法相當於使用 ``custom_speed = -1.0``\ 、\ ``from_end = true`` 呼叫 :ref:`play()`\ ，詳情請參考該方法說明。 .. rst-class:: classref-item-separator ---- .. _class_AnimationPlayer_method_play_section: .. rst-class:: classref-method |void| **play_section**\ (\ name\: :ref:`StringName` = &"", start_time\: :ref:`float` = -1, end_time\: :ref:`float` = -1, custom_blend\: :ref:`float` = -1, custom_speed\: :ref:`float` = 1.0, from_end\: :ref:`bool` = false\ ) :ref:`🔗` 播放鍵值為 ``name`` 的動畫，僅播放從 ``start_time`` 到 ``end_time`` 的區段。詳見 :ref:`play()`\ 。 若 ``start_time`` 超出動畫範圍，將改用動畫起點；若 ``end_time`` 超出範圍，將改用動畫終點。\ ``start_time`` 不可等於 ``end_time``\ 。 .. rst-class:: classref-item-separator ---- .. _class_AnimationPlayer_method_play_section_backwards: .. rst-class:: classref-method |void| **play_section_backwards**\ (\ name\: :ref:`StringName` = &"", start_time\: :ref:`float` = -1, end_time\: :ref:`float` = -1, custom_blend\: :ref:`float` = -1\ ) :ref:`🔗` 倒播鍵值為 ``name`` 的動畫，僅播放從 ``start_time`` 到 ``end_time`` 的區段。 此方法等同於以 ``custom_speed = -1.0`` 且 ``from_end = true`` 呼叫 :ref:`play_section()`\ ，詳情請參閱其說明。 .. rst-class:: classref-item-separator ---- .. _class_AnimationPlayer_method_play_section_with_markers: .. rst-class:: classref-method |void| **play_section_with_markers**\ (\ name\: :ref:`StringName` = &"", start_marker\: :ref:`StringName` = &"", end_marker\: :ref:`StringName` = &"", custom_blend\: :ref:`float` = -1, custom_speed\: :ref:`float` = 1.0, from_end\: :ref:`bool` = false\ ) :ref:`🔗` 播放鍵值為 ``name`` 的動畫，區段從 ``start_marker`` 開始至 ``end_marker`` 結束。 若開始標記為空，則從動畫開頭播放；若結束標記為空，則播放至動畫結尾。詳見 :ref:`play()`\ 。 .. rst-class:: classref-item-separator ---- .. _class_AnimationPlayer_method_play_section_with_markers_backwards: .. rst-class:: classref-method |void| **play_section_with_markers_backwards**\ (\ name\: :ref:`StringName` = &"", start_marker\: :ref:`StringName` = &"", end_marker\: :ref:`StringName` = &"", custom_blend\: :ref:`float` = -1\ ) :ref:`🔗` 倒播鍵值為 ``name`` 的動畫，區段從 ``start_marker`` 開始至 ``end_marker`` 結束。 此方法等同於以 ``custom_speed = -1.0`` 與 ``from_end = true`` 呼叫 :ref:`play_section_with_markers()`\ ，詳情請參閱其說明。 .. rst-class:: classref-item-separator ---- .. _class_AnimationPlayer_method_play_with_capture: .. rst-class:: classref-method |void| **play_with_capture**\ (\ name\: :ref:`StringName` = &"", duration\: :ref:`float` = -1.0, custom_blend\: :ref:`float` = -1, custom_speed\: :ref:`float` = 1.0, from_end\: :ref:`bool` = false, trans_type\: :ref:`TransitionType` = 0, ease_type\: :ref:`EaseType` = 0\ ) :ref:`🔗` 另見 :ref:`AnimationMixer.capture()`\ 。 此方法可提供比 :ref:`playback_auto_capture` 更細緻的捕捉選項。當 :ref:`playback_auto_capture` 為 ``false`` 時，其行為大致相當於： :: capture(name, duration, trans_type, ease_type) play(name, custom_blend, custom_speed, from_end) 若 ``name`` 為空，代表使用 :ref:`assigned_animation`\ 。 若 ``duration`` 為負，則時長設為目前位置到第一個關鍵影格的區間；若 ``from_end`` 為 ``true``\ ，則改為目前位置到最後一個關鍵影格的區間。 \ **注意：**\ ``duration`` 會考慮 :ref:`speed_scale`\ ，但 ``custom_speed`` 不會，因捕捉快取會與混合結果插值，而結果可能包含多段動畫。 .. rst-class:: classref-item-separator ---- .. _class_AnimationPlayer_method_queue: .. rst-class:: classref-method |void| **queue**\ (\ name\: :ref:`StringName`\ ) :ref:`🔗` 將動畫加入佇列，待目前動畫及先前所有佇列動畫播放完畢後才播放。 \ **注意：** 若目前正在播放循環動畫，除非該動畫被中止，否則佇列動畫永遠不會被播放。 .. rst-class:: classref-item-separator ---- .. _class_AnimationPlayer_method_reset_section: .. rst-class:: classref-method |void| **reset_section**\ (\ ) :ref:`🔗` 若已設定區段則會重設目前區段；若未設定則無任何作用。 .. rst-class:: classref-item-separator ---- .. _class_AnimationPlayer_method_seek: .. rst-class:: classref-method |void| **seek**\ (\ seconds\: :ref:`float`, update\: :ref:`bool` = false, update_only\: :ref:`bool` = false\ ) :ref:`🔗` 將動畫跳至 ``seconds`` 秒位置。若 ``update`` 為 ``true``\ ，動畫會立即更新；否則將於處理時更新。當前影格到 ``seconds`` 之間的事件會被略過。 若 ``update_only`` 為 ``true``\ ，方法／音訊／動畫播放軌將不會被處理。 \ **注意：** 跳到動畫結尾不會觸發 :ref:`AnimationMixer.animation_finished`\ 。若要跳過動畫並觸發訊號，請使用 :ref:`AnimationMixer.advance()`\ 。 .. rst-class:: classref-item-separator ---- .. _class_AnimationPlayer_method_set_blend_time: .. rst-class:: classref-method |void| **set_blend_time**\ (\ animation_from\: :ref:`StringName`, animation_to\: :ref:`StringName`, sec\: :ref:`float`\ ) :ref:`🔗` 指定以鍵值參照的兩段動畫之間的混合時間（秒）。 .. rst-class:: classref-item-separator ---- .. _class_AnimationPlayer_method_set_method_call_mode: .. rst-class:: classref-method |void| **set_method_call_mode**\ (\ mode\: :ref:`AnimationMethodCallMode`\ ) :ref:`🔗` **已棄用：** Use :ref:`AnimationMixer.callback_mode_method` instead. 設定「方法呼叫」軌道所使用的呼叫模式。 .. rst-class:: classref-item-separator ---- .. _class_AnimationPlayer_method_set_process_callback: .. rst-class:: classref-method |void| **set_process_callback**\ (\ mode\: :ref:`AnimationProcessCallback`\ ) :ref:`🔗` **已棄用：** Use :ref:`AnimationMixer.callback_mode_process` instead. 設定用於更新動畫的處理通知類型。 .. rst-class:: classref-item-separator ---- .. _class_AnimationPlayer_method_set_root: .. rst-class:: classref-method |void| **set_root**\ (\ path\: :ref:`NodePath`\ ) :ref:`🔗` **已棄用：** Use :ref:`AnimationMixer.root_node` instead. 設定節點路徑引用的起始節點。 .. rst-class:: classref-item-separator ---- .. _class_AnimationPlayer_method_set_section: .. rst-class:: classref-method |void| **set_section**\ (\ start_time\: :ref:`float` = -1, end_time\: :ref:`float` = -1\ ) :ref:`🔗` 變更正在播放區段的起始與結束時間，當前播放位置會被限制在新區段內。詳見 :ref:`play_section()`\ 。 .. rst-class:: classref-item-separator ---- .. _class_AnimationPlayer_method_set_section_with_markers: .. rst-class:: classref-method |void| **set_section_with_markers**\ (\ start_marker\: :ref:`StringName` = &"", end_marker\: :ref:`StringName` = &""\ ) :ref:`🔗` 變更正在播放區段的起始與結束標記，當前播放位置會被限制在新區段內。詳見 :ref:`play_section_with_markers()`\ 。 若參數為空，區段將使用動畫的開頭或結尾；若兩者皆空，代表未設定區段。 .. rst-class:: classref-item-separator ---- .. _class_AnimationPlayer_method_stop: .. rst-class:: classref-method |void| **stop**\ (\ keep_state\: :ref:`bool` = false\ ) :ref:`🔗` 停止當前播放的動畫，並將動畫位置重設為 ``0``\ 、\ ``custom_speed`` 重設為 ``1.0``\ 。另見 :ref:`pause()`\ 。 若 ``keep_state`` 為 ``true``\ ，動畫狀態不會在畫面上更新。 \ **注意：** 方法／音訊／動畫播放軌不會由此方法處理。 .. |virtual| replace:: :abbr:`virtual (本方法通常需要使用者覆寫才能生效。)` .. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)` .. |const| replace:: :abbr:`const (本方法沒有副作用。不會修改該實例的任何成員變數。)` .. |vararg| replace:: :abbr:`vararg (本方法除了這裡描述的參數外，還可以接受任意數量的參數。)` .. |constructor| replace:: :abbr:`constructor (本方法用於建構一個型別。)` .. |static| replace:: :abbr:`static (本方法無需實例即可呼叫，因此可以直接使用類別名稱呼叫。)` .. |operator| replace:: :abbr:`operator (本方法描述將本型別作為左運算元時可用的有效運算子。)` .. |bitfield| replace:: :abbr:`BitField (此值是由下列旗標組成的位元遮罩整數。)` .. |void| replace:: :abbr:`void (無回傳值。)`