PathWeaver

# PathWeaver ### Your server lags when there are lots of mobs. This fixes a big part of why. Every time a mob works out where to walk, Minecraft does that maths **on the server thread** — the same thread running everything else. A hundred zombies deciding where to go at once is a hundred searches the tick has to wait for, and that is what you feel as a stutter. PathWeaver moves those searches onto **spare CPU cores** instead. Same paths, same mob behaviour, just not blocking the tick. **Install it on the server (or in your singleplayer world). Clients need nothing.** Fabric, Minecraft **26.1.1, 26.1.2 or 26.2**, **Java 25 or newer** — most hosts still default to 21, so check. Needs Fabric API and Cloth Config. 26.1.1 and 26.1.2 share one file; 26.2 is a separate build. One difference worth knowing: the checked tier (`compatibilityTier=AUDITED`) works **only on 26.1.2**. Its per-mod exemptions are pinned to the exact bytecode they were derived from, so on 26.1.1 and 26.2 they refuse and that tier switches the mod off. The shipped default performs no such check and is unaffected. ⚠ **It ships with its compatibility checking turned off.** Back up worlds you care about, and read (#-read-this-before-installing) before you commit a world to it. --- ## What you actually get | | | |---|---| | 🐌 **Mob farm and crowd stutters** | Cut roughly in half | | 🏰 **Crowds of mobs pathing at once** | Server thread does ~60% less pathfinding work | | 🧟 **Mob behaviour** | Unchanged — the paths are identical, they just arrive off-thread | | 💤 **Quiet server** | No measurable difference. This does nothing until mobs are actually pathing | **It is spike reduction, not free TPS.** A server sitting at "20 TPS" still stutters when one tick in a hundred takes 80 ms. 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. --- ## Benchmarks **1024 zombies in a walled maze, all retargeting every 6 ticks.** Shipped limits, Lithium loaded, tier set to `AUDITED` — which on a lean pack is what the default gives you anyway. The only difference between the two arms is the master switch. | | Vanilla | PathWeaver | | |---|---|---|---| | **Mean tick** | 88.5–96.6 ms | **50.0–50.3 ms** | ▼ 43–48% | | **Worst 1% of ticks** | 832–958 ms | **367–383 ms** | ▼ 55–61% | | **Effective TPS**\* | 10.4–11.3 | **20.0** | ▲ ~2× | | **Main-thread cost per search** | 480–500 µs | **195–202 µs** | ▼ ~60% | Every async run beat every sync run. No overlap between the two sets. \* Effective TPS is *derived* from mean tick interval, and 20.0 is the pacing ceiling rather than a measurement of headroom — so "tick time halved" and "tick rate doubled" are one fact stated twice. The independent signals here are the p99 and the main-thread cost. ### On a real 221-jar pack, profiled with spark 220 mixed mobs — zombies, skeletons, spiders, bees, drowned — retargeting every 6 ticks. Two 45-second profiles. | | Server-thread time spent pathfinding | |---|---| | **PathWeaver off** | 5,572 ms of 45,000 — **12.38%** | | **PathWeaver on** | 2,216 ms of 45,000 — **4.92%** | **Pathfinding's share of the server thread fell by 60%.** 7,262 searches dispatched, 96.3% installed. ### Read the spread, not the headline Every async run across three separate sweeps landed between **50.0 and 50.3 ms** — the mod is the stable half. The *vanilla* baseline swings from 87 to 108 ms with ambient machine load, so almost all the variation in that percentage comes from the baseline rather than from the mod. One flattering pair would have let us print "66% faster". We are quoting the range instead. --- ## ⚠ Read this before installing **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 deliberate, 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 at **0 of 187 eligible mob types** on a 221-jar pack. Shipping that as the default would ship something indistinguishable from broken. As of 0.6.1 that tier is **frozen**: it stays as a conservative escape hatch, and it is not going to get better. The runtime failure breaker below is what replaced it. **What has actually happened so far:** across development this has run on packs of 200–371 mods through hundreds of thousands of dispatched searches, with no corruption or crash traced to it. That is an absence of reported problems, not a proof — it is exactly what you would also see if the failure were rare, or quiet, or not looked for hard enough. Several real defects *were* found in that time, by code review and bytecode audit, never by something visibly going wrong in a world. **So decide for yourself, on a copy.** Run it on a w