Label3D

继承： GeometryInstance3D < VisualInstance3D < Node3D < Node < Object

用于在 3D 空间显示纯文本的节点。

描述

用于在 3D 空间显示纯文本的节点。通过调整该节点的各种属性，可以配置文本外观、是否面朝相机等特性。

教程

3D 文本

属性

float	alpha_antialiasing_edge	`0.0`
AlphaAntiAliasing	alpha_antialiasing_mode	`0`
AlphaCutMode	alpha_cut	`0`
float	alpha_hash_scale	`1.0`
float	alpha_scissor_threshold	`0.5`
AutowrapMode	autowrap_mode	`0`
BitField[LineBreakFlag]	autowrap_trim_flags	`192`
BillboardMode	billboard	`0`
ShadowCastingSetting	cast_shadow	`0` (overrides GeometryInstance3D)
bool	double_sided	`true`
bool	fixed_size	`false`
Font	font
int	font_size	`32`
GIMode	gi_mode	`0` (overrides GeometryInstance3D)
HorizontalAlignment	horizontal_alignment	`1`
BitField[JustificationFlag]	justification_flags	`163`
String	language	`""`
float	line_spacing	`0.0`
Color	modulate	`Color(1, 1, 1, 1)`
bool	no_depth_test	`false`
Vector2	offset	`Vector2(0, 0)`
Color	outline_modulate	`Color(0, 0, 0, 1)`
int	outline_render_priority	`-1`
int	outline_size	`12`
float	pixel_size	`0.005`
int	render_priority	`0`
bool	shaded	`false`
StructuredTextParser	structured_text_bidi_override	`0`
Array	structured_text_bidi_override_options	`[]`
String	text	`""`
Direction	text_direction	`0`
TextureFilter	texture_filter	`3`
bool	uppercase	`false`
VerticalAlignment	vertical_alignment	`1`
float	width	`500.0`

方法

TriangleMesh	generate_triangle_mesh() const
bool	get_draw_flag(flag: DrawFlags) const
void	set_draw_flag(flag: DrawFlags, enabled: bool)

枚举

enum DrawFlags: 🔗

DrawFlags FLAG_SHADED = 0

如果打开，环境中的灯光会影响该标签。

DrawFlags FLAG_DOUBLE_SIDED = 1

如果打开，从后面也可以看到文本。如果不打开，从后面看该文本是不可见的。

DrawFlags FLAG_DISABLE_DEPTH_TEST = 2

禁用深度测试，所以这个对象被画在所有其他对象的上面。但是，在绘制顺序中，在它之后绘制的对象可能会覆盖它。

DrawFlags FLAG_FIXED_SIZE = 3

标签会根据深度进行缩放，从而在屏幕上始终以相同的大小显示。

DrawFlags FLAG_MAX = 4

代表 DrawFlags 枚举的大小。

enum AlphaCutMode: 🔗

AlphaCutMode ALPHA_CUT_DISABLED = 0

该模式会执行标准的 Alpha 混合。它可以显示半透明区域，但当多个透明材质重叠时，可能会出现透明度排序问题。GeometryInstance3D.cast_shadow 在使用该透明模式时无效；Label3D 永远不会投射阴影。

AlphaCutMode ALPHA_CUT_DISCARD = 1

该模式仅允许完全透明或完全不透明的像素。除非启用了某种形式的屏幕空间抗锯齿（见 ProjectSettings.rendering/anti_aliasing/quality/screen_space_aa），否则会看到粗糙的边缘。该模式也被称为 Alpha 测试 或 1 位透明度。

注意：该模式可能会出现抗锯齿字体和轮廓问题，请尝试调整 alpha_scissor_threshold 或使用 MSDF 字体。

注意：当使用具有重叠字形的文本（例如草书）时，该模式可能会在正文和轮廓之间，出现透明度排序问题。

AlphaCutMode ALPHA_CUT_OPAQUE_PREPASS = 2

这个模式会在深度预处理时绘制完全不透明的像素。比 ALPHA_CUT_DISABLED 或 ALPHA_CUT_DISCARD 要慢，但能够对半透明区域和平滑边缘进行正确的排序。

注意：文本中存在重叠的字形时（例如手写体），这个模式可能会造成主文本和轮廓的透明度排序问题。

AlphaCutMode ALPHA_CUT_HASH = 3

该模式绘制时会截断所有低于空间确定性阈值的值，其余值将保持不透明。

属性说明

float alpha_antialiasing_edge = 0.0 🔗

void set_alpha_antialiasing_edge(value: float)
float get_alpha_antialiasing_edge()

将在 Alpha 通道上应用抗锯齿的阈值。

AlphaAntiAliasing alpha_antialiasing_mode = 0 🔗

void set_alpha_antialiasing(value: AlphaAntiAliasing)
AlphaAntiAliasing get_alpha_antialiasing()

要应用的 Alpha 抗锯齿类型。

AlphaCutMode alpha_cut = 0 🔗

void set_alpha_cut_mode(value: AlphaCutMode)
AlphaCutMode get_alpha_cut_mode()

精灵所使用的 Alpha 剪切模式。

float alpha_hash_scale = 1.0 🔗

void set_alpha_hash_scale(value: float)
float get_alpha_hash_scale()

Alpha Hash 的哈希比例。推荐 0 和 2 之间的值。

float alpha_scissor_threshold = 0.5 🔗

void set_alpha_scissor_threshold(value: float)
float get_alpha_scissor_threshold()

Alpha 裁剪丢弃数值的阈值。

AutowrapMode autowrap_mode = 0 🔗

void set_autowrap_mode(value: AutowrapMode)
AutowrapMode get_autowrap_mode()

如果设置为 TextServer.AUTOWRAP_OFF 以外的值，则文本将在节点的边界矩形内自动换行。如果你调整节点大小，就会自动更改其高度，从而显示所有文本。

BitField[LineBreakFlag] autowrap_trim_flags = 192 🔗

void set_autowrap_trim_flags(value: BitField[LineBreakFlag])
BitField[LineBreakFlag] get_autowrap_trim_flags()

自动换行空格修剪标志。详见 TextServer.BREAK_TRIM_START_EDGE_SPACES 和 TextServer.BREAK_TRIM_END_EDGE_SPACES。

BillboardMode billboard = 0 🔗

void set_billboard_mode(value: BillboardMode)
BillboardMode get_billboard_mode()

标签使用的公告板模式。

bool double_sided = true 🔗

void set_draw_flag(flag: DrawFlags, enabled: bool)
bool get_draw_flag(flag: DrawFlags) const

如果为 true，则从后面也可以看到文本，如果为 false，则从后面看它是不可见的。

bool fixed_size = false 🔗

void set_draw_flag(flag: DrawFlags, enabled: bool)
bool get_draw_flag(flag: DrawFlags) const

如果为 true，则标签始终以相同的大小渲染，忽略距离。标签在屏幕上的大小与相机距离标签原点 1.0 单位时相同，忽略与相机的实际距离。Camera3D 的视野（使用正交/视锥模式时则为 Camera3D.size）仍然会影响标签绘制的大小。

Font font 🔗

void set_font(value: Font)
Font get_font()

用于显示文本的字体配置。

int font_size = 32 🔗

void set_font_size(value: int)
int get_font_size()

Label3D 文本的字体大小。为了让字体在近距离时看起来更细腻，可增加 font_size，同时减小 pixel_size。

较大的字体大小需要更多时间来渲染新字符，这可能会导致在游戏过程中卡顿。

HorizontalAlignment horizontal_alignment = 1 🔗

void set_horizontal_alignment(value: HorizontalAlignment)
HorizontalAlignment get_horizontal_alignment()

控制文本的水平对齐方式。支持左对齐、居中对齐、右对齐、填充（即两端对齐）。

BitField[JustificationFlag] justification_flags = 163 🔗

void set_justification_flags(value: BitField[JustificationFlag])
BitField[JustificationFlag] get_justification_flags()

行填充对齐规则。

String language = "" 🔗

void set_language(value: String)
String get_language()

Language code used for line-breaking and text shaping algorithms. If left empty, the current locale is used instead.

float line_spacing = 0.0 🔗

void set_line_spacing(value: float)
float get_line_spacing()

行与行之间的额外纵向留白（单位为像素），留白会被添加到行的降部。该值可以为负数。

Color modulate = Color(1, 1, 1, 1) 🔗

void set_modulate(value: Color)
Color get_modulate()

该 Label3D 的文本颜色 Color。

bool no_depth_test = false 🔗

void set_draw_flag(flag: DrawFlags, enabled: bool)
bool get_draw_flag(flag: DrawFlags) const

如果为 true，深度测试被禁用，对象将按渲染顺序绘制。

Vector2 offset = Vector2(0, 0) 🔗

void set_offset(value: Vector2)
Vector2 get_offset()

文本绘制偏移（单位为像素）。

Color outline_modulate = Color(0, 0, 0, 1) 🔗

void set_outline_modulate(value: Color)
Color get_outline_modulate()

文本轮廓的色调。

int outline_render_priority = -1 🔗

void set_outline_render_priority(value: int)
int get_outline_render_priority()

设置文本轮廓的渲染优先级。优先级高的物体将被排序在优先级低的物体前面。

注意：仅在 alpha_cut 为 ALPHA_CUT_DISABLED（默认值）时适用。

注意：仅适用于透明物体的排序。这不会影响透明物体相对于不透明物体的排序方式。这是因为不透明对象不被排序，而透明对象则从后往前排序（取决于优先级）。

int outline_size = 12 🔗

void set_outline_size(value: int)
int get_outline_size()

文本轮廓大小。

float pixel_size = 0.005 🔗

void set_pixel_size(value: float)
float get_pixel_size()

标签中一个像素宽度对应缩放至的 3D 大小。要让字体在较近距离时也能够看到细节，请在减小 pixel_size 的同时增大 font_size。

int render_priority = 0 🔗

void set_render_priority(value: int)
int get_render_priority()

设置文本的渲染优先级。优先级高的物体将被排序在优先级低的物体前面。

注意：仅在 alpha_cut 为 ALPHA_CUT_DISABLED（默认值）时适用。

注意：仅适用于透明物体的排序。这不会影响透明物体相对于不透明物体的排序方式。这是因为不透明对象不被排序，而透明对象则从后往前排序（取决于优先级）。

bool shaded = false 🔗

void set_draw_flag(flag: DrawFlags, enabled: bool)
bool get_draw_flag(flag: DrawFlags) const

如果为 true，则 Environment 中的 Light3D 会影响该标签。

StructuredTextParser structured_text_bidi_override = 0 🔗

void set_structured_text_bidi_override(value: StructuredTextParser)
StructuredTextParser get_structured_text_bidi_override()

为结构化文本设置 BiDi 算法覆盖。

Array structured_text_bidi_override_options = [] 🔗

void set_structured_text_bidi_override_options(value: Array)
Array get_structured_text_bidi_override_options()

设置 BiDi 覆盖的附加选项。

String text = "" 🔗

void set_text(value: String)
String get_text()

要在屏幕上显示的文本。

Direction text_direction = 0 🔗

void set_text_direction(value: Direction)
Direction get_text_direction()

基础文本书写方向。

TextureFilter texture_filter = 3 🔗

void set_texture_filter(value: TextureFilter)
TextureFilter get_texture_filter()

纹理的过滤标志。

bool uppercase = false 🔗

void set_uppercase(value: bool)
bool is_uppercase()

如果为 true，所有文本都将显示为大写。

VerticalAlignment vertical_alignment = 1 🔗

void set_vertical_alignment(value: VerticalAlignment)
VerticalAlignment get_vertical_alignment()

控制文本的垂直对齐方式。支持顶部对齐、居中对齐、底部对齐。

float width = 500.0 🔗

void set_width(value: float)
float get_width()

文本宽度（单位为像素），用于自动换行和填充对齐。

方法说明

TriangleMesh generate_triangle_mesh() const 🔗

返回使用该标签的顶点组成的 TriangleMesh，遵循当前的配置（例如 pixel_size）。

bool get_draw_flag(flag: DrawFlags) const 🔗

返回指定标志的值。

void set_draw_flag(flag: DrawFlags, enabled: bool) 🔗

如果为 true，则启用 flag 指定的标志。