Text

Text objects are individual 3D objects. All text objects that share the same font are rendered from a signed-distance-field (SDF) atlas in one draw call per scene.

Visually a text object with scale (1,1,1) appears as 20cm (0.2 world units) tall.

Creating a text object:

const textObject = Text('hi!')

or add a Text object in the UI editor: edit-> + icon ->Text.

Supported font formats

Text supports static, monochrome vector fonts in these formats:

• .ttf — TrueType outlines
• .otf — OpenType fonts with CFF or compatible TrueType outlines
• .woff — WOFF 1 fonts containing TrueType or CFF outlines

WOFF2 (.woff2) is not supported by the 3D text parser. Convert WOFF2 fonts to .ttf, .otf, or .woff before importing them. Font collections (.ttc and .otc) and color or bitmap fonts are unsupported.

Variable fonts with a wght axis support weight. Other variation axes remain at the defaults declared by the font. Static fonts ignore weight and render their authored weight.

Pair kerning is applied before letterSpacing, including weight-dependent kerning in variable fonts.

Properties

const optionalProps = {
	anchorX: 'left | center | right', // default = 'left'
	anchorY: 'top | center | bottom', // default = 'center'
	lineHeight: 1.1,
	letterSpacing: 1.1,
	wrap: 0.5, // default = 0 (none)
	font: 'yourFontAssetName.ttf',
	weight: 700, // default = 400; clamped to the font's wght range
	color: new U.Color() | '#fff0f0',
	opacity: 0.75, // default = 1; clamped to 0–1
	outline: true, // default = false
	outlineWidth: 0.025, // default = 0.025, range = 0–0.0625
	outlineColor: new U.Color() | '#000000', // default = '#000000'
	material: someMaterial,
	// Allocate geometry for 250 characters
	// This is more efficient for dynamic text
	preallocate: 250,
}

const text = Text('Hello World', props)

Outlines

Outlines are disabled by default. Set outline: true when creating the text to enable one:

const title = Text('Outlined', {
	color: '#ffffff',
	outline: true,
	outlineWidth: 0.025,
	outlineColor: '#000000',
})

outlineWidth is relative to the font size, so the outline scales with the text and its object transform. For example, 0.025 is 2.5% of the font size. The supported range is 0 to 0.0625; values outside that range are clamped.

The outline is evaluated from the existing SDF atlas in the same shader pass. It does not create duplicate geometry or add another draw call. When outlines are disabled, the renderer also skips the outline-color lookup.

Outline settings can also be changed in the editor under the selected Text object's Material panel.

Methods

setColor() is available immediately after Text() returns. While fonts and geometry load, it retains the latest colour and applies it when loading finishes.

// update the text
textObject.set('new string value')

// update text color
textObject.setColor('#fff000')
textObject.setColor(new U.Color())

// update fill and outline opacity without creating another draw call
textObject.setOpacity(0.5)

// update the optional outline
textObject.setOutline(true)
textObject.setOutlineWidth(0.025)
textObject.setOutlineColor('#000000')
textObject.setOutlineColor(new U.Color(1, 0, 0))

// update a variable font's wght axis and rebuild its geometry
textObject.setWeight(650)

// disable the outline without discarding its saved width or color
textObject.setOutline(false)