PathWeaver

Minecraft works out mob paths on the same thread that runs everything else. This moves that work off it.

Every time a mob decides where to walk, the server thread stops and does the maths. A few hundred mobs deciding at once is a few hundred searches the tick waits for, and that wait is what you feel.

PathWeaver runs those searches on spare cores instead. The mob gets the path it would have got, with a few exceptions listed further down; the tick just stops waiting for it.

What that is worth, measured rather than asserted: about 4 to 12% of server tick time with hundreds to thousands of zombies chasing a player, and a great deal more if your mobs repath constantly. Pathfinding is a few percent of a loaded server's tick, and this moves about three quarters of it off the main thread. The runs behind those figures are linked below.

That is a real saving and it is not a rescue. If your server is at 200 ms a tick, this will not save it, and the page tells you how to find out what your own number is before you install anything.

Free, and it does not change what paths your mobs take.

It needs Fabric API and nothing else. Cloth Config is optional and only draws the settings screen; without it the mod reads and writes the same config/pathweaver.json and behaves the same. A dedicated server never shows a settings screen, so it should never have had to install one.

Why a 6% mod is worth installing

Tick time you get back is budget you can spend. The point of taking a fixed cost off the main thread is not the percentage on its own, it is that the work no longer has to be cheap: once path searches are not blocking the tick, a server can afford more mobs, or more expensive pathfinding, than it could before.

This is the first of a planned set of mods that each take one fixed cost off the tick the same way, measured the same way, so the savings compound instead of competing. Where a thing cannot be moved off the tick safely, we say so rather than shipping it anyway.

Getting started

Most hosts still default to Java 21, so check yours before you file a bug.

Worth ten minutes before you install: is pathfinding actually your bottleneck? This mod only helps a server whose tick time is going into mob path searches, and plenty of struggling servers are slow for some other reason.

It ships with its compatibility checking turned off, which means it runs other mods' pathfinding code on worker threads. Back up worlds you care about, and read Compatibility before you commit a world to it.

What you get

This is spike reduction, not free TPS. A server sitting at "20 TPS" still stutters when one tick in a hundred takes 80 ms, and that is the number this moves. Average throughput only rises when pathfinding alone is already blowing the 50 ms tick budget and you have spare cores.

On a machine with two cores or fewer, PathWeaver tells you at world start to leave it off. At four or fewer it warns the gain will be small. It never switches itself off.

The numbers

Two scenarios, because the honest answer is that it depends on how much pathfinding your server is actually doing, and quoting only the flattering one is how this page used to oversell itself.

A busy server: 4 to 12% of tick time

Zombies chasing a player who is teleported every 11 seconds, so the whole crowd has to find a new route at once, on a 219-mod server, measured on the jar you download. Median tick, the middle of three runs each way:

The run-to-run spread is wider than the gain, because the test machine itself sped up partway through the series, for both arms alike. Compared back to back instead, each run with the mod against the run without it next to it, PathWeaver was faster in every pair from 2500 zombies up.

Why it is that size: in a profile at 5000 zombies, pathfinding was about 6% of server tick time, and PathWeaver moved about three quarters of it off the tick (6.12% to 1.55%). The gain follows from that and could not be much larger. That profile was taken in September, with the zombies wandering rather than chasing.

Mobs that repath constantly: much larger

1024 zombies in a walled maze with the target moving every 6 ticks, so every mob recomputes almost continuously:

This is a deliberately pathfinding-heavy case. It is what a mob farm or a large hostile group tracking a moving player looks like, and if that is your server the first table understates what you get. It is not what an average server looks like, and earlier versions of this page presented it as though it were.

What decides which end you land on

The share of your tick that is pathfinding, and nothing else. docs/IS-IT-YOUR-BOTTLENECK.md is a ten-minute check with spark that tells you your own number before you install anything. If pathfinding is 1% of your tick, this mod can win you at most 1%.

Two things that could make your result differ from ours

Cores. These were measured on a 32-core machine with cores to spare. PathWeaver does not delete work, it moves it: the searches still happen, on worker threads, and the tick stops waiting for them. That trade needs somewhere for the work to go. On a host with 2 to 4 cores and everything else already competing for them, the gain will be smaller than ours, and we have not measured that case. On a machine with more spare cores than ours, it could be larger.

Your mods. Our measurement ran on a 219-mod server, so the denominator includes everything that pack does. A lighter server spends a larger share of its tick on mobs, which moves the percentage up.

Method, settings, controls and the raw rows are in the repository under docs/evidence/perf-2026-10/, with the rules for reading them written down before the first run. If the numbers look wrong, the working is there to check.

What changes about your mobs

Villagers and other brain-driven mobs set off one tick later than they used to. On the tick their search is dispatched their behaviour is told "no path yet", and the route arrives on the next one. Nothing else differs.

That is a real behaviour change, which is why it is a setting rather than something you get regardless. brainSinkAsync=false turns it off. The warden is not covered either way, because its navigation builds a custom pathfinder.

Everything else keeps the path it would have had, with three exceptions. A mob whose target moved by a block or less keeps the path it already has instead of getting a new one: repathToleranceBlocks, 1 by default, and 0 turns it off. Earlier versions of this page left that one out. A shared route is used when route sharing is switched on. And the search runs against the world as it was a tick or two earlier rather than at the instant the mob asks. The first can leave a mob heading for a spot one block from where it was sent; the other two do not change where it is trying to go.

Redoing distant path searches less often

New in 0.9.0, and off by default. When a block changes on the route a mob is walking, the game redoes that mob's whole path search. It already refuses to do this more than once a second for any one mob. But in a place where terrain keeps changing, every mob whose route crosses the change pays that cost, whether or not anyone is near enough to see the result.

lodEnabled widens the limit for mobs beyond 64 blocks from every player: one search every 40 ticks instead of the game's once a second. Both numbers are settings, and anything at or below 21 ticks does nothing at all, because that is the game's own floor.

It ships off because it is the only thing here that keeps a mob walking a route after the ground under it has changed. A throttled mob keeps walking that out-of-date route for longer. Worth turning on for mob farms, penned herds near redstone, or a high simulation distance.

The only number for it is a best case. In a test built to favour it, 400 zombies at least 70 blocks from the player with terrain changing among them all the time, it cut the path searches PathWeaver started by 13 to 19% and did not measurably change tick time. What it saves on your server depends on how much terrain changes around mobs nobody is standing near, and for a mob in quiet surroundings it saves nothing, because the game never redoes its search at all.

Route sharing

One mob can reuse a route another mob already computed, but only when every input to the search is identical: same starting position, same target, same size, same terrain costs, same movement flags. A stored route is dropped when a block changes along it while the cache is running.

One honest limit remains: a block changed away from the route can open a shorter way through that a reused route will not take, which vanilla does not notice either.

The other one is fixed here. In 0.8.0 and 0.8.1, switching route sharing or the master switch off and on again inside a route's two-second lifetime could keep a route across changes made while it was off, because PathWeaver stops watching for block changes with the feature while stored routes lived until the server stopped. Both switches now discard what was learned under the old settings, including searches still in flight.

It ships measuring rather than serving. How often mobs repeat a search depends on your world, not on this mod. On the default setting PathWeaver fills the cache, counts what sharing would have saved, and hands out nothing, so /pathweaver status tells you what it is worth on your server before you spend it. Set resultCacheMode to SERVE when the number justifies it. Takes effect immediately.

On the benchmark the hit rate was 12 to 16%. What that is worth is unresolved, and this page previously said otherwise. The measured difference against the cache switched off was about 3% of sampled pathfinding with the run ranges overlapping, on an arena whose arms did not run identical populations and whose arm order was fixed rather than counterbalanced. That is not enough to establish a saving. The test arena was also 200 mobs walking corridors without stopping, close to the worst case for this feature; mobs that stand still and re-ask are what it helps, and that is not what got measured.

This is the reason it ships measuring rather than serving. /pathweaver status counts what serving would have found on YOUR world, which is a better number than anything here.

Compatibility

The default runs other mods' uninspected pathfinding code on worker threads.

That is deliberate. The checked tier, compatibilityTier=AUDITED, only trusts mods whose bytecode has been audited, and on a real modpack it denies everything and the mod does nothing. Measured on a 221-jar pack: 0 of 187 mob types eligible at that tier, against 184 of 187 at the default. Shipping the safe-looking tier by default would ship something indistinguishable from broken.

What has actually happened so far: this has run on packs of 200 to 371 mods through hundreds of thousands of searches, with no corruption or crash traced to it. That is an absence of reported problems rather than a proof, and it is also what you would see if the failure were rare or quiet. Try it on a world you can throw away.

If something does look wrong, switch to compatibilityTier=AUDITED and report it. Be clear about what that does on a heavy pack: it turns the speed-up off entirely. That is the tier working as designed, not failing. trustedMods is the middle option, naming specific mods you have decided about while the scan keeps checking the rest.

The checked tier depends on which download you have

Each audit is pinned to the exact bytes of the mod and the vanilla classes its proof reads, so a build for one Minecraft version cannot vouch for another. There are three downloads and they differ here:

• The 26.1.2 download, on 26.1.1 or 26.1.2: all seven audits verify.
• The 26.2 download, on 26.2: all seven audits verify, after Lithium and Diagonal Blocks were re-derived against the builds that ship for 26.2.
• The 26.3 download, on 26.3: every audit verifies except Lithium. Lithium's 26.3 build changed code the audit covers, and it is not certified until that change has been checked. With Lithium installed and AUDITED on, PathWeaver stands down rather than run it unchecked.

Install the download that matches your Minecraft version. Install one on a different version and the pins refuse, which turns the speed-up off rather than running anything unchecked.

Either way this only matters if you have opted into AUDITED. The shipped default consults none of it.

Whatever version you are on, mods that modify pathfinding are named at world start, with what PathWeaver decided about each.

Settings

All of them live in config/pathweaver.json. Install ModMenu and Cloth Config if you want to edit them in game instead; neither is required and a server needs neither. The two marked restart are read once at startup; the rest take effect as soon as you save.

Checking it is doing something

/pathweaver status reports what is dispatching, what is landing, and what route sharing would save. /pathweaver mobs lists which of your mob types are eligible.

Route sharing is reported as two numbers rather than one. Searches skipped is searches that did not run, which is the whole saving. Hits that saved nothing is real cache hits with no stored route behind them, which is what you get while the cache is measuring. Before 0.9.0 those were added together under the first label, so the figure you would have used to decide about SERVE was too large.

Eligible means nothing blocks dispatch for that mob, not that every movement it makes goes off-thread. On a 221-jar pack at the shipped default it is 184 of 187; the three held back navigate with a custom pathfinder rather than the stock one.

How many dispatched searches get used depends on load. Roughly 99% on a quiet server, 96% under normal play, about 82% in the saturated 1024-mob benchmark, where the mod deliberately refuses requests rather than queue ones that would land too late to be worth having.

Corrections

Published claims should not quietly change, so here is what was wrong. The raw benchmark artifacts they came from are unchanged in the repository.

Route sharing could keep a route across a settings toggle. Switching it or the master switch off and on again inside a route's lifetime could hand out a route computed before terrain changed while nothing was watching. In 0.8.0 and 0.8.1, reachable from the settings screen with no restart. Fixed in 0.9.0. Only affects you if you turned route sharing on; the shipped default measures rather than serves.

"Searches skipped" was two numbers added together. Cache hits with no stored route behind them skip nothing, and they were counted in the same figure as searches that really did not run. If you read that line in 0.7.0, 0.8.0 or 0.8.1 to decide whether route sharing was worth switching on, the number was larger than the saving. It is now two lines and only the first is a saving.

A setting screen inside the 0.8.x jars says a reused route "is never a stale one". A page edit cannot reach text compiled into a release. 0.9.0 changes it to what holds: a route is dropped when a block changes along it, and a change away from the route is not noticed, as in vanilla.

A permission check that was described but never existed. /pathweaver mobs builds one of every registered mob type to report which are eligible, which takes about a fifth of a second on a large pack, on the server thread. It was meant to need operator level: the source comment said so and the 0.7.0 notes said so. It did not, so any player on any server could run it repeatedly. Fixed in 0.8.1. /pathweaver status stays open to everyone, since that is the one the docs tell you to run. If you host a multiplayer server on 0.7.0 or 0.8.0, this is the reason to update.

"CPU" and "A*". The profiler samples thread stacks every 4 ms and counts how often something is on the stack, waiting included. It does not measure CPU time, and the classifier covers navigation and pathfinding broadly rather than the A* search alone. Figures once labelled "total CPU" and "server-thread A*" are sampled broad pathfinding, relabelled above. The direction and rough size of the villager result survive the relabelling. The words did not.

The route-sharing saving. An earlier version of this page presented about 3% as a measured gain. It is not established. The two arms did not run identical mob populations and the arm order was fixed rather than counterbalanced, so a small difference with overlapping ranges cannot be pinned on the feature. The 12 to 16% hit rate is real; what serving those hits is worth is unknown.

The busy-server benchmark had no player in it. The table on this page used to say "zombies chasing a player", but in those September runs another mod on the test server removed the test player a second after it joined, so the zombies were wandering. The benchmark was re-run on 2026-10-13 with the player staying put and the zombies really chasing, and the table above is that run. The gain is about the same at 500 to 1000 zombies and smaller at 2500 and up: 4 to 5.5% where the old table said 5 to 9%.

What did not change, because it was checked rather than assumed: the mob-eligibility counts, the audit and compatibility behaviour, the tick-interval benchmark, and the fact that every run with the mod on beat every run with it off on that benchmark.

Known limits

The checked tier does not cover Lithium on 26.3, above. Path quality while blocks are being changed underneath mobs is not measured. Behaviour at a thousand mobs or more is not measured.

Full detail, including what was tried and thrown away, is on GitHub: the README, the changelog and the roadmap.