AnimatedSprite3D

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

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

說明

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

教學

• 2D 精靈動畫（亦適用於 3D）

屬性

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" 🔗

• void set_animation(value: StringName)

• StringName get_animation()

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

---

String autoplay = "" 🔗

• void set_autoplay(value: String)

• String get_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 🔗

• void set_sprite_frames(value: SpriteFrames)

• SpriteFrames get_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 的情況下切換動畫：

GDScript

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()。