The language

var resting = false

# runs the moment a line arrives, between passes
on message(line, from) {
    if contains(lower(line), "you are tired") { resting = true }
    if contains(lower(line), ", well done")   { resting = false }
}

on loop {
    if resting { return 1000 }
    # ... do the work ...
    return 600
}

Fold the line with lower() and test it with contains() — a message is rarely the exact string you would compare with ==. If you would rather ask than react, lastServerMessage() reads the most recent line and is legal inside a wait until.

var taken = 0

# one right-click option or left-click default = one action
on menu(kind, action, target) {
    print(action, "->", target)
    if kind == "take_item" { taken = taken + 1 }
}

Fires whether your script asked for the action or you clicked it yourself. The whole story — all fifty kinds, every reader, and what each one gives back — is Menu actions, next.

# all three
on menu(kind, action, target) {
    print(kind, "|", action, "|", target)
}

All three names are optional and they are positional, so on menu(kind) binds the kind only, on menu(kind, action) the kind and the verb, and a bare on menu binds nothing and reads what it needs from the menu… commands. One block per script, and return inside it takes no value — it just ends that delivery, the way it does in on message. stop still stops the script.

var taken = 0
var coins = 0

on start {
    uiTab("Looter")
    if not menuWorks() { print("this server does not report its menu") }
}

on menu(kind) {
    if kind != "take_item" { return }

    taken = taken + 1
    let loot = menuDrop()
    if loot != none {
        print("picked up", loot.name, "at", loot.tile.x, loot.tile.y)
        if loot.name == "Coins" { coins = coins + 1 }
    }
    uiStat("loot", "Picked up", commas(taken), "items")
}

on loop {
    return 600
}

Counting from the message — You pick up some coins — misses a pickup whenever two arrive in one tick or the wording differs. Counting the action cannot: one take is one action.

var mine = 0        # actions this script asked for
var theirs = 0      # actions that appeared anyway

on menu {
    if mine > 0 {
        mine = mine - 1
    } else {
        theirs = theirs + 1
        print("not mine:", menuAction(), menuTarget())
    }
}

on loop {
    let rock = nearestObject(name: "Rock", within: 8)
    if rock != none {
        mine = mine + 1              # count it before you cause it
        if interact(rock, "Mine") { return 1200 }
        mine = mine - 1              # it never went out
    }
    return 600
}

Every action your script causes is one you can predict; anything left over came from the keyboard. Useful for pausing while somebody is playing by hand, and for catching a script that is firing twice.

var fighting = ""
var attacks = 0

on menu(kind, action, target) {
    if kind == "attack_npc" {
        attacks = attacks + 1
        fighting = target
        let it = menuNpc()
        if it != none { print("attacking", it.name, "at", it.tile.x, it.tile.y) }
    }

    if kind == "attack_player" {
        let them = menuPlayer()
        if them != none { print("attacking", target, "at", them.x, them.y) }
    }

    if kind == "cast_on_npc" {
        print("cast spell", menuSpell(), "on", target, "with", action)
    }
}

on loop {
    return 800
}

target is the text the menu drew, so it may read "Goblin (level 2)"; menuNpc().name is the clean name. Match on kind, print action and target.

var mined = 0
var chopped = 0

on menu(kind, action, target) {
    # scenery covers mining, chopping, fishing, cooking ranges, altars...
    if kind != "object_action" { return }

    if action == "Mine" {
        mined = mined + 1
        uiStat("ore", "Rocks mined", commas(mined), "")
    }
    if action == "Chop" {
        chopped = chopped + 1
        uiStat("logs", "Trees chopped", commas(chopped), "")
    }

    let thing = menuObject()
    if thing != none { print(action, thing.name) }
}

on loop {
    return 600
}

object_action is the catch-all for scenery, so the verb is what tells the jobs apart. That verb is display text and can differ between servers — check it against your own server before you rely on it, and prefer kind whenever a kind exists for what you mean.

on menu(kind) {
    if kind == "use_item_on_boundary" {
        let door = menuWall()
        let key = menuItem()
        if door != none and key != none {
            print("used", key.name, "on", door.name)
        }
        print("from slot", menuSlot())
    }

    if kind == "use_item_on_item" {
        print("combined slot", menuIndex(), "with slot", menuSlot())
    }
}

on loop {
    return 600
}

For a use-on, menuIndex() is what was acted on and menuSlot() is the item in your hand. That is the one pair worth remembering; everywhere else menuIndex() is the actor's server index.

on menu(kind, action, target) {
    print("kind    ", kind)
    print("verb    ", action)
    print("target  ", target)
    print("opcode  ", menuOpcode())
    print("index   ", menuIndex())
    print("slot    ", menuSlot())
    print("spell   ", menuSpell())
    let where = menuTile()
    if where != none { print("tile    ", where.x, where.y) }
}

on loop {
    return 5000
}

Drop this in, play by hand for a minute, and the console tells you exactly what your client sends for anything you click. It is the quickest way to find the kind and the verb for a job on a server nobody has written a script for yet.

var seen = 0

on loop {
    let now = menuActionCount()
    if now == seen {
        print("nothing happened last pass")
    } else {
        seen = now
        print("last was", lastMenuKind(), "-", lastMenuAction(), lastMenuTarget())
        if contains(recentMenuKinds(), "take_item") { print("and something was picked up") }
    }
    return 1000
}

menuActionCount() only ever goes up, so comparing it with what you saw last pass tells you whether anything happened without caring what. recentMenuKinds() then catches the several that may have happened while you slept. All three are readers, so they are also legal in a wait until:

wait until lastMenuKind() == "take_item" timeout 5000 else {
    print("nothing was picked up")
}

var banking = false

on start {
    uiTab("Miner")
    hotkey("F1", "toggleBanking")
    uiButton("Bank now", "toggleBanking")
}

fun toggleBanking() {
    banking = not banking
    print("banking is now", banking)
}

on loop {
    if banking { return 1200 }
    return 600
}

Neither runs where you pressed it. A key press arrives on the launcher's thread and a click on the UI thread; both are queued and your fun runs on the script thread, between passes, exactly like on message and on menu. So it never interrupts an on loop half way through, and it is safe to touch the same variables from both.

var paused = false

on start {
    uiTab("Fighter")
    hotkey("F2", "togglePause")
    hotkey("F4", "panic")
    uiButton("Pause", "togglePause")
}

fun togglePause() {
    paused = not paused
    print(paused, "<- paused")
}

fun panic() {
    print("stopping on request")
    stop
}

on loop {
    if paused { return 1000 }
    # ... the actual work ...
    return 600
}

stop inside a bound fun ends the script the same way it does anywhere else, and on stop still runs — so a total printed there is printed.

enum Mode { FIGHT, LOOT, BANK }

var mode = Mode.FIGHT

on start {
    uiTab("Multi")
    hotkey("F3", "nextMode")
    uiButton("Next mode", "nextMode")
}

fun nextMode() {
    if mode == Mode.FIGHT {
        mode = Mode.LOOT
    } else if mode == Mode.LOOT {
        mode = Mode.BANK
    } else {
        mode = Mode.FIGHT
    }
    uiStat("mode", "Mode", str(mode), "")
}

on loop {
    if mode == Mode.FIGHT { return 600 }
    if mode == Mode.LOOT { return 800 }
    return 1500
}

The fun takes no arguments and returns nothing — that is the whole contract. Everything it needs comes from vars, and everything it changes is read by the loop on its next pass.

on start {
    uiTab("Helper")
    hotkey("F5", "dropJunk")
    uiButton("Drop junk", "dropJunk")
}

fun dropJunk() {
    let gone = dropAll("Bones")
    print("dropped", gone, "bones")
    wait 600
}

on loop {
    return 600
}

Because it runs on the script thread, a bound fun may do anything a pass may do — act on the game, and even wait. The loop simply does not run while it is working, so keep it short: a fun that waits ten seconds is ten seconds the bot is not botting.

The rest of the panel

Buttons are one of a family that builds the script's own tab: uiTab, uiHeader, uiLabel, uiStat, uiProgress, uiNote, uiSeparator to show things; uiToggle/uiToggled, uiInput/uiText, uiNumber, uiChoice/uiChosen to ask for them; and uiHas, uiRemove, uiClear to manage the rows. Each has its own card in the ui group. A toggle you read on the next pass is often simpler than a button that sets a flag — reach for uiButton when you want something to happen, and for uiToggle when you want something to be.

bag — the script's own record

The closest thing the language has to a class. newBag() makes one; bagPut(b, "hp", 30) gives it named fields (numbers, texts, flags, tiles, nested bags, and lists of any of those); typed reads take them back — bagNumber(b, "hp") is an int? (none when missing or a different type), bagNumberOr(b, "hp", 0) an int. Bags are mutable and compared by identity (== asks "same bag"), unlike lists, which stay immutable. A list<bag> is a table — all the usual list commands work on it, and bag can be written as a type: var rows = bagList(), fun f(bag b) -> int, list<bag> in a fun's signature. The whole story — tables, queries, saving, JSON — is on Bags & JSON.

wait 600                                  # a fixed pause

wait until bankIsOpen() timeout 6000 else {
    print("the bank did not open")
    return 1000
}

state mining {
    if invIsFull() { become banking }
    let rock = nearestObject(id: 102, within: 6)
    if rock == none { return 1000 }
    interact(rock, "Mine")
    return 900
}

state banking {
    if invCount() == 0 { become mining }
    # ... walk to the bank and deposit ...
    return 1000
}

enum Mode { POWER, BANK, SELL }

setting Mode mode = Mode.POWER "What to do with ores"

if mode == Mode.BANK { become banking }
print(mode)        # Mode.POWER
print(mode.name)   # POWER