engine/docs/en/graphics/2D/text.md

order, title, type, group, label

order	title	type	group	label
4	Text Renderer	Graphics	2D	Graphics/2D

TextRenderer component is used to display text in 3D/2D scenes.

Editor Usage

Add Text Component

To display text, you need to add a text component to an entity, as shown below:

Parameter Description

Select an entity with the TextRenderer component, and you can set all related properties in the inspector on the right to configure the text component:

The property descriptions are as follows:

Property	Description
Text	The text to be displayed
Color	Text color
FontSize	Font size of the text
Font	Custom font
Width	The width of the text in 3D space, used for bounding box calculation and determining line breaks when multi-line text is needed
Height	The height of the text in 3D space, used for bounding box calculation and determining line breaks when multi-line text is needed
LineSpacing	Line spacing
FontStyle	Font style settings: bold/italic
HorizontalAlignment	Horizontal alignment options: Left/Center/Right
VerticalAlignment	Vertical alignment options: Top/Center/Bottom
EnableWrapping	Whether to enable wrapping mode. When wrapping mode is enabled, the text will wrap according to the set width. If the width is set to 0, the text will not render
OverflowMode	Handling method when the total height of the text exceeds the set height. Options: Overflow/Truncate. Overflow means the text will overflow and display, Truncate means only the content within the set height will be displayed. The specific display content is also related to the vertical alignment of the text
Mask Interaction	Mask type, used to set whether the text needs a mask, and if so, whether to display the content inside or outside the mask
Mask Layer	The mask layer to which the text belongs, used to match with SpriteMask. The default is Everything, meaning it can be masked by any SpriteMask
priority	Rendering priority. The smaller the value, the higher the rendering priority, and the earlier it will be rendered

Set Display Text

After adding the text component, you can set the Text property to display the desired text, as shown below:

Set Custom Font

To make the text display more diverse, developers can upload their own font files. The editor currently supports the following font file formats: .ttf, .otf, .woff

Script Usage

1. Create a TextRenderer component to display text
2. Set the Font object through the font property
3. Set the text to be displayed through the text property
4. Set the font size through the fontSize property
5. Set the text color through the color property

import {
  Camera,
  Color,
  Font,
  FontStyle,
  TextRenderer,
  Vector3,
  WebGLEngine,
} from "@galacean/engine";

const textEntity = rootEntity.createChild("text");
// 给实体添加 TextRenderer 组件
const textRenderer = textEntity.addComponent(TextRenderer);
// 通过 font 设置 Font 对象
textRenderer.font = Font.createFromOS(engine, "Arial");
// 通过 text 设置需要显示的文本
textRenderer.text = "Galacean 会写字了！";
// 通过 fontSize 设置字体大小
textRenderer.fontSize = 36;
// 通过 color 设置文本颜色
textRenderer.color.set(1, 0, 0, 1);

Set Width and Height

You can set the size of the text in 3D space through width/height, which mainly has the following uses:

1. Used for bounding box calculation
2. When multi-line text is needed, the width and height will be used to determine the line break principle

// 设置宽
textRenderer.width = 10;
// 设置高
textRenderer.height = 10;

Set Line Spacing

When you need to display multiple lines of text, you can set the vertical spacing between two lines of text through lineSpacing.

// Set line spacing
textRenderer.lineSpacing = 0.1;

Multi-line Text Display

When the text is too long, you may want the text to be displayed in multiple lines. At this time, you can set the enableWrapping field to enable the wrapping mode. After turning on the wrapping mode, it will wrap according to the width set earlier. If the width is set to 0 at this time, the text will not be rendered.

// Turn on wrapping mode
textRenderer.enableWrapping = true;

Text Truncation

When displaying multiple lines of text, there may be too many lines of text. At this time, you can set the overflowMode field to determine whether to truncate part of the display, only retaining the content within the set height. The specific display content is also related to the vertical alignment of the text (see: Text Alignment), as follows:

// 文本溢出
textRenderer.overflowMode = OverflowMode.Overflow;
// 文本截取
textRenderer.overflowMode = OverflowMode.Truncate;

Text Alignment

Text alignment is used to set how the text is displayed within the specified width and height, as follows:

Property Name	Property Type	Description
horizontalAlignment	TextHorizontalAlignment	Horizontal alignment: Left/Center/Right represent left-aligned/center-aligned/right-aligned display respectively
verticalAlignment	TextVerticalAlignment	Vertical alignment: Top/Center/Bottom represent top-aligned/center-aligned/bottom-aligned display respectively

Text Font Style

The text font style is used to set whether the text is displayed in bold or italic, as follows:

Property Name	Property Type	Description
fontStyle	FontStyle	Font style: None/Bold/Italic represent normal/bold/italic display respectively

Usage is as follows:

// 正常显示
textRenderer.fontStyle = FontStyle.None;
// 加粗显示
textRenderer.fontStyle = FontStyle.Bold;
// 斜体显示
textRenderer.fontStyle = FontStyle.Italic;
// 既加粗又斜体显示
textRenderer.fontStyle = FontStyle.Bold | FontStyle.Italic;

Multi-line Text

Custom Fonts

Font is a font resource used to represent the font used by the text.

Property Name	Property Type	Description
name	string	Font resource name, used to uniquely identify a font resource. Currently, this field is used to represent the required system font

const font = Font.createFromOS(engine, "Arial");

Currently supported formats: ttf/otf/woff

const font = await engine.resourceManager.load({
  url: "https://lg-2fw0hhsc-1256786476.cos.ap-shanghai.myqcloud.com/Avelia.otf",
});