Examples

The downloadable adapter demonstrates start, observation, waypoint refinement and stop. It is compiled against the released API during documentation generation. Its callback is where your mod queues persistence and UI work; it is not a complete loader entry point.

Waypoints and arrival

var request = NavigationRequest.builder(new NavigationRequest.Location(
        WorldPosition.block("minecraft:overworld", 100, 64, 200)))
    .name("Home")
    .waypoints(List.of(new NavigationRequest.PointWaypoint(
        WorldPosition.block("minecraft:overworld", 80, 64, 160), "Entrance")))
    .autoEnd(NavigationRequest.AutoEnd.AUTO)
    .arrivalRadius(3)
    .build();

Supply remaining waypoints in travel order, up to 16. Arrival radius is 0–3 blocks, default 3. AUTO ends at a passable destination; a solid target or entity remains active until stopped. ON and OFF override that policy. The player can still stop through Navi's HUD.

Follow an entity

var request = NavigationRequest.builder(new NavigationRequest.Entity(entityUuid))
    .name("Companion")
    .build();

The entity must be observed when the request starts. If it later leaves observation, guidance retains its last known location. Entity guidance uses walkable routes and cannot include transfer waypoints. If you specify a marker, it must identify the same entity.

A known portal connection

var entrance = new TransitNetwork.Endpoint("village",
    WorldPosition.block("minecraft:overworld", 80, 64, 80));
var exit = new TransitNetwork.Endpoint("nether_hub",
    WorldPosition.block("minecraft:the_nether", 10, 64, 10));
var connection = TransitNetwork.Connection.builder("to_hub",
        new TransitNetwork.FixedSource("village"), "nether_hub", "Enter the portal")
    .seconds(5)
    .evidence(TransitNetwork.Evidence.OBSERVED)
    .availability(TransitNetwork.Availability.AVAILABLE, "")
    .build();
var network = new TransitNetwork(List.of(entrance, exit), List.of(connection));
var request = NavigationRequest.builder(new NavigationRequest.Location(exit.position()))
    .network(network)
    .waypoints(List.of(new NavigationRequest.TransferWaypoint("to_hub", "Village portal")))
    .build();

Connections are directed; register the reverse separately if it exists. The caller supplies evidence and availability. Default availability is UNKNOWN, so declaring a connection does not prove it can be used. Navi gives the supplied instruction and observes travel; it does not operate the device. Networks can contain up to 512 endpoints and 512 connections.

For an item used from the player's current location, use ItemSource(dimension, itemId) instead of FixedSource. Such a transfer must be the first explicit waypoint. Recheck availability after use, including item consumption and cooldown. Known Nether connections can also shorten travel between Overworld locations.

Deliberate excavation

Set .routeStyle(NavigationRequest.RouteStyle.STAIRCASE) for a descending staircase approach, or VERTICAL for an approach above the target followed by descent. Default WALKABLE does not ask the player to dig. Excavation is guidance only; your request should reflect the player's intention to excavate.

Refining a journey

Call navigation.read(), use the returned request revision, and call refine. This preserves the destination and consumed progress. A network update additionally needs the observed network revision. For moving targets, waypoint changes additionally need the observed target revision. The lifecycle guide explains cancellation and stale results.