Text Renderer

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:

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:

Text Font Style

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

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.

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",
});