Scripts API

Everything a script of the Scripts module can read and do, in one page. Start with “How a script runs”, then look up the functions you need: each one has what it does and an example you can copy.

Want ready scripts to start from? See the examples

How a script runs

Where it runs

Scripts live in the Scripts module of the bot. Each one runs again every few seconds (you choose, from 0.1 s) while its switch and the Scripts module are on. Run now runs it once, even when it is off. A script that is on can’t be edited: turn it off first.

Reading the game

What the bot sees is ready to read: player, monsters(), players(), target, containers, depot, equipment, hotbar, skills, trade and messages(). The values are refreshed at the start of each run and after every await, so a script that waits always sees the game as it is now.

const close = monsters().filter((m) => distance(m) <= 1)
if (close.length >= 3) warn("Surrounded by", close.length, "monsters")

Doing things

Action functions (cast, useItem, attack, walk, say, buy…) return true when the bot did it and false when it couldn’t; why() tells you why (mana, cooldown, no-item…). Each script does one game action per tick, so put await wait(ms) between the steps of a sequence. Items, walking, the depot and shops need Direct Controls (General page), which is on by default.

if (!cast("exura vita")) log("no heal:", why())

Waiting

await wait(ms) pauses the script, await waitUntil(check, ms) waits until something is true and await goTo(x, y, z) walks there. Always write await before them. A script never runs twice at the same time: the next run starts only after this one ends.

say("hi")
await wait(1500)
say("trade")
if (!(await waitUntil(() => trade, 4000))) warn("the shop did not open")

Memory between runs

storage keeps values from one run to the next, until you edit the script or reload the game. now is the game clock in milliseconds: use it to do something every few minutes.

if (now - (storage.last || 0) > 60000) {
  storage.last = now
  log("one more minute")
}

The console

log() and warn() write in the script’s console, under the code (press Edit). Errors show there too, with the line number.

With the Cavebot

A Script waypoint of the Cavebot runs one of your scripts once and waits for it to end. Inside it, gotoLabel("Name") makes the Cavebot jump to a label, and cavebot.label, cavebot.index and cavebot.status tell where the route is. turnOn() and turnOff() flip a module’s switch; pause() holds a module only while the script is on.

if (itemCount("life fluid") < 100) gotoLabel("City")
else gotoLabel("Hunt")

Rules for the Target and the Loot

onAttack((monster) => …) decides whom the Target attacks: return false to skip a monster or a number to raise its priority. onLoot((item) => …) decides what the Loot takes: true takes it, false leaves it.

onAttack((m) => {
  if (m.name === "Rat") return false
  if (m.hpPercent !== null && m.hpPercent < 30) return 10
})

Limits and safety

Each run has 50 ms of work (waiting doesn’t count); a script that keeps going over it is stopped. Scripts run in a closed box: they can’t see the game page, your passwords or the internet. Scripts that come in someone else’s profile arrive blocked until you allow them.

Functions and values

Grouped like the Functions panel of the bot. The examples are short pieces: put them inside your own script.

Your character

player skills experience money

player

Your character: hp, maxHp, hpPercent, mana, maxMana, manaPercent, cap, soul, level, vocation, name, x, y, z, direction, skull, inPz, inBattle, pzLocked, hasted, paralyzed, poisoned, magicShield, invisible, hungry, moving, targetId.

Example

if (player.hpPercent < 50) cast("exura vita")

skills

Your skills: magic, fist, club, sword, axe, distance and shielding, each with level and percent.

Example

log(skills.magic && skills.magic.level)

experience

Your total experience points.

Example

log(experience)

money

Gold you carry (gold, platinum and crystal coins in gold). null when unknown.

Example

if (money !== null && money < 1000) warn("low on gold")

Creatures and the world

creatures monsters players npcs target findCreature distance messages

creatures

Everything visible except you: monsters, players and NPCs. Each has id, name, type, hpPercent, x, y, z, distance (sqm), sameFloor, skull, party, level, vocation, summon, attackingMe and isTarget.

Example

for (const c of creatures) log(c.name, c.type, c.distance)

monsters()

Only the monsters on your floor.

Example

if (monsters().length >= 3) cast("exevo gran mas vis")

players()

Only the players on your floor.

Example

if (players().length > 0) pause("cavebot")

npcs()

Only the NPCs on your floor.

Example

log(npcs().map((n) => n.name))

target

The creature you are attacking, or null.

Example

if (target && target.hpPercent < 20) useOnTarget(3155)

findCreature(name)

The first creature on your floor with that name (capital letters don't matter), or null.

Example

const bob = findCreature("Bob")

distance(a, b?)

Distance in sqm (the bigger gap of x and y). With one argument it measures from you. Another floor = Infinity.

Example

if (target && distance(target) > 4) chaseMode("chase")

messages()

New lines since the last call: server messages, NPC replies, monster speech, loot and private messages (sender only).

Example

for (const m of messages()) if (m.type === "npc") log(m.from, m.text)

Items

containers equipment hotbar item depot openDepot openItem moveItem closeContainer itemCount findItem

containers

Your open backpacks: index, name, size, free and items (id, name, count, slot, fluid, bag = true when the item is a backpack).

Example

for (const bp of containers) log(bp.name, bp.items.length)

equipment

What you wear: ring, amulet, boots, rightHand, leftHand and ammo (null when empty).

Example

if (!equipment.ring) warn("no ring on")

hotbar

Your hotbar slots: slot, key, words, itemId and mode (spell, self, target, crosshair, equip…).

Example

log(hotbar.map((h) => h.slot + ":" + (h.words || h.itemId)))

item(name)

Finds any item of the game by its name and gives its id, fluid and name, or null. Every item function also takes the name in quotes directly, like useItem("mana fluid"); the Functions panel has a search that shows the ids.

Example

const fluid = item("life fluid")
log(fluid.name, fluid.id, fluid.fluid)

depot

The depot when it is open, or null: index, size, free, items (id, name, count, slot, bag…) and bags (the backpacks of the depot you opened, with their items and free slots).

Example

if (depot) log(depot.items.length, "items in the depot")

openDepot()

Opens the depot: uses the free locker closest to you (up to 7 sqm; the game walks to it). Needs Direct Controls.

Example

openDepot()
await waitUntil(() => depot, 5000)

openItem(item)

Opens a backpack that is inside an open container, like a backpack of the depot. Needs Direct Controls.

Example

openItem(depot.items[1])
await waitUntil(() => depot.bags.length > 0, 3000)

moveItem(item, to, count?)

Moves an item (from containers or the depot) to a container (its first free slot), into a backpack item, or to "backpack" (your main backpack). count is optional: all by default. Needs Direct Controls.

Example

moveItem(containers[0].items[0], depot.bags[0])

closeContainer(container)

Closes an open container: one of your backpacks, a depot backpack or the depot.

Example

closeContainer(depot)

itemCount(item, fluid?)

How many of an item you carry, by name ("life fluid") or id. Counts closed backpacks when the item is on the hotbar. By id, fluids share the vial id 2874: add the fluid (7 mana, 10 life).

Example

if (itemCount("mana fluid") < 20) alarm()

findItem(name)

The first item with that name in your open backpacks, or null. Use its id in the other functions.

Example

const sd = findItem("sudden death rune")

Actions (true when the bot does it)

cast canCast say useItem useItemOn useOnTarget useHotbar attack stopAttack walk walkTo goTo turn useTile dropItem fightMode chaseMode logout alarm

cast(words)

Casts a spell of your vocation. Uses its hotbar key when it has one, otherwise types it. Checks level, mana and cooldown first.

Example

cast("utani hur")

canCast(words)

true when cast(words) would work right now.

Example

if (canCast("exura vita")) cast("exura vita")

say(text)

Says a text in the Default channel: NPC words, house spells, anything.

Example

say("hi")

useItem(id, fluid?)

Uses an item on yourself (food, fluid, rune), by name or id: useItem("mana fluid"). Uses its hotbar key in Self mode when it has one, otherwise the backpack.

Example

if (player.manaPercent < 40) useItem(2874, 7)

useItemOn(id, creatureOrSqm)

Uses an item (rune, rope, shovel) on a creature or on a sqm {x, y, z}. Needs Direct Controls.

Example

useItemOn(3160, findCreature("Bob"))

useOnTarget(id)

Uses a rune on the creature you are attacking.

Example

useOnTarget(3155)

useHotbar(slot)

Presses a hotbar slot. The slot numbers are in the hotbar list.

Example

useHotbar(4)

attack(creature)

Attacks a creature (the object, its id or its name). The Target module may pick another one on its next turn.

Example

attack(monsters()[0])

stopAttack()

Stops attacking.

Example

if (player.hpPercent < 30) stopAttack()

walk(direction)

One step: north, south, east, west, north-east, north-west, south-east or south-west.

Example

walk("north")

walkTo(x, y, z)

Walks to a sqm on your floor, like a click on the map. Needs Direct Controls.

Example

walkTo(32369, 32241, 7)

await goTo(x, y, z, timeoutMs?)

Walks to a sqm on your floor and waits until you are there (true) or the time runs out (false, default 30 s). Pause the Cavebot first so it doesn't walk elsewhere. Needs Direct Controls.

Example

pause("cavebot")
if (await goTo(32369, 32241, 7)) useTile(32369, 32240, 7)
resume("cavebot")

turn(direction)

Turns without walking: north, south, east or west.

Example

turn("west")

useTile(x, y, z)

Uses a sqm next to you: door, lever, ladder.

Example

useTile(player.x + 1, player.y, player.z)

dropItem(id, count?, x?, y?, z?)

Drops an item from your backpack on the ground (under you when no sqm is given). Needs Direct Controls.

Example

dropItem(3031, 10)

fightMode(mode)

Changes the fight mode: attack, balanced or defense.

Example

fightMode("defense")

chaseMode(mode)

Changes the chase mode: stand, chase or aggressive.

Example

chaseMode("stand")

logout()

Logs out (the game refuses while you are in battle).

Example

if (player.hpPercent < 15 && !player.inBattle) logout()

alarm()

Plays the alarm sound and flashes the bot window.

Example

if (player.cap < 50) alarm()

NPCs and shops

trade buy sell closeTrade

trade

The NPC shop window, or null when it is closed: npcName, tab, gold and offers (id, name, price, side buy/sell).

Example

if (trade) log(trade.npcName, trade.offers.length, trade.gold)

await buy(id, count, fluid?)

Buys from the open shop window, in lots of up to 100, and waits each lot to go through. Open the shop first (say hi, then trade). Needs Direct Controls.

Example

say("hi")
await wait(1500)
say("trade")
await waitUntil(() => trade, 3000)
await buy(3155, 50)
closeTrade()

await sell(id, count, fluid?)

Sells to the open shop window, like buy.

Example

await sell(3031, itemCount(3031))

closeTrade()

Closes the shop window.

Example

closeTrade()

Bot modules

onAttack onLoot cavebot gotoLabel turnOn turnOff pause resume isOn

onAttack((monster) => …)

A rule for the Target module: it asks your function about each monster on screen. false = never attack it, a number = priority (higher first, above the order of your list), nothing = as usual. Target must be on.

Example

onAttack((m) => {
  if (m.name === "Rat") return false
  if (m.hpPercent !== null && m.hpPercent < 30) return 10
})

onLoot((item) => …)

A rule for the Loot module: it asks about each item in an open corpse. false = never take it, true = always take it, nothing = your Loot settings decide. Loot must be on.

Example

onLoot((item) => {
  if (item.value !== null && item.value < 50) return false
  if (item.name === "dragon ham") return true
})

cavebot

The Cavebot now: status (walking, paused:monster, script…), label (the label of the part of the route it is in, like "Hunt"), index (the waypoint number), waypoint (its type), stuck (true after 3 skips in a row) and inWaypoint (true when a Script waypoint started this run). null with the Cavebot off.

Example

if (cavebot && cavebot.label === "Hunt") log("hunting, waypoint", cavebot.index)

gotoLabel(label)

Makes the Cavebot jump to a label. In a run started by a Script waypoint it jumps when the script ends; in any other script, right away.

Example

if (player.cap < 100) gotoLabel("Refill")

turnOn(module)

Turns a module on, like its switch (target, attack, loot, cavebot, healing…). It stays on until something turns it off.

Example

turnOn("target")

turnOff(module)

Turns a module off, like its switch. Unlike pause(), it stays off after the script ends.

Example

turnOff("target")

pause(module)

Holds a module (cavebot, target, attack, healing, loot, rune-maker, hunt-follow…) while this script is on. Turning the script off releases it.

Example

pause("cavebot")

resume(module)

Releases a module held by pause().

Example

resume("cavebot")

isOn(module)

true when the switch of that module is on.

Example

if (isOn("cavebot")) log("walking")

Script tools

wait waitUntil why log warn storage now

await wait(ms)

Waits, then goes on with the next line. Write await before it.

Example

say("hi")
await wait(1500)
say("trade")

await waitUntil(check, timeoutMs?)

Waits until the check returns true (true) or the time runs out (false, default 5 s). The check runs every 0.1 s.

Example

await waitUntil(() => player.manaPercent > 90, 60000)

why()

Why the last action returned false: mana, cooldown, no-item, chat-busy, one-action-per-tick…

Example

if (!cast("exura")) log(why())

log(...values)

Writes a line in this script's console, below the code.

Example

log("HP", player.hp, "of", player.maxHp)

warn(...values)

Like log, marked in yellow.

Example

warn("no mana fluids")

storage

An object that keeps its values between runs, until you edit the script or reload the game.

Example

storage.kills = (storage.kills || 0) + 1

now

The game clock, in milliseconds.

Example

if (now - (storage.last || 0) > 60000) storage.last = now