Loadouts

A loadout opens the bank, deposits what its goal does not include, and withdraws and equips what it does.

Why a loadout

A bank trip is a dozen small actions: open the bank, deposit, withdraw, equip, answer the prompt an equip opens. Each is queued, each has to be confirmed on a later tick, and any of them can fail. A Loadout does all of them in order. Your plugin sets what the player should wear and carry, and calls run once per tick until it is done.

The goal is fixed when you make the loadout, and a goal it cannot read raises then, so a typo cannot silently leave an item out of the goal and get it deposited.

Its run returns (RunStatus, string?), like every state machine, so it stacks with your own machines and with a webwalk.

The goal

bank:newLoadout(equipment, inventory) takes what to wear and what to carry. Everything else carried is deposited. Each side is a goal string or rows:

SideAs a stringAs rows
Worn"itemId:quantity" entries, comma separated, with an optional third field for stackable ammo: "4151:1,892:300:50". A "slot:empty" entry keeps a slot empty: "4151:1,shield:empty".Rows of { itemId, quantity?, lowAmountThreshold? }, or { emptySlot = "shield" } for a slot to keep empty. quantity is more than 1 only for stackable ammo.
Carried"itemId:quantity" entries, comma separated: "385:20,2434:4".Rows of { itemId, quantity }, or { kind = "anyOf", items = { ... } } for any one of several. quantity is a whole number, "all", or "=n" for exactly n.
-- Goal strings: itemId:quantity, comma separated. Worn: an abyssal whip, and rune
-- arrows with a third field, the count below which run returns "blocked".
-- Carried: 20 sharks and 4 prayer potions.
local MELEE = bank:newLoadout("4151:1,892:300:50", "385:20,2434:4")

-- The same kind of goal as rows, with ItemID constants and an alternative.
local RANGED = bank:newLoadout({
    { itemId = ItemID.MAGIC_SHORTBOW },
    { itemId = 892, quantity = 500, lowAmountThreshold = 100 },
}, {
    { itemId = ItemID.SHARK, quantity = 10 },
    -- Either potion will do.
    { kind = "anyOf", items = {
        { itemId = ItemID._4DOSEPRAYERRESTORE, quantity = 2 },
        { itemId = ItemID._4DOSE2RESTORE, quantity = 2 },
    } },
    { itemId = ItemID.COINS, quantity = "all" },
})

A slot the worn goal does not name is left as it is. To have one emptied, name it as empty, and whatever is worn there goes to the bank. An item the goal wears stays on, whatever its slot says.

A stackable ammo row's threshold sets when to stop: if fewer than its quantity can be had, and no more than the threshold are left worn, carried and banked together, run returns blocked. Above the threshold, the trip goes ahead with what there is.

A goal it cannot read raises: a malformed entry, a row without a quantity, an unknown field, a quantity that is not a whole number, "all" or "=n".

Making a loadout reads no game state, so make it once and keep it. The main chunk may make one, though it cannot use the rest of bank.

Run it

run() advances the trip one step and returns its status.

StatusMeans
runningIt acted, or is waiting for its last click to land. Call run again next tick.
doneThe goal is worn and carried, with the bank open. Stop calling run: with the bank shut, a further call opens it again.
blockedNo bank is in range, or the goal cannot be met from the bank, the inventory and what is worn. reason names which. It stays blocked until the goal is met or you call reset().
-- Made once, when the plugin loads: making it reads no game state.
local trip = bank:newLoadout("4151:1", "385:20,2434:4")

function plugin:onGameTick(_event: GameTick)
    local status, reason = trip:run()
    if status == "done" then
        -- Worn and carried, with the bank open. Stop calling run: with the bank
        -- shut, a further call opens it again.
        enabled = false
    elseif status == "blocked" then
        -- No bank in range, or the bank and the player do not hold the goal.
        -- It stays blocked until the goal is met or trip:reset().
        log:warn("cannot finish the trip: {}", reason)
        enabled = false
    end
    -- "running": it acted, or is waiting for its last click to land.
end

A loadout never returns idle, which is for machines that run on a policy, such as loot. Called from renderOverlay, which cannot act, run returns blocked and leaves the trip as it was.

Read without acting

These return without acting, for a panel, a log, or deciding whether to go to the bank at all.

CallReturns
isReady()Whether the player already wears and carries the goal, so no bank trip is needed. It works with the bank shut. With the bank open it is also false while something unwanted is carried.
isAvailable()Whether the goal could be made from what the player has and the open bank holds. false whenever the bank is shut: open it first.
deficit()What the carried goal still lacks or has too much of, as rows: withdraw, fill (all the bank holds, up to the free slots) or deposit, with an item and an amount.
step()The step it is on, such as "bankClosed" or "executeSchedule", for a status line.
intent()A description of what run would do next, for a log. The wording may change.
if trip:isReady() then
    panel:label("Ready: no bank trip needed")
elseif bank:isOpen() and not trip:isAvailable() then
    panel:label("The bank cannot supply this trip")
else
    panel:label(`{trip:step()}: {trip:intent()}`)
end
for _, need in trip:deficit() do
    panel:label(`{need.kind} {need.amount} x {need.itemId}`)
end

Let the player choose

Players build loadouts in the Loadouts plugin. A config item of type "loadout" shows a picker over the ones they saved, and your config reads it back as a ConfigLoadout, or nil when none is picked. Its fields are in the shapes the calls take, so your plugin passes them on and never reads inside a loadout.

FieldHolds
nameWhat the player called it.
equipmentThe worn goal, ready for bank:newLoadout.
inventoryThe carried goal, ready for bank:newLoadout.
runePouchWhat the rune pouch should hold, ready for runePouch:fillFromBank.
autocastThe spell to autocast, ready for magic:setAutocast. nil when the loadout sets none.
local TripConfig = ConfigGroup("bosstrip", {
    ConfigItem {
        keyName = "trip",
        name = "Trip",
        description = "What to wear and carry",
        type = "loadout",
    },
})

local plugin = Plugin.new({ name = "Boss Trip" })
local config = configManager:getConfig(TripConfig)

local picked: ConfigLoadout? = nil
local trip: Loadout? = nil

local function choose()
    -- The loadout the player picked, or nil when they have picked none.
    picked = config:trip()
    trip = if picked then bank:newLoadout(picked.equipment, picked.inventory) else nil
end

function plugin:startUp()
    choose()
end

function plugin:onConfigChanged(event: ConfigChanged)
    if event:getGroup() == "bosstrip" then
        choose()
    end
end

The rune pouch

player:magic():runePouch():fillFromBank(runes) makes the pouch hold at least amount of each rune, one step a call, with the bank open. It opens the pouch, empties it if it holds a rune the list does not want or has no room for one that it does, withdraws all of each missing rune into it, and closes it. It leaves the bank open.

  • done: the pouch holds them, and its interface is shut.
  • running: a click was queued. Call again next tick.
  • blocked: the bank is not open, no pouch is carried, or the bank lacks a rune. reason names which.

missing(runes) returns which runes the pouch is short of, and contents() what a spell can draw on now.

local RUNES = {
    { rune = Rune.LAW, amount = 500 },
    { rune = Rune.WATER, amount = 1000 },
}

-- With the bank open: one step a call. "done" once the pouch holds the runes and
-- its interface is shut. The bank stays open.
local function fillPouch(): (RunStatus, string?)
    return player:magic():runePouch():fillFromBank(RUNES)
end

-- Anywhere: which runes the pouch is short of.
function plugin:sidePanel(panel: Panel)
    for _, rune in player:magic():runePouch():missing(RUNES) do
        panel:label(`short of {rune}`)
    end
end

A whole trip

This is src/main.luau in full: it gets ready for a trip from the loadout the player picks, in four steps that each return (RunStatus, string?).

--!strict

-- Gets ready for a trip from the loadout the player picks in the plugin's
-- settings: wear and carry it, fill the rune pouch, close the bank, set the
-- autocast. Every step returns (RunStatus, string?), and so does prepare.

local TripConfig = ConfigGroup("tripprep", {
    ConfigItem { keyName = "trip", name = "Trip", description = "What to take", type = "loadout" },
})

local plugin = Plugin.new({ name = "Trip Prep", description = "Gets ready for a trip." })
local config = configManager:getConfig(TripConfig)

type Phase = "loadout" | "pouch" | "close" | "autocast" | "ready"

local picked: ConfigLoadout? = nil
local trip: Loadout? = nil
local phase: Phase = "loadout"

local function choose()
    picked = config:trip()
    trip = if picked then bank:newLoadout(picked.equipment, picked.inventory) else nil
    phase = "loadout"
end

local function prepare(): (RunStatus, string?)
    local loadout, machine = picked, trip
    if loadout == nil or machine == nil then
        return "blocked", "pick a loadout in the plugin's settings"
    end
    if phase == "loadout" then
        local status, reason = machine:run()
        if status ~= "done" then
            return status, reason
        end
        -- Worn and carried with the bank open: on to the pouch, and no more
        -- calls to run, which would open the bank again once it is shut.
        phase = "pouch"
    end
    if phase == "pouch" then
        if #loadout.runePouch > 0 then
            local status, reason = player:magic():runePouch():fillFromBank(loadout.runePouch)
            if status ~= "done" then
                return status, reason
            end
        end
        phase = "close"
    end
    if phase == "close" then
        if bank:isOpen() then
            bank:close()
            return "running", "closing the bank"
        end
        phase = "autocast"
    end
    if phase == "autocast" then
        if loadout.autocast then
            local status, reason = player:magic():setAutocast(loadout.autocast)
            if status ~= "done" then
                return status, reason
            end
        end
        phase = "ready"
    end
    return "done", nil
end

local enabled = false
local status: RunStatus = "idle"
local reason: string? = "paused"

function plugin:startUp()
    choose()
end

function plugin:onConfigChanged(event: ConfigChanged)
    if event:getGroup() == "tripprep" then
        choose()
    end
end

function plugin:onGameTick(_event: GameTick)
    if not enabled then
        return
    end
    status, reason = prepare()
    if status == "done" or status == "blocked" then
        enabled = false
    end
end

function plugin:sidePanel(panel: Panel)
    panel:heading("Trip Prep")
    panel:label(status .. ": " .. (reason or ""))
    if panel:button(if enabled then "Pause" else "Start") then
        enabled = not enabled
        if enabled and trip then
            -- A blocked trip stays blocked until the goal is met or it is reset.
            trip:reset()
            phase = "loadout"
        end
    end
end

return plugin
  • The loadout comes first. Once run returns done, the plugin moves on and never calls it again, so closing the bank does not open it again.
  • The pouch fills with the bank still open, since that is what fillFromBank needs. Then the plugin closes the bank and sets the autocast.
  • Blocked stops it. Start again after fixing what reason named: the Start button resets the trip, because a blocked trip stays blocked until then.
  • A new pick is a new trip. onConfigChanged makes the loadout again from the player's new choice.