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

Sprite2D

节点继承关系

继承链：Node → Node2D → CanvasItem → Sprite2D

定义

Sprite2D 的工作就是显示一张图片。它是 2D 游戏中最常用的节点——角色外观、道具图标、背景图都可以用它。几乎每一个 2D 游戏场景里都会有它的身影。

一句话理解：把 Sprite2D 想象成一个相框——你给它一张照片（图片），它就把照片显示在游戏画面中。

使用频率：★★★★ 维度专用常用——几乎所有 2D 游戏的核心显示节点。

节点用途

• 显示角色、敌人、道具的静态外观
• 作为精灵表动画的载体（配合 Hframes/Vframes/Frame 属性）
• 显示背景图、UI 装饰元素
• 通过水平/垂直翻转实现角色朝向切换

使用场景

场景	说明
角色显示	加载角色图片，配合动画脚本实现移动
道具拾取	显示金币、钥匙、血瓶等物品图标
背景装饰	显示树木、建筑等静态背景元素
精灵表动画	一张大图切成多帧，手动切换实现动画
简单特效	配合脚本实现闪烁、旋转等简单视觉效果

常用节点搭配

搭配节点	搭配方式	用途
AnimatedSprite2D	替代关系	需要多组动画切换时，用 AnimatedSprite2D 更方便
CollisionShape2D	作为兄弟子节点	给 Sprite2D 加上碰撞体，实现物理交互
Area2D	作为父节点	检测角色与道具的距离（拾取范围）
Camera2D	作为兄弟子节点	让摄像机跟随 Sprite2D 移动

生效必备素材/资源

资源类型	格式	说明
Texture2D	.png、.jpg、.svg、.webp	要显示的图片资源
SpriteFrames（可选）	.tres	如果要做精灵表动画，需要配置帧资源

节点属性与信号

显示属性

属性	类型	默认值	继承自	说明
Texture	Texture2D	null	—	要显示的图片资源
Hframes	int	1	—	横向切帧数（精灵动画用）
Vframes	int	1	—	纵向切帧数
Frame	int	0	—	当前显示第几帧
FrameCoords	Vector2i	Vector2i(0, 0)	—	用坐标方式指定当前帧（与 Frame 互斥）

翻转与偏移

属性	类型	默认值	继承自	说明
FlipH	bool	false	—	水平翻转（左右镜像）
FlipV	bool	false	—	垂直翻转（上下镜像）
Offset	Vector2	Vector2(0, 0)	—	图片偏移量，可以微调图片位置
Centered	bool	true	—	是否以图片中心为原点。true 时图片居中对齐节点位置

继承自 CanvasItem 的常用属性

属性	类型	默认值	继承自	说明
SelfModulate	Color	Color(1, 1, 1, 1)	CanvasItem	修改节点颜色（可做变色效果）
Modulate	Color	Color(1, 1, 1, 1)	CanvasItem	修改节点及其所有子节点的颜色
Visible	bool	true	CanvasItem	是否可见
ZIndex	int	0	CanvasItem	绘制顺序，数值越大越靠前
ZAsRelative	bool	true	CanvasItem	Z 索引是否相对于父节点

信号

Sprite2D 本身没有自定义信号，继承自 CanvasItem。

常用方法

方法	返回值	说明
GetFrame()	int	获取当前帧索引
SetFrame(value)	void	设置当前帧索引
GetFrameCount()	int	获取总帧数（Hframes × Vframes）
IsFlippedH()	bool	是否水平翻转
IsFlippedV()	bool	是否垂直翻转

代码示例

基础用法：显示一张图片并翻转

C

// 创建 Sprite2D 并加载图片
var sprite = new Sprite2D();
sprite.Texture = GD.Load<Texture2D>("res://icon.svg");
AddChild(sprite);

// 水平翻转（角色转向）
sprite.FlipH = true;

GDScript

# 创建 Sprite2D 并加载图片
var sprite = Sprite2D.new()
sprite.texture = load("res://icon.svg")
add_child(sprite)

# 水平翻转（角色转向）
sprite.flip_h = true

精灵表动画：手动切帧播放

C

// 假设有一张 4 帧横排的精灵表
var sprite = GetNode<Sprite2D>("Sprite2D");
sprite.Hframes = 4;
sprite.Vframes = 1;

// 在 _Process 中循环切换帧
private float _timer = 0f;
private const float FrameDuration = 0.15f; // 每帧停留 0.15 秒

public override void _Process(double delta)
{
    _timer += (float)delta;
    if (_timer >= FrameDuration)
    {
        _timer -= FrameDuration;
        sprite.Frame = (sprite.Frame + 1) % sprite.Hframes;
    }
}

GDScript

# 假设有一张 4 帧横排的精灵表
var sprite = $Sprite2D
sprite.hframes = 4
sprite.vframes = 1

# 在 _process 中循环切换帧
var _timer := 0.0
var frame_duration := 0.15 # 每帧停留 0.15 秒

func _process(delta):
    _timer += delta
    if _timer >= frame_duration:
        _timer -= frame_duration
        sprite.frame = (sprite.frame + 1) % sprite.hframes

场景树中获取并操作 Sprite2D

C

// 从场景树中获取 Sprite2D 节点
var sprite = GetNode<Sprite2D>("Character/Sprite2D");

// 动态更换图片（比如角色换装）
sprite.Texture = GD.Load<Texture2D>("res://assets/character_armor.png");

// 修改颜色（受伤闪红）
sprite.SelfModulate = Colors.Red;

// 调整偏移（微调角色图片位置）
sprite.Offset = new Vector2(0, -5);

GDScript

# 从场景树中获取 Sprite2D 节点
var sprite = $Character/Sprite2D

# 动态更换图片（比如角色换装）
sprite.texture = load("res://assets/character_armor.png")

# 修改颜色（受伤闪红）
sprite.self_modulate = Color.RED

# 调整偏移（微调角色图片位置）
sprite.offset = Vector2(0, -5)