API overview¶

The API is made of two global tables, available in every plugin:

Balltze: services for plugins themselves: events, console commands, configuration files, network channels, files, logging, timers, easing curves and raw memory.
Engine: the game itself: the camera, maps, the match, scripts, tags, objects, collision, players, the console, menus, mouse input and on-screen text and HUD.

Conventions¶

Live data¶

Tags, objects, players and widgets returned by the API are views into the game's memory, not copies. Reading a field returns its current value, and writing a field changes the game right away.

Field names are the engine's names in lower camel case: root_bsp_index is rootBspIndex.

Handles¶

Tags, objects and players are referenced by handles (TagHandle, ObjectHandle, PlayerHandle). A handle has a value field with its raw 32 bit value and an isNull() method that tells whether it points to nothing. Functions whose parameters are listed as ObjectHandle|integer also accept the raw integer.

local player = Engine.player.getPlayer()
if player and not player.unitHandle:isNull() then
    local unit = Engine.object.getObject(player.unitHandle)
end

Formatting¶

Balltze.logger and Engine.terminal.print format their messages with {} placeholders, like Python's str.format, instead of the % style of string.format:

Balltze.logger.info("{} has {} kills", name, kills)
Engine.terminal.print("Position: {:.2f}, {:.2f}", x, y)

With a single argument, the message is printed as is.

Errors¶

Wrong arguments raise Lua errors, as do calls that need a map when none is loaded. Errors raised inside event listeners, commands and timers are caught and printed to the console with a stack trace, so they do not stop the game or other plugins.

Threads¶

When plugins are loaded or unloaded by a map load, their main file and PluginUnload run on the map loading thread, as do the map_load and map_loaded listeners. Everything else, including a reload with balltze_reload_plugins, runs on the game's main thread.

Type annotations¶

Every function and type is described in annotation files for the Lua language server. See Types.