Skip to main content

Interface: TextDefaultedOptions

Defined in: text/components/text-component.ts:33

Fields of TextEcsComponent with a sensible default; callers may omit these.

Extended by​

Properties​

category​

category: number

Defined in: text/components/text-component.ts:114

The render category this text's glyphs are drawn with, matched against each camera's cullingMask (the same bitmask-matching SpriteEcsComponent.renderable.category convention). Defaults to TEXT_RENDER_CATEGORY, shared by every text entity that doesn't override it - not a reserved value, just a default: override it per entity when a game needs a specific text entity (e.g. a UI label) under a different camera's culling mask than whatever else already uses the default category.

color​

color: Color

Defined in: text/components/text-component.ts:38

Multiplies against the atlas's tint (same semantics as SpriteEcsComponent.tintColor).

enabled​

enabled: boolean

Defined in: text/components/text-component.ts:117

Whether this text is drawn at all.

horizontalAlign​

horizontalAlign: TextHorizontalAlign

Defined in: text/components/text-component.ts:55

Horizontal alignment of each line within maxWidth. Irrelevant, and ignored, when maxWidth is unset (a single unwrapped line is always exactly as wide as the block itself, so every mode produces the same result).

horizontalAlignPivot​

horizontalAlignPivot: number

Defined in: text/components/text-component.ts:96

Where this entity's own local origin sits within the horizontalAlign box, as a fraction of maxWidth from the box's left edge - 0 (the default) means the entity's local x = 0 is the box's left edge. Set this to match a parent RectTransformEcsComponent's pivot.x when that pivot isn't 0: createUiLayoutEcsSystem already does this automatically for any stretch-x-anchored label (see its own doc comment), so most callers never need to set it themselves. See ShapeTextOptions.horizontalAlignPivot for the full mechanics.

layer​

layer: number

Defined in: text/components/text-component.ts:102

The draw-order layer for this text, relative to other sprites/text drawn by the same camera. Identical semantics to SpriteEcsComponent.layer.

letterSpacing​

letterSpacing: number

Defined in: text/components/text-component.ts:44

Extra spacing between glyphs, in world units, added to each glyph's advance.

lineHeight​

lineHeight: number

Defined in: text/components/text-component.ts:47

Multiplier on the font's authored line height.

maxWidth?​

optional maxWidth?: number

Defined in: text/components/text-component.ts:84

Wraps at word boundaries when a line would exceed this width, in world units. undefined (the default) never wraps.

outlineColor​

outlineColor: Color

Defined in: text/components/text-component.ts:123

Outline color. outlineWidth of 0 (the default) draws no outline regardless of this value.

outlineWidth​

outlineWidth: number

Defined in: text/components/text-component.ts:138

Outline thickness, in screen-pixel-range units - a fixed number of screen pixels regardless of camera zoom or entity scale, the same scale-independent unit the MSDF anti-aliasing band itself uses. Drawn as its own pass, always before every glyph's fill (see createTextRenderable), so an outline can safely reach past a same-word neighboring glyph - even merge with that neighbor's own outline - without ever painting over any glyph's fill. Requesting more than the atlas's own encoded distanceRange can faithfully represent silently clamps to the widest safe value rather than corrupting glyphs; see text-effects.md's Text Effects guide for the safe range of the font you're using and how to raise it.

shadowColor​

shadowColor: Color

Defined in: text/components/text-component.ts:144

Soft shadow/glow color. shadowColor's alpha of 0 (the default) draws no shadow regardless of shadowSoftness/shadowOffset.

shadowOffset​

shadowOffset: Vector2

Defined in: text/components/text-component.ts:152

Offset of the soft shadow/glow from the glyph, in screen-pixel-range units (see outlineWidth). Bounded the same way outlineWidth is - by the atlas's own encoded distanceRange budget - rather than by anything to do with neighboring glyphs.

shadowSoftness​

shadowSoftness: number

Defined in: text/components/text-component.ts:160

How far, in screen-pixel-range units (see outlineWidth), the soft shadow/glow fades out from its offset sample. 0 leaves it exactly as crisp as the glyph itself, just offset. Bounded the same way shadowOffset is.

verticalAlign​

verticalAlign: TextVerticalAlign

Defined in: text/components/text-component.ts:78

Vertical alignment of the shaped block's visible ink relative to the entity's position - not the font's line-height box, which typically doesn't match the ink's own extent.

'top', 'bottom', 'capline', and 'baseline' all anchor to a fixed reference that doesn't depend on this specific string's rendered bounds, so a line's position stays stable as its text is edited: 'top' anchors the font's ascender (so text hangs below the entity's position), 'bottom' anchors the font's descender (so text sits above it), 'capline' anchors the font's cap height - the top of a capital letter like "H", shorter than ascender's "tallest glyph including ascenders like b/d/h" - and 'baseline' anchors the first line's own baseline directly (most useful for single-line text).

'middle' instead centers this exact string's actual rendered ink, since a font's ascender is typically taller than its descender is deep - most glyphs have no descender at all - so centering on the font's metrics would bias every descender-less string (numbers, titles, most short UI labels) above the true visual center of its box.