acron.ui

RmlUi machinery for game UIs (menus, HUDs) on the acron engine.

Godot ships UI as Control-node scenes; the ports rebuild theirs as acron.rmlui documents. This module is the mechanism layer every port was re-implementing — games supply the .rml/.rcss documents, the button ids and the action handlers (policy).

Hard-won rules baked in (RUNTIME.md rule 4; exponaut docs/gotchas.md):

  • apply_prc() must run BEFORE ShowBase — RmlUi clipping needs a stencil buffer (and on macOS the GL compat profile: never force gl-version 3 2).

  • Fonts are per-context (RmlUI.load_fonts()).

  • RmlRegion auto-pumps per frame — no update task needed.

  • A shown document is pulled to the front, and a pointer-opaque full-screen body eats input for everything beneath it: give document bodies pointer-events: none in the theme; interactive elements opt back in with pointer-events: auto.

  • Never mutate the scene graph or raise SystemExit inside an RmlUi event callback — bounce through RmlUI.defer() / RmlUI.defer_exit().

  • RmlRegion.make context names are global to the process, and a destroyed context’s name is freed only once its region is gone: a RmlUI built under a name that has been used before in this process takes a fresh one (name, name2, name3…) rather than waiting for that — RmlUI.name is the one it got.

  • Data models and their event callbacks must exist BEFORE load_document of any document referencing them (RmlUI.make_model() enforces the shape).

  • Data expressions have no backslash escapes: write action('foo') with bare single quotes inside the double-quoted attribute.

ChangedWrites()

Apply a value only when it changed since the last apply.

RmlUI(base, *[, name, authored_height, ...])

Region + context + input plumbing for one window's RmlUi layer.

StateMenu(ui, document, sets, *[, pause, ...])

One menu document, many screens: per-state button sets + keyboard nav.

Global Functions

apply_prc(name: str = 'acron-rmlui') → None

Call BEFORE ShowBase: RmlUi clipping needs a stencil buffer. This is the one line RmlUi needs; acron.window.apply_prc() is the whole prc a window wants and includes it.

name is the descriptive label the prc data is registered under (what print(cpMgr) shows); the engine reads only the prc content.

escape_rml(text) → str

Text into markup: everything that came from data gets escaped. Markup a game authors on purpose (a <kbd> key prompt) is NOT sent through here — that is the whole distinction.

event_number_arg(args)

The numeric payload of a data-model event callback, as int (or None).

event_string_arg(args)

The string payload of a data-model event callback (RmlUi mixes the event object into *args; sniff the payload out by type).

unique_name(name: str) → str

name the first time it is asked for, name2… after that.