AnimatedSprite3D

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

3D 世界中的 2D 精灵节点，可以使用多个 2D 纹理进行动画处理。

描述

AnimatedSprite3D 与 Sprite3D 节点类似，但是包含多张纹理，可用作动画 sprite_frames。动画使用 SpriteFrames 资源创建，可以导入图像文件（或包含此类文件的文件夹）为该精灵提供动画帧。可以在编辑器的“动画帧”底部面板中配置 SpriteFrames 资源。

教程

• 2D 精灵动画（也适用于 3D）

属性

方法

信号

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 中，就会非常有用。

示例：

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。