API reference
Opusbot exposes two layers:
- Namespaced modules (preferred for scripts / ZeroBot ports):
Game,Player,Map, … - Flat natives (lower-level; used by the compat layer and advanced scripts)
Unless noted, return values match ZeroBot-style expectations. Missing or not-yet-wired features return safe defaults (nil, false, 0, empty tables) rather than crashing.
Game
| Function | Description |
|---|---|
Game.talk(text[, talkType]) | Say / whisper / yell (default say) |
Game.talkPrivate(text, name) | Private message (args: text, name — ZeroBot order) |
Game.getItemCount(itemId) | Count item id across open containers |
Game.equipItem(itemId, slot) | Equip item into CIPSOFT slot 1–10 |
Game.useItem(itemId) | Hotkey-style use (potions, food, …) |
Game.useItemOnGround(id, x, y, z) | Use item on map tile |
Game.useItemOnCreature(id, creatureId) | Use item on creature |
Game.useItemWithCreature(id, creatureId) | Alias of use-on-creature |
Game.useItemFromGround(x, y, z) | Use top thing on tile |
Game.closeImbuementWindow() | Close imbuement dialog |
Game.registerEvent(event, fn) | Multi-listener register (see Events) |
Game.unregisterEvent(event[, fn]) | Unregister one or all listeners for event |
Game.Events constants: TEXT_MESSAGE, MODAL_WINDOW, TALK, LABEL, CREATURE_APPEAR, CONTAINER_OPEN, CONTAINER_CLOSE, LEVEL_UP, PLAYER_STAT_CHANGE, IMBUEMENT_OPEN_WINDOW, plus reserved keys (MAGIC_EFFECT, HUD_CLICK, …) that accept registration safely even when dispatch is not fully wired yet.
Player
| Function | Returns |
|---|---|
Player.getName() | string |
Player.getId() | number (creature id) |
Player.getHealthPercent() | 0–100 |
Player.getManaPercent() | 0–100 |
Player.getState() | condition bitmask |
Player.getPosition() | {x,y,z} (camera / self) |
Player.getVocation() | vocation id or nil |
Player.getContainers() | open container ids |
Player.getInventorySlot(slot) | {id, count} or nil (slot 1–10) |
Player.getDusts() | exaltation dust balance (number) |
Player.getDustsMaximum() | dust max |
Player.getTotalGoldBalance() | total gold (number) |
Player.getBankGoldBalance() | bank gold |
Player.getInventoryGoldBalance() | inventory gold |
Player.getBlessingState() / getBlessings() | 0 none · 1 partial · 2 full |
:::tip Inventory at login
Equipment slots update when the client receives set/delete inventory. If a slot is empty/nil right after login, open a container or re-equip once so the store fills.
:::
Map
| Function | Description |
|---|---|
Map.getCameraPosition() | {x,y,z} |
Map.getCreatureIds([monsters][, players]) | id list (defaults: monsters true, players false depending on call) |
Map.getThings(x, y, z) | top-level things / object ids on tile |
Map.getTiles() | best-effort tile helper |
Map.isTileWalkable(x, y, z) | bool |
Map.goTo(x, y, z) | walk via client pathfinder |
Client
| Function | Description |
|---|---|
Client.isConnected() | in game / storage present |
Client.getLatency() / getServerLatency() | ms (client FPS/latency indicator) |
Client.isTradeShopOpen() | NPC trade window open |
Client.sendHotkey(qtKey[, qtModifiers]) | Qt key event (queued to GUI thread) |
Client.showMessage(msg) | toast via ClientStatus (native/QML) + print |
Client.XLog(...) | debug log line |
Client.getAllItems() | {id, flags, name[, marketData.marketName]} from AppearanceDb (names: market → dat → item_names / Look cache) |
Client.getItemName(id) | live display name (picks up Look-learned fills after getAllItems cache) |
Client.isKeyPressed(...) | always false (pending) |
Client.flashWindow() | no-op |
Client.getGameWindowDimensions() | {width=0,height=0} pending |
Common hotkey: Client.sendHotkey(16777220, 0) — Qt Return / Enter (used by many death-respawn scripts).
Engine (modules + scripts)
| Function | Description |
|---|---|
Engine.enableCaveBot(on) / isCaveBotEnabled() | Cavebot module |
Engine.enableHealing(on) / isHealingEnabled() | Healing |
Engine.enableTargeting(on) / isTargetingEnabled() | Targeting (enabled setting) |
Engine.enableMagicShooter(on) / isMagicShooterEnabled() | Spell shooter |
Engine.enableEquipment(on) / isEquipmentEnabled() | Equipment |
Engine.isReconnectEnabled() | Auto-reconnect |
Engine.loadScript / unloadScript / reloadScript / isScriptLoaded | Script loader |
Engine.getBotVersion() | "opusbot" |
Engine.enableBot(on) / isBotEnabled() | master pause/restore of major modules |
Engine.getScriptsDirectory() | from setting scripts_dir |
Profile / niche helpers exist as safe no-ops or "default" return values so large community scripts do not error on missing APIs.
CaveBot
| Function | Description |
|---|---|
CaveBot.pause() / resume() | toggle cave_enabled |
CaveBot.GoTo(label) or GoTo(x,y,z) | jump label or walk |
CaveBot.addWaypoint(type, x, y, z) | append waypoint |
CaveBot.insertWaypoint / replaceWaypoint / deleteWaypoint / clearWaypoints | edit route |
CaveBot.selectWaypoint(id) | start at index |
CaveBot.getSelectedWaypointId() | current index |
CaveBot.getWaypointDataById(id) | from JSON snapshot |
CaveBot.setWalkMode(mode) | SMART/MAP_CLICK=pathfinder; ARROW_KEYS=naive |
CaveBot.addSpecialArea(type, …) | AVOID(0) forces Opus A* (client PF can't see boxes); STAND(1) soft-prefers; other ints → AVOID |
CaveBot.setAlarm(…) | typed Enums.AlarmType → AlarmModule detectors (flash/sound/Game.Events.ALARM) |
All ZeroBot Enums.AlarmType values (0–16) enable live detectors. DETECTED/ON_SCREEN pairs share the same screen-range scan (alarm_player_range, default 7). PLAYER_ATTACK is best-effort (player ≤2 sqm + HP drop). GM_DETECTED matches name prefixes (alarm_gm_prefixes, default gm ,cm ,god ,tutor). PLAYER_IDLE uses alarm_idle_sec (default 60).
Waypoint type strings include: node, stand, walk, use, ladder, rope, hole, door, label, …
Spells
| Function | Description |
|---|---|
Spells.getIdByWords(words) | catalog lookup |
Spells.getIdByName(name) | best-effort same catalog |
Spells.isInCooldown(id) | bool |
Spells.getLeftCooldownTime(id) | remaining ms |
Spells.groupIsInCooldown(groupId) | group CD |
Also: flat cast(words[, talkType]), spellCd(words), spellCdMs(words).
Npc / Inventory
| Function | Description |
|---|---|
Npc.buy(id, amount) | buy offer |
Npc.sell(id, amount) | sell offer |
Inventory.lookAt(slot) | look equipment slot |
Inventory.pickItemImbuement(slot) | imbuement pick |
Flat helpers: npcTalk, npcCloseTrade, lookNpcTradeItem, closeContainer.
Timer
local t = Timer.new("name", function()
-- body
end, 1000, true) -- interval ms, repeating (default true)
t:stop()
destroyTimer("name")
Low-level: setTimeout(ms, fn), setInterval(ms, fn), clearTimer(id).
Creature / Container objects
local c = Creature.new(creatureId)
c:getId()
c:getName()
c:getHealthPercent()
c:getPosition()
c:getType() -- Enums.CreatureTypes.*
local bag = Container.new(containerId)
-- methods over getContainerData / items (see runtime)
Flat helpers: getCreatureData(id), getOpenContainerIds(), getContainerItems(cid), findItemInContainers(itemId), getContainerData(cid).
Enums (selected)
Enums.InventorySlot.CONST_SLOT_ARMOR -- 4
Enums.TalkTypes.TALKTYPE_SAY -- 1
Enums.Directions.NORTH -- 0
Enums.CreatureTypes.CREATURETYPE_MONSTER
Enums.MessageTypes.MESSAGE_EVENT_ADVANCE -- verify against live log
Enums.SpellGroups.SPELLGROUP_HEALING
Enums.States.STATE_HASTE
Enums.WaypointType.WAYPOINT_TYPE_NODE -- "node"
:::warning MessageTypes
Numeric message types can be client-version dependent. Prefer matching on eventText.text when possible, or calibrate against the bot log line TEXT_MESSAGE type=….
:::
JSON / string / table helpers
JSON.encode(value)/JSON.decode(str)string.starts,string.trim,string.split, …table.includes,table.find,table.map,table.filter,table.merge, …bit/bit32via Lua 5.4 operators
Flat utility natives (selection)
| Native | Description |
|---|---|
print(msg) | bot log |
getTick() | GetTickCount64() ms |
getTime() | unix seconds (float) |
wait(ms) | sleep |
getHp / getMana | percents |
isOnline / isPz | state |
attack / stopAttack / setTarget / clearTarget | combat |
follow / turn / walk / goTo | movement |
useItem / useOnCreature / useOnTile / useRuneOnTile | items |
equipItem / moveItem / quickLoot | inventory |
getSetting / setSetting (+ Int/Bool) | settings |
Storage.get / set / save / load | script storage |
enableCaveBot / enableHealing / … | module toggles |
hudCreate / hudSetText / … | raw HUD (prefer HUD.*) |
HotkeyManager
HotkeyManager.keyMapping maps names ("F1", "A", "Escape", …) to Windows virtual-key codes for scripts that build key tables. Delivery still goes through Client.sendHotkey with Qt key codes when using the client input path.