Skip to content

Class UiSystem

Namespace: Apogee.UI
Assembly: Apogee.UI.dll

The game's user interface: RmlUi with one context (the screen), its documents, fonts and input, behind the script global ui. Documents are written in RML and RCSS (HTML and CSS as RmlUi knows them) with scripts of their own in Luau, or built from Luau; both go through s. RmlUi is process-wide, so there is one system at a time.

public sealed class UiSystem : EngineObject, IDisposable

Inheritance

object ← EngineObject ← UiSystem

Implements

IDisposable

Inherited Members

EngineObject.IsAdopted, EngineObject.Handle, EngineObject.IsDestroyed, EngineObject.Class, EngineObject.Adopt(), EngineObject.TryGet(SlotHandle, out EngineObject), EngineObject.Destroy(), object.Equals(object?), object.Equals(object?, object?), object.GetHashCode(), object.GetType(), object.ReferenceEquals(object?, object?), object.ToString()

Remarks

Call when the window changes size, once a frame (it lays out and runs animations and delivers nothing by itself: events are delivered when input is given), and let the draw (it is the render overlay: it asks for the picture when the frame's graph is built). Input comes from or from the Mouse, Key and Text calls; each says whether the UI used it, so the game can leave it alone. Without a renderer (headless runs, tests) everything but drawing works. What a document asks to read (its stylesheets, images and fonts) is read through the virtual file system, as res://, mod:// and user:// paths. RmlUi has no stylesheet of its own: ui_base.rcss is put under every document (the document's own rules win), with the default font, Inter.

Constructors

UiSystem(VirtualFileSystem, ContentLoader?, int, int)

Starts RmlUi with width x height pixels of screen. Throws when there is a system already (RmlUi has one state per process) or the library is missing.

public UiSystem(VirtualFileSystem files, ContentLoader? content = null, int width = 1280, int height = 720)

Parameters

files VirtualFileSystem

content ContentLoader?

width int

height int

Properties

BaseStyle

The engine's base stylesheet (ui_base.rcss), which every document is given under its own rules.

public static string BaseStyle { get; }

Property Value

string

Class

What the registry knows about this object's class.

public override ClassInfo Class { get; }

Property Value

ClassInfo

Cursor

The mouse cursor the UI wants (pointer, text, default...), as RmlUi last said.

public string Cursor { get; }

Property Value

string

Debugger

RmlUi's inspector (the element tree and styles of every document, and a log) as a window over the UI.

public bool Debugger { get; set; }

Property Value

bool

Density

How many pixels a density-independent pixel (dp in RCSS) is: 1 on an ordinary screen, 2 on a high-density one, or what the player's UI scale says.

public float Density { get; set; }

Property Value

float

DocumentsLoaded

How many documents have been loaded since the system started: a host makes the renderer only when this is more than zero.

public int DocumentsLoaded { get; }

Property Value

int

Height

The height of the screen in pixels.

public int Height { get; }

Property Value

int

ListenerCount

The number of listeners scripts have on elements that still exist (after the dead ones are pruned).

public int ListenerCount { get; }

Property Value

int

Renderer

The renderer that draws the UI, once there is one.

public UiRenderer? Renderer { get; }

Property Value

UiRenderer?

ScriptEnvironments

The scripting layer that runs the code in documents. Without it a <script> or an onclick is ignored, with a warning.

public IScriptEnvironments? ScriptEnvironments { get; set; }

Property Value

IScriptEnvironments?

ScriptedDocuments

The number of documents that have scripts running (they have an environment of their own).

public int ScriptedDocuments { get; }

Property Value

int

Time

The seconds the UI has run: the sum of the steps, what its animations and transitions go by.

public double Time { get; }

Property Value

double

WantsKeyboard

True while a text field has the focus: typed text and keys are the UI's, not the game's.

public bool WantsKeyboard { get; }

Property Value

bool

WantsMouse

True while the pointer is over an element of a document: the game should not also react to the mouse.

public bool WantsMouse { get; }

Property Value

bool

Width

The width of the screen in pixels.

public int Width { get; }

Property Value

int

Methods

CreateDocument()

An empty document, with a body to put elements in, for a UI built in code.

public UiElement? CreateDocument()

Returns

UiElement?

Dispose()

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.

public void Dispose()

Key(ArKey, bool, int)

A key went down or up ().

public bool Key(ArKey key, bool down, int modifiers = 0)

Parameters

key ArKey

down bool

modifiers int

Returns

bool

LoadDocument(string)

Loads the RML document at path (res://ui/menu.rml). It is not shown until . Null when it cannot be read or parsed (the log says why).

public UiElement? LoadDocument(string path)

Parameters

path string

Returns

UiElement?

LoadDocumentText(string, string)

Loads a document from RML text; sourceUrl is what its relative paths (stylesheets, images) are relative to.

public UiElement? LoadDocumentText(string rml, string sourceUrl = "")

Parameters

rml string

sourceUrl string

Returns

UiElement?

LoadFont(string, string, bool, bool, bool)

Loads a font from the file at path for the family family (documents say font-family: Family). False when it is not a font.

public bool LoadFont(string path, string family, bool bold = false, bool italic = false, bool fallback = false)

Parameters

path string

family string

bold bool

italic bool

fallback bool

Returns

bool

LoadFont(ReadOnlySpan<byte>, string, bool, bool, bool)

Loads a font from memory (RmlUi keeps its own copy).

public bool LoadFont(ReadOnlySpan<byte> data, string family, bool bold = false, bool italic = false, bool fallback = false)

Parameters

data ReadOnlySpan<byte>

family string

bold bool

italic bool

fallback bool

Returns

bool

MouseButton(int, bool, int)

A button went down or up: 0 left, 1 right, 2 middle. False when the UI used it.

public bool MouseButton(int button, bool down, int modifiers = 0)

Parameters

button int

down bool

modifiers int

Returns

bool

MouseLeave()

public bool MouseLeave()

Returns

bool

MouseMove(int, int, int)

The pointer moved to (x, y) pixels. False when the UI used it.

public bool MouseMove(int x, int y, int modifiers = 0)

Parameters

x int

y int

modifiers int

Returns

bool

MouseWheel(float, float, int)

public bool MouseWheel(float x, float y, int modifiers = 0)

Parameters

x float

y float

modifiers int

Returns

bool

OnDestroyed()

protected override void OnDestroyed()

OnUpdate(ScriptFunction)

Calls handler with the frame's time step at the start of every , before layout: where a script puts what changed in the game (a speed, a health value) into the UI, so that it is in the picture of this frame. Returns a number for . A handler that fails is logged and removed.

public long OnUpdate(ScriptFunction handler)

Parameters

handler ScriptFunction

Returns

long

OpenDataModel(string, ScriptTable)

Opens a data model called name over a table: its fields are what documents with data-model="name" show. Null when there is a model of that name already. Open it before the documents that use it load (a script in the document's head can).

public UiDataModel? OpenDataModel(string name, ScriptTable fields)

Parameters

name string

fields ScriptTable

Returns

UiDataModel?

RemoveUpdate(long)

public void RemoveUpdate(long id)

Parameters

id long

SetSize(int, int, float)

Tells the UI how big the screen is, in pixels, and how many pixels a density-independent one is (see ).

public void SetSize(int width, int height, float density = 0)

Parameters

width int

height int

density float

Text(string)

Typed text, as UTF-8 characters.

public bool Text(string text)

Parameters

text string

Returns

bool

Unlisten(long)

Takes back a listener (the number returned). False when it was gone already.

public bool Unlisten(long token)

Parameters

token long

Returns

bool

Update(float)

Lays out what changed and runs animations, deltaSeconds after the last call. Returns whether anything changed.

public bool Update(float deltaSeconds)

Parameters

deltaSeconds float

Returns

bool