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
It exists for one simple reason: The rest of the Java pathfinding world collectively shits itself above a few hundred concurrent requests.
| Scenario | Pathetic | The "competition" | Your tears |
|---|---|---|---|
| 10k concurrent paths | ~7 ms | ~300 ms + | Priceless |
| One 20k distance path | ~60 ms | Minutes, timeout, or suicide | We measured twice |
| CPU when the world burns | <2% on 16 cores | 20–100% or instant OOM | Eco-mode |
| Memory | Spark shows a flat line | Hundreds of MB of GC tears | Spark thinks nothing happened |
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.
<dependencies>
<dependency>
<groupId>de.bsommerfeld.pathetic</groupId>
<artifactId>engine</artifactId>
<version>5.4.6</version>
</dependency>
<dependency>
<groupId>de.bsommerfeld.pathetic</groupId>
<artifactId>api</artifactId>
<version>5.4.6</version>
</dependency>
</dependencies>implementation("de.bsommerfeld.pathetic:engine:5.4.6")
implementation("de.bsommerfeld.pathetic:api:5.4.6")Pathfinder pf = factory.createPathfinder(config);
pf.findPath(start, goal, context)
.ifPresent(result -> {
moveThatEntity(result.path())
}).orElse(result -> System.out.println("No path found!"));- 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 "lemme check"(O(n)) to "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.
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?
| Metric | Old FibonacciHeap | New PrimitiveMinHeap | Your server now |
|---|---|---|---|
| Allocations per run | Objects everywhere | 0 (Zero. Zilch. Nada.) | GC went on vacation |
| Cache efficiency | Pointer chasing hell | Contiguous array bliss | CPU utilization dropped 50 % |
| Benchmark (1k nodes) | Baseline | ~4.5× faster | Teleportation enabled |
| Benchmark (10k nodes) | Baseline | ~3× faster | Your players noticed |
| Large Scale (50k nodes) | Exponential degradation | Linearly stable | The dragon never stood a chance |
Result: 10 000 concurrent pathfinds now finish before you can blink.
We kept the old FibonacciHeap code in a branch called archaeology.
Now Doom isn't the only thing that runs everywhere.
We didn’t build this library to just "run." We trained Pathetic to subjugate your hardware, make your RAM cry, and then politely ask: "Another round?"
While other pathfinding libraries beg for more heap, more cores, and more mercy, while being sorry for being a bad pathfinder, Pathetic puts a belt around your scheduler and whispers: "You’re going to sit still and swallow 20,000 nodes in ~60ms — and you’re going to thank me for it."
Pathetic doesn’t ask your hardware for permission. Your hardware needs permission from Pathetic to send a heartbeat. Welcome to the food chain.
Safe-word? OutOfMemoryError — but you’ll never reach it.
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.
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 ❤️)
Don't be pathetic, use Pathetic. 🥀
Add Powered by [Pathetic](https://github.com/bsommerfeld/pathetic) to your project's page to show dominance.