API

API reference

Generated from the docstrings by tools/gen_api_pages.py.

Page	Module	Description
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.
Errors	proleak.errors	Exceptions raised by the ProLeak API.
Game assets	proleak.assets	The game's assets as this player hears and sees them: sounds, music, models, the map, effects and lighting.
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

# Decorator: call the function for each dispatch of event.
def on(event: str, pre: bool = False, priority: int = 0) -> Callable[[Handler], Handler]

Details

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.

Argument	Type	Default	Description
event	str	required	The event's name, such as "wave.started", as the Events pages list them.
pre	bool	False	True runs the handler before the game acts, where it may edit fields or call ev.cancel().
priority	int	0	Higher runs first; ties go by plugin load order.

from proleak import on, ui

@on("chat.received", pre=True, priority=10)
def hide_spam(ev):
    if "free gold" in ev.text:
        ev.cancel()

@on("wave.started")
def announce(ev):
    ui.toast(f"{ev.info.name} is coming", header=f"Wave {ev.wave}")

# Remove every subscription made for fn with on.
def off(fn: Handler) -> None

Details

Argument	Type	Default	Description
fn	Handler	required	A handler given to on.

from proleak import log, off, on

@on("unit.built")
def first_build(ev):
    log.info(f"first fighter: {ev.info.name}")
    off(first_build)                    # only the first one

Value	Type	Description
Handler	type	A function that handles one dispatch of an event.

# One dispatch of an event, given to each handler.
class Event

Details

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.

from proleak import on

@on("chat.send", pre=True)
def shout(ev):
    if ev.text.startswith("!!"):
        ev.text = ev.text[2:].upper()   # an editable field

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

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

# Stop the remaining pre handlers and the original call.
def cancel() -> None

Details

from proleak import on

@on("mercenary.buying", pre=True)
def no_snails(ev):
    if ev.info.name == "Snail":
        ev.cancel()                     # the hire is never sent

---

# All field values as a dict (converts every field; prefer attribute reads).
def fields() -> dict[str, object]

Details

from proleak import log, on

@on("unit.died")
def died(ev):
    log.debug(ev.fields())              # every field, by name

---

Previous: Developer options | Next: Background tasks