https://github.com/bsommerfeld/pathetic
The Java pathfinder that ended the era of “good enough”
https://github.com/bsommerfeld/pathetic
3d astar java pathfinder
Last synced: 3 days ago
JSON representation
The Java pathfinder that ended the era of “good enough”
- Host: GitHub
- URL: https://github.com/bsommerfeld/pathetic
- Owner: bsommerfeld
- License: mit
- Created: 2022-01-13T19:17:19.000Z (about 4 years ago)
- Default Branch: trunk
- Last Pushed: 2026-01-22T19:53:12.000Z (6 days ago)
- Last Synced: 2026-01-23T12:34:33.858Z (6 days ago)
- Topics: 3d, astar, java, pathfinder
- Language: Java
- Homepage: https://docs.pathetic.site/
- Size: 6.2 MB
- Stars: 237
- Watchers: 6
- Forks: 21
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
- trackawesomelist - Pathetic (⭐208) - A highly configurable 3D A\* pathfinding library that uses specific optimizations for high performance. (Recently Updated / [Jul 27, 2025](/content/2025/07/27/README.md))
- awesome-java - Pathetic - A highly configurable 3D A\* pathfinding library that uses specific optimizations for high performance. (Projects / Pathfinding)
- fucking-awesome-java - Pathetic - A highly configurable 3D A\* pathfinding library that uses specific optimizations for high performance. (Projects / Pathfinding)
README
# Pathetic 🥀
**The pathfinding library that's too good for this pathetic world.**
[](https://github.com/akullpp/awesome-java)
[](https://central.sonatype.com/search?q=de.bsommerfeld.pathetic)
[](https://github.com/bsommerfeld/pathetic/actions)
[](https://github.com/bsommerfeld/pathetic/blob/main/LICENSE)
> “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.
| 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.
### Drop-in and watch the magic
```xml
de.bsommerfeld.pathetic
engine
LATEST
de.bsommerfeld.pathetic
api
LATEST
```
```kotlin
implementation("de.bsommerfeld.pathetic:engine:LATEST")
implementation("de.bsommerfeld.pathetic:api:LATEST")
```
```java
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?
| 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 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](https://github.com/bsommerfeld/pathetic/wiki) – for mortals who still read docs
[Discord](https://discord.gg/zGx9BSzKfJ) – 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 ❤️)
[](https://jb.gg/OpenSource)