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

Sprite3D

节点继承关系

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

定义

Sprite3D 在 3D 空间中显示一张 2D 图片。它最常用于"广告牌效果"（Billboard）——让图片始终朝向摄像机，看起来就像一张贴在空中的卡片。3D 场景中的远处树木、云朵、粒子特效等，经常用 Sprite3D 来实现。

一句话理解：想象一张照片被立在 3D 世界里，不管你怎么绕着它转，它都始终"面"对着你——这就是 Sprite3D 的广告牌效果。

使用频率：★★★ 一般常用——3D 游戏中常用于远处装饰、粒子特效、公告牌。

节点用途

• 在 3D 场景中显示 2D 图片
• 广告牌效果（Billboard）：图片始终朝向摄像机
• 3D 场景中的 2D 风格装饰物（树木、云朵、远景山脉）
• 粒子特效的显示载体

使用场景

场景	说明
远景装饰	远处的树木、云朵用 Sprite3D 模拟，节省性能
公告牌标签	物品上方显示的图标标记
粒子特效	火焰、烟雾、光效的显示
2D 风格元素	在 3D 游戏中混入 2D 风格的元素

常用节点搭配

搭配节点	搭配方式	用途
Label3D	作为兄弟子节点	Sprite3D 显示图标 + Label3D 显示名称
GPUParticles3D	替代/配合	更高级的粒子效果，Sprite3D 作为简单替代
StaticBody3D	作为兄弟子节点	给广告牌加上物理碰撞
Area3D	作为父节点	检测玩家是否靠近广告牌

生效必备素材/资源

资源类型	格式	说明
Texture2D	.png、.webp、.svg	要显示的 2D 图片资源

节点属性与信号

显示属性

属性	类型	默认值	继承自	说明
Texture	Texture2D	null	—	要显示的图片
Hframes	int	1	—	横向切帧数
Vframes	int	1	—	纵向切帧数
Frame	int	0	—	当前帧索引
FrameCoords	Vector2i	Vector2i(0, 0)	—	用坐标方式指定帧

朝向模式与渲染控制

属性	类型	默认值	继承自	说明
BillboardMode	BillboardMode	Disabled	—	广告牌模式（Billboard）。Enabled 始终朝向摄像机，FixedY 仅绕 Y 轴旋转
Transparent	bool	true	—	是否启用透明（图片中的透明区域可见）
AlphaCutMode	AlphaCutMode	Disabled	—	透明裁剪模式
Shaded	bool	false	—	是否受 3D 光照影响
DoubleSided	bool	true	—	是否双面渲染（从背面也能看到）
NoDepthTest	bool	false	—	禁用深度测试（常用于特效，避免被物体遮挡）
FixedSize	bool	false	—	是否固定大小（不受距离影响）
PixelSize	float	0.01	—	每像素对应的 3D 空间大小（仅在 FixedSize 时有效）

继承自 SpriteBase3D 的属性

属性	类型	默认值	继承自	说明
Centered	bool	true	[SpriteBase3D]	是否以中心为原点
Offset	Vector3	Vector3(0, 0, 0)	[SpriteBase3D]	偏移量

信号

Sprite3D 本身没有自定义信号，继承自 Node3D。

常用方法

方法	返回值	说明
GetFrame()	int	获取当前帧索引
SetFrame(value)	void	设置当前帧索引
GetFrameCount()	int	获取总帧数

代码示例

基础用法：在 3D 空间中显示图片

C

// 创建 Sprite3D 并设置图片
var sprite = new Sprite3D();
sprite.Texture = GD.Load<Texture2D>("res://assets/tree_billboard.png");
AddChild(sprite);

// 设置位置（远处的一棵树）
sprite.Position = new Vector3(20, 0, -30);

// 开启广告牌效果（始终朝向摄像机）
sprite.BillboardMode = BaseMaterial3D.BillboardMode.Enabled;

GDScript

# 创建 Sprite3D 并设置图片
var sprite = Sprite3D.new()
sprite.texture = load("res://assets/tree_billboard.png")
add_child(sprite)

# 设置位置（远处的一棵树）
sprite.position = Vector3(20, 0, -30)

# 开启广告牌效果（始终朝向摄像机）
sprite.billboard_mode = BaseMaterial3D.BILLBOARD_ENABLED

固定大小图标标记（FixedSize Billboard）

C

// 创建一个固定大小的图标标记
var icon = new Sprite3D();
icon.Texture = GD.Load<Texture2D>("res://assets/exclamation_mark.png");
icon.BillboardMode = BaseMaterial3D.BillboardMode.Enabled;
icon.FixedSize = true;       // 固定大小，不受距离影响
icon.PixelSize = 0.05f;      // 每像素 0.05 个单位
icon.NoDepthTest = true;     // 始终可见，不被遮挡
icon.Transparent = true;
AddChild(icon);

GDScript

# 创建一个固定大小的图标标记
var icon = Sprite3D.new()
icon.texture = load("res://assets/exclamation_mark.png")
icon.billboard_mode = BaseMaterial3D.BILLBOARD_ENABLED
icon.fixed_size = true       # 固定大小，不受距离影响
icon.pixel_size = 0.05       # 每像素 0.05 个单位
icon.no_depth_test = true    # 始终可见，不被遮挡
icon.transparent = true
add_child(icon)

场景树中操作 Sprite3D

C

// 从场景树获取 Sprite3D
var sprite = GetNode<Sprite3D>("BillboardTree");

// 动态更换纹理
sprite.Texture = GD.Load<Texture2D>("res://assets/autumn_tree.png");

// 让精灵只绕 Y 轴旋转朝向摄像机（适合地面上的人物/树木）
sprite.BillboardMode = BaseMaterial3D.BillboardMode.FixedY;

// 让精灵受光照影响
sprite.Shaded = true;

GDScript

# 从场景树获取 Sprite3D
var sprite = $BillboardTree

# 动态更换纹理
sprite.texture = load("res://assets/autumn_tree.png")

# 让精灵只绕 Y 轴旋转朝向摄像机（适合地面上的人物/树木）
sprite.billboard_mode = BaseMaterial3D.BILLBOARD_FIXED_Y

# 让精灵受光照影响
sprite.shaded = true