Events Game events

Game events

Game events keep their names and fields across game updates.

Generated from catalog/events.json by tools/gen_events_doc.py.

Contents (55 sections)

• ability.using
• chat.received
• chat.send
• emote.received
• emote.sending
• fighter.died
• game.ended
• game.started
• input.click
• input.hover
• input.key
• king.damaged
• king.died
• king.upgraded
• king.upgrading
• mastermind.choosing
• mastermind.chosen
• mercenary.buying
• mercenary.hired
• mercenary.sent
• phase.changed
• ping.received
• ping.sending
• player.afk
• player.disconnected
• player.leaked
• player.reconnected
• purchase.cancelled
• purchase.failed
• roll.rerolled
• roll.rerolling
• send_mode.changed
• send_mode.changing
• signal.received
• signal.sending
• spell.choosing
• spell.chosen
• spell.placed
• spell.placing
• spell.removed
• spell.undoing
• team.leaked
• unit.built
• unit.died
• unit.downgraded
• unit.downgrading
• unit.selling
• unit.sold
• unit.spawned
• unit.trained
• unit.upgraded
• upgrade.buying
• wave.ended
• wave.started
• worker.buying

ability.using

This player orders units to use an ability other than selling, downgrading, or placing or undoing the legion spell.

Before and after the game acts (pre=True for before); cancelling needs actions.

Field	Type	Editable	Notes
player	integer	no	This player. Handed as a world.Player.
order	string	no	The game's order name in snake case, for example search_for_treasure.
ability	string	no	Ability id.
units	list	no	The units ordered. Handed as a world.Unit.

chat.received

A chat message arrives. Cancel to hide it; edit text to change what you see.

Before and after the game acts (pre=True for before); cancellable.

Field	Type	Editable	Notes
text	string	yes	Message text as it will be shown.
sender	string	no	Sender display name (empty for in-game chat; use player).
player	integer	no	Sender in game, None in lobby rooms. Handed as a world.Player.
all_chat	bool	no	True for all chat.
channel	string	no	"game" or "room".
timestamp	integer	no	Server timestamp of the message.

chat.send

The player sends a chat message. Cancel to keep it from being sent; edit text to change it.

Before and after the game acts (pre=True for before); cancellable.

Field	Type	Editable	Notes
text	string	yes	Message text.
all_chat	bool	yes	True for all chat, false for team chat. Fixed to false in lobby chat rooms.
channel	string	no	"game" for in-game chat, "room" for lobby chat rooms.

emote.received

A player's emote arrives.

Before and after the game acts (pre=True for before); cancellable.

Field	Type	Editable	Notes
player	integer	no	The player. Handed as a world.Player.
emote	integer	no	Emote slot.

emote.sending

This player plays an emote.

Before and after the game acts (pre=True for before); cancelling needs actions.

Field	Type	Editable	Notes
player	integer	no	This player. Handed as a world.Player.
emote	integer	no	Emote slot.

fighter.died

A fighter died during a wave (it comes back for the next one).

Raised after the game acts only (no pre=True); not cancellable.

Field	Type	Editable	Notes
unit	integer	no	The wave fighter that died. Handed as a world.Unit.
placed	integer	no	The placed fighter it fought for. Handed as a world.Unit.
player	integer	no	Owner slot. Handed as a world.Player.
wave	integer	no	Wave. ev.info gives its data.WaveInfo.

game.ended

The game is over and the result is known.

Before and after the game acts (pre=True for before); not cancellable.

Field	Type	Editable	Notes
result	string	no	Game result as the game names it.
wave	integer	no	Last wave reached. ev.info gives its data.WaveInfo.
seconds	integer	no	Game length in seconds.
game_id	string	no	Game id.

game.started

The game begins (after loading).

Before and after the game acts (pre=True for before); not cancellable.

Field	Type	Editable	Notes
tick	integer	no	Server tick at the start.
mission_id	string	no	Mission id for campaign and challenge games, else empty.

input.click

The player clicks.

Raised after the game acts only (no pre=True); not cancellable.

Field	Type	Editable	Notes
button	integer	no	0 left, 1 right, 2 middle.
screen_x	float	no	Screen x in pixels.
screen_y	float	no	Screen y in pixels.
world_x	float	no	Map x under the cursor (NaN when nothing is hit).
world_z	float	no	Map z under the cursor (NaN when nothing is hit).
unit	integer	no	Unit under the cursor, None when there is none. Handed as a world.Unit.

input.hover

The cursor moves onto a unit.

Raised after the game acts only (no pre=True); not cancellable.

Field	Type	Editable	Notes
unit	integer	no	Unit now under the cursor. Handed as a world.Unit.

input.key

A key some plugin watches is pressed (also while typing in chat).

Raised after the game acts only (no pre=True); not cancellable.

Field	Type	Editable	Notes
key	string	no	Unity KeyCode name, for example F8.
shift	bool	no	Shift held.
ctrl	bool	no	Control held.
alt	bool	no	Alt held.

king.damaged

A king lost health.

Raised after the game acts only (no pre=True); not cancellable.

Field	Type	Editable	Notes
king	integer	no	King unit id. Handed as a world.Unit.
team	integer	no	Team id. Handed as a world.Team.
amount	float	no	Health lost since the last frame.
hp	float	no	Health now.
max_hp	float	no	Maximum health.

king.died

A king's health reached zero.

Raised after the game acts only (no pre=True); not cancellable.

Field	Type	Editable	Notes
king	integer	no	King unit id. Handed as a world.Unit.
team	integer	no	Team id. Handed as a world.Team.

king.upgraded

A player bought a king upgrade.

Raised after the game acts only (no pre=True); not cancellable.

Field	Type	Editable	Notes
player	integer	no	Player slot. Handed as a world.Player.
team	integer	no	Team id of the king. Handed as a world.Team.
upgrade	string	no	"attack", "regen" or "spell".
level	integer	no	Level after the upgrade.

king.upgrading

This player buys a king upgrade, or queues one.

Before and after the game acts (pre=True for before); cancelling needs actions.

Field	Type	Editable	Notes
player	integer	no	This player. Handed as a world.Player.
upgrade	string	no	"attack", "regen" or "spell".
research	string	no	The game's id for the upgrade (a research id), for example king_attack_research_id.
level	integer	no	Level after the purchase.
queued	bool	no	True when put in the queue (bought once affordable).

mastermind.choosing

This player chooses a Mastermind playstyle.

Before and after the game acts (pre=True for before); cancelling needs actions.

Field	Type	Editable	Notes
player	integer	no	This player. Handed as a world.Player.
mastermind	string	no	Playstyle id. Handed as a data.MastermindInfo.

mastermind.chosen

A player chose a Mastermind playstyle.

Raised after the game acts only (no pre=True); not cancellable.

Field	Type	Editable	Notes
player	integer	no	Player slot. Handed as a world.Player.
mastermind	string	no	Playstyle id. Handed as a data.MastermindInfo.

mercenary.buying

This player hires a mercenary, or queues one.

Before and after the game acts (pre=True for before); cancelling needs actions.

Field	Type	Editable	Notes
player	integer	no	This player. Handed as a world.Player.
type	string	no	Mercenary unit type. ev.info gives its data.UnitInfo.
builder	integer	no	The unit it is hired from. Handed as a world.Unit.
queued	bool	no	True when put in the queue (bought once affordable).
from_queue	bool	no	True when the queue sends a mercenary queued earlier.

mercenary.hired

A player hired a mercenary.

Before and after the game acts (pre=True for before); not cancellable.

Field	Type	Editable	Notes
player	integer	no	Player slot. Handed as a world.Player.
unit	integer	no	Unit id. Handed as a world.Unit.
type	string	no	Mercenary type id. ev.info gives its data.UnitInfo.
from_queue	bool	no	True when sent from the queue.

mercenary.sent

A mercenary a player sent reaches its target at the start of a wave.

Raised after the game acts only (no pre=True); not cancellable.

Field	Type	Editable	Notes
player	integer	no	Sender slot. Handed as a world.Player.
target	integer	no	Slot of the player it attacks. Handed as a world.Player.
type	string	no	Mercenary unit type. ev.info gives its data.UnitInfo.
wave	integer	no	Wave it attacks in. ev.info gives its data.WaveInfo.

phase.changed

The game switches between build and fight.

Raised after the game acts only (no pre=True); not cancellable.

Field	Type	Editable	Notes
phase	string	no	"build" or "fight".
wave	integer	no	Current wave. ev.info gives its data.WaveInfo.

ping.received

A player's map ping arrives.

Before and after the game acts (pre=True for before); cancellable.

Field	Type	Editable	Notes
player	integer	no	The player who pinged. Handed as a world.Player.
kind	string	no	"regular", "on_my_way", "target", "warning", "question", "help", "regular_ground", "checkmark", "reached_king" or "leaked_them".
x	float	no	Map x.
z	float	no	Map z.

ping.sending

This player pings the map.

Before and after the game acts (pre=True for before); cancelling needs actions.

Field	Type	Editable	Notes
player	integer	no	This player. Handed as a world.Player.
kind	string	no	"regular", "on_my_way", "target", "warning", "question", "help", "regular_ground", "checkmark", "reached_king" or "leaked_them".
x	float	no	Map x.
z	float	no	Map z.

player.afk

A player was marked away from keyboard.

Raised after the game acts only (no pre=True); not cancellable.

Field	Type	Editable	Notes
player	integer	no	Player slot. Handed as a world.Player.

player.disconnected

A player lost the connection.

Raised after the game acts only (no pre=True); not cancellable.

Field	Type	Editable	Notes
player	integer	no	Player slot. Handed as a world.Player.

player.leaked

A player's leak share for a wave is known.

Before and after the game acts (pre=True for before); not cancellable.

Field	Type	Editable	Notes
player	integer	no	Player slot. Handed as a world.Player.
wave	integer	no	Wave number. ev.info gives its data.WaveInfo.
percent	float	no	Leaked share, 0 to 100.

player.reconnected

A player came back.

Raised after the game acts only (no pre=True); not cancellable.

Field	Type	Editable	Notes
player	integer	no	Player slot. Handed as a world.Player.

purchase.cancelled

This player takes a queued purchase back out of the queue, or cancels a worker in training.

Before and after the game acts (pre=True for before); cancelling needs actions.

Field	Type	Editable	Notes
player	integer	no	This player. Handed as a world.Player.
kind	string	no	"mercenary", "worker" or "king_upgrade".
type	string	no	Unit type, or "" for a king upgrade or a training cancel. ev.info gives its data.UnitInfo.
research	string	no	The game's id for a king upgrade (a research id), else "".
builder	integer	no	The unit the purchase was queued at. Handed as a world.Unit.

purchase.failed

The game refused a purchase this player clicked, before sending anything.

Raised after the game acts only (no pre=True); not cancellable.

Field	Type	Editable	Notes
player	integer	no	This player. Handed as a world.Player.
kind	string	no	"fighter", "mercenary", "worker", "king_upgrade" or "upgrade".
type	string	no	Unit type, or "" for an upgrade. ev.info gives its data.UnitInfo.
research	string	no	The game's id for the upgrade (a research id), or "" for a unit.
reason	string	no	"gold", "mythium", "food", "cooldown", "out_of_stock", "queue_full", "max_level", "already_researched", "already_built", "unit_type", "hp", "mana" or "invalid".

roll.rerolled

A player's roll of fighters changed.

Raised after the game acts only (no pre=True); not cancellable.

Field	Type	Editable	Notes
player	integer	no	Player slot. Handed as a world.Player.
old	list	no	Unit types before.
new	list	no	Unit types after.

roll.rerolling

This player rerolls their fighter choices (Mastermind).

Before and after the game acts (pre=True for before); cancelling needs actions.

Field	Type	Editable	Notes
player	integer	no	This player. Handed as a world.Player.
research	string	no	The game's id for the reroll (a research id).
level	integer	no	How many rerolls after this one.

send_mode.changed

The server confirms a player's mercenary send mode.

Before and after the game acts (pre=True for before); not cancellable.

Field	Type	Editable	Notes
player	integer	no	The player. Handed as a world.Player.
mode	string	no	"none", "save", "income" or "power".
preview	list	no	Mercenary types the mode will send.

send_mode.changing

This player switches the mercenary send mode.

Before and after the game acts (pre=True for before); cancelling needs actions.

Field	Type	Editable	Notes
player	integer	no	This player. Handed as a world.Player.
mode	string	no	"save", "income" (auto mercs) or "power" (auto power).

signal.received

A signal arrives: a teammate's, or this player's own as the server echoes it back.

Before and after the game acts (pre=True for before); cancellable.

Field	Type	Editable	Notes
player	integer	no	The player who signalled. Handed as a world.Player.
key	string	no	What it says, for example wants_to_hire, wants_to_hire_need_mythium or ping_player_gold.
type	string	no	Unit type it is about, or "". ev.info gives its data.UnitInfo.
research	string	no	The game's id for the upgrade it is about (a research id), or "".
amount	integer	no	Gold or mythium still missing in a "need" signal, else 0.
args	list	no	The signal's raw arguments.

signal.sending

This player signals teammates (right-click or Alt-click on a HUD element, such as a mercenary to hire).

Before and after the game acts (pre=True for before); cancelling needs actions.

Field	Type	Editable	Notes
player	integer	no	This player. Handed as a world.Player.
key	string	no	What it says, for example wants_to_hire, wants_to_hire_need_mythium or ping_player_gold.
type	string	no	Unit type it is about, or "". ev.info gives its data.UnitInfo.
research	string	no	The game's id for the upgrade it is about (a research id), or "".
amount	integer	no	Gold or mythium still missing in a "need" signal, else 0.
args	list	no	The signal's raw arguments.

spell.choosing

This player chooses a legion spell.

Before and after the game acts (pre=True for before); cancelling needs actions.

Field	Type	Editable	Notes
player	integer	no	This player. Handed as a world.Player.
spell	string	no	Legion spell id. Handed as a data.SpellInfo.
sub_spell	bool	no	True for the second choice of a spell that offers one.

spell.chosen

A player chose a legion spell.

Raised after the game acts only (no pre=True); not cancellable.

Field	Type	Editable	Notes
player	integer	no	Player slot. Handed as a world.Player.
spell	string	no	Legion spell id; spell.placed follows when it goes on a fighter. Handed as a data.SpellInfo.

spell.placed

A player put their legion spell on a fighter.

Raised after the game acts only (no pre=True); not cancellable.

Field	Type	Editable	Notes
player	integer	no	Player slot. Handed as a world.Player.
spell	string	no	Legion spell id. Handed as a data.SpellInfo.
unit	integer	no	The fighter that carries it. Handed as a world.Unit.

spell.placing

This player puts the chosen legion spell on a fighter.

Before and after the game acts (pre=True for before); cancelling needs actions.

Field	Type	Editable	Notes
player	integer	no	This player. Handed as a world.Player.
spell	string	no	Legion spell id. Handed as a data.SpellInfo.
unit	integer	no	The fighter. Handed as a world.Unit.

spell.removed

A player took their legion spell back off a fighter.

Raised after the game acts only (no pre=True); not cancellable.

Field	Type	Editable	Notes
player	integer	no	Player slot. Handed as a world.Player.
spell	string	no	Legion spell id. Handed as a data.SpellInfo.
unit	integer	no	The fighter that carried it. Handed as a world.Unit.

spell.undoing

This player takes the legion spell back off its fighter (possible during the build phase it was placed in).

Before and after the game acts (pre=True for before); cancelling needs actions.

Field	Type	Editable	Notes
player	integer	no	This player. Handed as a world.Player.
spell	string	no	Legion spell id. Handed as a data.SpellInfo.
unit	integer	no	The fighter. Handed as a world.Unit.

team.leaked

A team's leak for the wave grew.

Raised after the game acts only (no pre=True); not cancellable.

Field	Type	Editable	Notes
team	integer	no	Team id. Handed as a world.Team.
wave	integer	no	Wave. ev.info gives its data.WaveInfo.
percent	float	no	Sum of the team's players' leak percent for the wave.
players	list	no	Slots of the team's players. Handed as a world.Player.

unit.built

A player places a fighter on their grid (any player).

Raised after the game acts only (no pre=True); not cancellable.

Field	Type	Editable	Notes
player	integer	no	Player slot that placed it. Handed as a world.Player.
unit	integer	no	Unit id of the placed fighter. In waves another unit fights for it. Handed as a world.Unit.
type	string	no	Unit type id, for example mudman_unit_id. ev.info gives its data.UnitInfo.
x	float	no	Map x position.
z	float	no	Map z position.

unit.died

A unit dies.

Raised after the game acts only (no pre=True); not cancellable.

Field	Type	Editable	Notes
unit	integer	no	Unit id. Handed as a world.Unit.
killer	integer	no	Killing unit id. Handed as a world.Unit.
bounty	integer	no	Gold bounty paid.
bounty_receiver	integer	no	Player slot that got the bounty. Handed as a world.Player.
placed	integer	no	For a wave fighter, the placed fighter it fights for (the unit unit.built named); else -1. Handed as a world.Unit.

unit.downgraded

A placed fighter was taken back down its upgrade chain.

Raised after the game acts only (no pre=True); not cancellable.

Field	Type	Editable	Notes
player	integer	no	Player slot. Handed as a world.Player.
unit	integer	no	Unit id (kept by the downgrade). Handed as a world.Unit.
old_type	string	no	Unit type before. ev.info gives its data.UnitInfo.
new_type	string	no	Unit type after. ev.info gives its data.UnitInfo.

unit.downgrading

This player takes placed fighters back down their upgrade chain (the Downgrade button), for a refund of the last step.

Before and after the game acts (pre=True for before); cancelling needs actions.

Field	Type	Editable	Notes
player	integer	no	This player. Handed as a world.Player.
units	list	no	The fighters downgraded. Handed as a world.Unit.

unit.selling

This player sells placed fighters.

Before and after the game acts (pre=True for before); cancelling needs actions.

Field	Type	Editable	Notes
player	integer	no	This player. Handed as a world.Player.
units	list	no	The fighters sold. Handed as a world.Unit.

unit.sold

A placed fighter of yours or a teammate's left the grid: sold, or removed by the game.

Raised after the game acts only (no pre=True); not cancellable.

Field	Type	Editable	Notes
player	integer	no	Owner slot. Handed as a world.Player.
unit	integer	no	Unit id of the placed fighter. Handed as a world.Unit.
type	string	no	Unit type id. ev.info gives its data.UnitInfo.

unit.spawned

A unit appears on the map: a placed fighter, a wave fighter, a mercenary, a wave unit, a worker or a king.

Raised after the game acts only (no pre=True); not cancellable.

Field	Type	Editable	Notes
unit	integer	no	Unit id (reused after the unit dies). Handed as a world.Unit.
type	string	no	Unit type id, for example pirate_skeleton_unit_id. ev.info gives its data.UnitInfo.
owner	integer	no	Owning player slot. Handed as a world.Player.
x	float	no	Map x position.
z	float	no	Map z position.

unit.trained

A player trained a unit at their king, such as a worker (or canceled the training).

Before and after the game acts (pre=True for before); not cancellable.

Field	Type	Editable	Notes
player	integer	no	Player slot. Handed as a world.Player.
unit	integer	no	Unit id that did the training. Handed as a world.Unit.
type	string	no	Trained unit type id, for example worker_unit_id. ev.info gives its data.UnitInfo.
canceled	bool	no	True when the training was canceled.

unit.upgraded

A placed fighter upgraded into another unit.

Raised after the game acts only (no pre=True); not cancellable.

Field	Type	Editable	Notes
player	integer	no	Owner slot. Handed as a world.Player.
unit	integer	no	Unit id (kept by the upgrade). Handed as a world.Unit.
old_type	string	no	Unit type before. ev.info gives its data.UnitInfo.
new_type	string	no	Unit type after. ev.info gives its data.UnitInfo.

upgrade.buying

This player buys an upgrade other than a king upgrade, such as Upgrade Supply.

Before and after the game acts (pre=True for before); cancelling needs actions.

Field	Type	Editable	Notes
player	integer	no	This player. Handed as a world.Player.
research	string	no	The game's id for the upgrade (a research id), for example upgrade_supply_research_id.
level	integer	no	Level after the purchase.

wave.ended

The fight of a wave is over and the build phase begins.

Raised after the game acts only (no pre=True); not cancellable.

Field	Type	Editable	Notes
wave	integer	no	The wave that ended. ev.info gives its data.WaveInfo.

wave.started

A new wave number is shown.

Before and after the game acts (pre=True for before); not cancellable.

Field	Type	Editable	Notes
wave	integer	no	Wave number. ev.info gives its data.WaveInfo.

worker.buying

This player trains a worker, or queues one.

Before and after the game acts (pre=True for before); cancelling needs actions.

Field	Type	Editable	Notes
player	integer	no	This player. Handed as a world.Player.
type	string	no	Worker unit type. ev.info gives its data.UnitInfo.
builder	integer	no	The unit that trains it. Handed as a world.Unit.
queued	bool	no	True when put in the queue (bought once affordable).

---

Previous: Events | Next: Incoming network messages