Table of Contents

Class EntityTextComponent

Namespace
Stride.CommunityToolkit.Rendering.Text
Assembly
Stride.CommunityToolkit.dll

Draws a line of screen-space text for the entity it is attached to, without using Stride's UI system.

[DefaultEntityComponentProcessor(typeof(EntityTextProcessor), ExecutionMode = ExecutionMode.Runtime)]
[AllowMultipleComponents]
[DataContract("EntityTextComponent")]
[Display("Entity Text (call AddEntityTextRenderer)", null, Expand = ExpandRule.Once)]
[ComponentCategory("Text")]
public class EntityTextComponent : EntityComponent, IIdentifiable
Inheritance
EntityTextComponent
Implements
Inherited Members

Remarks

Add EntityTextRenderer to the graphics compositor for anything to appear - the component records what to draw, the renderer draws it.

The text can follow its entity through the world, sit at a fixed pixel position, or anchor to a corner of the window; see PositionMode. Where the text sits relative to that point is Anchor.

A label floating above an object: 
entity.Add(new EntityTextComponent
{
    Text = "Player",
    Anchor = TextAnchor.BottomCenter,
    Offset = new Vector2(0, -12),
    EnableShadow = true
});

A score in the top-left that survives the window being resized:

entity.Add(new EntityTextComponent
{
    Text = "Score: 0",
    PositionMode = TextPositionMode.Anchored,
    ScreenAnchor = DisplayPosition.TopLeft,
    Offset = new Vector2(16, 16),
    FontSize = 20
});

Constructors

EntityTextComponent()

Initializes a new instance of the EntityTextComponent class.

public EntityTextComponent()

Properties

Alignment

Gets or sets how the lines of a multi-line text sit relative to one another. Defaults to Left.

public TextAlignment Alignment { get; set; }

Property Value

TextAlignment

Remarks

This has no effect on single-line text, where every value produces the same result. To centre a label on its position use Anchor.

Anchor

Gets or sets which point of the text is placed on the resolved position. Defaults to TopLeft.

public TextAnchor Anchor { get; set; }

Property Value

TextAnchor

AutoScale

Gets or sets whether everything measured in pixels - FontSize, Offset, ScreenPosition, Padding and ShadowOffset - follows the display's scale, so the text is the same size to the eye on a 150% laptop as on a 100% monitor. Defaults to true.

public bool AutoScale { get; set; }

Property Value

bool

Remarks

The factor comes from DisplayScale, shared with everything else in the toolkit that draws in pixels, and is re-read when the window moves to another monitor. Turn it off to get exactly the pixels asked for - a screenshot at a known size, or a game applying its own UI-scale setting through DisplayScale.Override and nothing else should compound it.

BackgroundColor

Gets or sets the background colour. Leave null for the renderer's default.

public Color4? BackgroundColor { get; set; }

Property Value

Color4?

EnableBackground

Gets or sets whether a filled rectangle is drawn behind the text. Defaults to false.

public bool EnableBackground { get; set; }

Property Value

bool

EnableShadow

Gets or sets whether a drop shadow is drawn behind the text. Defaults to false.

public bool EnableShadow { get; set; }

Property Value

bool

Remarks

Worth turning on for anything drawn over a scene rather than over a flat background: it costs one extra draw of the same string and is usually the difference between text that is readable against any colour underneath it and text that disappears against some of them.

FadeStartDistance

Gets or sets the distance from the camera at which the text starts fading out, in world units. Leave null to disable fading.

public float? FadeStartDistance { get; set; }

Property Value

float?

Remarks

Only applies in World. Requires MaxDistance to be set as well; the text fades from fully opaque at this distance to invisible at that one.

Font

Gets or sets the font. Leave null to use Stride's default font.

public SpriteFont? Font { get; set; }

Property Value

SpriteFont

FontSize

Gets or sets the size the glyphs are rasterised at, in pixels on a 100% display. Defaults to 18.

public float FontSize { get; set; }

Property Value

float

Remarks

Animate Scale rather than this. Changing the font size re-rasterises the glyphs and re-measures the text every frame it changes; scaling does neither. On a scaled display the glyphs are rasterised that much larger while AutoScale is on, so they stay sharp rather than being stretched.

IsVisible

Gets or sets whether the text is drawn at all. Defaults to true.

public bool IsVisible { get; set; }

Property Value

bool

Remarks

Prefer this over removing and re-adding the component, which throws away the cached text measurement along with it.

LayerDepth

Gets or sets the draw order. Higher values are drawn on top. Defaults to 0.

public float LayerDepth { get; set; }

Property Value

float

MaxDistance

Gets or sets the distance from the camera beyond which the text is not drawn, in world units. Leave null for no limit.

public float? MaxDistance { get; set; }

Property Value

float?

Remarks

Only applies in World. Useful on its own as a cutoff, without FadeStartDistance, when labels should simply stop rather than fade.

Offset

Gets or sets a pixel offset applied after the position is resolved, in every position mode.

public Vector2 Offset { get; set; }

Property Value

Vector2

Remarks

In Anchored this is the margin from the chosen corner, and it always points inwards - a positive offset moves the text away from its corner rather than off the screen.

Opacity

Gets or sets an overall opacity from 0 to 1, applied on top of the text, shadow and background colours. Defaults to 1.

public float Opacity { get; set; }

Property Value

float

Remarks

Fading with this leaves the configured colours alone, so a fade can be restarted without having to remember what the colours were before it began.

Padding

Gets or sets the padding between the text and the edge of its background, in pixels.

public Vector2 Padding { get; set; }

Property Value

Vector2

PositionMode

Gets or sets how the position to draw at is decided. Defaults to World, which follows the entity.

public TextPositionMode PositionMode { get; set; }

Property Value

TextPositionMode

Rotation

Gets or sets the clockwise rotation of the text, in radians. Defaults to 0.

public float Rotation { get; set; }

Property Value

float

Scale

Gets or sets a multiplier applied to the drawn size. Defaults to 1.

public float Scale { get; set; }

Property Value

float

Remarks

This is the cheap way to make text pop or shrink over time, because it does not touch the glyph cache. Scaling happens about Anchor, so a centred text grows evenly rather than drifting to one side.

ScreenAnchor

Gets or sets the window corner used when PositionMode is Anchored. Defaults to the top-left.

public DisplayPosition ScreenAnchor { get; set; }

Property Value

DisplayPosition

Remarks

Custom and None are treated as the top-left; use Screen for an explicit position and IsVisible to hide the text.

ScreenPosition

Gets or sets the pixel position used when PositionMode is Screen, measured from the top-left of the window.

public Vector2 ScreenPosition { get; set; }

Property Value

Vector2

ShadowColor

Gets or sets the shadow colour. Defaults to half-transparent black.

public Color ShadowColor { get; set; }

Property Value

Color

ShadowOffset

Gets or sets how far the shadow is offset from the text, in pixels. Defaults to one pixel right and down.

public Vector2 ShadowOffset { get; set; }

Property Value

Vector2

Text

Gets or sets the text to draw.

public required string Text { get; set; }

Property Value

string

TextColor

Gets or sets the text colour. Defaults to White.

public Color TextColor { get; set; }

Property Value

Color
Edit this page