Up to date

This page is up to date for Godot 4.2. If you still find outdated information, please open an issue.

AnimatedSprite3D

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

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

描述

AnimatedSprite3DSprite3D 节点类似,但是包含多张纹理,可用作动画 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 ( StringName name=&"", float custom_speed=1.0, bool from_end=false )

void

play_backwards ( StringName name=&"" )

void

set_frame_and_progress ( int frame, float progress )

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

  • void set_autoplay ( String value )

  • String get_autoplay ( )

场景加载时要播放的动画名称。


int frame = 0

  • void set_frame ( int value )

  • int get_frame ( )

所显示动画帧的索引。设置这个属性会重置 frame_progress。如果不希望这样,请使用 set_frame_and_progress


float frame_progress = 0.0

  • void set_frame_progress ( float value )

  • float get_frame_progress ( )

当前帧过渡到下一帧的进度值,在 0.01.0 之间。如果动画是倒放的,则该值是从 1.00.0


float speed_scale = 1.0

  • void set_speed_scale ( float value )

  • float get_speed_scale ( )

速度缩放比。例如,如果该值为 1,则动画以正常速度播放。如果它是 0.5,那么它会半速播放。如果是 2,则会以双倍速度播放。

如果设置为负值,则动画反向播放。如果设置为0,则动画不会前进。


SpriteFrames sprite_frames

包含动画的 SpriteFrames 资源。可以对 SpriteFrames 资源进行加载、编辑、清空、唯一化、保存状态等操作。


方法说明

float get_playing_speed ( ) const

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

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


bool is_playing ( ) const

如果动画目前正在播放,则返回 true(即便 speed_scale 和/或 custom_speed0)。


void pause ( )

暂停当前正在播放的动画。会保留 frameframe_progress,不带参数调用 playplay_backwards 会从当前播放位置恢复播放该动画。

另见 stop


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

播放名称键为 name 的动画。如果 custom_speed 为负且 from_endtrue,则该动画会倒放(等价于 play_backwards)。

如果调用这个方法时使用了相同的动画名称 name 或者没有使用 name 参数,则会继续播放已暂停的分配动画。


void play_backwards ( StringName name=&"" )

倒放名称键为 name 的动画。

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


void set_frame_and_progress ( int frame, float progress )

设置 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