Interface NavigationAPI

All Known Subinterfaces:
GameAPI
public interface NavigationAPI
Navigation and pathfinding.

One script walks at a time

A client has one character, one position, and one server-side action queue that drains a single action per server tick. Two scripts walking the same character therefore cannot both make progress: their per-tile clicks interleave, neither sees the character move toward its own goal, and both re-plan forever from a position neither predicted. So the character is held by one walker at a time:

  • A walk request from a script while another script is walking is refused. It returns immediately without starting anything, the walk already in progress is left alone, and getWalkStatus() reports "refused_busy" to the script that was refused. It does not queue and it will not be retried for you — decide in your own script whether to wait and ask again.
  • Re-targeting your own walk is always allowed: the walk in flight is cancelled and joined, then the new one starts.
  • walkCancel() only cancels a walk you started. Asking to cancel somebody else's is a no-op, not an error.
  • getWalkStatus() is scoped to the calling script: it reports your walk, or the outcome of your last one — never a sibling script's.
  • The host, and any ManagementScript orchestrating this client, walk with override authority: they may take the character from a script and cancel any walk. This is deliberate — an orchestrator that could not move a character it manages could not do its job.
See Also:

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    clearRegionCache()
    Invalidates all cached region collision data.
    PathResult
    findPath(int toX, int toY)
    Finds a local A* path between the player and a destination.
    PathResult
    findPath(int fromX, int fromY, int toX, int toY)
    Finds a local A* path from a specific origin.
    PathResult
    findWorldPath(int toX, int toY)
    Finds a world-scale path without walking it.
    PathResult
    findWorldPath(int fromX, int fromY, int toX, int toY)
    Finds a world-scale path from a specific origin without walking it.
    int
    getRegionCacheSize()
    Returns the region collision cache size.
    WalkStatus
    getWalkStatus()
    Returns the walker state for the calling script: walking while its own walk is in flight, otherwise the outcome of its last request — arrived, cancelled, failed, refused_busy, or idle if it has never asked for one.
    boolean
    isReachable(int x, int y)
    Checks if a tile is reachable from the player's current position.
    boolean
    isReachable(int x, int y, int maxIterations)
    Checks if a tile is reachable with a custom iteration limit.
    void
    walkCancel()
    Cancels the walk this script started.
    default long
    walkRefusalCount()
    How many of the calling script's walk requests have been refused because another script held the character.
    void
    walkToAsync(int x, int y)
    Starts a local A* walk to the given tile.
    default void
    walkWorldPath(int x, int y, int plane)
    Plane-aware convenience — equivalent to walkWorldPathAsync(x, y, plane).
    void
    walkWorldPathAsync(int x, int y, int plane)
    Starts a world-scale walk using HPA*/flat A* with teleport, door, shortcut, and transport support.
    default void
    walkWorldPathAsync(int x, int y, int plane, boolean exactDestTile)
    Starts a world-scale walk with exact destination tile control.
    void
    walkWorldPathAsync(int x, int y, int plane, boolean exactDestTile, WorldPathConfig config)
    Starts a world-scale walk with full pathfinder configuration.

  • Method Details

    • walkToAsync

      void walkToAsync(int x, int y)
      Starts a local A* walk to the given tile. Returns immediately.

      Refused, silently and without starting a walk, if another script is already walking this character — check getWalkStatus() for "refused_busy".

      Parameters:
      x - target world tile X
      y - target world tile Y

    • walkWorldPathAsync

      void walkWorldPathAsync(int x, int y, int plane)
      Starts a world-scale walk using HPA*/flat A* with teleport, door, shortcut, and transport support. Returns immediately.

      Refused, silently and without starting a walk, if another script is already walking this character — check getWalkStatus() for "refused_busy".

      Parameters:
      x - target world tile X
      y - target world tile Y
      plane - target plane (height level)

    • walkWorldPath

      default void walkWorldPath(int x, int y, int plane)
      Plane-aware convenience — equivalent to walkWorldPathAsync(x, y, plane).

      The no-plane convenience that walks to the local player's current plane lives on GameAPI because it needs getLocalPlayer(), which isn't part of this navigation surface.

    • walkWorldPathAsync

      default void walkWorldPathAsync(int x, int y, int plane, boolean exactDestTile)
      Starts a world-scale walk with exact destination tile control.
      Parameters:
      x - target world tile X
      y - target world tile Y
      plane - target plane (height level)
      exactDestTile - if true, click the exact destination tile

    • walkWorldPathAsync

      void walkWorldPathAsync(int x, int y, int plane, boolean exactDestTile, WorldPathConfig config)
      Starts a world-scale walk with full pathfinder configuration.

      Refused, silently and without starting a walk, if another script is already walking this character — check getWalkStatus() for "refused_busy".

      Parameters:
      x - target world tile X
      y - target world tile Y
      plane - target plane (height level)
      exactDestTile - if true, click the exact destination tile
      config - pathfinder config overrides, or null for defaults

    • walkCancel

      void walkCancel()
      Cancels the walk this script started. A no-op if the walk in progress belongs to another script; the host and management scripts may cancel any walk.

    • getWalkStatus

      WalkStatus getWalkStatus()
      Returns the walker state for the calling script: walking while its own walk is in flight, otherwise the outcome of its last request — arrived, cancelled, failed, refused_busy, or idle if it has never asked for one.

      Never reports a sibling script's walk. The host and management scripts see whichever walk is in progress, whoever started it.

      This is a level, so it cannot on its own tell you whether the request you just made was the one refused — an older refusal reads the same. Use walkRefusalCount() for that.

      Returns:
      the walk status

    • walkRefusalCount

      default long walkRefusalCount()
      How many of the calling script's walk requests have been refused because another script held the character.

      Monotonic and caller-scoped. Read it before a walk request and again after: an increase means that request was refused. This is the reliable way to detect a refusal — getWalkStatus() reports a level, so a refusal left over from an earlier request is indistinguishable from one caused by this one, and a host or management caller sees walking for whatever walk is in progress rather than its own refusal at all.

      Implementations that do not track refusals return 0, which simply reads as "never refused".

      Returns:
      the refusal count for the calling script, never negative

    • isReachable

      boolean isReachable(int x, int y)
      Checks if a tile is reachable from the player's current position.
      Parameters:
      x - target world X
      y - target world Y
      Returns:
      true if the tile is reachable

    • isReachable

      boolean isReachable(int x, int y, int maxIterations)
      Checks if a tile is reachable with a custom iteration limit.
      Parameters:
      x - target world X
      y - target world Y
      maxIterations - max A* iterations
      Returns:
      true if the tile is reachable

    • findPath

      PathResult findPath(int toX, int toY)
      Finds a local A* path between the player and a destination.
      Parameters:
      toX - destination world X
      toY - destination world Y
      Returns:
      the path result

    • findPath

      PathResult findPath(int fromX, int fromY, int toX, int toY)
      Finds a local A* path from a specific origin.
      Parameters:
      fromX - origin world X
      fromY - origin world Y
      toX - destination world X
      toY - destination world Y
      Returns:
      the path result

    • findWorldPath

      PathResult findWorldPath(int toX, int toY)
      Finds a world-scale path without walking it.
      Parameters:
      toX - destination world X
      toY - destination world Y
      Returns:
      the path result

    • findWorldPath

      PathResult findWorldPath(int fromX, int fromY, int toX, int toY)
      Finds a world-scale path from a specific origin without walking it.
      Parameters:
      fromX - origin world X
      fromY - origin world Y
      toX - destination world X
      toY - destination world Y
      Returns:
      the path result

    • getRegionCacheSize

      int getRegionCacheSize()
      Returns the region collision cache size.
      Returns:
      the number of cached regions

    • clearRegionCache

      void clearRegionCache()
      Invalidates all cached region collision data.