Getting started

Callbacks

The global functions the game calls in your plugin.

The main file runs once when the plugin starts. To react to the game afterwards, it defines callbacks: global functions with these names. Define only the ones you need; a callback that isn't defined costs nothing.

on_tick()
Every game tick. Game logic goes here.
on_render()
Every frame. The only place where ui, gfx and gfx3d work; calling them anywhere else is an error.
on_map_load(map_id)
A map finished loading. content.map(map_id) describes it.
on_message(timestamp, channel, text)
A chat message arrived. channel is one of the chat channel constants, such as chat.LOCAL.
on_damage(event)
Damage was dealt nearby, by anyone to anyone. event is {source_agent_id, target_agent_id, skill_id, damage, damage_absorbed, flags}. This can fire many times a second in a fight.
on_create_buff(event)
A boon, condition or effect was applied nearby. event is {id, source_agent_id, target_agent_id, skill_id, duration, active}.
on_key_pressed(key)boolean
A key was pressed. key is a Windows virtual-key code (0x41 is A, 0x77 is F8); input.key_name(key) names it. Return true to keep the key from the game.
on_keydown(key)boolean
A key went down. Return true to keep it from the game.
on_keyup(key)boolean
A key came up. Return true to keep it from the game.
on_lose_window_focus()
The game window lost focus. Key-up events don't arrive while the game is in the background, so forget any keys you think are held.
on_plugin_event(name, data)
Another plugin sent an event with plugins.emit. data is a string.
on_trading_post_query(result)
The answer to a trading_post.query(item_id): {item_id, min_price, buys, sells}, where buys and sells are lists of {price, quantity}.
on_stop(reason)
The plugin is stopping. reason is "stopped" (stopped by the user), "reload", "error" (it failed), "removed" (its folder went away) or "shutdown" (the game is closing). Undo game settings you changed here; settings are saved once more after it returns.

A small example

local count = 0

function on_tick()
    count = count + 1
end

function on_render()
    ui.begin_window("Hello")
    ui.text("Ticks: " .. count)
    if ui.button("Say hi") then
        chat.send(chat.LOCAL, "hi")
    end
    ui.end_window()
end
Callbacks are plain function calls: they can't wait. To do something over time from a callback, start a task with spawn. See Tasks and wait.
PreviousYour first plugin