Navigation

Moves the character to a point on the current map by itself. It plans a route over the map's platforms, ladders, ropes and portals using the moves your character has (flash jump, up jump, teleport, rope lift), plays it with human-like timing, and replans when the character is pushed off the route.

#Functions

#core.nav.path_to(x: number, y: number, opts?: table) -> boolean, string?

Starts travelling to the map coordinate (x, y) and returns at once; follow the trip with status(). The point can also be passed as a table: core.nav.path_to({x = 1200, y = -85}, opts).

The target is matched to the platform just below the point, or the nearest platform a short way from it, so y can be approximate. Calling path_to() during a trip replaces it.

Returns true when travel started, or false and a reason when it did not:

A trip ends when the character arrives, when no route can be found, and when you call stop(). Changing map or channel, logging out and Panic Mode stop it too. When the character is knocked or falls off the route, navigation plans again from where it lands, up to 4 times per trip; after that the trip fails with too many replans: ... in status().message.

#core.nav.stop()

Stops the current trip and lets go of the movement keys.

#core.nav.is_active() -> boolean

Returns true from a successful path_to() until the trip arrives, fails or is stopped.

#core.nav.status() -> table

Returns what the current or last trip is doing.

A finished trip keeps its arrived or failed status until the next path_to().

#core.nav.plan(x: number, y: number, seed?: number) -> table?, string?

Works out the route to (x, y) without moving, and returns it as a list of steps with a total_seconds field. Returns nil and a reason when there is no route; the reasons are the same as for path_to(), with stand on a platform before planning when the character is not on a platform. The call waits for the route, so on a large map it can take a moment.

#core.nav.get_capabilities() -> table

Returns the movement model routes are planned with. Violet fills it in from the character's job and skills the first time it plans a route.

#core.nav.set_capabilities(caps: table) -> boolean

Changes the movement model. Only the fields you pass change; the rest keep their values. From then on your values are used in place of the ones Violet fills in. Returns true.

#core.nav.get_persona() -> table

Returns the style routes are chosen with. Each time Violet loads it picks a random style, so different characters take slightly different routes.

#core.nav.set_persona(persona: table) -> boolean

Changes the route style. Only the fields you pass change. Returns true.

#core.nav.refresh() -> boolean

Reads the current map's platforms again. Returns true when it succeeded. Navigation reads them by itself the first time it plans on a map, so this is rarely needed.

#Example

-- Walk to a spot, and report how the trip ended
local ok, reason = core.nav.path_to(1200, -85)
if not ok then
    core.log("Can't go there: " .. reason)
end

local reported = false
function on_tick(stage)
    local status = core.nav.status()
    if reported or core.nav.is_active() then return end
    if status.state == "arrived" then
        core.log("Arrived")
    elseif status.state == "failed" then
        core.log("Navigation failed: " .. status.message)
    end
    reported = true
end

-- Preview a route before taking it
local route, reason = core.nav.plan(1200, -85)
if route then
    core.log(string.format("%d steps, about %.1f s", #route, route.total_seconds))
    for i, step in ipairs(route) do
        core.log(string.format("%d. %s to (%.0f, %.0f)", i, step.kind, step.to_x, step.to_y))
    end
else
    core.log("No route: " .. reason)
end