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 资源。

教程¶

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 资源。可以对 SpriteFrames 资源进行加载、编辑、清空、唯一化、保存状态等操作。

方法说明¶

float get_playing_speed() const 🔗

返回当前动画的实际播放速度，未播放时则为 0。这个速度是 speed_scale 属性乘以调用 play 时指定的 custom_speed 参数。

如果当前动画是倒放的，则返回负值。

bool is_playing() const 🔗

如果动画目前正在播放，则返回 true（即便 speed_scale 和/或 custom_speed 为 0）。

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 的动画。

这个方法是简写，等价于调用 play 时使用 custom_speed = -1.0 和 from_end = true，所以更多信息请参阅其描述。

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

设置 frame 时会隐式将 frame_progress 重置为 0.0，但这个方法可以避免。

如果你想要把当前的 frame_progress 带到其他 frame 中，就会非常有用。

示例：

# 更改动画的同时保留帧索引和进度。
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。