Events¶

Events call a function of your plugin when something happens in the game.

Functions¶

Balltze.addEventListener¶

Balltze.addEventListener(eventName, callback, priority)

Calls callback every time the event fires. An event can have any number of listeners.

Parameter	Type	Description
`eventName`	`string`	One of the events below.
`callback`	`function`	Receives the event's context object, or `nil` for events without one.
`priority`	`string`, optional	`"highest"`, `"above_default"`, `"default"` or `"lowest"`. Default is `"default"`.

Returns an EventListener:

Field	Type	Description
`handle`	`string`	Identifier of the listener.
`event`	`string`	Name of the event.
`priority`	`string`	Priority of the listener.
`remove`	`function`	Removes this listener only.

local listener = Balltze.addEventListener("tick", function()
    -- ...
end)

listener.remove()

Listeners run from the highest priority to the lowest. When a listener cancels an event, the listeners of lower priorities are skipped, in every plugin; the remaining listeners of the same priority still run.

Balltze.removeEventListeners¶

Balltze.removeEventListeners(eventName)

Removes every listener your plugin added to an event. Listeners of other plugins are not touched.

Event list¶

Event	When	Context	Can be cancelled
`frame`	At the end of every rendered frame.	`nil`	No
`frame_begin`	At the start of every rendered frame.	`nil`	No
`frame_end`	Same as `frame`.	`nil`	No
`tick`	At the end of every game tick, 30 times per second.	`nil`	No
`map_load`	When a map starts loading, before its tags are loaded.	`MapLoadEvent`	No
`map_loaded`	When a map has finished loading.	`MapLoadedEvent`	No
`player_input`	When a key, mouse button or gamepad button is pressed.	`PlayerInputEvent`	Yes
`widget_loaded`	After a menu widget is created.	`WidgetLoadedEvent`	No
`widget_event_dispatch`	Before a menu widget handles an event.	`WidgetEventDispatchEvent`	Yes
`object_damage`	When an object is about to take damage.	`ObjectDamageEvent`	Yes

The dedicated server draws nothing, so the frame events do not fire there. Use tick for work that must also run on a server.

Contexts¶

map_load¶

MapLoadEvent

Method	Returns	Description
`getMapName()`	`string`	Name of the map being loaded.

This event runs on the map loading thread. The tags of the new map are not loaded yet.

map_loaded¶

MapLoadedEvent

Method	Returns	Description
`getMapName()`	`string`	Name of the map that was loaded.

This event runs on the map loading thread, once the map and its first BSP are loaded.

player_input¶

PlayerInputEvent

Method	Returns	Description
`getDevice()`	`string`	`"keyboard"`, `"mouse"`, `"gamepad"` or `"unknown"`.
`getKeyCode()`	`integer`	Index of the key. Raises an error when the device is not the keyboard.
`getMouseButton()`	`integer`	0 left, 1 middle, 2 right, 3 to 7 extra buttons. Raises an error when the device is not the mouse.
`getGamepadButton()`	`integer`	Index of the button. Raises an error when the device is not a gamepad.
`isMapped()`	`boolean`	Whether the input is bound to a game control.
`cancel()`		Hides the press from the game control it is bound to.

The event fires only when the input is first pressed, not while it is held. Cancelling it hides the press: actions that happen when a control is pressed do not happen, but if the key is held, the game sees it as held from the next update on. Analog sticks and triggers do not fire this event.

widget_loaded¶

WidgetLoadedEvent

Method	Returns	Description
`getWidget()`	`Widget`	The new widget.

widget_event_dispatch¶

WidgetEventDispatchEvent

Method	Returns	Description
`getWidget()`	`Widget`	The widget handling the event.
`getEventRecord()`	`UIWidgetEventRecord`	The event: its type and the input that caused it.
`getEventHandler()`	`UiWidgetDefinitionEventHandler`	The handler of the widget's tag that is about to run.
`cancel()`		Skips the widget's handling of the event.

object_damage¶

ObjectDamageEvent

Method	Returns	Description
`getObjectHandle()`	`TableResourceHandle`	The object taking the damage.
`getDamageEffectTagHandle()`	`TableResourceHandle`	The `damage_effect` tag being applied.
`getCauserPlayerHandle()`	`TableResourceHandle`	The player causing the damage. May be null.
`getCauserObjectHandle()`	`TableResourceHandle`	The object causing the damage. May be null.
`getMultiplier()`	`number`	Damage multiplier.
`cancel()`		The damage is not applied.

Example¶

-- Make the local player's unit immune to damage.
Balltze.addEventListener("object_damage", function(event)
    local player = Engine.player.getPlayer()
    if player and event:getObjectHandle().value == player.unitHandle.value then
        event:cancel()
    end
end, "highest")