An event calls one of your functions when something happens: someone speaks in chat, an effect shows on the screen, you press a key, the CaveBot reaches a label. This way the script reacts right away, without checking in a loop.

How to register#

Game.registerEvent(event, function) binds the function to the event and returns the function itself. Game.unregisterEvent(event, function) unbinds it. Keep the function in a variable if you want to unbind it later. A script can have several functions on the same event: all of them are called, in the order they were registered.

-- Registers, uses and unbinds an event
local function onTalk(name, level, mode, x, y, z, text)
  print(name .. ": " .. text)
end

Game.registerEvent(Game.Events.TALK, onTalk)

-- 60 s later, stops listening to the chat
Timer.new("stop", function()
  Game.unregisterEvent(Game.Events.TALK, onTalk)
  destroyTimer("stop")
end, 60000)

-- The same code runs on ZeroBot and on DrenoxBot.
-- Here wait() does not block events: they keep arriving while it waits.
Game.registerEvent(Game.Events.TEXT_MESSAGE, function(msg)
  if msg.messageType == Enums.MessageTypes.MESSAGE_LOOT then
    print(msg.text)
  end
end)

while true do
  wait(1000)
end

How events arrive#

• Each script runs on its own thread. Events go into a queue and run on that thread, one at a time, so two events of the same script never run at the same time.
• The bot only sends an event to a script that has a function registered on it. HUD and window click events go only to the script that created the HUD or the window.
• An error inside the function shows in the Console as event <number>: <error> and the script keeps running.
• wait(ms) does not block events: while the script waits, the queued events and timers keep running.

Summary#

TALK#

Fires for every speech message the server sends: Default, yell, whisper, channels, PMs and NPC speech.

-- Flashes the window when someone says your name
Game.registerEvent(Game.Events.TALK, function(name, level, mode, x, y, z, text)
  if text:lower():find(Player.getName():lower(), 1, true) then
    print(name .. " (" .. level .. "): " .. text)
    Client.flashWindow()
  end
end)

MAGIC_EFFECT#

Fires for each magic effect (not projectile) the server draws on a tile.

-- Shows in the Console the effects around you
Game.registerEvent(Game.Events.MAGIC_EFFECT, function(id, x, y, z)
  local p = Player.getPosition()
  if z == p.z and math.abs(x - p.x) <= 1 and math.abs(y - p.y) <= 1 then
    print("effect " .. id .. " at " .. x .. "," .. y)
  end
end)

HUD_CLICK#

Fires when you click a HUD created by the script. Only the script that owns the HUD receives it. Before the registered functions, the bot calls the HUD's own callback (hud:setCallback), if there is one.

local button = HUD.new(20, 100, "[ CaveBot ]")

Game.registerEvent(Game.Events.HUD_CLICK, function(hudId)
  if hudId == button:getId() then
    Engine.enableCaveBot(not Engine.isCaveBotEnabled())
  end
end)

HOTKEY_SHORTCUT_PRESS#

Fires when a key is pressed (not while it is held) and the client window is in focus. Modifier keys alone (Ctrl, Alt, Shift, Win, Num Lock) do not fire it: they only go into the mask.

local ok, mods, key = HotkeyManager.parseKeyCombination("Ctrl+F5")

Game.registerEvent(Game.Events.HOTKEY_SHORTCUT_PRESS, function(k, m)
  if k == key and bit.band(m, 7) == mods then
    Engine.enableTargeting(not Engine.isTargetingEnabled())
  end
end)

TEXT_MESSAGE#

Fires for every text message from the server: loot, damage, healing, experience, green and red warnings, look.

-- Adds up the damage taken
local total = 0
Game.registerEvent(Game.Events.TEXT_MESSAGE, function(msg)
  if msg.messageType == Enums.MessageTypes.MESSAGE_DAMAGE_RECEIVED then
    total = total + (msg.value or 0)
    print("total damage: " .. total)
  end
end)

MODAL_WINDOW#

Fires when the server opens a window with buttons and choices (NPCs, quests, OT systems). Answer with Game.modalWindowAnswer.

-- Presses "Yes" on every window that has that button
Game.registerEvent(Game.Events.MODAL_WINDOW, function(window)
  for _, b in ipairs(window.buttons) do
    if b.text == "Yes" then
      Game.modalWindowAnswer(window.id, b.id, 0)
    end
  end
end)

CUSTOM_MODAL_WINDOW_BUTTON_CLICK#

Fires when you click a button in a window created by the script with CustomModalWindow. The window closes with the click. Only the owner script receives it, and the window's callback (setCallback) is called first.

local window = CustomModalWindow.new("Refill", "Go back to town?")
window:addButton("Yes")  -- 0
window:addButton("No")  -- 1

Game.registerEvent(Game.Events.CUSTOM_MODAL_WINDOW_BUTTON_CLICK, function(id, button)
  if id == window:getId() and button == 0 then
    CaveBot.GoTo("refill")
  end
end)

QUEST_LOG#

Fires when the server sends the quest list, for example after Game.requestQuestLog().

Game.registerEvent(Game.Events.QUEST_LOG, function(quests)
  for _, q in ipairs(quests) do
    if not q.completed then print("pending: " .. q.name) end
  end
end)
Game.requestQuestLog()

QUEST_LINES#

Fires when the server sends the missions of a quest, for example after Game.requestQuestLines(id).

Game.registerEvent(Game.Events.QUEST_LINES, function(questId, missions)
  for _, m in ipairs(missions) do
    print(m.name .. ": " .. m.description)
  end
end)

DISTANCE_SHOOT_EFFECT#

Fires for each projectile (arrow, rune, distance spell) the server draws.

-- Warns when a projectile lands on your tile
Game.registerEvent(Game.Events.DISTANCE_SHOOT_EFFECT, function(id, fx, fy, fz, tx, ty, tz)
  local p = Player.getPosition()
  if tx == p.x and ty == p.y and tz == p.z then
    print("projectile " .. id .. " on you")
  end
end)

LABEL#

Fires when the CaveBot reaches a Label waypoint, and only if some script has a function registered on this event. The CaveBot pauses before sending the event and stays stopped until a script calls CaveBot.pause(0). If the script that registered the event stops, the pause ends by itself.

-- At label "check": under 50 mana potions, go to label "refill"
Game.registerEvent(Game.Events.LABEL, function(index, label)
  if label == "check" and Game.getItemCount(268) < 50 then -- 268 = mana potion
    CaveBot.GoTo("refill")
  end
  CaveBot.pause(0) -- releases the route
end)

OPEN_STASH#

Fires when the server sends the contents of your stash (supply stash).

Game.registerEvent(Game.Events.OPEN_STASH, function(stash)
  for _, item in ipairs(stash.stashItems) do
    print(item.itemId .. " x" .. item.count)
  end
end)

HUD_DRAG#

Fires when you drop a draggable HUD (hud:setDraggable(true)) of the script at a new position. The HUD's position is already updated when the event arrives.

local hud = HUD.new(20, 60, "Drag me")
hud:setDraggable(true)

Game.registerEvent(Game.Events.HUD_DRAG, function(id, x, y)
  if id == hud:getId() then print("HUD now at " .. x .. ", " .. y) end
end)

ALARM#

Fires together with an alarm from the Tools tab (the same one that shows in the Console as [ALARM]). If alarms are turned off with Engine.allAlarmsEnable(false), the event does not fire either.

Game.registerEvent(Game.Events.ALARM, function(alarmType)
  if alarmType == Enums.AlarmType.PLAYER_ON_SCREEN then
    Engine.enableCaveBot(false)
    Sound.play("alarm.wav", true)
  end
end)

CREATURE_HEALTH#

DrenoxBot extra (does not exist in ZeroBot). Fires when the server sends a creature's new HP.

local hud = HUD.new(20, 60, "Target: -")
Game.registerEvent(Game.Events.CREATURE_HEALTH, function(id, hp)
  if id == Player.getTargetId() then
    hud:setText(Creature.new(id):getName() .. "  " .. hp .. "%")
  end
end)

PLAYER_DATA#

DrenoxBot extra (does not exist in ZeroBot). Fires every time the server sends the packet with your status data (HP, mana, cap, level...).

Game.registerEvent(Game.Events.PLAYER_DATA, function(hp, maxHp, mana, maxMana)
  if hp < maxHp * 0.3 then
    Client.showMessage("Low HP!")
  end
end)

ZeroBot events that do not fire yet#

Game.Events has all of ZeroBot's names, so registering the events below does not raise an error. But DrenoxBot does not fire any of them yet: the function stays registered and is never called.

See also: Scripting and the function reference.