API documentation

Put your .lua files in this folder. They show up in the Scripts window (with an editor and console), and you run them with one click. Errors land in the console, not in a crash.

-- my_script.lua — runs every time you click it in the Scripts window
local x, y, z = zorbitGetPos()
zorbitLog("hello from " .. x .. "," .. y .. "," .. z)

Enables or disables one engine toggle. Returns true if the name is valid.

zorbitSetToggle("heal", true)   -- enable the Healbot engine
zorbitSetToggle("cavebot", false) -- stop walking the route

Reads a toggle's current state. Returns true or false.

if zorbitGetToggle("alarm") then zorbitLog("alarms are on") end

Returns the engine's status line — the same text the UI shows.

The master switch — turns the whole bot engine on or off at once.

Returns your position as three values. When offline you get 0, 0, 0.

local x, y, z = zorbitGetPos()
zorbitLog("pos: " .. x .. "," .. y .. "," .. z)

Profiles are numbered sets of settings (rules, waypoints, priorities). zorbitGetProfile() returns the active number, zorbitSetProfile(n) switches to profile n (1-based).

-- swap to the second profile for a different hunt spot
zorbitSetProfile(2)

The name of the player the Follow module walks after.

Cavebot runtime state — which waypoint is active, whether the bot is walking or on a delay.

A comma-separated list of creature names — the bot attacks in this order. Unknown names fall last.

zorbitSetTargetPriority("Demon, Dragon Lord, Dragon")

Refreshed every engine tick. Use them directly — if hp < 50 then ... end.

Each returns true/false — perfect for alarms and auto-reactions in your scripts.

-- refresh haste whenever it drops
macro(500, "autoHaste", function()
  if hpercent > 80 and not hasHaste() then
    say("utani hur")
  end
end)

Returns every creature visible around you — players, monsters and NPCs included.

-- warn when an unknown player walks into your screen
macro(1000, "playerWatch", function()
  for _, c in ipairs(getSpectators()) do
    if c:isPlayer() and not c:isLocalPlayer() then
      zorbitLog("player nearby: " .. c:getName())
    end
  end
end)

Look up a specific creature by name or id, and measure distances between two positions.

Methods available on any creature you hold.

Find an item anywhere in open containers, or read a specific equipment slot. findItem(itemId) returns an item you can pass to use / usewith.

List every open container (or a specific one by index) and read your money pouch.

-- count strong health potions across all open backpacks
local function countPot(id)
  local n = 0
  for _, c in ipairs(getContainers()) do
    for _, it in ipairs(c:getItems()) do
      if it:getId() == id then n = n + it:getCount() end
    end
  end
  return n
end
zorbitLog("SHP left: " .. countPot(236))

Move an item into a specific equipment slot — e.g. swap amulets, rings or the ammo slot.

Equipment slots usable with getInventoryItem / moveToSlot.

Walk somewhere with the client's pathfinder, or plan first and decide later. findAllPaths returns several alternatives; translateEveryPathToPath / translateAllPathsToPath normalize path formats.

-- walk to the depot one screen away
autoWalk({ x = posx + 8, y = posy - 6, z = posz })

Turn your character in place without stepping.

Numeric directions for turn, direction fields and path steps.

For deeper checks, the client's map module is available: g_map.getTile(pos) (then tile:getThings(), tile:getTopCreature(), tile:isWalkable()) and g_map.isSightClear(from, to) to see if a straight shot is unobstructed.

say(text) speaks on the default channel; saySpell(text) is the spell-flavored variant that respects the spell timeout.

Use an item, use it on a target, or throw a rune at a creature.

-- emergency SMP from the script layer
local smp = findItem(237)
if smp then use(smp) end

-- throw an SD at your current target
useRune(3155, target)

Combat control — attack a creature, follow a player, and cancel either or both.

Leave the game when you decide to — safeLogout waits for a safe moment, canLogout tells you whether the server allows it right now.

Save a screenshot of the client window — nice for level-up moments or evidence after a bug.

macro(timeout, name, fn) runs fn every timeout ms — the heartbeat of most scripts (it also appears on the dashboard as a toggleable hotkey entry). schedule(ms, fn) fires once. removeEvent cancels a scheduled event.

-- every 2 s: log stamina drops below 14 h
macro(2000, "staminaWatch", function()
  if stamina > 0 and stamina < 14 * 3600 then
    zorbitLog("stamina low!")
  end
end)

delay(ms) sleeps the current coroutine, now() / time() give you current engine and wall-clock timestamps.

Register your own hotkeys inside the bot's hotkey panel: hotkey(text, fn) adds a switch, singlehotkey fires once per press, listen taps chat lines.

storage is a free-form Lua table that survives script restarts and is autosaved with the bot config. Call saveConfig() to force a save.

-- remember the last deposit position between sessions
storage = storage or {}
storage.lastDepot = storage.lastDepot or { x = 0, y = 0, z = 0 }
zorbitLog("last depot: " .. storage.lastDepot.x)

The bot's own session key–value store — values live in memory for the current session only.

Key–value pairs persisted with the bot settings — a permanent place for your script's options.

Adds a spell rule for kind "heal" or "mana". The spell fires when HP (or MP) drops below maxPct; minPct is the lower band edge. Cooldown is in milliseconds (default 1000).

zorbitAddRule("heal", 0, 70, "exura gran mas res", 1000)
zorbitAddRule("mana", 0, 60, "utani gran hur", 1000)

Read or clear the band rules for "heal" / "mana". zorbitGetRules returns one rule per line, e.g. 0-70%: exura gran mas res.

The full priority list behind the Healbot window — one row per line, in priority order (line 1 fires first). Each row: trig|mode|value|kind|action|cooldown|manaCost, where trig is hp|mp, mode is b (below) or a (above), kind is spell|item, and action is the spell words or the item id.

-- hp below 70% → cast exura gran mas res (1 s cooldown, 20 mana)
local rows = "hp|b|70|spell|exura gran mas res|1000|20\n" ..
             "hp|b|50|item|266|1000|0"
zorbitHealSetRules(rows)

Appends a waypoint to the active profile. Returns false for invalid arguments (e.g. a 0,0,0 position).

local x, y, z = zorbitGetPos()
zorbitAddWaypoint("node", x, y, z)
zorbitAddWaypoint("stand", x + 3, y, z)
zorbitAddWaypoint("say", 0, 0, 0, "hi")
zorbitAddWaypoint("delay", 2000)

zorbitGetWaypoints() returns a numbered list, one waypoint per line ("1. Stand 32310,32220,7"). zorbitClearWaypoints() empties the route and resets the cavebot index.

Manage the loot ID list. IDs come back as a comma-separated string.

zorbitAddLootId(3031) -- gold coin
zorbitAddLootId(3035) -- platinum coin

Returns the state of every alarm as rows of key|on|param — handy to snapshot and restore configurations.

Sets one alarm. Important: pass on as a number (1/0), not a boolean. The param meaning depends on the alarm (see the table below).

zorbitAlarmSet("hp", 1, 50)   -- low health alarm at 50%
zorbitAlarmSet("posc", 1, 0)  -- player on screen: on

Fires the sound of an alarm right now — useful for custom triggers in your scripts.

Plays the alarm's sound like zorbitAlarmNotify but bypasses the enabled check — handy for testing volumes.

setFriends takes a comma-separated whitelist — names on it are not counted as enemies (the "enemy" alarm ignores them). setCmsg sets the phrase the Custom message alarm watches for in default chat.

zorbitAlarmSetFriends("Tankmaster, Bestfriend")
zorbitAlarmSetCmsg("sell")

Returns every condition as rows of key|on|param|opt — the keys match the Conditions window.

Sets one condition. Pass on as a number (1/0). Valid keys are whatever zorbitCondGet() lists for your version.

Returns the Friend Healer state — rule rows, healing mode and the friends list — as CSV.

Sets one Friend Healer entry (switch, rule parameter or option). Pass on as a number (1/0); keys match zorbitFHGet() output.

Work with files from Documents\ZorbitBot\scripts\: list them, read a source, execute one by name, or open the folder in Explorer.

zorbitExecScript("hunt_rotworms")

Writes a line to the bot log — your best friend while debugging scripts.

Force-save the current profile, reload settings from disk, or open the settings folder in Explorer.

Starts key capture for the settings window's hotkey fields — the next key (or mouse-wheel move, for kind "MW") is recorded; Escape cancels. Normally driven by the settings UI itself.

One call per widget — no layout math. Switches and buttons take callbacks; addTab groups widgets on a named tab.

local extraHeal = false
addSwitch("Extra heal", function(on) extraHeal = on end, false)
addButton("Reset loot list", function()
  zorbitClearLootIds()
  zorbitLog("loot cleared")
end)

setupUI(ui, parent) builds a whole UI from a table definition, importStyle(name) loads an extra OTUI style, and displayGeneralBox pops a Tibia-style message box.

Beyond g_game and g_map, the proxied context exposes g_ui (create widgets), g_keyboard (bind hotkeys), g_settings, g_resources, g_sounds, g_things and modules (all loaded client modules). Power-tools: handle with care and pcall everything.

A hotkey that stops everything and plays the alarm — for when you come back to a surprise.

-- stops the bot and screams when you press the "PANIC" hotkey
singlehotkey("PANIC", function()
  zorbitMasterToggle(false)
  cancelAttackAndFollow()
  zorbitAlarmNotify("gm")
  zorbitLog("PANIC — bot stopped, target cleared")
end)

Counts your potions every 5 s, logs a warning and flashes the taskbar when you run low.

local function countPot(id)
  local n = 0
  for _, c in ipairs(getContainers()) do
    for _, it in ipairs(c:getItems()) do
      if it:getId() == id then n = n + it:getCount() end
    end
  end
  return n
end

macro(5000, "supplyWatch", function()
  if countPot(266) < 10 then
    zorbitLog("LOW SUPPLIES: strong health potions!")
    zorbitAlarmNotify("cap")
  end
end)

Switches to profile 2 (a safe, passive setup) whenever an unknown player appears on screen, and back when the screen is clear.

macro(1500, "safeSpot", function()
  local intruder = false
  for _, c in ipairs(getSpectators()) do
    if c:isPlayer() and not c:isLocalPlayer() then
      intruder = true
      break
    end
  end
  if intruder and zorbitGetProfile() ~= 2 then
    zorbitSetProfile(2)
    zorbitLog("player detected — safe profile ON")
  elseif not intruder and zorbitGetProfile() == 2 then
    zorbitSetProfile(1)
    zorbitLog("screen clear — normal profile ON")
  end
end)