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

AnimatedSprite3D

繼承： SpriteBase3D < GeometryInstance3D < VisualInstance3D < Node3D < Node < Object

3D 世界中的 2D 精靈節點，可使用多張 2D 紋理做動畫。

說明

AnimatedSprite3D 與 Sprite3D 節點類似，但會使用多張紋理作為動畫 sprite_frames。動畫使用 SpriteFrames 資源建立，可匯入影像檔（或資料夾）提供影格，並可在編輯器下方的 SpriteFrames 面板中設定。

教學

屬性

StringName

animation

&"default"

String

autoplay

""

int

frame

0

float

frame_progress

0.0

float

speed_scale

1.0

SpriteFrames

sprite_frames

方法

float

get_playing_speed() const

bool

is_playing() const

void

pause()

void

play(name: StringName = &"", custom_speed: float = 1.0, from_end: bool = false)

void

play_backwards(name: StringName = &"")

void

set_frame_and_progress(frame: int, progress: float)

void

stop()

訊號

animation_changed() 🔗

當 animation 發生變更時觸發。

animation_finished() 🔗

當動畫播放至結束（倒放則為起點）時觸發，並會暫停播放。

注意： 若動畫為循環播放則不會發出此訊號。

animation_looped() 🔗

動畫進入下一次循環時觸發。

frame_changed() 🔗

當 frame 改變時觸發。

sprite_frames_changed() 🔗

當 sprite_frames 變更時觸發。

屬性說明

StringName animation = &"default" 🔗

當前動畫來自 sprite_frames 資源。若此值變更，frame 與 frame_progress 均會被重設。

String autoplay = "" 🔗

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

int frame = 0 🔗

  • void set_frame(value: int)

  • int get_frame()

顯示的動畫影格索引。設定此屬性會同時重設 frame_progress；若不希望如此，請改用 set_frame_and_progress()。

float frame_progress = 0.0 🔗

  • void set_frame_progress(value: float)

  • float get_frame_progress()

從當前影格過渡到下一影格的進度值，範圍為 0.0–1.0。若動畫倒放，則值會從 1.0 遞減至 0.0。

float speed_scale = 1.0 🔗

  • void set_speed_scale(value: float)

  • float get_speed_scale()

速度倍率。值為 1 時以正常速度播放；0.5 為半速；2 為兩倍速。

若為負值則反向播放；若為 0 則動畫停止推進。

SpriteFrames sprite_frames 🔗

包含動畫的 SpriteFrames 資源，並可進行載入、編輯、清除、唯一化與儲存等操作。

方法說明

float get_playing_speed() const 🔗

回傳目前動畫的實際播放速度，若未播放則為 0。此速度為 speed_scale 與呼叫 play() 時指定的 custom_speed 相乘所得。

若動畫以倒放方式播放，則回傳負值。

bool is_playing() const 🔗

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

void pause() 🔗

暫停目前正在播放的動畫。系統會保留 frame 與 frame_progress，若在無參數下呼叫 play() 或 play_backwards()，將自當前位置續播。

另請參閱 stop()。

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

播放鍵名為 name 的動畫。若 custom_speed 為負數且 from_end 為 true，將倒放動畫（等同於呼叫 play_backwards()）。

若以相同 name 或未指定 name 呼叫此方法，則已暫停的動畫會續播。

void play_backwards(name: StringName = &"") 🔗

倒放鍵名為 name 的動畫。

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

void set_frame_and_progress(frame: int, progress: float) 🔗

同時將 frame 與 frame_progress 設為指定值。與直接設定 frame 不同，此方法不會自動將 frame_progress 重設為 0.0。

範例： 在保留現有 frame 與 frame_progress 的情況下切換動畫：

var current_frame = animated_sprite.get_frame()
var current_progress = animated_sprite.get_frame_progress()
animated_sprite.play("walk_another_skin")
animated_sprite.set_frame_and_progress(current_frame, current_progress)

void stop() 🔗

停止目前動畫。動畫位置將重設為 0，且 custom_speed 亦重設為 1.0。另請參閱 pause()。