最后同步日期：2026-04-15 | Godot 官方原文 — AnimatedSprite3D

AnimatedSprite3D

节点继承关系

继承链：Node → Node3D → [SpriteBase3D] → AnimatedSprite3D

继承自 SpriteBase3D

类型	名称	说明
属性	Centered	是否以中心为原点
属性	Offset	偏移量
属性	Billboard	朝向模式（固定 / Y 轴 / 全朝相机）
属性	Texture	显示的纹理

Node3D

类型	名称	说明
属性	Position	本地位置（X / Y / Z）
属性	GlobalPosition	全局位置
属性	Rotation	旋转角度（欧拉角，弧度）
属性	Scale	缩放比例
属性	TopLevel	是否脱离父节点的变换
方法	LookAt()	朝向目标点
方法	ToGlobal()	本地坐标转全局坐标
方法	ToLocal()	全局坐标转本地坐标
方法	RotateX/Y/Z()	绕指定轴旋转

Node

类型	名称	说明
属性	Name	节点名称
属性	ProcessMode	处理模式（始终 / 暂停时 / 仅编辑器）
属性	ProcessPriority	处理优先级，数字越小越先执行
信号	ready	节点进入场景树并准备就绪
信号	tree_entered	节点进入场景树
信号	tree_exited	节点完全离开场景树
方法	GetNode<T>()	按路径获取子节点
方法	AddChild()	添加子节点
方法	RemoveChild()	移除子节点
方法	QueueFree()	帧结束后释放节点
方法	GetParent()	获取父节点

定义

AnimatedSprite3D 在 3D 空间中播放精灵帧动画，继承自 SpriteBase3D。它和 AnimatedSprite2D 的用法几乎一模一样，只不过它活在 3D 世界里。比如 3D 场景中一面会动的魔法卷轴、一只 2D 风格的小精灵在 3D 地形上走来走去，都可以用它。

一句话理解：Sprite3D 是 3D 世界里的一张照片，AnimatedSprite3D 是 3D 世界里的一段 GIF 动图。

使用频率：★★★ 一般常用——在 2D/3D 混合风格的游戏中常用。

节点用途

• 在 3D 空间中播放 2D 帧动画
• 管理多组动画并随时切换
• 配合广告牌模式（Billboard）实现始终朝向摄像机的动画效果
• 2D 风格角色/特效在 3D 世界中的表现

使用场景

场景	说明
2D 风格角色在 3D 世界中	类似《原神》中远处 NPC 的 2D 动画表现
魔法卷轴/符文动画	3D 场景中漂浮的动画卷轴
火把/光源动画	3D 火把上方的火焰动画效果
传送门效果	旋转、闪烁的传送门动画

常用节点搭配

搭配节点	搭配方式	用途
Label3D	作为兄弟子节点	动画精灵 + 3D 文字标签
Area3D	作为父节点	检测玩家靠近时触发动画
AudioStreamPlayer3D	作为兄弟子节点	播放动画对应的 3D 音效
PointLight3D	作为兄弟子节点	配合火焰动画产生光照效果

生效必备素材/资源

资源类型	格式	说明
SpriteFrames	.tres / .res	核心资源！存放所有动画组和帧图片
Texture2D	.png、.webp	每一帧的图片资源，嵌入到 SpriteFrames 中

节点属性与信号

动画控制属性

属性	类型	默认值	继承自	说明
SpriteFrames	SpriteFrames	null	—	动画资源，存放所有动画组和帧图片
Animation	StringName	&""	—	当前播放的动画名称
Frame	int	0	—	当前帧索引
SpeedScale	float	1.0	—	播放速度倍率。1.5 = 1.5 倍速

朝向模式与渲染控制

属性	类型	默认值	继承自	说明
BillboardMode	BillboardMode	Disabled	—	广告牌模式（Billboard）。Enabled 始终朝向摄像机，FixedY 仅绕 Y 轴旋转
Transparent	bool	true	—	是否启用透明
Shaded	bool	false	—	是否受 3D 光照影响
DoubleSided	bool	true	—	是否双面渲染
NoDepthTest	bool	false	—	禁用深度测试（常用于特效）
FixedSize	bool	false	—	是否固定大小
PixelSize	float	0.01	—	每像素对应的 3D 空间大小

自动播放

属性	类型	默认值	继承自	说明
Autoplay	StringName	&""	—	场景加载后自动播放的动画名

信号

信号	参数	触发时机
AnimationFinished	无	当前动画播放完毕（仅在非循环动画时触发）
AnimationFrameChanged	animation: StringName, frame: int	帧切换时触发

常用方法

方法	返回值	说明
Play(name, customSpeed, fromEnd)	void	播放指定动画
Pause()	void	暂停当前动画
Stop()	void	停止动画并回到第一帧
IsPlaying()	bool	当前是否正在播放动画

代码示例

基础用法：播放 3D 精灵动画

C

var anim3D = GetNode<AnimatedSprite3D>("AnimatedSprite3D");

// 播放"飞行"动画
anim3D.Play("fly");

// 让精灵始终朝向摄像机（广告牌效果）
anim3D.BillboardMode = BaseMaterial3D.BillboardMode.FixedY;

// 加速播放
anim3D.SpeedScale = 1.5f;

GDScript

var anim_3d = $AnimatedSprite3D

# 播放"飞行"动画
anim_3d.play("fly")

# 让精灵始终朝向摄像机（广告牌效果）
anim_3d.billboard_mode = BaseMaterial3D.BILLBOARD_FIXED_Y

# 加速播放
anim_3d.speed_scale = 1.5

动画播放完毕回调

C

var anim3D = GetNode<AnimatedSprite3D>("AnimatedSprite3D");

// 飞行动画播完后切换到"盘旋"动画
anim3D.AnimationFinished += () =>
{
    GD.Print("飞行动画播完了，切换到盘旋");
    anim3D.Play("hover");
};

GDScript

var anim_3d = $AnimatedSprite3D

# 飞行动画播完后切换到"盘旋"动画
anim_3d.animation_finished.connect(func():
    print("飞行动画播完了，切换到盘旋")
    anim_3d.play("hover")
)

火把动画 + 光照效果

C

public partial class Torch : Node3D
{
    private AnimatedSprite3D _fireAnim;
    private PointLight3D _light;

    public override void _Ready()
    {
        _fireAnim = GetNode<AnimatedSprite3D>("AnimatedSprite3D");
        _light = GetNode<PointLight3D>("PointLight3D");

        // 播放火焰动画
        _fireAnim.Play("fire");
        _fireAnim.BillboardMode = BaseMaterial3D.BillboardMode.Enabled;
        _fireAnim.NoDepthTest = true;
        _fireAnim.Transparent = true;
    }

    public override void _Process(double delta)
    {
        // 让光源随机闪烁，模拟火焰光影效果
        _light.Energy = 2.0f + (float)GD.RandRange(-0.3, 0.3);
    }
}

GDScript

extends Node3D

@onready var _fire_anim: AnimatedSprite3D = $AnimatedSprite3D
@onready var _light: PointLight3D = $PointLight3D

func _ready():
    # 播放火焰动画
    _fire_anim.play("fire")
    _fire_anim.billboard_mode = BaseMaterial3D.BILLBOARD_ENABLED
    _fire_anim.no_depth_test = true
    _fire_anim.transparent = true

func _process(delta):
    # 让光源随机闪烁，模拟火焰光影效果
    _light.energy = 2.0 + randf_range(-0.3, 0.3)