How scripting works

Shrouded Bot exposes the game to Lua as a flat set of global functions — there is nothing to require and no objects to construct. A script is ordinary Lua: it runs once, top to bottom, the moment you start it. To keep doing something on a timer, schedule a function with autoRun; to react to chat, register a handler with foreachMessage; to pause, call sleep. Each script runs in its own isolated Lua state, so one script can never overwrite another's variables.

-- Auto-heal: drink a health potion when HP drops below 60%.
-- Requires an open backpack that contains the potion (item id 266 here).
local HEALTH_POTION = 266

local function heal()
    if getPlayerHppc() < 60 then
        useItemFromOpenContainerOnSelf(HEALTH_POTION)
    end
end

autoRun(500, heal)   -- run heal() about twice per second

Keep scripts lightweight

Reading game state (your position, nearby creatures, the items in a container…) has a cost, and the game can change between two calls. Read what you need once into local variables, act on those values, then let autoRun schedule the next pass — avoid querying the same thing many times inside a tight loop.

Core types

Every signature is annotated with the type of each argument and of the return value. A type shown before the function name is what it returns; NIL in a return type means the value can be absent, so test for it before you use it.

Thing is the common base of Item and Creature, so any function that accepts a Thing also accepts an Item or a Creature. A position is a table with fields x, y and z (the floor; 7 is ground level). While you are offline, position getters return the sentinel x = 65535, y = 65535, z = 255 instead of a real tile, so guard against it.

Working with items

An item can be handled in two ways. Most often you hold an actual Item value — its own type (a Thing) returned by getItems, getInventoryItem, getTopUseItem and similar — and pass it to functions such as moveItem, getItemStackSize, isContainer or open. Other, more convenient functions instead take a numeric item id (the sprite / client id) and find a matching item for you. Those id-based functions usually need the item to be in an open container, which the name makes explicit (...FromOpenContainer...); "inventory" variants search every open backpack, and "equipped" / "slot" functions refer to the ten equipment slots under Constants.

Inventory slots

Slot ids (or the equivalent named globals) used by equipItem, unequip, getInventoryItem, getInventoryItemId and useEquippedItemOnThing.

1	HELMET_SLOT	Helmet / head
2	NECKLACE_SLOT	Amulet / necklace
3	BP_SLOT	Backpack / main container
4	ARMOR_SLOT	Armor
5	LEFT_HAND_SLOT	Left hand (weapon)
6	RIGHT_HAND_SLOT	Right hand (shield)
7	LEGS_SLOT	Legs
8	BOOTS_SLOT	Boots
9	RING_SLOT	Ring
10	AMMO_SLOT	Ammunition / arrow

Directions

Used by move and turn, and returned by getDirection. turn only accepts the four cardinal directions (0–3).

0	DIR_NORTH	North
1	DIR_EAST	East
2	DIR_SOUTH	South
3	DIR_WEST	West
4	DIR_NE	North-east
5	DIR_SE	South-east
6	DIR_SW	South-west
7	DIR_NW	North-west

AOE runes

Area shape passed to useItemOnMostMonsters so the bot can pick the tile that hits the most monsters.

0	RUNE_GFB	Great fireball — large square area
1	RUNE_FIREBALL	Fireball — smaller area

Creature types

Returned by getType; the values come straight from the game-server source.

0	player	Player
1	monster	Monster
2	npc	NPC
3	summon own	Your own summon
4	summon other	Someone else's summon

autoRun($int repetitionDelay, $func scriptFunction)

Repeatedly calls scriptFunction, waiting repetitionDelay milliseconds between runs. The delay is measured from the end of one call to the start of the next, so a slow function does not overlap itself. This is the main way to keep a script alive.

• repetitionDelay $int — milliseconds to wait between calls.
• scriptFunction $func — the function to run each cycle.

local function spamTalk()
    talk("spam")
end

autoRun(2000, spamTalk)   -- say "spam" every 2 seconds

sleep($int milliseconds)

Pauses the current script for the given number of milliseconds, then resumes where it left off. Useful for spacing out actions so they look human and respect game cooldowns.

• milliseconds $int — how long to pause.

talk("hi")
sleep(800)
talk("bye")

foreachMessage($func onMessage)

Registers a handler that runs once for every new message the client receives — chat, server log, combat text and so on. Ideal for chat triggers and alarms.

• onMessage $func — called as onMessage(msg) for each new message.

The msg table passed to your handler has these fields:

• msg.content $str — the message text.
• msg.sender $str or $nil — who sent it.
• msg.level $int or $nil — the sender's level.
• msg.mode $int — the message mode (see the warning below).
• msg.channel $int or $nil — channel id, if the message belongs to one.
• msg.x $int or $nil — x of the message origin.
• msg.y $int or $nil — y of the message origin.
• msg.z $int or $nil — z of the message origin.

-- Sound an alarm when a GM messages you.
local function onMessage(msg)
    if msg.content == "Are you botting?" and msg.sender == "GM Antibot" then
        playSound("botcheck.wav")
        flashWindow()
    end
end

foreachMessage(onMessage)

Mode names (the number is only their position in this list — see the warning):

1. MessageSay
2. MessageWhisper
3. MessageYell
4. PrivateFrom
5. MessagePrivateTo
6. MessageChannelManagement
7. MessageChannel
8. MessageChannelHighlight
9. MessageSpell
10. MessageNpcFrom
11. MessageNpcTo
12. MessageGamemasterBroadcast
13. MessageGamemasterChannel
14. MessageGamemasterPrivateFrom
15. MessageGamemasterPrivateTo
16. MessageLogin
17. MessageWarning
18. MessageGame
19. MessageFailure
20. MessageLook
21. MessageDamageDealed
22. MessageDamageReceived
23. MessageHeal
24. MessageExp
25. MessageDamageOthers
26. MessageHealOthers
27. MessageExpOthers
28. MessageStatus
29. MessageLoot
30. MessageTradeNpc
31. MessageGuild
32. MessagePartyManagement
33. MessageParty
34. MessageBarkLow
35. MessageBarkLoud
36. MessageReport
37. MessageHotkeyUse
38. MessageTutorialHint
39. MessageThankyou
40. MessageMarket
41. MessageMana
42. MessageMonsterYell
43. MessageMonsterSay
44. MessageRed
45. MessageBlue
46. MessageRVRChannel
47. MessageRVRAnswer
48. MessageRVRContinue
49. MessageGameHighlight
50. MessageNpcFromStartBlock

$int nowMs()

Returns a monotonic timestamp in milliseconds. Use it to measure how long something takes or to build your own cooldowns.

Returns $int — milliseconds since an arbitrary fixed point.

local start = nowMs()
someTimeConsumingFunction()
local elapsed = nowMs() - start
print("took " .. elapsed .. " ms")

print($str text)

Writes a line to the bot console. The main tool for debugging scripts and inspecting game state.

• text $str — the text to print.

$int getPlayerHppc()

Your current health as a percentage of your maximum. For example, 700 HP out of 1000 returns 70.

Returns $int — health percentage 0–100 (0 when offline).

$int getHp()

Your current health points.

Returns $int — current HP (0 when offline).

$int getMaxHp()

Your maximum health points.

Returns $int — maximum HP (0 when offline).

$int getPlayerMppc()

Your current mana as a percentage of your maximum. For example, 700 MP out of 1000 returns 70.

Returns $int — mana percentage 0–100 (0 when offline).

$int getMana()

Your current mana points.

Returns $int — current MP (0 when offline).

$int getMaxMana()

Your maximum mana points.

Returns $int — maximum MP (0 when offline).

$bool isHasted()

Whether your character currently has the haste effect.

Returns $bool — true if hasted, otherwise false.

$table{x, y, z} getSelfPosition()

Your character's position as a table. While offline it returns the sentinel x = 65535, y = 65535, z = 255, so check before trusting it.

Returns $table — {x, y, z}; read fields with pos.x, pos.y, pos.z.

local pos = getSelfPosition()
if pos.z ~= 255 then
    print("standing at " .. pos.x .. ", " .. pos.y .. ", " .. pos.z)
end

$str or $nil getSelfName()

Your character's name.

Returns $str — your name, or $nil when offline.

$int getPlayerStates()

Returns all active status effects (poisoned, hasted, in combat, paralyzed…) packed into one integer, where each bit is one state. If only the in-combat bit (value 1) is set the function returns 1; if only the haste bit (value 2) is set it returns 2; with both it returns 3. Prefer playerHasState to test a single state.

Returns $int — bitmask of active states (0 when offline). Bit meanings are server-specific.

$bool playerHasState($int state)

Tests whether a single state bit is active. Pass the value of the bit you care about (for example 2 if haste is bit 2 on your server).

• state $int — the state bit value to test for.

Returns $bool — true if that state is active.

$int getSelfOutfitId()

The looktype id of your character's current outfit.

Returns $int — outfit id (0 when offline).

$int getSoul()

Your current soul points.

Returns $int — soul points (0 when offline).

$int getSkillLevel($int skillId)

The current level of one skill (fist, sword, fishing…). Each skill has a numeric id; fist fighting is usually 1, so getSkillLevel(1) returns the fist level.

• skillId $int — the skill id (server-specific; see the note under Constants).

Returns $int — the skill level (0 when offline).

$int getStamina()

Your stamina, in minutes. For example 42:00 hours is 42 × 60 = 2520.

Returns $int — stamina in minutes.

$int getCapacity()

Your free carrying capacity — how much weight you can still pick up.

Returns $int — free capacity.

$int getExperience()

Your total accumulated experience points.

Returns $int — experience (0 when offline).

$int getItemStackSize($item item)

How many units are in a stack. For example a stack of 100 arrows is one item with a stack size of 100.

• item $item — the item to measure.

Returns $int — number of units in the stack.

$bool isContainer($item item)

Whether an item is itself a container (a bag, backpack, etc.).

• item $item — the item to test.

Returns $bool — true if the item is a container.

$int getInventoryItemId($int itemSlotId)

The item id currently equipped in a given equipment slot.

• itemSlotId $int — an equipment slot (see Inventory slots under Constants).

Returns $int — the equipped item id, or 0 if the slot is empty.

if getInventoryItemId(AMMO_SLOT) == 0 then
    equipItem(AMMO_SLOT, 3447, 100)   -- re-equip arrows
end

$item getInventoryItem($int itemSlotId)

The actual item equipped in a slot, as an Item you can pass to other functions.

• itemSlotId $int — an equipment slot (see Constants).

Returns $item — the equipped item.

equipItem($int itemSlot, $int itemId, $int itemsAmount)

Moves an item from your open containers into an equipment slot. If you own fewer than itemsAmount, whatever is available is equipped.

• itemSlot $int — target slot (see Constants).
• itemId $int — id of the item to equip.
• itemsAmount $int — how many units to equip (for stackables like ammo).

unequip($int itemSlotId)

Moves the item in an equipment slot back into the first open container with room.

• itemSlotId $int — the slot to clear (see Inventory slots under Constants).

$int getItemCount($int itemId)

Total units of an item id visible across all open containers (stack sizes are summed).

• itemId $int — the item id to count.

Returns $int — total count in open containers.

moveItem($item itemToMove, $int x, $int y, $int z)

Moves an item (the whole stack) to a map position.

• itemToMove $item — the item to move.
• x, y, z $int — destination position.

dropItem($int itemId, $int itemCount)

Drops an item from your open containers onto the tile under your character.

• itemId $int — id of the item to drop.
• itemCount $int — how many units to drop (capped at how many you have).

stackItems()

Merges loose stacks of the same stackable item in your open containers into fuller stacks, freeing up slots. Moves one stack per call.

useItem($int itemId)

Uses an item from any of your backpacks by id, even with the backpack closed — it behaves like an 8.0 client hotkey use.

• itemId $int — id of the item to use.

useItem($item item)

Uses a specific item (or other Thing) you already have a reference to.

• item $item — the item to use.

useItemInContainer($int itemId)

Uses the first item with this id found in an open container.

• itemId $int — id of the item to use.

openItemInContainer($int itemId)

Opens the first item with this id found in an open container (for example a bag inside a bag).

• itemId $int — id of the item to open.

usePosition($int x, $int y, $int z)

Uses the top usable item on a map position (open a door, pull a lever, etc.).

• x, y, z $int — the position to use.

useNearbyGroundItem($int groundItemId)

Uses a ground item with this id if it is within 1 sqm of your character.

• groundItemId $int — id of the ground item to use.

$bool moveItemToContainerWithId($int containerId, $int movedItemId)

Moves an item with id movedItemId into an open container identified by its own item id containerId.

• containerId $int — item id of the destination container.
• movedItemId $int — id of the item to move.

Returns $bool — true if a matching item and container were found and a move was attempted.

$bool useInventoryItemOnNearbyGroundItem($int itemFromInventoryId, $int groundItemId)

Uses an item from your backpacks (by id) on a ground item within 1 sqm — like a "use with" from inventory onto a nearby tile. Stops after the first match.

• itemFromInventoryId $int — id of the item to use.
• groundItemId $int — id of the nearby ground item to target.

Returns $bool — true if a matching pair was found and the use was attempted.

useInventoryItemOnNearbyGroundItems($int itemFromInventoryId, $int groundItemId)

Like useInventoryItemOnNearbyGroundItem, but applies to every matching ground item within 1 sqm instead of stopping at the first.

• itemFromInventoryId $int — id of the item to use.
• groundItemId $int — id of the nearby ground items to target.

$bool useItemFromOpenContainerOnNearbyGroundItem($int itemFromInventoryId, $int groundItemId)

Same as useInventoryItemOnNearbyGroundItem but requires the item to be in an open container. Use this when the inventory variant does not work on your server.

• itemFromInventoryId $int — id of the item to use (must be in an open container).
• groundItemId $int — id of the nearby ground item to target.

Returns $bool — true if a matching pair was found and the use was attempted.

useItemFromOpenContainerOnNearbyGroundItems($int itemFromInventoryId, $int groundItemId)

Like useItemFromOpenContainerOnNearbyGroundItem, but applies to every matching ground item within 1 sqm.

• itemFromInventoryId $int — id of the item to use (must be in an open container).
• groundItemId $int — id of the nearby ground items to target.

useInventoryItemOnThing($int itemId, $thing thing)

Uses an item from your backpacks (by id) on a specific Thing — a creature or an item.

• itemId $int — id of the item to use.
• thing $thing — the target creature or item.

useItemFromOpenContainerOnThing($int itemId, $thing thing)

Same as useInventoryItemOnThing but requires the item to be in an open container (equivalent to "use with" from a backpack onto the target).

• itemId $int — id of the item to use (must be in an open container).
• thing $thing — the target creature or item.

useItemWithSubtypeFromOpenContainerOnThing($int itemId, $int subtype, $thing thing)

Like useItemFromOpenContainerOnThing, but only picks an item whose subtype matches — useful when several items share an id but differ by subtype (e.g. fluids).

• itemId $int — id of the item to use (must be in an open container).
• subtype $int — the required subtype / fluid id.
• thing $thing — the target creature or item.

useItemFromOpenContainerOnSelf($int itemId)

Uses an item from an open container on your own character (e.g. drink a potion).

• itemId $int — id of the item to use (must be in an open container).

useItemFromOpenContainerOnPosition($int itemId, $int x, $int y, $int z)

Uses an item from an open container on a map position.

• itemId $int — id of the item to use (must be in an open container).
• x, y, z $int — the target position.

useItemWithSubtypeFromOpenContainerOnSelf($int itemId, $int subtype)

Uses an item of a specific subtype from an open container on yourself. On some servers mana fluid and life fluid share an item id and differ only by subtype, so matching the subtype stops the bot from trying to use empty vials.

• itemId $int — id of the item to use (must be in an open container).
• subtype $int — the required subtype / fluid id.

useManafluidOnSelf()

Uses a mana fluid from your backpack on yourself (as if you clicked "use with" on your character). Supports the 7.4 and 8.0 mana-fluid subtypes only.

useLifefluidOnSelf()

Uses a life fluid from your backpack on yourself. Supports the 7.4 and 8.0 life-fluid subtypes only.

useInventoryItemOnInventoryItem($int itemFromInventoryId, $int otherInventoryItemId)

Uses one backpack item (by id) on another backpack item (by id) in any open container.

• itemFromInventoryId $int — id of the item to use.
• otherInventoryItemId $int — id of the target item in an open backpack.

useInventoryItemOnInventoryItem2($int itemFromInventoryId, $int otherInventoryItemId)

An alternative implementation of useInventoryItemOnInventoryItem. Use this version if the first one does not work on your server.

• itemFromInventoryId $int — id of the item to use.
• otherInventoryItemId $int — id of the target item in an open backpack.

useEquippedItemOnThing($int itemSlot, $thing thing)

Uses the item currently equipped in a slot on a Thing (creature or item).

• itemSlot $int — the equipment slot holding the item (see Constants).
• thing $thing — the target creature or item.

useItemOnMostMonsters($int itemId, $int range, $int runeAoe)

Throws an AOE rune at the single tile that hits the most monsters within range, picking the best spot for you.

• itemId $int — id of the rune to use.
• range $int — maximum distance (in tiles) to consider.
• runeAoe $int — the area shape: RUNE_GFB (0) or RUNE_FIREBALL (1).

useItemOnMostMonsters(3191, 7, RUNE_GFB)   -- GFB the best tile within 7 sqm

crosshairUse($int itemId, $int subtype)

Turns the cursor into a crosshair that, on the next left click, uses the item with this id and subtype from an open container on whatever you click.

• itemId $int — id of the item to arm.
• subtype $int — the required subtype (use the item's normal subtype if unsure).

collectNearbyGroundItem($int containerId, $int groundItemId)

Picks up a ground item within 1 sqm into an open container identified by its item id.

• containerId $int — item id of the destination container.
• groundItemId $int — id of the ground item to collect.

collectNearbyGroundItem(2854, 3031)   -- pick nearby gold (3031) into bp 2854

collectNearbyGroundItemMoveCorpses($int containerId, $int groundItemId)

Same as collectNearbyGroundItem, but if the wanted item is buried under a corpse or other item, that covering item is first moved onto your own tile to expose it.

• containerId $int — item id of the destination container.
• groundItemId $int — id of the ground item to collect.

collectGroundItem($int containerId, $int groundItemId)

Picks up a ground item into an open container from a distance (not limited to 1 sqm).

• containerId $int — item id of the destination container.
• groundItemId $int — id of the ground item to collect.

buyItem($int itemId, $int subtype, $int amount)

Buys an item from an open NPC trade window.

• itemId $int — id of the item to buy.
• subtype $int — subtype (0 if the item has none).
• amount $int — how many to buy.

sellItem($int itemId, $int subtype, $int amount)

Sells an item to an open NPC trade window.

• itemId $int — id of the item to sell.
• subtype $int — subtype (0 if the item has none).
• amount $int — how many to sell.

A Thing is anything that sits on a tile, and is the base type of both Item and Creature. These functions work on any of them.

$int getId($thing thing)

The id of a Thing: the item id for an item, or the unique runtime creature id for a creature.

• thing $thing — the item or creature to inspect.

Returns $int — the id (0 if the Thing is invalid).

$table{x, y, z} getPosition($thing thing)

The map position of a Thing. Returns the sentinel x = 65535, y = 65535, z = 255 when the Thing is invalid.

• thing $thing — the item or creature to locate.

Returns $table — {x, y, z}.

$int or $nil getDistanceFromThing($thing wantedThing)

The distance, in tiles, between your character and a Thing. Returns $nil when the Thing is on a different floor. While you are offline it returns a large sentinel number (99999) rather than a real distance.

• wantedThing $thing — the item or creature to measure to.

Returns $int — tile distance, or $nil if the Thing is on another floor.

look($thing thing)

Looks at a Thing, exactly like right-click → Look. The result arrives as a MessageLook message (read it via foreachMessage).

• thing $thing — the item or creature to look at.

$item getTopUseItem($int x, $int y, $int z)

The top usable item on a tile. Ground tiles such as water count as usable items.

• x, y, z $int — the position to inspect.

Returns $item — the top usable item (an empty item if none).

$thing getTopMoveThing($int x, $int y, $int z)

The top movable Thing on a tile (the thing you would drag if you clicked and held).

• x, y, z $int — the position to inspect.

Returns $thing — the top movable Thing (an empty Thing if none).

$thing{} getAllThingOnPos($int x, $int y, $int z)

Every Thing stacked on a tile — items and creatures — in stack order.

• x, y, z $int — the position to inspect.

Returns $table — array of $thing (empty if the tile is unknown or empty).

Creatures (players, monsters, NPCs) are returned by the screen-scan functions below and by getCreatureByName. A Creature is also a Thing, so you can pass it to Thing functions like getId, getPosition and look.

$creature{} getScreenMonsters()

All monsters visible on your own floor.

Returns $table — array of $creature.

-- Attack the nearest monster if nothing is targeted yet.
if getAttackingCreature() == nil then
    local monsters = getScreenMonsters()
    if #monsters > 0 then
        attack(monsters[1])
    end
end

$creature{} getScreenPlayers()

All players visible on your own floor.

Returns $table — array of $creature.

$creature{} getCreaturesMultiFloor()

All creatures visible across every floor the client is aware of, including your own character.

Returns $table — array of $creature.

$creature or $nil getCreatureByName($str name)

Finds a visible creature by exact name.

• name $str — the exact creature name to find.

Returns $creature — the creature, or $nil if it is not on screen.

$int countScreenCreatures($str pattern)

Counts visible creatures whose name contains the pattern (a substring match). For example countScreenCreatures("Drag") counts both "Dragon" and "Dragon Lord".

• pattern $str — substring to look for in creature names.

Returns $int — number of matching creatures.

$int getScreenMonstersCountInRange($int range)

Number of monsters within range tiles of your character.

• range $int — maximum tile distance.

Returns $int — monster count in range.

$int getScreenPlayersCountInRange($int range)

Number of other players within range tiles of your character (you are not counted).

• range $int — maximum tile distance.

Returns $int — player count in range.

attack($creature creatureToAttack)

Sets a creature as your attack target.

• creatureToAttack $creature — the creature to attack.

follow($creature creatureToFollow)

Sets a creature as your follow target, walking after it.

• creatureToFollow $creature — the creature to follow.

cancelAttack()

Stops attacking the current target.

$creature or $nil getAttackingCreature()

The creature you are currently attacking (targeting).

Returns $creature — the current target, or $nil if none.

$str getCreatureName($creature wantedCreature)

The name of a creature.

• wantedCreature $creature — the creature to inspect.

Returns $str — the creature's name.

$int getCreatureHppc($creature wantedCreature)

A creature's current health as a percentage.

• wantedCreature $creature — the creature to inspect.

Returns $int — health percentage 0–100.

$bool isMonster($creature creature)

Whether a creature is a monster.

• creature $creature — the creature to test.

Returns $bool — true if it is a monster.

$bool isPlayer($creature creature)

Whether a creature is a player.

• creature $creature — the creature to test.

Returns $bool — true if it is a player.

$int getType($creature wantedCreature)

The creature's type as a number (see Creature types under Constants).

• wantedCreature $creature — the creature to inspect.

Returns $int — 0 player, 1 monster, 2 npc, 3 own summon, 4 other summon.

$int getDirection($creature creature)

The direction a creature is facing (see Directions under Constants).

• creature $creature — the creature to inspect.

Returns $int — direction 0–7 (DIR_NORTH … DIR_NW).

$int getOutfitId($creature creature)

The looktype id of a creature's outfit.

• creature $creature — the creature to inspect.

Returns $int — outfit looktype id.

setOutfit($creature creature, $int outfitId)

Changes a creature's outfit to the given looktype (visual only / client-side).

• creature $creature — the creature to restyle.
• outfitId $int — the looktype id to apply.

$int getPartyShield($creature wantedCreature)

The party-shield icon id of a creature (its party relationship to you). The value is server/client-specific; 0 means no shield.

• wantedCreature $creature — the creature to inspect.

Returns $int — shield icon id (0 if none).

$int getSkull($creature wantedCreature)

The skull icon id of a creature (white skull, red skull, etc.). Value is server/client-specific; 0 means no skull.

• wantedCreature $creature — the creature to inspect.

Returns $int — skull icon id (0 if none).

$int getEmblem($creature wantedCreature)

The emblem icon id of a creature (e.g. war emblems). Value is server/client-specific; 0 means no emblem.

• wantedCreature $creature — the creature to inspect.

Returns $int — emblem icon id (0 if none).

$container{} getOpenContainers()

Every container window currently open.

Returns $table — array of $container.

-- Count gold coins (id 3031) across all open containers.
local gold = 0
for _, container in ipairs(getOpenContainers()) do
    for _, item in ipairs(getItems(container)) do
        if getId(item) == 3031 then
            gold = gold + getItemStackSize(item)
        end
    end
end
print("gold visible: " .. gold)

$item{} getItems($container container)

The items inside a container, in slot order.

• container $container — the container to read.

Returns $table — array of $item.

$item or $nil getContainerItem($container container)

The item that this container window represents (the bag/backpack itself).

• container $container — the container to inspect.

Returns $item — the container's own item, or $nil if the container is invalid.

moveItemToContainer($item item, $container container, $int count)

Moves an item into the first free slot of a container. For stackables, a count above 1 moves only that many units — e.g. move 35 arrows out of a stack of 50.

• item $item — the item to move.
• container $container — the destination container.
• count $int — how many units to move (use the full stack size to move everything).

open($item item, $container parentContainer)

Opens a container item in the same window, replacing the current view (like opening a bag that sits inside another bag). The item must be inside parentContainer.

• item $item — the container item to open.
• parentContainer $container — the container that currently holds item.

openInNewWindow($item item)

Opens a container item in a new window, leaving existing windows open.

• item $item — the container item to open.

closeContainer($container container)

Closes a container window.

• container $container — the container to close.

openParentContainer($container container)

Navigates up one level, like clicking the up-arrow on a container window.

• container $container — the container whose parent to open.

printEffects()

Prints every effect currently visible near you and its position to the console. Handy for discovering the effect id you want to watch for with findEffectPosition.

$table{x, y, z} or $nil findEffectPosition($int effectId)

Searches the tiles around your character for a visible effect with the given id and returns where it is.

• effectId $int — the effect id to look for.

Returns $table — {x, y, z} of the effect, or $nil if it is not currently visible.

$bool isVipOnline($str vipName)

Checks your VIP list for a player and whether they are online.

• vipName $str — the VIP's exact name.

Returns $bool — true if online; false if offline or not in your VIP list.

move($int direction)

Takes a single step in a direction (all eight directions are allowed).

• direction $int — a direction 0–7 (see Directions under Constants).

turn($int direction)

Turns to face a direction without moving. Only the four cardinal directions are valid.

• direction $int — DIR_NORTH (0), DIR_EAST (1), DIR_SOUTH (2) or DIR_WEST (3).

mapClick($int x, $int y, $int z)

Auto-walks to a map position using the client's pathfinder, exactly like clicking the tile on the game map.

• x, y, z $int — destination position.

mapClickChase($creature chasedCreature)

Auto-walks toward a creature, aiming for the closest reachable tile next to it — a map-click "chase".

• chasedCreature $creature — the creature to walk toward.

$bool isReachable($int x, $int y, $int z)

Whether a walkable path exists from your character to a position.

• x, y, z $int — the position to test.

Returns $bool — true if reachable, false otherwise.

$bool isWalkable($int x, $int y, $int z, $bool ignoreCreatures)

Whether a single tile can be stood on. With ignoreCreatures = true a creature standing on the tile does not count as blocking.

• x, y, z $int — the tile to test.
• ignoreCreatures $bool — if false, a creature on the tile makes it non-walkable.

Returns $bool — true if nothing forbids walking on the tile.

setChaseMode($int mode)

Sets the client's chase mode.

• mode $int — 0 = stand still, 1 = chase opponent.

reachGroundItem($int itemId)

Auto-walks next to the nearest visible ground item with the given id.

• itemId $int — id of the ground item to walk to.

$int countGroundItems($int itemId)

How many ground items with the given id are currently visible to you.

• itemId $int — the ground item id to count.

Returns $int — number of visible ground items with that id.

goToLabel($str labelName)

Makes the cavebot jump to the waypoint tagged with this label.

• labelName $str — the waypoint label to jump to.

loadWaypoints($str fileName)

Loads a waypoint file from the bot's Cavebot directory (the .SBWayPt extension is added for you).

• fileName $str — waypoint file name, without extension.

enableFollowWaypoints($bool on)

Turns cavebot waypoint following on or off. Cavebot scripts and targeting keep running; re-enabling the cavebot in the GUI also switches this back on.

• on $bool — true to follow waypoints, false to stop.

allowWalk($int itemId)

Marks an item id as walkable, so the cavebot and targeting will path through tiles containing it.

• itemId $int — the item id to treat as walkable.

disallowWalk($int itemId)

Marks an item id as not walkable, so the cavebot and targeting will avoid tiles containing it.

• itemId $int — the item id to treat as blocking.

spyUp()

Shifts the rendered view one floor up and keeps it floating over your character as you walk. Call it repeatedly to peek further up; call spyDown until you are back on your own floor to return to the normal camera.

spyDown()

Shifts the rendered view one floor down and keeps it floating over your character as you walk. Only floors the server has already sent can be drawn. Call spyUp back up to your own floor to reset.

enableTargeting($bool on)

Enables or disables the main frame's targeting. It applies to whichever tab is active: on the PVP tab it controls PVP targeting, on the PVE tab it controls PVE targeting.

• on $bool — true enables targeting, false disables it.

enableCavebotTargeting($bool on)

Enables or disables cavebot targeting.

• on $bool — true enables it, false disables it.

$int getKilledMonstersCount($str monsterName)

How many of a named monster you have killed. Only works while a Hunt is running in the Hunt frame; the count is based on loot messages, so leave the party to be credited with kills.

• monsterName $str — the monster name to count.

Returns $int — kills recorded for that monster.

resetKilledMonstersCount($str monsterName)

Resets the kill counter for a monster — handy after completing a task.

• monsterName $str — the monster whose count to reset.

talk($str message)

Says a message on the default (local) channel.

• message $str — the text to say.

npcTalk($str message)

Sends a message on the NPC channel — use it to talk to NPCs ("hi", "trade", …).

• message $str — the text to send.

tradeTalk($str message)

Sends a message on the trade channel. Some servers use a different channel id; if this does not work, use talkChannel with the correct id.

• message $str — the text to send.

talkChannel($int mode, $int channelId, $str message)

Sends a message on a specific channel with a specific mode. Use this when a server numbers its channels differently and the helpers above hit the wrong chat.

• mode $int — a message mode (server-specific; see the modes list under Script flow).
• channelId $int — the channel id to send on.
• message $str — the text to send.

talkPrivate($str receiver, $str message)

Sends a private message to another player.

• receiver $str — the recipient's name.
• message $str — the text to send.

sendKey($str hotkey)

Simulates a single key press in the client. Key names are case-insensitive.

• hotkey $str — one of: F1–F12; a letter A–Z; or a special key Enter, Left, Right, Up, Down, Tab, Esc.

writeText($str text)

Types text into the client as if typed on the keyboard. Only works while the client window is focused.

• text $str — the text to type.

acceptParty($str{} partyLeaders)

Automatically accepts a party invite when it comes from one of the named leaders.

• partyLeaders $str{} — array of leader names to accept invites from.

-- Accept invites from either leader.
acceptParty({"Leader1", "Big Ben"})

partyInvite($str{} partyMemberNamesToInvite)

Invites any of the named players to your party when they are visible on screen and not already in it.

• partyMemberNamesToInvite $str{} — array of player names to invite.

partyInvite({"Bob", "Elite Maciek"})

enableBot($bool on)

Turns most bot functionality on or off at once (the Extras, Hunt and Hotkeys systems are not affected).

• on $bool — true enables the bot, false disables it.

enableScript($str scriptName, $bool on)

Enables or disables every script whose name matches scriptName.

• scriptName $str — the script name to toggle.
• on $bool — true enables, false disables.

enableCavebotScript($str scriptName, $bool on)

Enables or disables every cavebot script whose name matches scriptName.

• scriptName $str — the cavebot script name to toggle.
• on $bool — true enables, false disables.

enableFishing($bool on)

Turns fishing in the Extras frame on or off.

• on $bool — true enables fishing, false disables it.

hideOrShowMainWindow()

Toggles the main bot window — hides it if shown, shows it if hidden.

flashWindow()

Flashes the game window in the taskbar to get your attention.

xlog()

Shows the login screen while your character stays online — a quick way to hide the game view.

shutdownPc()

Shuts down your PC.

setGlobal($str globalName, $str or $int data)

Stores a value in shared global storage under a name. Globals are shared across all scripts and the cavebot, so use them to pass state between them.

• globalName $str — the storage key.
• data $str or $int — the value to store.

$str or $int or $nil getGlobal($str globalName)

Reads a value previously stored with setGlobal.

• globalName $str — the storage key to read.

Returns $str or $int — the stored value, or $nil if nothing was set.

writeToFile($str fileName, $str content)

Appends text to a file in the bot directory, creating it if needed. For example fileName = "logs.txt" writes to logs.txt in the bot folder. Use \n for a new line.

• fileName $str — file name relative to the bot directory.
• content $str — the text to append.

writeToFile("logs.txt", "started hunt\n")

playSound($str fileName)

Plays a .wav file from the bot's Alarms directory.

• fileName $str — the .wav file name inside the Alarms folder.

These functions drive the bot's spellcasting rotations. Spell names must match the spells you configured in the currently active spellcasting tab (PVE or PVP).

enableSpellcasting($bool enable)

Enables or disables spellcasting for the currently active tab (PVE or PVP).

• enable $bool — true enables casting, false disables it.

castSpell($str spellName)

Casts a configured spell once, applying everything it needs (such as auto-turning). Does nothing if the spell is not defined in the active tab.

• spellName $str — name of a spell in the active spellcasting tab.

forceOffensiveSpell($str spellName, $int time)

Pauses the offensive rotation and forces only the named spell for time milliseconds. The forced spell still respects its pre/post-cast delays and its use condition, then the normal rotation resumes.

• spellName $str — the spell to force.
• time $int — how long to force it, in milliseconds.

Typical use: bind a hotkey to fire an occasional spell on demand (forceOffensiveSpell("Stun", 1100)) while the rotation otherwise runs your main DPS spells. The special name "MW" instead suspends the offensive rotation — useful on servers where magic walls share a cooldown, so a magic-wall hotkey can fire immediately.

forceOffensiveSpell("Stun", 1100)

forceSupportiveSpell($str spellName, $int time)

Same as forceOffensiveSpell, but for the supportive rotation.

• spellName $str — the supportive spell to force.
• time $int — how long to force it, in milliseconds.

$bool areSpellRangeConditionsMet($str spellName)

Checks whether a configured spell's area/range requirements are currently satisfied.

• spellName $str — a spell defined in the active tab.

Returns $bool — true if the spell is defined and its range/area conditions are met.

$bool areSpellRangeConditionsMetForCreature($str spellName, $creature creature)

Like areSpellRangeConditionsMet, but checks the requirements against a specific creature.

• spellName $str — a spell defined in the active tab.
• creature $creature — the creature to test against.

Returns $bool — true if the spell is defined and its conditions are met for that creature.

forceItemUse($str itemName, $int time)

The item-rotation equivalent of forceOffensiveSpell: pauses the Items-frame rotation and forces the named item entry for time milliseconds, then resumes the normal rotation.

• itemName $str — the name of the item entry in the Items frame to force.
• time $int — how long to force it, in milliseconds.