API

API reference

Generated from the docstrings by tools/gen_api_pages.py.

Page	Module
Background tasks	proleak.tasks	Background work that never blocks the game.
Camera	proleak.camera	Read the game camera; moving it, and riding a unit in first person, needs the actions capability (local games only).
Chat	proleak.chat	Chat commands and messages.
Cosmetics	proleak.cosmetics	What this player hears and sees of the game: music, sounds, the map's decorations and effects.
Errors	proleak.errors	Exceptions raised by the ProLeak API.
Game data	proleak.data	The game's data: units, legions, waves, mercenaries, legion spells, masterminds, king upgrades.
Game modes	proleak.modes	Game modes: your own rules on ProLeak's local server.
Game state	proleak.game	Read-only view of the game: players and units. Main thread only.
Logging	proleak.log	Unified logging. from proleak import log then log.info("...").
Mouse and keyboard	proleak.input	Mouse and keyboard hooks. Handlers observe; they cannot block the game's own input.
Player actions	proleak.actions	Act as the player. Needs the actions capability (local servers).
Plugin lifecycle	proleak.plugins	The calling plugin's own lifecycle.
Plugin settings	proleak.settings	Plugin settings: declared with add (or in plugin.yml), saved between sessions and editable from the plugin's Settings form in the Mods menu.
Raw game access	proleak.advanced	Raw access to the game, for what the event API does not cover.
Server kinds	proleak.server	What kind of server the game is connected to, and what that allows.
Sounds	proleak.sfx	Play sounds on this client only.
Timers	proleak.timers	Timers driven by the game's frame loop. All callbacks run on the main thread.
User interface	proleak.ui	Game UI: menu entries, pages built from widgets, popups and toasts, and raw HTML panels.
World	proleak.world	The game world as live objects: players, teams, units and areas. Read-only. Main thread only.

Event handlers

on

on(event: str, pre: bool = False, priority: int = 0) -> Callable[[Handler], Handler]

Decorator: call the function for each dispatch of event.

pre=True runs before the game acts; the handler may edit fields or ev.cancel(). Post handlers (the default) run after, see final values, and never run for a cancelled event. Higher priority runs first; ties go by plugin load order.

off

off(fn: Handler) -> None

Remove every subscription made for fn with on.

Handler

Handler = Callable[[Event], None]

A function that handles one dispatch of an event.

Event class

One dispatch of an event, given to each handler.

Type	Property
str	name read-only	Event name, for example chat.send.
bool	pre read-only	True in a pre handler, False in a post handler.
bool	cancelled read-only	True once a pre handler cancelled the event.
bool | int | float | str | None	result read-only	Return value of the original call (post handlers only, when there is one).
int	frame read-only	Unity frame number of the dispatch.
int	net_ticks read-only	Game network time of the dispatch in 100 ns ticks (0 for events that carry none).
UnitInfo | WaveInfo | None	info read-only	The game data record of the event's unit type or wave field, or None.

Returns	Method
None	cancel()	Stop the remaining pre handlers and the original call.
dict[str, object]	fields()	All field values as a dict (converts every field; prefer attribute reads).

Detailed description

Read and write the event's fields as attributes (ev.unit, ev.gold = 0); the events pages list each event's fields. The object is valid only while the handler runs.

Property documentation

name

name: str [read-only]

Event name, for example chat.send.

pre

pre: bool [read-only]

True in a pre handler, False in a post handler.

cancelled

cancelled: bool [read-only]

True once a pre handler cancelled the event.

result

result: bool | int | float | str | None [read-only]

Return value of the original call (post handlers only, when there is one).

frame

frame: int [read-only]

Unity frame number of the dispatch.

net_ticks

net_ticks: int [read-only]

Game network time of the dispatch in 100 ns ticks (0 for events that carry none).

info

info: UnitInfo | WaveInfo | None [read-only]

The game data record of the event's unit type or wave field, or None.

Method documentation

cancel

cancel() -> None

Stop the remaining pre handlers and the original call.

fields

fields() -> dict[str, object]

All field values as a dict (converts every field; prefer attribute reads).

---

Previous: Developer options | Next: Background tasks