Callbacks

RegistrationCopy Anchor Link

events.render(fn)
events.render(fn, false)
events.player_hurt(fn, enable?)

events.<name>(fn) adds a callback if that function is not already registered for the event. Identity is checked with rawequal, including callbacks disabled by an error. Adding a disabled function again does not re-enable it; reload the script.

events.<name>(fn, false) removes the callback. Only the boolean false removes it; any other second argument adds it. Removal during dispatch is safe and takes effect from the next invocation.

Available built-in events members:

render          resize_window   level_init      level_shutdown
override_view   console_input   shutdown        createmove
frame_stage     key             player_chat     string_cmd

Any other member is looked up as a game event name: events.<event name> is a registrar when the client knows that event and nil otherwise, so events.no_such_event(fn) raises attempt to call field 'no_such_event' (a nil value). There is no events.paint, events.unload or events.game_event.

Registration functions return no values. fn should be a function; callable tables are also supported. nil is accepted at registration but fails on invocation, disabling the callback.

Within a script, callbacks run in registration order. Callbacks added during dispatch begin with the next delivery. Scripts are dispatched in the order they were first loaded in the session. A failing callback is disabled and its return value is ignored.

Callback referenceCopy Anchor Link

renderCopy Anchor Link

events.render(function() end)

Runs once per rendered frame while the frame's draw list is recorded. Return values are ignored. See render for drawing availability.

resize_windowCopy Anchor Link

events.resize_window(function() end)

Runs at the start of a frame if the screen size changed since the previous frame. It does not run on the first frame. Return values are ignored.

keyCopy Anchor Link

events.key(function(vk, pressed) end)

Runs at the start of a frame for each key or mouse-button transition since the previous frame.

• vk: integer Windows virtual-key code.
• pressed: true on press, false on release.

Auto-repeat and keypad Enter are not reported. Mouse and modifier codes are listed under input. Return values are ignored.

frame_stageCopy Anchor Link

events.frame_stage(function(stage) end)

Runs after the game's FrameStageNotify for each stage. stage is an integer; no Lua constants are defined. Return values are ignored.

level_initCopy Anchor Link

events.level_init(function(map) end)

Runs after a map loads. map is the engine's map-name string, or "" if unavailable. Return values are ignored.

level_shutdownCopy Anchor Link

events.level_shutdown(function() end)

Runs once when leaving a map or changing maps. If no shutdown was delivered, it runs immediately before the next level_init. Return values are ignored.

Map transitions are tracked only while at least one script listens to level_init or level_shutdown. A script loaded during a map does not receive level_init for that map, but receives level_shutdown when it ends.

override_viewCopy Anchor Link

events.override_view(function(view) end)

Runs each frame after the game sets up the view and before rendering. The argument is a mutable view_setup. Return values are ignored.

createmoveCopy Anchor Link

events.createmove(function(cmd) end)

Runs once per command after it is closed, before it is sent. cmd is a read-only user_cmd_t snapshot. Scripts cannot change the real command's movement, buttons or angles.

Return values are ignored. Callback execution delays sending the frame's commands.

console_inputCopy Anchor Link

events.console_input(function(text) end)

Runs before a client console command executes, including typed commands. text is a string.

Return false to block the command. Any other return value allows it. All callbacks run even if an earlier callback blocks the command.

string_cmdCopy Anchor Link

events.string_cmd(function(text) end)

Runs before text is inserted into the command buffer, including commands sent through console.execute. Every callback receives the original text, not the previous callback's replacement.

Replacement text is sent without quoting, escaping or filtering.

Commands sent from inside either console_input or string_cmd bypass both callbacks to prevent recursive dispatch.

player_chatCopy Anchor Link

events.player_chat(function(msg) end)

Runs before a message appears in HUD chat. msg is a mutable chat_message_t.

Return false to hide the message. All callbacks still run. Other return values have no effect.

shutdownCopy Anchor Link

events.shutdown(function() end)

Runs on unload, reload and delete, before the script's UI is removed. Also runs for callbacks registered before a load-time failure. Return values are ignored.

Game eventsCopy Anchor Link

events.player_hurt(function(event) end)
events.player_hurt(fn, false)

events.<event name>(fn, enable?) registers a listener for a game event, with the same add and remove rules as the built-in members. The name is checked against the client's game-event descriptors when the member is read: a known name returns a registrar, an unknown one returns nil. Names match case-insensitively; events.Player_Hurt and events.player_hurt are the same registration.

Runs when the client fires or receives the named event, including events the client raises itself (for example item_pickup_failed), once per event. The argument is a gameevent, valid only during the callback. Return values are ignored.

Registration does not subscribe the engine to new events. Only events already listened to by the game or NIXWARE are delivered.

Frame orderCopy Anchor Link

For each script, a rendered frame processes:

1. resize_window, if needed.
2. All pending key transitions.
3. Due timers.
4. Script UI: hotkeys, on_change, visibility and disabled predicates, removals.
5. render callbacks.
6. A pending utils.unload_script() request.

The Scripts tab then processes queued load, unload and reload actions. Scripts loaded through the tab receive their first callbacks on the next frame.