Navigation

Purpose

This report maps DreamBot walking and NavigationCoordinator behavior to the shared n3 Walker. The full development plan owns module scope and delivery order.

PacketUtilsPlugin owns Walker ticking. The AIO plugin requests routes and retains only the goal or handle that belongs to its active task. It must not add a second pathfinder, Walker tick owner, or movement scheduler.

Coordinate mapping

DreamBot	RuneLite/n3Plugins	Use
Tile(x, y, z)	WorldPoint(x, y, plane)	World navigation and gameplay location.
Area	RuneLite WorldArea, SDK query bounds, or a module-owned polygon/rectangle	Target and arrival policy.
Scene-relative tile	LocalPoint	Canvas and scene calculations only.

Port named locations and areas from old source. Verify coordinates against current RuneLite world data and the module requirement. Do not scatter coordinate literals across state handlers.

Starting and observing a walk

Use the result-aware navigation owner when a workflow needs InteractionResult:

InteractionResult result = NavigationActions.walkNear(destination, 2);
if (result.getStatus() == InteractionStatus.PACED
        || result.getStatus() == InteractionStatus.MOVEMENT_IN_PROGRESS) {
    return CarouselResult.stay("walk_wait", result.getMessage());
}
if (result.accepted()) {
    return CarouselResult.transitionTo(
            State.WAITING_FOR_ARRIVAL,
            "walk_dispatched",
            result.getMessage());
}
return CarouselResult.fail("walk_failed", result.getMessage());

The arrival state checks the module's destination predicate:

• Same plane and within the accepted distance.
• Inside the required WorldArea.
• Required NPC, object, bank, altar, furnace, or range is loaded and reachable.
• A transport-specific destination state has occurred.

Walker.walkTo(...) and walkNear(...) expose the WalkerPath handle for callers that need direct ownership and terminal telemetry. Retain that exact handle and stop it with an ownership-aware API. Do not cancel another plugin's active path.

Walker.isWalking() means a nonterminal shared path exists. It does not prove that the AIO owns the path or reached its destination.

Path and reachability rules

• Global and cross-plane routes belong to Walker and Shortest Path.
• .walkable() on an entity query filters current-scene reachability. It does not decide whether Walker can reach a remote target through doors, stairs, or transports.
• A local NavigationActions.pathTo(...) preview can be empty for a valid global route. Do not use it as a global Walker admission gate.
• QueryResults.nearestTo(...) uses straight-line distance. Use path-aware query terminals or the shared accessible-bank selector where route cost matters.
• DISPATCHED proves that a movement request was accepted. Arrival requires an observed location or domain postcondition.

Current path-related failures include PATH_NOT_FOUND, PATH_EMPTY, MOVEMENT_NOT_QUEUED, MOVEMENT_IN_PROGRESS, and general readiness failures. InteractionStatus.UNREACHABLE does not exist.

Nearest-bank routing

Use BankActions.openNearestAccessible() when the goal is an open bank. That owner selects a catalog-authorized bank with an exact Bank action, a reachable interaction tile, and path-aware routing.

Use AccessibleBankSelector.nearestAccessibleBank(...) or walkNearestBank() only when the workflow needs the bank destination without opening it. A nearest anchor is not proof that the bank interface opened.

Keep the Port Sarim deposit box as a separate deposit-box outcome. Do not model it as an ordinary bank.

Old NavigationCoordinator disposition

The old class combines transport mechanics and AIO policy. Split its responsibilities:

Old behavior	Target disposition
DreamBot Walking.walk, walkExact, and click retry	Delete. Walker owns route planning and movement.
Re-click throttling and no-progress counters	Use Walker terminal state and telemetry. Keep a module-level bound only for failures outside Walker.
Door and stair traversal	Reuse Walker actions and route catalogs. Repair the shared facility when multiple consumers need a missing route.
Lumbridge Castle stair oscillation policy	Verify current Walker behavior. Port the guard only if live or static evidence shows the shared route lacks it.
Al Kharid paid/free gate policy	Preserve toll requirements and postconditions. Put shared transport knowledge in Walker when absent.
F2P boundary enforcement	Preserve as AIO destination validation before requesting a route.
Home-teleport route preference	Reuse shared teleport actions and route options. Port the policy only after comparing current Walker route selection.
Contextual bank selection	Prefer the shared accessible-bank selector. Add AIO policy only for an unmet module requirement.
On-screen versus minimap walking variance	Delete. Packet Utils owns input and humanization.
Building-exit and stuck recovery	Map each observed trap to Walker telemetry or a bounded module recovery. Do not add random fallback walking.

Do not copy the old NavigationCoordinator as one n3 class.

Recovery

Use this recovery order:

1. Inspect the owned Walker handle or current result.
2. If the path remains active, yield without issuing another route.
3. If the path completed, verify the module destination predicate.
4. If the path failed or ended at the wrong postcondition, record terminal telemetry and re-query the intended facility or target.
5. Replan once when current state changed enough to make progress plausible.
6. Use a module-specific alternate location or bank when policy allows it.
7. Block the module after its bounded recovery budget expires.

Reset recovery counters after observed position, plane, route-step, interface, or target progress. Do not reset them because another dispatch was accepted.

Tests

Add focused tests for:

• Same-plane, cross-plane, door, stair, and transport routes.
• A valid global route with no local collision preview.
• AIO-owned path versus a foreign active path.
• Completed, failed, and cancelled Walker terminal states.
• Completed path with missing domain arrival postcondition.
• F2P boundary rejection.
• Paid and free Al Kharid gate paths.
• Lumbridge bank stairs and Port Sarim deposit box.
• Contextual bank selection and inaccessible bank candidates.
• Logout, hop, scene load, stop, and shutdown cleanup.
• Bounded replan, alternate destination, and terminal block.

Static route tests establish planner and state-machine behavior. Live acceptance must observe the character at the intended facility or the requested interface/state after the route.