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>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());
});- 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.
We used to use jheaps FibonacciHeap 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.
We called it Pathetic instead.
Because that’s what every other library became the moment we released this.
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 ❤️)
