Table of Contents

Class DebugOverlay

Namespace
Stride.CommunityToolkit.Scripts.Utilities
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

A debug overlay that is unreadable on first launch is a bug in the tool, so this is on by default; Scale stays yours on top of it. The figure comes from DisplayScale, which is shared with everything else that draws in pixels and is re-read when the window moves to another monitor. Turn it off to draw at exactly Scale - for a screenshot at a known size, or when the game applies its own UI-scale setting through Override and nothing else should compound it.

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

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

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 16, the size of Stride's debug text.

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

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. None draws nothing.

public DisplayPosition Position { get; set; }

Property Value

DisplayPosition

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 Custom, which is an explicit choice 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.

Sections

Gets the sections currently registered, in insertion order.

public IReadOnlyList<DebugOverlaySection> Sections { get; }

Property Value

IReadOnlyList<DebugOverlaySection>

TitleColor

Gets or sets the colour used for section title lines.

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, skipping None and Custom.

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.

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.

Update(GameTime) 

public override void Update(GameTime gameTime)

Parameters

gameTime GameTime
Edit this page