Pathfinding

Entity navigation for Minestom


Report Bug · Request Feature

About The Project

A standalone, deterministic entity-navigation library for Minestom.

Path computation is independent of entities, instances, schedulers, and ticks. It uses real block collision shapes, immutable results, and hard search limits, and is safe to call concurrently: a pathfinder holds no mutable search state.

Supported navigation modes, modeled from Minecraft 26.2:

• Ground
• Water
• Flying
• Amphibious
• Wall-climbing

Platform jumping, planned climbing, block manipulation, and shared-mesh planning are opt-in and never inferred from terrain.

Getting Started

A full, runnable example server can be found here

One NavigationSystem per server, one controller per mob, and you call tick():

// Once per server.
NavigationSystem navigation = NavigationSystem.create();

// Once per mob.
EntityNavigationController controller = navigation.controller(mob);
controller.moveTo(destination);

// Every tick, from the entity or instance tick thread.
controller.tick();

// When the mob despawns, and at shutdown.
controller.close();
navigation.close();

Searching happens off the tick thread, following happens on it, and you never wait for a path. moveTo is cheap enough to call every tick: the mob keeps its current route until the replacement lands, so a chased target never stands still.

controller.state() reports progress: COMPLETED arrived, PARTIAL ran out short of the goal, STUCK cannot walk the route it has.

That is the whole everyday API; see the wiki.

Adding as a dependency

Add the following to your build.gradle.kts file:

repositories {
    maven("https://reposilite.atlasengine.ca/public")
}

Add the library as a dependency

dependencies {
    implementation("ca.atlasengine:pathfinding:<version>")
}

The lastest version number can be found here

Demo server

../Minestom/gradlew runExamples

Join localhost:25565 in offline mode and type /nav: walk, chase, jump, doors, climb, swim, fly, custom, crowd <n>, shed, metrics, stop. Each teleports you to a course and spawns the mobs for that capability.

Documentation

The wiki starts with the simplest use and goes deeper: Getting Started, Reacting to Navigation, Seeing the Path, Zones and Influences, Jumping, Climbing and Doors, Custom Mobs, Terrain and World Changes, Planning Without the Follower, Running at Scale, Shared Mesh.

(back to top)