2D
Text Renderer
The TextRenderer component is used to display text in 3D/2D scenes, supporting features such as dynamic text, custom fonts, multi-line display, alignment, and more.
Editor Usage
Adding a Text Component
- Select the target entity in the scene.
- Add a TextRenderer component via the entity property panel.
- Configure component parameters to define the text style.
Parameter Description
Select an entity with a TextRenderer component and configure the following properties in the right-side Inspector panel:
| Property | Description |
|---|---|
| Text | The text content to display (supports multi-line input) |
| Color | Text color (RGBA format) |
| FontSize | Font size (unit: pixels) |
| Font | Custom font resource (defaults to system font) |
| Width | Design width of the text (affects line wrapping and layout, unit: scene units) |
| Height | Design height of the text (affects truncation and layout, unit: scene units) |
| LineSpacing | Line spacing (unit: pixels) |
| FontStyle | Font style: None (default) / Bold (bold) / Italic (italic) |
| HorizontalAlignment | Horizontal alignment: Left (left) / Center (center) / Right (right) |
| VerticalAlignment | Vertical alignment: Top (top) / Center (center) / Bottom (bottom) |
| EnableWrapping | Whether to enable automatic line wrapping (requires valid Width) |
| OverflowMode | Overflow handling: Overflow (show overflowed content) / Truncate (truncate overflow) |
| Mask Interaction | Mask interaction mode (used with SpriteMask) |
| Mask Layer | Mask layer (defaults to Everything to match all layers) |
| Priority | Render priority (lower values render earlier) |
Width and Height are used to define the layout range of the text (e.g., line wrapping and alignment), not the actual rendering size. To obtain the real bounding box size of the text in 3D space, read the TextRenderer.bounds property.Basic Operation Examples
Setting Text Content
- Enter the target text in the Text property field.
- Directly input multi-line text with line breaks.
Using Custom Fonts
- Prepare font files (supports
.ttf,.otf,.woffformats). - Drag and drop the font files into the editor's resource panel.
- Select the uploaded font in the Font property.
Script Development Guide
Basic Usage
import { TextRenderer, Font, Color } from "@galacean/engine";
// Create a text entity and add a component
const textEntity = rootEntity.createChild("text");
const textRenderer = textEntity.addComponent(TextRenderer);
// Set basic properties
textRenderer.text = "Galacean Text Rendering"; // Text content
textRenderer.fontSize = 24; // Font size (pixels)
textRenderer.color = new Color(1, 0, 0, 1); // Red textAdvanced Features
1. Custom Font Loading
// Method 1: Use system font
textRenderer.font = Font.createFromOS(engine, "Arial");
// Method 2: Load external font file
engine.resourceManager.load({ url: "fonts/Avelia.otf" }).then((font) => {
textRenderer.font = font;
});2. Layout and Wrapping
// Set bounding box size (unit: scene units)
textRenderer.width = 5; // Controls auto-wrap width
textRenderer.height = 3; // Affects truncation height
// Enable auto-wrap
textRenderer.enableWrapping = true;
// Set line spacing
textRenderer.lineSpacing = 0.5;3. Overflow and Truncation
// Set overflow mode
textRenderer.overflowMode = OverflowMode.Truncate; // or OverflowMode.Overflow
// Alignment (requires width/height)
textRenderer.horizontalAlignment = TextHorizontalAlignment.Center;
textRenderer.verticalAlignment = TextVerticalAlignment.Top;4. Font Style Combinations
// Apply bold and italic simultaneously
textRenderer.fontStyle = FontStyle.Bold | FontStyle.Italic;Notes
- Zero Width/Height Trap: If line wrapping is enabled (
enableWrapping=true) but no valid width/height is set, the text will not render. - Font Compatibility: Some complex fonts (e.g., those containing variant characters) may render abnormally. Testing is recommended.
- Performance Optimization: Frequent text updates may impact performance. Batch rendering is advised for static text.
API Reference
| Class/Enum | Key Properties/Values | Description |
|---|---|---|
TextRenderer | text, font, fontSize | Main class for text rendering |
TextHorizontalAlignment | Left, Center, Right | Horizontal alignment modes |
TextVerticalAlignment | Top, Center, Bottom | Vertical alignment modes |
FontStyle | None, Bold, Italic | Font style combinations |