Pathwright

Pathwright

Mob pathfinding optimization for Minecraft 26.1.2.

Pathwright targets one of the most expensive hot-paths in Minecraft's server loop: mob pathfinding. Every mob that wants to move somewhere has to compute a path — and in vanilla, every single one of those calculations happens on the main server thread, one after another. Pathwright replaces that with a three-layer optimization system. Every layer is independently toggleable, so you can disable anything that conflicts with another mod in a single config line.

---

Summary

The Pathwright mod makes mob pathfinding faster by computing paths smarter. Instead of recalculating every mob's path every tick on the main thread, Pathwright caches paths that have already been computed, offloads path updates to background threads, and slows down path recalculation for mobs that are far away from any player. This keeps your TPS higher and your server loop shorter. The mod is especially helpful on servers with lots of mobs — mob farms, breeders, large group AI — but also makes a noticeable difference in singleplayer and locally hosted worlds where the server and client share the same CPU.

---

Performance Improvements

TPS (Server Ticks Per Second)

Pathwright's optimizations live entirely on the server side. TPS gains depend on how many mobs are loaded and actively pathfinding:

Estimated TPS improvement:

• +1 – 3 TPS in a typical survival world with normal mob counts
• +3 – 8 TPS on mob farms, breeders, or servers with 100+ active pathfinding mobs
• Larger gains the more mobs are far from players (LOD system kicks in)

FPS (Client Frames Per Second)

NB!
FPS improvements will only be seen when the server/world is running on the same computer as the client — for example when hosting a server for you and your friends locally on your PC, or playing singleplayer. When the mod is put on an externally hosted server you will experience that the server runs smoother rather than your client getting higher FPS.

When the server and client share the same CPU:

1. Fewer server lag spikes → smoother animation interpolation
When the server misses a tick (falls below 20 TPS), the client interpolates entity positions incorrectly. Rubber-banding and stuttering trace back to server lag. Pathwright keeps the server at 20 TPS more consistently, which the client experiences as visibly smoother movement even if your GPU FPS hasn't changed.

2. Singleplayer / integrated server
Every millisecond saved in the server tick is a millisecond returned to the render thread. In a typical survival world with mobs:

• Async pathfinding moves path calculations off the main thread entirely
• LOD throttling eliminates redundant calculations for mobs you can't even see

Estimated singleplayer FPS improvement: +2 – 8 FPS at 60 FPS baseline; higher gains on mob-heavy worlds, mob farms, or villager breeders.

---

How Each Optimization Works

Async Pathfinding

In vanilla, when a mob needs a new path — a zombie chasing you, a villager walking home — the entire path calculation runs on the main server thread. This blocks everything else until it's done. In a world with dozens of mobs all trying to recalculate their paths at once, this stacks up fast.

Pathwright offloads path updates to a small background thread pool. When a mob already has an active path and needs to recalculate (for example, you moved and it needs to reroute), the calculation happens off the main thread and the result is applied on the next tick. New paths — when a mob has no path at all and needs to start moving — are still computed synchronously, so mobs start moving immediately without any delay.

Mobs in combat always get synchronous pathfinding. Async is only used for routine movement updates.

Path Result Caching

Many mobs in the same area often travel the same routes — villagers walking between the same workstation and bed, for example. Pathwright caches the results of completed path calculations. If another mob needs to go from the same position to the same destination in the same world state, it reuses the already-computed path instead of recalculating from scratch.

The cache invalidates automatically when blocks change (a door opens, a wall is placed) so cached paths never become stale. Paths to moving targets like players or other mobs are never cached — those change every tick anyway.

Pathfinding LOD (Level of Detail)

Close to players, mobs need accurate, frequently updated pathfinding. Far away from players, it genuinely doesn't matter if a mob updates its path every tick or every 15 ticks — you can't see the difference. Pathwright applies this insight: mobs more than 48 blocks from any player only recalculate their paths every 15 ticks instead of every tick.

Mobs in combat, mobs that were recently hurt, and mobs with no active path are never throttled regardless of distance. LOD only affects routine movement updates on mobs that are already traveling somewhere.

---

Configuration

config/pathwright.json — auto-created with safe defaults on first launch:

{
  "enablePathCaching": true,
  "pathCacheSize": 1024,
  "pathCacheExpiryTicks": 200,
  "enableLOD": true,
  "lodDistance": 48.0,
  "lodTickInterval": 15,
  "enableAsync": true,
  "asyncThreadCount": 2
}

All three modules are independently toggleable. asyncThreadCount defaults to 2 — increasing this helps on servers with many mobs, but don't set it higher than your CPU core count minus 1.

---

FAQ — just that i am answering my own questions heh

Will this change how my mob farms work?
No. Mob behavior, attack AI, breeding, and all gameplay logic is untouched. Pathwright only changes how quickly paths get calculated, not what the mobs decide to do.

Will villager breeders still work?
Yes. Villagers need to reach their beds and workstations to breed. Pathwright ensures mobs with no active path always get immediate pathfinding, so they never get stuck waiting.

Will mobs walking toward me feel different?
No. Mobs targeting a player or entity always get synchronous, uncached, full-speed pathfinding. LOD and async only apply to routine movement — not combat.

Can this corrupt my world?
No. Pathwright never writes block data or modifies world state. It only changes how paths are computed and when.

What if it conflicts with another mod?
Most sertantly wont make conflicts but in the case it does: Disable whichever module causes the conflict in pathwright.json. All three systems are independent — you can run caching only, LOD only, async only, or any combination.