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。与直接设置 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("行走动画_换皮版")
animated_sprite.set_frame_and_progress(current_frame, current_progress)

void stop() 🔗

停止当前正在播放的动画。会将动画的位置重置为 0，并将 custom_speed 重置为 1.0。另见 pause()。