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.

CallWalks 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.

stateMeans
idleNo walk since the last stop().
runningThe route is being walked. step describes the current step.
arrivedThe destination was reached.
closestNo 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.
failedA failure ended the walk. failure is the code and reason the description. The state stays failed until stop() or the next start.
FieldHolds
stateOne of the five states above.
failureA failure code, below. nil unless state is "failed".
reasonA description of the failure, or why the walk stopped short. nil when there is neither.
stepA description of the current step. nil unless a route is being walked.
destinationThe 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
end

snapshot() 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
end

Stop 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
SetterEffect
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.

failureWhat happenedWhat to do
NO_ROUTENo 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_UNAVAILABLEThe path server did not answer, after the walk asked several times.Try again later.
STUCKThe 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_ITEMSA 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_ROOMA bank stop had no inventory room for what the route needs.Free some slots.
WILDERNESS_REFUSEDThe game asked to confirm entering the Wilderness, and the walk's options avoid it.Allow it with setAvoidWilderness(false), or go somewhere else.
STEP_FAILEDA step, such as a door, a transport or a bank stop, still failed after its retries.reason names the step.
HELD_TOO_LONGSomething 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_BOATNo 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_UNREACHABLEThe 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_HANDThe player holds a cargo crate aboard a boat with no crew to sail it.Put the crate down, then start again.
UNKNOWN_DOCKThe 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}`
end

Ask 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