PathQuery

Methods
14
Fields
None

Getting one

PathQuery.between(…)
PathQuery.plan(…)
PathQuery.toNearestBank(…)

Methods

MethodReturnsDescription
isDone()booleanWhether the server has answered (or the request failed).
reached()booleanWhether the server found a route to the target; false while waiting.
problem()string?Why there is no route, or nil: the server's termination reason ("NO_BOAT", "CUTOFF_REACHED"), the code of a request it refused (`"UNK…
durationTicks()number?Estimated travel ticks (every step's ticks summed), or nil.
destination()WorldPoint?Where the route ends (the bank tile for toNearestBank, the target reached for plan), or nil until answered.
start()WorldPoint?Where the route begins (for plan, the cheapest of its starts), or nil until a route is found.
cost()number?The route's cost as the path server counts it (tiles walked plus each transport's ticks), plus the start's own cost for plan; nil until…
steps(){ RouteStep }?The route, one step at a time, or nil until a route is found. A walk step is a stretch between the server's waypoints, not every tile wal…
between(WorldPoint, WorldPoint, RouteOptions?)PathQuerySends the route question from from to to, with config (or the webwalker's own settings), and answers on a later tick. Raises when fou…
plan({WorldPoint}, {number}?, {WorldPoint}, RouteOptions?)PathQueryThe cheapest route from any of starts (each costing startCosts[i] first, 0 where startCosts is shorter or nil: a teleport's landing…
toNearestBank(RouteOptions?)PathQueryThe route from the player to the bank nearest by path, answered on a later tick; its destination() is the bank tile.
toDock(number, DockOptions?, RouteOptions?)PathQueryThe route from the player to a Sailing dock with the boat (walk to a dock where one of the player's boats is moored, board it, sail, and di…
toSea(WorldPoint, SeaOptions?, RouteOptions?)PathQueryThe route from the player to open sea with the boat (walk to a dock where one of the player's boats is moored, board it, and sail; started…
seaCosts({number}, {WorldPoint}?, SeaCostOptions?)SeaCostQueryFrom one place, for one boat, the cheapest sail to each of docks (their berths) and then each of tiles (any sea tile within `options.wi…

Returned by

MethodReturnsDescription
PathQueryClass.betweenPathQuerySends the route question from from to to, with config (or the webwalker's own settings), and answers on a later tick. Raises when fou…
PathQueryClass.planPathQueryThe cheapest route from any of starts (each costing startCosts[i] first, 0 where startCosts is shorter or nil: a teleport's landing…
PathQueryClass.toDockPathQueryThe route from the player to a Sailing dock with the boat (walk to a dock where one of the player's boats is moored, board it, sail, and di…
PathQueryClass.toNearestBankPathQueryThe route from the player to the bank nearest by path, answered on a later tick; its destination() is the bank tile.
PathQueryClass.toSeaPathQueryThe route from the player to open sea with the boat (walk to a dock where one of the player's boats is moored, board it, and sail; started…

Method details

isDone

isDone: (PathQuery) -> boolean

Whether the server has answered (or the request failed).

reached

reached: (PathQuery) -> boolean

Whether the server found a route to the target; false while waiting.

problem

problem: (PathQuery) -> string?

Why there is no route, or nil: the server's termination reason ("NO_BOAT", "CUTOFF_REACHED"), the code of a request it refused ("UNKNOWN_DOCK", "INVALID_REQUEST"), else the failure in words.

destination

destination: (PathQuery) -> WorldPoint?

Where the route ends (the bank tile for toNearestBank, the target reached for plan), or nil until answered.

start

start: (PathQuery) -> WorldPoint?

Where the route begins (for plan, the cheapest of its starts), or nil until a route is found.

cost

cost: (PathQuery) -> number?

The route's cost as the path server counts it (tiles walked plus each transport's ticks), plus the start's own cost for plan; nil until a route is found.

steps

steps: (PathQuery) -> { RouteStep }?

The route, one step at a time, or nil until a route is found. A walk step is a stretch between the server's waypoints, not every tile walked. A transport step says what fires it: option on one of itemIds (ItemHandle:interact(option)), or option on objectId (TileObject:interact(option)); Webwalk:start runs a whole route itself.

local steps = q:steps()
if steps then
    local transports = 0
    for _, step in steps do
        if step.kind == "transport" then transports += 1 end
    end
end

plan

plan: ({WorldPoint}, {number}?, {WorldPoint}, RouteOptions?) -> PathQuery

The cheapest route from any of starts (each costing startCosts[i] first, 0 where startCosts is shorter or nil: a teleport's landing tile with its extra cost, the player's tile with 0) to whichever of targets is cheapest to reach (the tiles around an area for "adjacent to"). With config's planned inventory the server plans as if those items were held, so the transport steps of steps() are the teleports and transports to bank for; start() is the chosen start, cost() its cost plus the route's. The full catalogue (every teleport the items could pay for) stays on the path server; the transports a plan may use are config's transport types, not a caller-given list. One request per distinct start, at most 16, answered on a later tick; raises for no start, no target, more than 16 starts, or when four queries are already running.

Example
local query: PathQuery? = nil

function plugin:startUp()
    local here = player:tile()
    if here == nil then
        return
    end
    -- Plan as if a games necklace were carried, so the route may teleport with it.
    local options = RouteOptions.defaults()
    options:setPlannedInventory({ GAMES_NECKLACE })
    query = PathQuery.plan({ here }, nil, { GOAL }, options)
end

function plugin:onGameTick(_event: GameTick)
    if query and query:isDone() then
        for _, step in query:steps() or {} do
            if step.kind == "transport" then
                -- What the trip needs: bank for these before setting out.
                log:info("{} ({})", step.name, table.concat(step.itemIds, ", "))
            end
        end
        query = nil
    end
end

toNearestBank

toNearestBank: (RouteOptions?) -> PathQuery

The route from the player to the bank nearest by path, answered on a later tick; its destination() is the bank tile.

toDock

toDock: (number, DockOptions?, RouteOptions?) -> PathQuery

The route from the player to a Sailing dock with the boat (walk to a dock where one of the player's boats is moored, board it, sail, and disembark unless stayAboard), answered on a later tick. Whether the player can make the trip: problem() is "NO_BOAT" (no usable boat), "BOAT_UNREACHABLE" (no sea route fits one, or a dock's level or quest), "UNKNOWN_DOCK" (the path server has no data for the dock) or "CUTOFF_REACHED". Raises for an id outside 0 to 60, as Webwalk:startDock.

toSea

toSea: (WorldPoint, SeaOptions?, RouteOptions?) -> PathQuery

The route from the player to open sea with the boat (walk to a dock where one of the player's boats is moored, board it, and sail; started aboard, the boat the player is on), ending aboard on a sea tile within within tiles of tile (2 when left out, at most 64), answered on a later tick. destination() is where the route ends. Whether the player can make the trip: problem() is "NO_BOAT" (no usable boat), "BOAT_UNREACHABLE" (no sea route fits one: its width, a hazard it does not resist, or no sea tile within reach of tile) or "CUTOFF_REACHED". Raises for a within outside 0 to 64, as Webwalk:startSea.

seaCosts

seaCosts: ({number}, {WorldPoint}?, SeaCostOptions?) -> SeaCostQuery

From one place, for one boat, the cheapest sail to each of docks (their berths) and then each of tiles (any sea tile within options.within of it, 2 when left out), in that order, answered on a later tick: the path server floods the sea once, with a route's moves, hazards and costs, and times each sail at the boat's live pace (the side panel aboard, a moored boat's parts ashore). What to order stops by, a courier's docks or a charting tour's spots, without a route request per pair. The sail starts at options.fromDock's berth or options.from, else where the boat is (aboard, or its dock); the boat is options.boat (a slot, 1 to 5), else the one aboard, else the lowest-slot boat moored at a dock. options.maxCost stops the flood past that route cost. Raises for a dock outside 0 to 60, a within outside 0 to 64, no target or more than 256, or when four queries are already running; counts as one of them.

local q = PathQuery.seaCosts({ 1, 23 }, nil, { fromDock = 0 })
-- on a later tick
local costs = q:isDone() and q:costs()
if costs and costs[1].reached then log:info(`{costs[1].ticks} ticks to The Pandemonium`) end