Pathetic 🥀

The pathfinding library that's too good for this pathetic world.

“I used to use library X… then I tried Pathetic and suddenly my server stopped crying.”
— every future user, probably

Listen up, peasants

It exists for one simple reason: The rest of the Java pathfinding world collectively shits itself above a few hundred concurrent requests.

All demos from a real Paper server.
Minecraft is a pathfinding hell — Pathetic just walked in, pissed on Hades' leg, and asked for a lighter.

Most libraries need minutes or give up entirely on paths longer than 1000 positions.
Pathetic does 20 000 in the time you need to blink twice.
You're welcome.

Drop-in and watch the magic

<dependencies>
    <dependency>
        <groupId>de.bsommerfeld.pathetic</groupId>
        <artifactId>engine</artifactId>
        <version>LATEST</version>
    </dependency>
    <dependency>
        <groupId>de.bsommerfeld.pathetic</groupId>
        <artifactId>api</artifactId>
        <version>LATEST</version>
    </dependency>
</dependencies>

implementation("de.bsommerfeld.pathetic:engine:LATEST")
implementation("de.bsommerfeld.pathetic:api:LATEST")

Pathfinder pf = factory.createPathfinder(config);

pf.findPath(start, goal, context).thenAccept(result -> {
    if (result.state() == FOUND) moveThatEntity(result.path());
});

Features that hurt other libraries' feelings

• Hand-rolled primitive binary min-heap that makes FibonacciHeap look like a participation trophy
  → Zero allocations, perfect cache locality, O(log n) decrease-key that’s faster in practice than every “amortized O(1)” heap in the Java ecosystem.
  → Two contiguous primitive arrays + fastutil Long2IntOpenHashMap. Your CPU prefetcher just sent us a thank-you note.
• Bloomfilter first-line-of-defense → closed-set lookups go from "please wait"(O(n)) to "already done"(O(1))
• Composite Heuristics from Hell™ – Manhattan + Octile + real perpendicular deviation + height penalty, all weighted, all running in parallel. Choose linear (accurate as fuck) or squared (2–3× faster, still consistent). One heuristic? Adorable.
• Perpendicular tie-breaking → paths so straight your NPCs look like they're cheating
• Processor pipeline → walking, swimming, flying, restricted areas - just drop a lambda, peasant
• Pure Java 8+ → works on your grandma's server and still murders modern rigs
• 100 % async & concurrent → because blocking the main thread is for libraries that hate their users
• [X: 26 bit] [Z: 26 bit] [Y: 12 bit] → One primitive long. No more millions of BlockPos objects crying for GC. Supports coordinates up to ±33,000,000. Zero allocations, zero tears.
• We use LongOpenHashSet. That means ~6 bytes per closed node instead of 64+ bytes of boxed Java sadness. At 500k nodes, that’s 30-40 MB of saved heap that the "competition" just hands straight to the Garbage Collector.

Yeah but how is it actually this fast?

We used to use FibonacciHeaps like all the other “serious” libraries.
It was fine.
It was fast enough.
It was also allocating objects like a crypto miner on Christmas.

So we took it out back and replaced it with a hand-rolled, array-backed, zero-allocation primitive binary heap.

What changed?

Result: 10 000 concurrent pathfinds now finish before you can blink.

We kept the old FibonacciHeap code in a branch called archaeology.

We could’ve called it HyperQuantumPathUltra Enterprise God Mode Edition™

We called it Pathetic instead.
Because that’s what every other library became the moment we released this.

Some say "this README reads like they belong in a hospital."
And you're goddamn right.

Hang out with us

Wiki – for mortals who still read docs
Discord – come cry or worship
Issues, PRs, death threats → right here: https://github.com/bsommerfeld/pathetic/issues

Powered by JetBrains (they saw the name and still sponsored us – legends recognize legends ❤️)