Getting started

1. Add the repository

The Maven repository serves versioned release artifacts. In your existing Minecraft mod project:

repositories {
    maven {
        url = uri("https://miyomiyo-mods.pages.dev/maven")
        content { includeGroup("dev.miyomiyo.navi") }
    }
}

Choose one loader artifact for each client module:

With Fabric Loom:

dependencies {
    modImplementation "dev.miyomiyo.navi:navi-fabric:1.0.0"
}

With NeoForge ModDevGradle (1.21.1 shown):

dependencies {
    implementation "dev.miyomiyo.navi:navi-neoforge:1.0.0"
}

These are the actual released mod JARs. Use your project's Minecraft toolchain and mappings. Do not shade them or add them with Loom's include. For a common module that only needs Minecraft-independent DTOs, use compileOnly "dev.miyomiyo.navi:navi-api:1.0.0". That small API JAR is not a playable mod, does not contain NaviClient, and should not be installed beside Navi.

2. Declare the client dependency

The mod ID is navi. Declare a required or optional client dependency in your loader metadata. In an optional integration, check the loader's mod list before loading any class that references Navi, and put that code in a separate adapter. A conditional around a method call alone is not sufficient to isolate class loading. Do not invoke client-only code on a dedicated server.

3. Start after joining a world

Call from the Minecraft client thread. NaviClient.ready() reports whether Navi has an attached world; it does not reserve the service.

var request = NavigationRequest.builder(
    new NavigationRequest.Location(
        WorldPosition.block("minecraft:overworld", 100, 64, 200)))
    .name("Home")
    .build();

var result = NaviClient.navigation().start("example_mod", request);
if (result instanceof NavigationResult.Success<Navigation> success) {
    Navigation navigation = success.value(); // Keep this in your world-session adapter.
} else if (result instanceof NavigationResult.Failure<Navigation> failure) {
    // Present an appropriate state in your mod. BUSY does not authorize takeover.
}

Imports come from dev.miyomiyo.navi.api.* and dev.miyomiyo.navi.client.NaviClient. WorldPosition.block centers X/Z within the block; Y is the player's feet position, not eye height.

A successful start acknowledges the request. The path may still be computing. Subscribe with observe to follow its progress. See the complete example and lifecycle rules before adding persistence or asynchronous investigation.

Settings

On the client thread, NaviClient.openSettings(parentScreen) opens Navi's own settings screen. Adjust route preferences, appearance, and CPU and memory usage there; requests express the player's destination and journey. Navi's settings shortcut is unbound by default.