Skip to main content

Interface: TextEcsComponent

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

Fields of TextEcsComponent with no sensible default; callers must always provide these.

Extends​

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.

Inherited from​

TextDefaultedOptions.category

color​

color: Color

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

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

Inherited from​

TextDefaultedOptions.color

enabled​

enabled: boolean

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

Whether this text is drawn at all.

Inherited from​

TextDefaultedOptions.enabled

fontAtlas​

fontAtlas: FontAtlas

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

The loaded font atlas glyphs are drawn from.

Inherited from​

TextRequiredOptions.fontAtlas

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).

Inherited from​

TextDefaultedOptions.horizontalAlign

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.

Inherited from​

TextDefaultedOptions.horizontalAlignPivot

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.

Inherited from​

TextDefaultedOptions.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.

Inherited from​

TextDefaultedOptions.letterSpacing

lineHeight​

lineHeight: number

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

Multiplier on the font's authored line height.

Inherited from​

TextDefaultedOptions.lineHeight

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.

Inherited from​

TextDefaultedOptions.maxWidth

opacityMultiplier?​

optional opacityMultiplier?: number

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

An additional multiplier applied to color.a when computing this text's final rendered alpha, on top of (not instead of) the color's own alpha - only its fill, not its outlineColor/shadowColor effects, currently inherit this. Left undefined, this text renders at color.a alone. Mirrors SpriteEcsComponent.opacityMultiplier exactly, including why it's a separate field from color.a itself - see that field's own doc comment.

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.

Inherited from​

TextDefaultedOptions.outlineColor

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.

Inherited from​

TextDefaultedOptions.outlineWidth

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.

Inherited from​

TextDefaultedOptions.shadowColor

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.

Inherited from​

TextDefaultedOptions.shadowOffset

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.

Inherited from​

TextDefaultedOptions.shadowSoftness

size​

size: number

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

Font size, in world units - the rendered em height.

Inherited from​

TextRequiredOptions.size

sortDepth?​

optional sortDepth?: number

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

Overrides the depth this text is sorted by within its layer, in place of the default (position.world.y). Lower values draw first (further back). Left undefined, text sorts by world Y as before - this is a genuinely optional field, not one with a 0 default, since 0 would silently override world-Y sorting for every text entity. Mirrors SpriteEcsComponent.sortDepth exactly.

text​

text: string

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

The string to render.

Inherited from​

TextRequiredOptions.text

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.

Inherited from​

TextDefaultedOptions.verticalAlign