events
Subscribe to what the overlay does: frames, drawing, the menu, setting changes, and (with game data) match changes.
A script can have at most 64 handlers. Handlers run on the thread that draws, inside the time budget (3 ms; see performance). Every handler is removed when the script stops.
The order in one frame is: finished downloads and uploads, timers, tasks, frame handlers, the menu and your tabs, then the overlay (draw handlers and widgets).
Reference#
events.on#since 1.0
events.on(name: string, fn: function): integerSubscribes fn to an event. A bad event name is an error.
| Parameter | Type | Description |
|---|---|---|
name | string | An event name from the list below. |
fn | function | Called with the event's arguments. |
| Returns | Description |
|---|---|
integer | A handler id for events.off. |
local id = events.on("frame", function(dt)
-- runs every frame
end)events.once#since 1.0
events.once(name: string, fn: function): integerLike on, for a handler that should run a single time.
| Parameter | Type | Description |
|---|---|---|
name | string | An event name. |
fn | function | Called once, then removed. |
| Returns | Description |
|---|---|
integer | A handler id. |
events.off#since 1.0
events.off(id: integer): booleanRemoves one handler.
| Parameter | Type | Description |
|---|---|---|
id | integer | An id returned by on or once. |
| Returns | Description |
|---|---|
boolean | true when a handler was removed. |
frame#since 1.0event
events.on("frame", function(dt) end) -- dt: numberEvery frame, before the menu is built. Good for logic that does not draw.
| Parameter | Type | Description |
|---|---|---|
dt | number | Seconds since the previous frame. |
draw#since 1.0event
events.on("draw", function() end)The overlay layer: draw here with the draw functions, in screen coordinates. draw.* is only valid inside this handler, a widget's draw and a ui.canvas callback.
unload#since 1.0event
events.on("unload", function() end)The script is about to go away (switched off, reloaded, removed, or the overlay is closing). It has 25 ms. A script the host has already stopped for misbehaving does not get it. Save what you need; the store is saved afterwards anyway.
settings#since 1.0event
events.on("settings", function(key) end) -- key: stringA value in the script's store changed, by a control with an id or by store.set.
| Parameter | Type | Description |
|---|---|---|
key | string | The store key that changed. |
ingame#since 1.0event
events.on("ingame", function(in_game) end) -- in_game: booleanThe player entered or left a match. Fires on the change only, not when the script loads: read data.snapshot().in_game on your first frame for the starting state.
| Parameter | Type | Description |
|---|---|---|
in_game | boolean | Whether a match is loaded. |
map#since 1.0event
events.on("map", function(name) end) -- name: stringA different map was loaded. Fires on the change only; data.snapshot().map has the current one.
| Parameter | Type | Description |
|---|---|---|
name | string | The map name, for example de_mirage. |
bomb#since 1.0event
events.on("bomb", function(state) end) -- state: stringThe bomb was planted, or is no longer planted (exploded, defused or the round ended).
| Parameter | Type | Description |
|---|---|---|
state | string | "planted" or "gone". |
media_track#since 1.0event
events.on("media_track", function(track) end) -- track: tableThe system's media session changed track. See media.
| Parameter | Type | Description |
|---|---|---|
track | table | {title, artist, app, duration} of the new track. |
Example#
Several events in one script:
events.on("frame", function(dt) end)
events.on("map", function(name) log.info("map: " .. name) end)
events.on("unload", function() log.info("bye") end)