Callback functions

clear_callback

documented onlysource

Create three explosions and then clear the interval

local count = 0 -- this upvalues to the interval
set_interval(function()
  count = count + 1
  spawn(ENT_TYPE.FX_EXPLOSION, 0, 0, LAYER.FRONT, 0, 0)
  if count >= 3 then
    -- calling this without parameters clears the callback that's calling it
    clear_callback()
  end
end, 60)

function clear_callback(id: CallbackId?)

id: CallbackId?

Clear previously added callback id or call without arguments inside any callback to clear that callback after it returns.

clear_screen_callback

source

function clear_screen_callback(screen_id: integer, cb_id: CallbackId)

screen_id: integer
cb_id: CallbackId

Clears a callback that is specific to a screen.

clear_vanilla_sound_callback

source

function clear_vanilla_sound_callback(id: CallbackId)

id: CallbackId

Clears a previously set callback

set_callback

source

function set_callback(cb: function, event: ON): CallbackId

cb: function: The signature depends on the ON value passed.
event: ON

Returns CallbackId

Returns unique id for the callback to be used in clear_callback. Add global callback function to be called on an event.

set_global_interval

source

function set_global_interval(cb: fun(): boolean, frames: integer): CallbackId

cb: fun(): boolean: Returning nil (or nothing): treated as true.
frames: integer

Returns CallbackId

Returns unique id for the callback to be used in clear_callback. You can also return false from your function to clear the callback. Add global callback function to be called every frames engine frames. This timer is never paused or cleared.

set_global_timeout

source

function set_global_timeout(cb: fun(), frames: integer): CallbackId

cb: fun()
frames: integer

Returns CallbackId

Returns unique id for the callback to be used in clear_callback. Add global callback function to be called after frames engine frames. This timer is never paused or cleared.

set_interval

source

Create three explosions and then clear the interval

local count = 0 -- this upvalues to the interval
set_interval(function()
  count = count + 1
  spawn(ENT_TYPE.FX_EXPLOSION, 0, 0, LAYER.FRONT, 0, 0)
  if count >= 3 then
    -- calling this without parameters clears the fallback that's calling it
    clear_callback()
  end
end, 60)

function set_interval(cb: fun(): boolean, frames: integer): CallbackId

cb: fun(): boolean: Returning nil (or nothing): treated as true.
frames: integer

Returns CallbackId

Returns unique id for the callback to be used in clear_callback. You can also return false from your function to clear the callback. Add per level callback function to be called every frames engine frames Ex. frames = 100 - will call the function on 100th frame from this point. This might differ in the exact timing of first frame depending as in what part of the frame you call this function or even be one frame off if called right before the time_level variable is updated If you require precise timing, choose the start of your interval in one of those safe callbacks: The SCREEN callbacks: from ON.LOGO to ON.ONLINE_LOBBY or custom callbacks ON.FRAME, ON.SCREEN, ON.START, ON.LOADING, ON.RESET, ON.POST_UPDATE Timer is paused on pause and cleared on level transition.

set_on_player_instagib

source

function set_on_player_instagib(uid: integer, fun: fun(victim: Entity?): boolean): CallbackId?

uid: integer
fun: fun(victim: Entity?): boolean: Returning nil (or nothing): treated as false.

Returns CallbackId? (may be nil)

Returns unique id for the callback to be used in clear_callback or nil if uid is not valid. Sets a callback that is called right when an player/hired hand is crushed/insta-gibbed, return true to skip the game's crush handling. The game's instagib function will be forcibly executed (regardless of whatever you return in the callback) when the entity's health is zero. This is so that when the entity dies (from other causes), the death screen still gets shown. Use this only when no other approach works, this call can be expensive if overused.
The callback signature is bool on_player_instagib(Entity self)

set_post_entity_spawn

source

function set_post_entity_spawn(cb: fun(entity: Entity?, spawn_type_flags: integer), flags: SPAWN_TYPE, mask: MASK, ...: any): CallbackId

cb: fun(entity: Entity?, spawn_type_flags: integer)
flags: SPAWN_TYPE
mask: MASK
...: any

Returns CallbackId

Add a callback for a spawn of specific entity types or mask. Set mask to MASK.ANY to ignore that. This is run right after the entity is spawned but before and particular properties are changed, e.g. owner or velocity.
The callback signature is nil post_entity_spawn(Entity ent, SPAWN_TYPE spawn_flags)

set_post_render_screen

source

function set_post_render_screen(screen_id: integer, fun: fun(p1: Screen?, p2: VanillaRenderContext)): CallbackId?

screen_id: integer
fun: fun(p1: Screen?, p2: VanillaRenderContext)

Returns CallbackId? (may be nil)

Returns unique id for the callback to be used in clear_screen_callback or nil if screen_id is not valid. Sets a callback that is called right after the screen is drawn.
The callback signature is nil render_screen(Screen self, VanillaRenderContext render_ctx)

set_pre_entity_spawn

source

function set_pre_entity_spawn(cb: fun(entity_type: integer, x: number, y: number, layer: integer, overlay: Entity?, spawn_type_flags: integer): integer, flags: SPAWN_TYPE, mask: MASK, ...: any): CallbackId

cb: fun(entity_type: integer, x: number, y: number, layer: integer, overlay: Entity?, spawn_type_flags: integer): integer: Returning nil (or nothing): no override: the C++ side keeps its default.
flags: SPAWN_TYPE
mask: MASK
...: any

Returns CallbackId

Add a callback for a spawn of specific entity types or mask. Set mask to MASK.ANY to ignore that. This is run before the entity is spawned, spawn your own entity and return its uid to replace the intended spawn. In many cases replacing the intended entity won't have the intended effect or will even break the game, so use only if you really know what you're doing.
The callback signature is optional pre_entity_spawn(ENT_TYPE entity_type, float x, float y, int layer, Entity overlay_entity, SPAWN_TYPE spawn_flags)

set_pre_render_screen

source

function set_pre_render_screen(screen_id: integer, fun: fun(p1: Screen?, p2: VanillaRenderContext): boolean): CallbackId?

screen_id: integer
fun: fun(p1: Screen?, p2: VanillaRenderContext): boolean: Returning nil (or nothing): treated as false.

Returns CallbackId? (may be nil)

Returns unique id for the callback to be used in clear_screen_callback or nil if screen_id is not valid. Sets a callback that is called right before the screen is drawn, return true to skip the default rendering.
The callback signature is bool render_screen(Screen self, VanillaRenderContext render_ctx)

set_timeout

source

function set_timeout(cb: fun(), frames: integer): CallbackId

cb: fun()
frames: integer

Returns CallbackId

Returns unique id for the callback to be used in clear_callback. Add per level callback function to be called after frames engine frames. Timer is paused on pause and cleared on level transition.

set_vanilla_sound_callback

source

function set_vanilla_sound_callback(name: VANILLA_SOUND, types: VANILLA_SOUND_CALLBACK_TYPE, cb: fun(p1: PlayingSound, p2: PlayingSound)): CallbackId

name: VANILLA_SOUND
types: VANILLA_SOUND_CALLBACK_TYPE
cb: fun(p1: PlayingSound, p2: PlayingSound)

Returns CallbackId

Returns unique id for the callback to be used in clear_vanilla_sound_callback. Sets a callback for a vanilla sound which lets you hook creation or playing events of that sound Callbacks are executed on another thread, so avoid touching any global state, only the local Lua state is protected If you set such a callback and then play the same sound yourself you have to wait until receiving the STARTED event before changing any properties on the sound. Otherwise you may cause a deadlock.
The callback signature is nil on_vanilla_sound(PlayingSound sound)