PathWeaver

Minecraft 版本： 26.1.2

平台： fabric

标签： optimization utility

PathWeaver

Moves vanilla mob path searches off the server thread, so pathfinding stops eating your tick.

Minecraft runs every mob's A* path search on the server thread. When a lot of mobs want paths at once — a mob farm, a raid, a busy spawner area — those searches land on the tick and you feel it as stutter. PathWeaver runs eligible searches on a small worker pool instead.

Read this first

PathWeaver ships with its compatibility checking turned off. Out of the box it runs other mods' uninspected pathfinding code on worker threads. Back up worlds you care about.

That is a deliberate choice and the reasoning is in the open. The checked tier, Audited, only honours individual bytecode audits — and on a real modpack that means it denies everything and the mod does nothing. Measured on a 222-mod pack: 0 of 187 mob types eligible at Audited, all 187 at Unsafe. Shipping the checked tier shipped something indistinguishable from broken.

What you are accepting: the most likely failure is quiet — a wrong path, a torn read, which you would probably never report. It is not the only possible one. Nothing has been proven about code that was never inspected, so a crash or a corrupted world is not excluded, only less likely.

Two ways to opt back into checking, both one setting away:

• compatibilityTier=Audited — full checking. Expect it to refuse on a heavy pack; the log names which mods did it.
• trustedMods — the middle option, and the one worth knowing about. Name the specific mods you have decided to run unaudited and the scan keeps working for everything else.

Whichever you land on, the game log says so at world start and names the mods responsible.

What it actually does for you

The benefit is fewer tick spikes, not a higher average TPS. A server sitting at "20 TPS" still stutters when one tick in a hundred takes 800 ms. That is the part this fixes.

1024 zombies in a walled maze, all retargeted every 6 ticks. Four paired runs, interleaved and order-reversed so machine drift cannot fake the result, on the exact jar in this release:

That is mean tick time down ~41% and p99 down ~50%.

Separately, profiled with spark on an identical workload with only the master switch changed:

On a real 510-mod client, with only the master switch differing between two captures two minutes apart: TPS 18.9 → 20.0, mean tick 27.3 ms → 20.4 ms, blocking findPath down 33%. Treat those magnitudes as approximate — background CPU load differed between the two captures — but the direction matches every controlled measurement above.

It will tell you if your machine is too small for it

PathWeaver does not make pathfinding cheaper. It moves the same work to another thread so the server thread has room, and it adds a little of its own on the way. That trade only pays when a core is free for the worker to use.

On 2 cores or fewer it says so at world start and recommends turning it off. On 4 or fewer it warns the benefit will be small. Nothing is switched off automatically.

What it does not do

• It does not move entity ticking, collision, or AI goals off-thread. Only the A* search.
• It does not speed up a single path. It stops many paths landing on one tick.
• Brain-driven movement (villagers, piglins, axolotls, frogs, allays, the warden) and wall-climber chases call pathfinding in a way that needs the answer in the same tick, so those routes stay synchronous by construction. This is deliberate, not a gap — deferring them would make mobs conclude their target is unreachable.

It covers all six concrete vanilla evaluators: walking, swimming, flying, amphibious, and the frog's and creaking's.

Compatibility

At startup PathWeaver scans every loaded mod for mixins into pathfinding code. At Audited, any mod that modifies that code and has not been individually audited switches the affected movement family back to synchronous. At the shipped Unsafe default that scan is waived — it still runs, still reports, and its verdict is ignored.

Audited today: Lithium, Diagonal Blocks, Farmer's Delight, ServerCore, rabbit-pathfinding-fix, and Fabric API's own modules. Exemptions are pinned to exact artifact hashes — a different build of an audited mod is not audited.

Check your log for:

Foreign-mixin scan complete: scanned=…, failed=…, deniedFamilies=…

deniedFamilies=0 means searches can run off-thread. A scan failure is never waived by any tier: if the scanner cannot tell what is installed, everything stays synchronous regardless of the setting.

The compatibility matrix lists every audited verdict, the artifact hash it is pinned to, and — deliberately — the boundary of what each piece of evidence actually proves.

Testing

274 unit tests, four in-game server harnesses and a client harness that drives a real singleplayer world. Verified against real mobs in extended server sessions: 170,000 dispatched searches with no state drift, and a 371-mod pack booting clean.

This release went through ten rounds of independent code review, and the last three found real defects in the code the previous round had just approved: a data race in the search loop, a silent config-migration inversion, seven tests that could not fail, a bug that permanently corrupted axolotls', turtles' and frogs' pathfinding costs, a second attribute race affecting every mob chasing a player, and — twice — an assertion written to prevent a recurrence that could not actually fail. All fixed, each one mutation-tested. The changelog records what was rejected as well as what was fixed, and the 0.6 roadmap names what is still known to be missing.

It is still experimental, it still ships with its checks off by default, and the honest summary is at the top of this page.