Webwalking
player:webwalk() returns your plugin's webwalk, which walks the player to a tile anywhere in the world along a route from a path server.
Why webwalk
player:walkTo(tile) walks to a tile in the loaded scene, the part of the world around the player. A webwalk also reaches tiles outside it. It asks a path server for a route and follows it: walking, opening doors, climbing ladders, taking boats and teleports, and stopping at a bank for what a later step needs.
A route may also go by sea in the player's own boat: walk to a dock where one is moored, board it, sail, and disembark at a dock the player has the Sailing level and quests for. The boat stays moored where the route went ashore. setTransport("BOARD_BOAT", false) keeps a walk on land.
Your plugin gives the destination and reads the walk's status. The walk gets the route, clicks the doors and deals with a door that does not open. It keeps its route, and plans again only when the player is off the route or has stalled, or a step fails.
The walk turns run on by itself on any walk, not only in a fight. Each walk picks a run energy between 5% and 50%, and turns run on once the player has that much. While an NPC is targeting the player, it also waits for the run floor: setRunFloor in the walk's options, or with none the player's webwalker setting, 50% unless they changed it. It never turns run off. With stamina potions on, it drinks a stamina or energy potion on the way when run energy is low.
player:webwalk() returns the same webwalk from any callback. A plugin has only one, so you do not need to store it. The walk waits while the player is logged out and through a Humanizer pause.
Start a walk
Each of these returns at once, and the walk begins on the ticks that follow. Each takes route options as its last argument.
| Call | Walks to |
|---|---|
start(tile, options?) | Walk to a tile. Calling it again with the same tile keeps the current route; another tile replaces it. If the tile cannot be stood on, the walk ends beside it. |
startTiles(tiles, options?) | Walk to whichever of several tiles is cheapest to reach, chosen when the first route is planned. Raises for no tile, or more than 256. |
startObject(tile, id, options?) | Walk to one object, such as one staircase among several. The route goes through that object. |
startNearestBank(options?) | Walk to the nearest bank, chosen when the first route is planned. |
startDock(dockId, { stayAboard }?, options?) | Sail to a Sailing dock with the player's boat: walk to a dock where one of their boats is moored, board it, sail there, and disembark. { stayAboard = true } ends aboard, at the dock's berth. Started aboard, the boat the player is on sails. dockId is a Dock.id from player:sailing():docks(), 0 to 60. Another number raises. |
walk:start(TILE)
walk:startTiles({ WorldPoint.new(3185, 3436, 0), WorldPoint.new(3253, 3420, 0) })
walk:startObject(LADDER_TILE, LADDER_ID)
walk:startNearestBank()If no route reaches the destination, the walk ends on the nearest tile that can be reached when that tile is within 10 tiles of the destination and on its plane, with the state "closest" rather than "failed". Farther, or on another plane, the walk fails "NO_ROUTE". On Karamja with setMaxFare(0) and teleports off, a walk to the mainland fails rather than ending at the island's dock.
Follow it
status() returns the walk's state without advancing the walk, so you can read it on any tick. isWalking() returns only whether a started walk is still under way.
| state | Means |
|---|---|
idle | No walk since the last stop(). |
running | The route is being walked. step describes the current step. |
arrived | The destination was reached. |
closest | No route reaches the destination, and the walk ended on the nearest tile one does, within 10 tiles of the destination and on its plane. reason is why it stopped short. |
failed | A failure ended the walk. failure is the code and reason the description. The state stays failed until stop() or the next start. |
| Field | Holds |
|---|---|
state | One of the five states above. |
failure | A failure code, below. nil unless state is "failed". |
reason | A description of the failure, or why the walk stopped short. nil when there is neither. |
step | A description of the current step. nil unless a route is being walked. |
destination | The tile the walk is going to. For several tiles or the nearest bank, the one chosen when the first route was planned. nil until then. |
To report a walk the way a state machine does, convert its status to (RunStatus, string?):
local GRAND_EXCHANGE = WorldPoint.new(3165, 3487, 0)
-- The walk's status as (RunStatus, string?).
local function travel(): (RunStatus, string?)
local status = player:webwalk():status()
if status.state == "running" then
return "running", status.step
elseif status.state == "arrived" then
return "done", nil
elseif status.state == "closest" then
return "blocked", status.reason or "nothing reaches the Grand Exchange"
elseif status.state == "failed" then
return "blocked", `{status.failure}: {status.reason}`
end
return "idle", "no walk started"
end
function plugin:sidePanel(panel: Panel)
if panel:button("Go to the Grand Exchange") then
-- Returns at once. The walk continues on later ticks.
player:webwalk():start(GRAND_EXCHANGE)
enabled = true
end
end
function plugin:onGameTick(_event: GameTick)
if not enabled then
return
end
local status, reason = travel()
if status ~= "running" then
log:info("{}: {}", status, reason)
enabled = false
end
endsnapshot() returns the route: steps, each a RouteStep with where it starts and ends, what kind it is and what it needs, and index, the step the walk is on, counting from 1. At sea, each "sail" step is one sea tile, and boarding and disembarking are transports. A sea step's sail holds its dock, and for boarding the boat's slot.
Stop it
stop() ends the walk where the player stands: it makes no further clicks, discards the route and sets the state back to "idle". Gear the walk put on for a step, such as a ring to teleport with, stays on.
function plugin:onGameTick(_event: GameTick)
local walk = player:webwalk()
if walk:isWalking() and player:currentHitpoints() <= EAT_AT_HITPOINTS then
-- Ends where the player stands. Start again once the player has eaten.
walk:stop()
end
endStop the walk before your plugin clicks something of its own, such as food, as the example does. The walk's clicks and your plugin's go through the same action queue. A click of yours in the middle of a step, such as a door, a teleport or a dialogue's answers, can make that step fail. The walk then plans again, and a transport that fails twice is left out for the rest of the walk. Start the walk again once the player has eaten. It asks for a new route, because stop() discarded the old one.
You do not need to stop a walk in shutDown: stopping the plugin stops it.
Route options
With no options, a walk uses the player's own webwalker settings. Pass RouteOptions to choose for this walk instead. RouteOptions.defaults() starts from Bento's defaults, not the player's: avoid the Wilderness, every transport, teleport items from the inventory and the bank, bank stops, fares up to 10,000 coins, stamina potions, a run floor of 50, arrive within 1 tile, and the house pool.
-- Bento's defaults, then what this plugin needs. Build it once and reuse it.
local ON_FOOT = RouteOptions.defaults()
ON_FOOT:setUseTeleports(false)
ON_FOOT:setTransport("CHARTER_SHIP", false)
ON_FOOT:setBankStops(false)
ON_FOOT:setArriveDistance(2)
function plugin:startUp()
-- This walk only. Without the second argument it walks with the player's
-- own webwalker settings.
player:webwalk():start(BANK_TILE, ON_FOOT)
end| Setter | Effect |
|---|---|
setAvoidWilderness(on) | Keep out of the Wilderness. |
setUseTeleports(on) | Allow every teleport: spells, items, portals, levers and minigames. |
setTransport(type, on) | Allow or forbid one transport type, such as "FAIRY_RING", "SPIRIT_TREE" or "CHARTER_SHIP". An unknown name raises. |
setTransportCost(type, ticks) | Extra cost, in ticks, the route adds for one transport type. |
setTeleportItems(mode) | Where teleport items may come from, and whether the route may use up ones that run out: "NONE", "INVENTORY", "INVENTORY_NON_CONSUMABLE", "INVENTORY_AND_BANK" or "INVENTORY_AND_BANK_NON_CONSUMABLE". |
setBankStops(on) | Let the walk stop at a bank for what later steps need. |
setMaxFare(coins) | The most one fare or toll may cost. |
setUseStamina(on) | Drink stamina potions on the way. |
setEatFood(on) | Eat on the way, with Bento's own food logic. On unless set off. |
setRunFloor(percent) | The least run energy at which run is turned on while an NPC is targeting the player. At other times the walk turns run on at an energy it picks for itself, between 5% and 50%. |
setArriveDistance(tiles) | How many tiles from the destination count as arrived. |
setUseHouse(on), setHouseFeature(name, on) | Allow the player-owned house's routes, or one feature of it such as "PORTALS" or "POOL". An unknown name raises. |
setAvoidAreas(areas) | Keep routes out of these WorldAreas, such as the ground around aggressive NPCs. It replaces any areas set before, and {} clears them. A walk still reaches a target inside one, and a walk that starts inside one walks out of it. Repeats, areas off the map and any past the 256th are left out. Returns how many areas it kept. |
setPlannedInventory is for a route question only. A walk routes with the items the player holds.
Failure codes
A failed walk has state "failed", a code in failure, and a description in reason. Branch on the code. The description is for a log or a panel, and may change.
| failure | What happened | What to do |
|---|---|---|
NO_ROUTE | No route reaches the destination, or a tile within 10 tiles of it on its plane, or the path server refused the request. When the nearest tile a route reaches is farther off, reason names that tile and how far off it is. | Asking again from the same place does not help. Change the destination or the options. |
SERVER_UNAVAILABLE | The path server did not answer, after the walk asked several times. | Try again later. |
STUCK | The player stopped getting closer along the route, and planning again did not help. | Try again from where the player stands, or walk somewhere near first. |
MISSING_ITEMS | A bank stop could not get an item the route needs, from the bank or the inventory. | Get the item, or set options that keep the route off what needs it. |
NO_ROOM | A bank stop had no inventory room for what the route needs. | Free some slots. |
WILDERNESS_REFUSED | The game asked to confirm entering the Wilderness, and the walk's options avoid it. | Allow it with setAvoidWilderness(false), or go somewhere else. |
STEP_FAILED | A step, such as a door, a transport or a bank stop, still failed after its retries. | reason names the step. |
HELD_TOO_LONG | Something held the walk for 60 seconds: a cutscene, a loading screen, an instance, or the player busy with an animation. | Deal with what holds the player, then start again. |
NO_BOAT | No boat of the player's can make the trip: they own none, none is moored where the route needs one, or the boat the route boards is not there. | Moor a boat where the route can board it. A walk to a tile can go without one: setTransport("BOARD_BOAT", false). |
BOAT_UNREACHABLE | The player has a boat, but no sea route fits it: its size, the seas' hazards, or a dock's Sailing level or quest. Or the boat found no way through at sea. | Pick another dock, or another boat. |
CARGO_IN_HAND | The player holds a cargo crate aboard a boat with no crew to sail it. | Put the crate down, then start again. |
UNKNOWN_DOCK | The path server has no data for the dock asked for. | Asking again does not help. Pick another dock. |
local function afterFailure(status: WebwalkStatus): (RunStatus, string?)
local failure = status.failure
if (failure == "SERVER_UNAVAILABLE" or failure == "STUCK") and not retried then
-- Worth one more try, from where the player stands now.
retried = true
player:webwalk():start(TARGET)
return "running", "trying again"
elseif failure == "MISSING_ITEMS" or failure == "NO_ROOM" then
-- The route needs what the player does not have: change the inventory first,
-- or walk without that transport.
return "blocked", status.reason
end
return "blocked", `{failure}: {status.reason}`
endAsk without walking
PathQuery asks the path server for a route as a walk does, without moving the player, so you can find out how far somewhere is before you go. PathQuery.between(from, to), PathQuery.toNearestBank(), PathQuery.toDock(dockId, ...) and PathQuery.plan(...) each send a request whose result arrives on a later tick: poll isDone(). At most four run at once in the client, and a fifth raises.
toDock takes what startDock takes, and tells you whether the player can sail there. When they cannot, problem() says why: "NO_BOAT", "BOAT_UNREACHABLE" and "UNKNOWN_DOCK" mean what the failure codes above mean.
local query: PathQuery? = nil
function plugin:startUp()
local here = player:tile()
if here then
-- Sent now; the result arrives on a later tick. The player does not move.
query = PathQuery.between(here, GRAND_EXCHANGE)
end
end
function plugin:onGameTick(_event: GameTick)
if query and query:isDone() then
if query:reached() then
log:info("about {} ticks away", query:durationTicks())
else
log:warn("no route: {}", query:problem())
end
query = nil
end
end