API User interface

User interface

Import	from proleak import ui

Game UI: menu entries, pages built from widgets, popups and toasts, and raw HTML panels.

Classes

Class
State	A value widgets can bind to.
SettingBinding	Binds a widget to one of the plugin's settings (saved, validated against plugin.yml).
Widget	One piece of a page, made by the functions of this module (text, button, row, ...).
Page	What a page builder receives.
MenuItem	An entry in the main or in-game menu.
Menu	The main menu or the in-game menu (main_menu, game_menu).
UnitMenuItem	An entry in the menu a right-click on a unit opens.
UnitMenu	The menu a right-click on a unit opens (unit_menu).
Panel	A raw HTML panel owned by a plugin.
ScriptHandle	A JavaScript file loaded into the game page.
Nameplate	A label floating above a unit.

Functions

Returns	Function
State	state(value: object)	A State holding value.
SettingBinding	setting(key: str)	Bind a widget to the plugin setting key.
Widget	text(s: str)	A line of text.
Widget	heading(s: str)	A section heading.
Widget	button(label: str, on_click: Callable[[], None] | None = None, style: str = 'standard', tone: str | None = None)	A button; style is standard, emphasized or text (the game's menu buttons), or small (a compact button for lists).
Widget	toggle(label: str, bind: State | SettingBinding | None = None, on_change: Callable[[bool], None] | None = None)	An On/Off toggle, like the game options.
Widget	slider(label: str, min: float, max: float, step: float = 1, bind: State | SettingBinding | None = None, on_change: Callable[[float], None] | None = None)	A number slider from min to max.
Widget	choice(label: str, options: list[str], bind: State | SettingBinding | None = None, on_change: Callable[[str], None] | None = None)	A drop-down of options (strings).
Widget	multi(label: str, options: list[str], bind: State | SettingBinding | None = None, on_change: Callable[[list[str]], None] | None = None)	A drop-down where any number of options (strings) can be ticked; its value is the list of ticked options.
Widget	key(label: str, bind: State | SettingBinding | None = None, on_change: Callable[[str], None] | None = None)	A key binding: click it, then press a key; its value is the key's Unity name ("V", "F12").
Widget	color(label: str, bind: State | SettingBinding | None = None, on_change: Callable[[str], None] | None = None)	A color field showing its #rrggbb code; clicking the code opens a color picker.
Widget	input(label: str, bind: State | SettingBinding | None = None, on_change: Callable[[str], None] | None = None)	A one-line text field; reports on Enter or when it loses focus.
Widget	image(src: str)	An image from the game's UI files (for example hud/img/icons/Gold.png).
Widget	row(*widgets: Widget, align: str = 'start')	Widgets side by side: from the left (align="start"), against the right ("end"), or from the left with the last one against the right ("split").
Widget	column(*widgets: Widget)	Widgets stacked.
Widget	group(*widgets: Widget)	Widgets stacked in a framed box, one entry of a list.
Widget	table(headers: list[str], rows: list[list[str]])	A table of strings.
Widget	entry(title: str, *lines: str, buttons: list[tuple] = (), badge: str | None = None, tone: str = 'neutral', author: str | None = None, version: str | None = None)	One entry of a list: a framed box with a heading, lines of text and small buttons.
list[Widget]	settings_form()	Widgets for every setting the calling plugin declares (settings.add or plugin.yml), the same form the Mods menu shows.
Widget	tab(label: str, *widgets: Widget)	One tab of a page's tabs (the builder's p.tabs(...)).
Callable[[Builder], Builder]	page(name: str, title: str | None = None)	Decorator: fn(p) builds the page name.
None	open(name: str)	Show the page name of the calling plugin.
None	refresh(name: str)	Run the builder of the calling plugin's page name again if it is open.
None	close(name: str)	Close the page name if it is open (back to the launcher).
None	popup(title: str, text: str, buttons: tuple[str, ...] = ('OK',), on_result: Callable[[str], None] | None = None)	A modal popup; on_result(label) gets the clicked button's label.
None	toast(text: str, header: str = '', seconds: float = 4)	A short notification in the corner of the screen.
Panel	panel(name: str, html: str, css: str = '', anchor: str = 'top-right')	Raw HTML in a corner of the screen.
Callable	on_js(evt: str, fn: Callable[[object], None] | None = None)	Handle evt sent by this plugin's panels and scripts (decorator or call).
ScriptHandle	script(path: str)	Load path (a .js file inside the plugin folder) into the game page.
Nameplate	nameplate(unit_id: int, text: str, color: str | SettingBinding | None = None, size: float | SettingBinding = 1.0, name_suffix: bool = False, spacing: float | SettingBinding = 16)	A text label above unit_id; one per unit for each plugin.
list[Nameplate]	nameplates(unit: int | None = None)	The calling plugin's labels the game still shows, or only the one on unit.
Nameplate	world_text(x: float, z: float, text: str, color: str | None = None, size: float = 1.0)	A text label at map point (x, z).

Values

Type	Value
type	Builder	A page builder: it gets the Page and adds its widgets.
Menu	main_menu read-only	The game's main menu.
Menu	game_menu read-only	The menu Escape opens in a game.
UnitMenu	unit_menu read-only	The menu a right-click on a unit opens.

Detailed description

Pages are drawn by the game's own React and components. Everything a plugin creates is removed when it unloads.

Function documentation

state

state(value: object) -> State

A State holding value.

setting

setting(key: str) -> SettingBinding

Bind a widget to the plugin setting key.

text

text(s: str) -> Widget

A line of text.

heading

heading(s: str) -> Widget

A section heading.

button

button(label: str, on_click: Callable[[], None] | None = None, style: str = 'standard', tone: str | None = None) -> Widget

A button; style is standard, emphasized or text (the game's menu buttons), or small (a compact button for lists). A small button's tone is primary (the game's gold button, for the main action), quiet (dimmed, for secondary actions) or danger (red, for an action that removes something).

toggle

toggle(label: str, bind: State | SettingBinding | None = None, on_change: Callable[[bool], None] | None = None) -> Widget

An On/Off toggle, like the game options. bind is a state or setting.

slider

slider(label: str, min: float, max: float, step: float = 1, bind: State | SettingBinding | None = None, on_change: Callable[[float], None] | None = None) -> Widget

A number slider from min to max.

choice

choice(label: str, options: list[str], bind: State | SettingBinding | None = None, on_change: Callable[[str], None] | None = None) -> Widget

A drop-down of options (strings).

multi

multi(label: str, options: list[str], bind: State | SettingBinding | None = None, on_change: Callable[[list[str]], None] | None = None) -> Widget

A drop-down where any number of options (strings) can be ticked; its value is the list of ticked options.

key

key(label: str, bind: State | SettingBinding | None = None, on_change: Callable[[str], None] | None = None) -> Widget

A key binding: click it, then press a key; its value is the key's Unity name ("V", "F12"). Escape cancels.

color

color(label: str, bind: State | SettingBinding | None = None, on_change: Callable[[str], None] | None = None) -> Widget

A color field showing its #rrggbb code; clicking the code opens a color picker.

input

input(label: str, bind: State | SettingBinding | None = None, on_change: Callable[[str], None] | None = None) -> Widget

A one-line text field; reports on Enter or when it loses focus.

image

image(src: str) -> Widget

An image from the game's UI files (for example hud/img/icons/Gold.png).

row

row(*widgets: Widget, align: str = 'start') -> Widget

Widgets side by side: from the left (align="start"), against the right ("end"), or from the left with the last one against the right ("split").

column

column(*widgets: Widget) -> Widget

Widgets stacked.

group

group(*widgets: Widget) -> Widget

Widgets stacked in a framed box, one entry of a list.

table

table(headers: list[str], rows: list[list[str]]) -> Widget

A table of strings.

entry

entry(title: str, *lines: str, buttons: list[tuple] = (), badge: str | None = None, tone: str = 'neutral', author: str | None = None, version: str | None = None) -> Widget

One entry of a list: a framed box with a heading, lines of text and small buttons.

buttons is a list of (label, on_click) pairs, or (label, on_click, button_tone) with primary or quiet as for button. Empty lines are left out. badge is a short status shown small beside the title, coloured by tone: neutral, good (green), bad (red) or busy (amber). author and version close the entry as "By author (vversion)".

settings_form

settings_form() -> list[Widget]

Widgets for every setting the calling plugin declares (settings.add or plugin.yml), the same form the Mods menu shows. Changes are validated and saved like settings.set.

tab

tab(label: str, *widgets: Widget) -> Widget

One tab of a page's tabs (the builder's p.tabs(...)).

page

page(name: str, title: str | None = None) -> Callable[[Builder], Builder]

Decorator: fn(p) builds the page name. Open it with open or a menu item.

open

open(name: str) -> None

Show the page name of the calling plugin.

refresh

refresh(name: str) -> None

Run the builder of the calling plugin's page name again if it is open.

close

close(name: str) -> None

Close the page name if it is open (back to the launcher).

popup

popup(title: str, text: str, buttons: tuple[str, ...] = ('OK',), on_result: Callable[[str], None] | None = None) -> None

A modal popup; on_result(label) gets the clicked button's label.

toast

toast(text: str, header: str = '', seconds: float = 4) -> None

A short notification in the corner of the screen.

panel

panel(name: str, html: str, css: str = '', anchor: str = 'top-right') -> Panel

Raw HTML in a corner of the screen. Elements with data-proleak-evt call on_js handlers.

on_js

on_js(evt: str, fn: Callable[[object], None] | None = None) -> Callable

Handle evt sent by this plugin's panels and scripts (decorator or call).

script

script(path: str) -> ScriptHandle

Load path (a .js file inside the plugin folder) into the game page.

nameplate

nameplate(unit_id: int, text: str, color: str | SettingBinding | None = None, size: float | SettingBinding = 1.0, name_suffix: bool = False, spacing: float | SettingBinding = 16) -> Nameplate

A text label above unit_id; one per unit for each plugin.

Calling it again for the same unit updates that label's text and style and returns it. color is "#rrggbb". The label scales with the unit's health bar as the camera zooms. spacing is the gap between the top of the bar and the bottom of the label, in the bar's own pixels; a negative value moves the label down onto or below the bar. color, size and spacing also take ui.setting(key): the label then follows that setting as it changes.

With name_suffix=True the text also appears in brackets after the unit's name when the player selects it (the unit fighting for a placed fighter in a wave counts as that fighter).

nameplates

nameplates(unit: int | None = None) -> list[Nameplate]

The calling plugin's labels the game still shows, or only the one on unit.

world_text

world_text(x: float, z: float, text: str, color: str | None = None, size: float = 1.0) -> Nameplate

A text label at map point (x, z). Returns a Nameplate.

Value documentation

Builder

Builder = Callable[[Page], None]

A page builder: it gets the Page and adds its widgets.

main_menu

main_menu: Menu [read-only]

The game's main menu.

game_menu

game_menu: Menu [read-only]

The menu Escape opens in a game.

unit_menu

unit_menu: UnitMenu [read-only]

The menu a right-click on a unit opens.

State class

A value widgets can bind to. Setting .value redraws the bound widgets.

Type	Property
object	value read-only	The value; setting it redraws the widgets bound to it.

Property documentation

value

value: object [read-only]

The value; setting it redraws the widgets bound to it.

SettingBinding class

Binds a widget to one of the plugin's settings (saved, validated against plugin.yml).

Type	Property
str	key	The setting's key.

Property documentation

key

key: str

The setting's key.

Widget class

One piece of a page, made by the functions of this module (text, button, row, ...).

Detailed description

Pass widgets to p.add(...) in a page builder, or to a layout such as row or column.

Page class

What a page builder receives. Add widgets with p.add(...) or p.tabs(...).

Type	Property
str	owner	The id of the plugin that owns it.
str	id	"<plugin id>/<name>".
str	title	The title shown above it.
Builder	builder	The function that builds it.
bool	is_open	True while the page is shown.

Returns	Method
None	add(*widgets: Widget)	Append widgets to the page.
None	tabs(*tabs: Widget)	A tab bar of tab widgets.
None	redraw()	Run the builder again and send the page.

Property documentation

owner

owner: str

The id of the plugin that owns it.

id

id: str

"<plugin id>/<name>".

title

title: str

The title shown above it.

builder

builder: Builder

The function that builds it.

is_open

is_open: bool

True while the page is shown.

Method documentation

add

add(*widgets: Widget) -> None

Append widgets to the page.

tabs

tabs(*tabs: Widget) -> None

A tab bar of tab widgets.

redraw

redraw() -> None

Run the builder again and send the page.

MenuItem class

An entry in the main or in-game menu.

Type	Property
str	owner	The id of the plugin that added it.
str	menu	"main" or "game".
str	id	Its id.
str | None	page	The page it opens, or None.
Callable[[], None] | None	on_click	The function it calls, or None.

Returns	Method
None	remove()	Remove the entry.

Property documentation

owner

owner: str

The id of the plugin that added it.

menu

menu: str

"main" or "game".

id

id: str

Its id.

page

page: str | None

The page it opens, or None.

on_click

on_click: Callable[[], None] | None

The function it calls, or None.

Method documentation

remove

remove() -> None

Remove the entry.

Menu class

The main menu or the in-game menu (main_menu, game_menu).

Returns	Method
MenuItem	add(label: str, page: str | None = None, on_click: Callable[[], None] | None = None, after: str | None = None, before: str | None = None, huge: bool = False, badge: str | None = None)	Add an entry.

Method documentation

add

add(label: str, page: str | None = None, on_click: Callable[[], None] | None = None, after: str | None = None, before: str | None = None, huge: bool = False, badge: str | None = None) -> MenuItem

Add an entry. Without after/before it goes at the end, before the promotional slot.

UnitMenuItem class

An entry in the menu a right-click on a unit opens.

Type	Property
str	owner	The id of the plugin that added it.
str	id	Its id.
str	label	Its text.
Callable[[Unit], None]	on_click	Called with the unit the menu was opened on.
Callable[[Unit], bool] | None	when	Decides whether it shows for a unit; None: always.
bool	alt read-only	True: the entry shows only on Alt + right-click.

Returns	Method
None	remove()	Remove the entry.

Property documentation

owner

owner: str

The id of the plugin that added it.

id

id: str

Its id.

label

label: str

Its text.

on_click

on_click: Callable[[Unit], None]

Called with the unit the menu was opened on.

when

when: Callable[[Unit], bool] | None

Decides whether it shows for a unit; None: always.

alt

alt: bool [read-only]

True: the entry shows only on Alt + right-click.

Method documentation

remove

remove() -> None

Remove the entry.

UnitMenu class

The menu a right-click on a unit opens (unit_menu).

Returns	Method
UnitMenuItem	add(label: str, on_click: Callable[[Unit], None], when: Callable[[Unit], bool] | None = None, alt: bool = False)	Add an entry to the menu a right-click on a unit opens, and return it as a UnitMenuItem.

Method documentation

add

add(label: str, on_click: Callable[[Unit], None], when: Callable[[Unit], bool] | None = None, alt: bool = False) -> UnitMenuItem

Add an entry to the menu a right-click on a unit opens, and return it as a UnitMenuItem.

on_click(unit) runs with the Unit the menu was opened on. when(unit), when given, decides whether the entry shows for that unit; an entry whose when raises is left out. With alt=True the entry shows only on Alt + right-click (set item.alt to change it later). A right-click on a unit opens the menu, in place of the game's ping wheel, when at least one entry shows for that click.

Panel class

A raw HTML panel owned by a plugin.

Type	Property
str	owner	The id of the plugin that owns it.
str	id	Its id.

Returns	Method
None	send(evt: str, data: object = None)	Deliver evt to this plugin's scripts (api.on(evt, fn)) and to the panel element as a proleak DOM event.
None	remove()	Remove the panel now.

Property documentation

owner

owner: str

The id of the plugin that owns it.

id

id: str

Its id.

Method documentation

send

send(evt: str, data: object = None) -> None

Deliver evt to this plugin's scripts (api.on(evt, fn)) and to the panel element as a proleak DOM event.

remove

remove() -> None

Remove the panel now.

ScriptHandle class

A JavaScript file loaded into the game page.

Type	Property
str	owner	The id of the plugin that loaded it.
str	id	Its id.

Returns	Method
None	remove()	Unload the script (its onUnload callbacks run).

Property documentation

owner

owner: str

The id of the plugin that loaded it.

id

id: str

Its id.

Method documentation

remove

remove() -> None

Unload the script (its onUnload callbacks run).

Nameplate class

A label floating above a unit. Removed when the unit dies or is sold, or the plugin unloads; alive tells whether the game still shows it.

Type	Property
str | None	owner	The id of the plugin that owns it.
int | None	unit	The id of the unit it floats above; None for a label at a map point.
str	text	Its text.
bool	alive read-only	False once the game or the plugin removed the label.

Returns	Method
None	set_text(text: str)	Change the label.
None	set_style(color: str | None = None, size: float | None = None, spacing: float | None = None)	Change the color, size or spacing of the label; None keeps the current one.
None	remove()	Remove the label now.

Property documentation

owner

owner: str | None

The id of the plugin that owns it.

unit

unit: int | None

The id of the unit it floats above; None for a label at a map point.

text

text: str

Its text.

alive

alive: bool [read-only]

False once the game or the plugin removed the label.

Method documentation

set_text

set_text(text: str) -> None

Change the label.

set_style

set_style(color: str | None = None, size: float | None = None, spacing: float | None = None) -> None

Change the color, size or spacing of the label; None keeps the current one.

remove

remove() -> None

Remove the label now.

---

Previous: Timers | Next: World