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

Label3D

节点继承关系

继承链：Node → Node3D → [VisualInstance3D] → [GeometryInstance3D] → Label3D

定义

Label3D 在 3D 空间中显示文字。和 UI 界面中的 Label 不同，Label3D 的文字是"放在 3D 世界里"的——它会随着距离变远而变小，会被其他 3D 物体遮挡，就像写在现实世界物体上的字一样。常用于角色头顶的名字、物品标签、路标等。

一句话理解：Label 是贴在屏幕上的便签纸，Label3D 是立在 3D 世界里的路牌——远近大小会变化，会被东西挡住。

使用频率：★★★ 一般常用——3D 游戏中需要场景内文字时使用。

节点用途

• 显示角色头顶的名字（NPC 名、玩家名）
• 显示 3D 场景中的路标、指示牌
• 显示物品上方的标签（宝箱"已开启"、门"上锁"等）
• 显示场景中的提示信息

使用场景

场景	说明
角色名字	NPC/玩家头顶飘着的名字
物品标签	宝箱、门、开关等物体上方的说明
路标指示	3D 世界中的方向指示牌
场景提示	"按 E 键交互"等提示信息

常用节点搭配

搭配节点	搭配方式	用途
Sprite3D	作为兄弟子节点	Sprite3D 显示图标 + Label3D 显示名称
Control（Label）	替代关系	需要固定在屏幕上时用 UI Label
Area3D	作为父节点	检测玩家靠近时显示/隐藏标签
TextMesh	替代关系	需要真正的 3D 立体文字时用 TextMesh

生效必备素材/资源

资源类型	格式	说明
Font（可选）	.ttf、.otf、.woff2	自定义字体文件。不设置则使用默认字体

节点属性与信号

文本属性

属性	类型	默认值	继承自	说明
Text	String	""	—	要显示的文字内容
Font	Font	null（使用主题默认）	—	自定义字体
FontSize	int	16（使用主题默认）	—	字体大小（单位：像素）
TextDirection	TextDirection	Auto	—	文字方向
Uppercase	bool	false	—	是否全部大写

外观属性

属性	类型	默认值	继承自	说明
PixelSize	float	0.01	—	每像素对应的 3D 空间大小。值越小文字越大
BillboardMode	BillboardMode	Disabled	—	广告牌模式（Billboard）。Enabled 始终朝向摄像机，FixedY 仅绕 Y 轴旋转
Color	Color	Color(1, 1, 1, 1)	—	文字颜色
OutlineColor	Color	Color(0, 0, 0, 1)	—	描边颜色
OutlineSize	int	0	—	描边大小
FontColor	Color	Color(1, 1, 1, 1)	—	字体颜色（与 Color 功能相同）

布局属性

属性	类型	默认值	继承自	说明
HorizontalAlignment	HorizontalAlignment	Center	—	水平对齐方式
VerticalAlignment	VerticalAlignment	Center	—	垂直对齐方式
AutowrapMode	AutowrapMode	Off	—	自动换行模式
Width	float	0.0	—	文字区域宽度（开启自动换行后生效）

渲染控制

属性	类型	默认值	继承自	说明
Transparent	bool	true	—	是否启用透明
NoDepthTest	bool	false	—	禁用深度测试（始终显示在最前面）
Shaded	bool	false	—	是否受 3D 光照影响
DrawFlag	DrawFlags	—	—	绘制标志（描边、阴影等）

继承自 GeometryInstance3D 的常用属性

属性	类型	默认值	继承自	说明
CastShadow	ShadowCastingSetting	Off	[GeometryInstance3D]	是否投射阴影
GIMode	GIMode	Disabled	[GeometryInstance3D]	全局光照模式

信号

Label3D 本身没有自定义信号，继承自 [GeometryInstance3D] 和 Node3D。

常用方法

方法	返回值	说明
GetText()	String	获取当前文本
SetText(text)	void	设置文本
SetFont(font)	void	设置字体
SetPixelSize(value)	void	设置像素大小

代码示例

基础用法：在 3D 空间中显示文字

C

// 创建角色头顶名字
var nameLabel = new Label3D();
nameLabel.Text = "勇者阿尔伯特";
nameLabel.PixelSize = 0.02f;
nameLabel.BillboardMode = BaseMaterial3D.BillboardMode.Enabled;
nameLabel.Position = new Vector3(0, 2.5f, 0); // 头顶上方
nameLabel.Color = Colors.White;
nameLabel.OutlineSize = 8;
nameLabel.OutlineColor = new Color(0, 0, 0, 0.5f);
AddChild(nameLabel);

GDScript

# 创建角色头顶名字
var name_label = Label3D.new()
name_label.text = "勇者阿尔伯特"
name_label.pixel_size = 0.02
name_label.billboard_mode = BaseMaterial3D.BILLBOARD_ENABLED
name_label.position = Vector3(0, 2.5, 0)  # 头顶上方
name_label.color = Color.WHITE
name_label.outline_size = 8
name_label.outline_color = Color(0, 0, 0, 0.5)
add_child(name_label)

物品标签：玩家靠近时显示

C

public partial class TreasureChest : Node3D
{
    private Label3D _hintLabel;

    public override void _Ready()
    {
        _hintLabel = GetNode<Label3D>("Label3D");
        _hintLabel.Text = "按 E 键打开";
        _hintLabel.Visible = false;
        _hintLabel.BillboardMode = BaseMaterial3D.BillboardMode.Enabled;
    }

    public void OnBodyEntered(Node3D body)
    {
        // 玩家靠近时显示提示
        if (body.IsInGroup("player"))
        {
            _hintLabel.Visible = true;
        }
    }

    public void OnBodyExited(Node3D body)
    {
        // 玩家离开时隐藏提示
        if (body.IsInGroup("player"))
        {
            _hintLabel.Visible = false;
        }
    }
}

GDScript

extends Node3D

@onready var _hint_label: Label3D = $Label3D

func _ready():
    _hint_label.text = "按 E 键打开"
    _hint_label.visible = false
    _hint_label.billboard_mode = BaseMaterial3D.BILLBOARD_ENABLED

func _on_body_entered(body):
    # 玩家靠近时显示提示
    if body.is_in_group("player"):
        _hint_label.visible = true

func _on_body_exited(body):
    # 玩家离开时隐藏提示
    if body.is_in_group("player"):
        _hint_label.visible = false

始终显示在最前面的标签（不受遮挡）

C

// 创建一个始终可见的标签（不被 3D 物体遮挡）
var label = new Label3D();
label.Text = "任务目标";
label.NoDepthTest = true;  // 禁用深度测试
label.BillboardMode = BaseMaterial3D.BillboardMode.Enabled;
label.Color = Colors.Yellow;
label.OutlineSize = 4;
AddChild(label);

GDScript

# 创建一个始终可见的标签（不被 3D 物体遮挡）
var label = Label3D.new()
label.text = "任务目标"
label.no_depth_test = true   # 禁用深度测试
label.billboard_mode = BaseMaterial3D.BILLBOARD_ENABLED
label.color = Color.YELLOW
label.outline_size = 4
add_child(label)