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:
| Side | As a string | As 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.
| Status | Means |
|---|---|
running | It acted, or is waiting for its last click to land. Call run again next tick. |
done | The goal is worn and carried, with the bank open. Stop calling run: with the bank shut, a further call opens it again. |
blocked | No 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.
endA 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.
| Call | Returns |
|---|---|
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}`)
endLet 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.
| Field | Holds |
|---|---|
name | What the player called it. |
equipment | The worn goal, ready for bank:newLoadout. |
inventory | The carried goal, ready for bank:newLoadout. |
runePouch | What the rune pouch should hold, ready for runePouch:fillFromBank. |
autocast | The 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
endThe 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.reasonnames 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
endA 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
runreturnsdone, 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
fillFromBankneeds. Then the plugin closes the bank and sets the autocast. - Blocked stops it. Start again after fixing what
reasonnamed: the Start button resets the trip, because a blocked trip stays blocked until then. - A new pick is a new trip.
onConfigChangedmakes the loadout again from the player's new choice.