Table of Contents

Class DebugOverlay

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

A single on-screen block of debug text, assembled from sections contributed by anything that has something to say, with one position and one toggle key for the lot.

public sealed class DebugOverlay : GameSystemBase, IDisposable, ICollectorHolder, IGameSystemBase, IComponent, IReferencable, IUpdateable, IDrawable, IContentable
Inheritance
DebugOverlay
Implements
Inherited Members

Examples

var overlay = DebugOverlay.GetOrCreate(game);

overlay.AddSection("Stress pile", () =>
[
    new($"{bodies.Count:N0} bodies", Color.LightGreen),
    new("Space", "Spawn more", Color.Yellow),
]);

Remarks

This is a game system rather than a script, so it is unaffected by scenes being swapped and draws itself once per frame with no help from the caller. Get one with GetOrCreate(IGame) - it is registered as a service, so every caller shares the same instance and the camera controller, your own instructions and any dropdowns end up in one place.

Contributors add a DebugOverlaySection whose callback runs each frame, so content that changes needs no pushing. Sections are separated by a blank line and sorted by Order.

Text is drawn with an installed font chosen by FontFamily - monospace by default, like Stride's own debug text - rasterised at FontSize times Scale, so it stays sharp on high-DPI displays. Each line gets a BackgroundColor strip behind it.

Constructors

DebugOverlay(IServiceRegistry)

Initializes a new overlay. Prefer GetOrCreate(IGame), which shares one instance.

public DebugOverlay(IServiceRegistry registry)

Parameters

registry IServiceRegistry

The service registry to resolve input and the graphics device from.

Properties

AutoScale

Gets or sets whether the overlay follows the display's scale, so it 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

Scale multiplies on top. The factor comes from DisplayScale and is re-read when the window moves to another monitor. Turn it off to draw at exactly Scale, for example for a screenshot at a known size or when the game sets its own UI scale through Override.

BackgroundColor

Gets or sets the colour of the strip drawn behind each line of text, exactly as wide as the text. Defaults to black at 49% alpha, which is the look Stride's own debug text has; Transparent draws no strips.

public Color BackgroundColor { get; set; }

Property Value

Color

BackgroundPadding

Gets or sets how far each background strip extends beyond its text, in unscaled pixels. Defaults to 3 by 1.

public Vector2 BackgroundPadding { get; set; }

Property Value

Vector2

BlockBounds

Gets the rectangle the block was last drawn in, in screen pixels, background strips included. Empty until the first draw, and one frame behind whatever the sections say now.

public RectangleF BlockBounds { get; }

Property Value

RectangleF

Remarks

For laying a scene out around the overlay: the overlay is pixels and a scene is world units, so a panel that must sit under the help block asks for this rather than guessing how tall twelve lines are on this display.

CharacterWidth

Gets or sets the assumed width of one character, in pixels, used to right-align the overlay.

[Obsolete("Text is measured with the font since the overlay draws with a SpriteFont; this value is no longer used.")]
public int CharacterWidth { get; set; }

Property Value

int

CollapsedMarker

Gets or sets the marker shown on a collapsed section's title line.

public string CollapsedMarker { get; set; }

Property Value

string

Remarks

Printable ASCII only; arrow glyphs such as ▼ render as blanks.

CustomPosition

Gets or sets the pixel position used when Position is null, in unscaled pixels from the top left. Setting this alone changes nothing while Position is an anchor; SetPosition(Int2) sets both.

public Int2 CustomPosition { get; set; }

Property Value

Int2

DefaultTextColor

Gets or sets the colour of lines that do not specify one. Defaults to LightGreen, the same as Stride's own debug text.

public Color DefaultTextColor { get; set; }

Property Value

Color

ExpandedMarker

Gets or sets the marker shown on an expanded section's title line.

public string ExpandedMarker { get; set; }

Property Value

string

Font

Gets or sets a font to draw with, overriding FontName. null, the default, uses the system font named by FontName.

public SpriteFont? Font { get; set; }

Property Value

SpriteFont

FontFamily

Gets or sets which kind of installed font to draw with when FontName is not set. Defaults to Monospace, the character of Stride's own debug text.

public DebugOverlayFontFamily FontFamily { get; set; }

Property Value

DebugOverlayFontFamily

Remarks

The font file is located in the system font folders and rasterised at the size asked for, so it stays sharp at any FontSize and Scale. If none of the family's fonts is installed, Stride's default font is used - which is bold and proportional.

FontFile

Gets or sets the path of the TrueType file for FontName, for fonts that are not in the system font folders. null, the default, searches those folders.

public string? FontFile { get; set; }

Property Value

string

FontName

Gets or sets the family name of a specific installed font to draw with, such as "Consolas" or "Segoe UI", overriding FontFamily. null, the default, chooses from FontFamily. A font that cannot be found falls back the same way.

public string? FontName { get; set; }

Property Value

string

Remarks

Set FontFile to point at a specific file instead of searching the system font folders.

FontSize

Gets or sets the text height in unscaled pixels. Defaults to 14.

public float FontSize { get; set; }

Property Value

float

FontStyle

Gets or sets the weight and slant of FontName. Defaults to Regular.

public FontStyle FontStyle { get; set; }

Property Value

FontStyle

KeyColor

Gets or sets the colour of markers and keys. null, the default, draws them in the line's own colour blended halfway to white, so they stand a shade apart from the text without leaving its palette.

public Color? KeyColor { get; set; }

Property Value

Color?

KeyFormat

Gets or sets how a key named by a TextElement is decorated when drawn: a composite format with the key at {0}. Defaults to [{0}], so H reads [H]; {0}: reads H:. One place to restyle every help line in every example.

public string KeyFormat { get; set; }

Property Value

string

KeySeparator

Gets or sets what separates the keys of a line that names several, as in [Q] [E]. Defaults to one space.

public string KeySeparator { get; set; }

Property Value

string

LineHeight

Gets or sets a fixed vertical distance between lines, in unscaled pixels. null, the default, derives it from the font: the text height plus the background padding plus LineSpacing, so lines neither overlap nor drift apart when FontSize changes.

public int? LineHeight { get; set; }

Property Value

int?

LineSpacing

Gets or sets the gap between one line's background strip and the next, in unscaled pixels, when LineHeight is not set. Defaults to 2; 0 makes the strips touch.

public float LineSpacing { get; set; }

Property Value

float

Margin

Gets or sets the gap kept between the overlay and the edge of the screen, in pixels.

public Int2 Margin { get; set; }

Property Value

Int2

Position

Gets or sets where the overlay is drawn: a corner, the middle of an edge or the centre, or null for the pixel position in CustomPosition. Hide the overlay with Visible, which the ToggleKey flips.

public ScreenAnchor? Position { get; set; }

Property Value

ScreenAnchor?

RepositionKey

Gets or sets the key that moves the overlay to the next corner. Defaults to F3.

public Keys RepositionKey { get; set; }

Property Value

Keys

Remarks

Does nothing while Position is null, a pixel position chosen by the caller and not something a keypress should silently override.

Scale

Gets or sets how much the whole overlay is enlarged on top of the display's own scale: text, line spacing, margins and padding. 1, the default, is the size of Stride's debug text on a 100% display; 2 doubles everything. Any positive value works, since the font is rasterised at the resulting size rather than stretched. Values below a small minimum are treated as that minimum.

public float Scale { get; set; }

Property Value

float

Remarks

FontSize, LineHeight, Margin, CustomPosition and BackgroundPadding are in unscaled pixels and are multiplied by this, so the block keeps its corner and its layout at any scale.

This multiplies the DisplayScale while AutoScale is on, so it is a preference - "a bit bigger" - rather than a DPI figure. To pin the overlay to an exact size regardless of the display, turn AutoScale off.

SectionGap

Gets or sets how many blank lines separate one section from the next - the empty line under the camera controls, for one. Defaults to 1; 0 runs a section straight on from the one above it.

public int SectionGap { get; set; }

Property Value

int

Sections

Gets the sections currently registered, in insertion order.

public IReadOnlyList<DebugOverlaySection> Sections { get; }

Property Value

IReadOnlyList<DebugOverlaySection>

TextNudge

Gets or sets how far the text is shifted inside its background strip, in screen pixels, positive downwards. Defaults to -1: a font's line gap sits above its ascender, so glyphs land about a pixel low in a strip sized from the line height, and one pixel up centres them. Not multiplied by the scale: the imbalance stays close to one pixel at the sizes the overlay is drawn at.

public float TextNudge { get; set; }

Property Value

float

TitleColor

Gets or sets the colour of section title lines. null, the default, uses DefaultTextColor.

public Color? TitleColor { get; set; }

Property Value

Color?

ToggleKey

Gets or sets the key that shows and hides the whole overlay. Defaults to F4.

public Keys ToggleKey { get; set; }

Property Value

Keys

Remarks

This is the blunt instrument, for a clean screenshot. Prefer collapsing individual sections - a collapsed section leaves a line saying which key brings it back, whereas hiding everything leaves no clue that there was anything to see. F2 is deliberately left to the camera controllers, whose help is what most callers actually want out of the way.

Methods

AddCollapsibleSection(string, string, Keys, Func<IReadOnlyList<TextElement>>, bool, int)

Adds a section that can be collapsed to a single title line and expanded again with a key.

public DebugOverlaySection AddCollapsibleSection(string name, string title, Keys toggleKey, Func<IReadOnlyList<TextElement>> lines, bool collapsed = false, int order = 0)

Parameters

name string

A name for the section, used to find it again. Not displayed.

title string

The heading, shown above the lines and on its own while collapsed.

toggleKey Keys

The key that collapses and expands the section.

lines Func<IReadOnlyList<TextElement>>

Produces the section's lines. Called every frame it is drawn expanded.

collapsed bool

Whether it starts collapsed.

order int

Sort order; lower is drawn first.

Returns

DebugOverlaySection

The section, so it can be collapsed, disabled or removed later.

AddSection(string, Func<IReadOnlyList<TextElement>>, int)

Adds a section to the overlay.

public DebugOverlaySection AddSection(string name, Func<IReadOnlyList<TextElement>> lines, int order = 0)

Parameters

name string

A name for the section, used to find it again. Not displayed.

lines Func<IReadOnlyList<TextElement>>

Produces the section's lines. Called every frame the overlay is drawn.

order int

Sort order; lower is drawn first.

Returns

DebugOverlaySection

The section, so it can be disabled or removed later.

CyclePosition()

Moves the overlay to the next corner clockwise. From an edge, the centre or a pixel position it goes to the top left.

public void CyclePosition()

Destroy() 

protected override void Destroy()

Draw(GameTime) 

public override void Draw(GameTime gameTime)

Parameters

gameTime GameTime

FindSection(string)

Finds a section by name, or null if there is none.

public DebugOverlaySection? FindSection(string name)

Parameters

name string

The name given when the section was added.

Returns

DebugOverlaySection

The section, if found.

FormatKeys(IReadOnlyList<string>)

Decorates keys the way this overlay draws them: each through KeyFormat, joined by KeySeparator. ["Q", "E"] gives [Q] [E] with the defaults.

public string FormatKeys(IReadOnlyList<string> keys)

Parameters

keys IReadOnlyList<string>

The keys, in order.

Returns

string

The decorated keys, or an empty string for none.

GetOrCreate(IGame)

Returns the overlay registered with the game, creating and registering one if there is none.

public static DebugOverlay GetOrCreate(IGame game)

Parameters

game IGame

The game to attach to.

Returns

DebugOverlay

The shared overlay.

RemoveSection(DebugOverlaySection)

Removes a section previously added with AddSection(string, Func<IReadOnlyList<TextElement>>, int).

public bool RemoveSection(DebugOverlaySection section)

Parameters

section DebugOverlaySection

The section to remove.

Returns

bool

true if it was present.

SetPosition(Int2)

Places the overlay at a pixel position instead of an anchor: sets CustomPosition and clears Position in one call, so the block moves at once rather than after a second assignment.

public void SetPosition(Int2 position)

Parameters

position Int2

The top-left corner of the block, in unscaled pixels from the top left of the window; multiplied by Scale and the display's scale when drawn.

Remarks

The RepositionKey is ignored from then on, because a position chosen by the caller is not something a keypress should silently override. Set Position back to an anchor to hand it back.

SetPosition(int, int)

Places the overlay at a pixel position instead of an anchor. See SetPosition(Int2).

public void SetPosition(int x, int y)

Parameters

x int

Pixels from the left edge of the window, unscaled.

y int

Pixels from the top edge of the window, unscaled.

SetPosition(ScreenAnchor?)

Places the overlay at an anchor. The same as setting Position; here so an anchor and a pixel position are chosen through one method.

public void SetPosition(ScreenAnchor? position)

Parameters

position ScreenAnchor?

The corner, edge or centre, or null to draw at CustomPosition as last set.

Update(GameTime) 

public override void Update(GameTime gameTime)

Parameters

gameTime GameTime
Edit this page