PathWeaver
Minecraft 在运行其他所有内容的同一个线程上计算生物的路径。本模组将该工作移至其他线程。
每当一个生物决定行走路线时,服务器线程就会暂停并进行数学计算。数百个生物同时决定路径意味着服务器需要等待数百次寻路搜索完成,而这段等待时间正是你感受到的卡顿。
PathWeaver 让这些搜索在空闲的核心上进行。生物会获得原本应有的路径(见下文列出的少数例外情况);服务器刻只需不再等待其结果即可继续。
用数据而非断言来衡量其价值:在数百到数千个僵尸追逐玩家的情况下,可节省约 4% 至 12% 的服务器刻时间;如果你的生物不断重新寻路,节省效果会大得多。 寻路约占已加载服务器刻时间的百分之几,而本模组将其中约四分之三的工作移出了主线程。支持上述数据的测试链接如下。
这是一项切实的优化,并非救急方案。如果你的服务器每刻耗时已达 200 毫秒,本模组无法挽救它。在安装任何内容之前,页面会告诉你如何确定你自己的数值是多少。
免费,且不会改变生物的行进路径。
仅需 Fabric API,无需其他依赖。Cloth Config 为可选组件,仅用于显示设置界面;若无 Cloth Config,模组仍会读取和写入相同的 config/pathweaver.json 文件,行为保持一致。专用服务器从不显示设置界面,因此理论上不应需要安装该可选依赖。
为什么一个带来 6% 优化的模组值得安装
你回收到的刻时间是可用于支出的预算。将固定开销从主线程移除的意义不仅在于百分比本身,而在于这部分工作不再必须保持“轻量”:一旦寻路搜索不再阻塞服务器刻,服务器就能容纳比之前更多的生物,或执行更昂贵的寻路算法。
这是计划中的一系列模组中的第一个,每个模组都以相同的方式从服务器刻中移除一项固定开销,并以相同的方式衡量性能,从而使优化效果叠加而非相互竞争。对于无法安全移出服务器刻的任务,我们会明确说明,而不是强行推送。
快速开始
|
|
| 安装位置 |
服务器,或你的单人世界。客户端无需安装 |
| 依赖环境 |
Fabric、Minecraft 26.1.1 / 26.1.2 / 26.2 / 26.3、Java 25 或更高版本 |
| 必需依赖 |
Fabric API。无其他 |
| 可选依赖 |
Cloth Config 和 ModMenu,用于游戏内设置界面 |
| 之后 |
开始游玩。运行 /pathweaver status 查看其工作状态 |
大多数主机默认仍使用 Java 21,因此在提交错误报告前请检查你的 Java 版本。
安装前值得花十分钟阅读: 寻路真的是你的瓶颈吗? 本模组仅对服务器刻时间主要消耗在生物寻路上的情况有帮助,许多运行缓慢的服务器是因为其他原因导致的。
本模组默认关闭兼容性检查,这意味着它会在工作者线程上运行其他模组的寻路代码。请备份你重视的世界存档,并在向世界提交更改前阅读 兼容性。
优化效果
|
|
| 刷怪笼与密集群集 |
卡顿减少约一半 |
| 服务器主线程 |
采样的寻路工作量减少约一半 |
| 村庄 |
村民的路径规划也移出服务器刻 |
| 生物行为 |
普通游戏中路径不变。村民出发延迟一 tick,且路径共享可能导致一个生物获得另一个生物计算出的路径 |
| 空闲服务器 |
无差异。只有在生物实际进行路径规划时才会生效 |
这是峰值降低,而非免费的 TPS 提升。 一台显示“20 TPS”的服务器仍然会在百分之一的刻耗时达到 80 毫秒时出现卡顿,而本模组优化的正是这一指标。只有当寻路单独已经超出 50 毫秒的刻预算,且你有额外核心可用时,平均吞吐量才会上升。
在双核或更少核心的机器上,PathWeaver 会在世界启动时提示你关闭它。在四核或更少核心的机器上,它会警告收益较小。它永远不会自行关闭。
数据表现
提供两种场景,因为诚实的答案是这取决于你的服务器实际进行了多少寻路操作,而只引用有利数据是此页面过去自我推销的做法。
繁忙服务器:占服务器刻时间的 4% 至 12%
僵尸追逐一名每 11 秒传送一次的玩家,导致整个群体必须同时寻找新路线。这是在包含 219 个模组的服务器上,针对你下载的 jar 包进行的测量。中位数取三次往返运行的中间值:
| 僵尸数量 |
未启用 |
已启用 |
增益 |
| 500 |
10.1 ms |
8.9 ms |
12% |
| 1000 |
18.2 ms |
16.7 ms |
8% |
| 2500 |
45.8 ms |
43.3 ms |
5.5% |
| 5000 |
106.9 ms |
102.7 ms |
4% |
| 10000 |
258 ms |
246 ms |
4.5% |
由于测试机器在系列测试中途加速,单次运行的波动范围大于增益幅度,这对两组测试均适用。如果改为背靠背对比(每次启用模组的运行与其紧邻的不启用模组的运行对比),从 2500 只僵尸开始,每一对中启用 PathWeaver 的版本都更快。
为何是这个量级:在 5000 只僵尸的性能分析中,寻路约占服务器刻时间的 6%,而 PathWeaver 将其约四分之三的工作移出了服务器刻(从 6.12% 降至 1.55%)。增益由此产生,且不可能显著更大。该性能分析数据采集于九月,当时僵尸处于漫游状态而非追逐状态。
不断重新寻路的生物:效果更大
在围墙迷宫中有 1024 只僵尸,目标每 6 ticks 移动一次,导致几乎所有生物都在持续重新计算路径:
|
关闭 |
开启 |
| 平均刻耗时 |
88.5 至 96.6 ms |
50.0 至 50.3 ms |
| 最差的 1% 刻耗时 |
832 至 958 ms |
367 至 383 ms |
| 每次搜索的主线程开销 |
480 至 500 us |
195 至 202 us |
这是一个刻意增加寻路负载的场景。它类似于刷怪笼或大型敌对群体追踪移动玩家的情况。如果是你的服务器状况,第一张表格低估了你的实际收益。但这并不代表平均服务器的情况,此页面的早期版本曾将其呈现为普遍现象。
决定结果的因素
你的每个游戏刻中用于寻路的时间占比,且仅包含这部分。docs/IS-IT-YOUR-BOTTLENECK.md 提供了一份使用 Spark 进行的十分钟检测指南,帮助你在安装任何内容之前得出属于自己的具体数值。如果你的寻路时间占单个游戏刻的 1%,那么这个模组最多只能为你节省 1% 的时间。
可能导致你的结果与我们的不同的两个因素
核心数。 我们的测试是在拥有充足闲置核心的 32 核机器上进行的。PathWeaver 并不会删除工作,而是转移工作:搜索仍然会在工作者线程上发生,而主游戏刻不再等待它们完成。这种权衡需要工作去处的空间。在只有 2 到 4 个核心且其他所有任务都在争夺这些资源的宿主机上,收益会比我们测得的更小,而我们尚未对该情况进行测量。在拥有比我们更多闲置核心的机器上,收益可能会更大。
你的模组。 我们的测量运行在一个包含 219 个模组的服务器上,因此分母包含了整合包中的所有组件。一个更精简的服务器会在生物上花费更大的游戏刻比例,从而使百分比上升。
方法、设置、控制变量以及原始数据行均位于仓库的 docs/evidence/perf-2026-10/ 目录下,读取规则的记录早于首次运行。如果数字看起来有误,那里的详细过程可供核查。
关于你方生物的变更
村民和其他由大脑驱动的生物会比以前晚一个游戏刻开始行动。 在其搜索被派发的那个游戏刻,其行为被告知“尚无路径”,而路线会在下一个游戏刻到达。除此之外没有任何区别。
这是一个真实的行为变更,这也是为什么它作为一个设置项存在,而不是无论怎样都会生效的功能。将 brainSinkAsync=false 可关闭此功能。监守者也不受此影响,因为它的导航系统构建了自定义的寻路器。
其余情况保持原本应有的路径不变,但有三个例外。如果目标移动了一个方块或更少,生物会保留其已有路径,而不是获取新路径:这是 repathToleranceBlocks 参数,默认为 1,设为 0 则关闭此功能。本页面之前的版本遗漏了这一项。当开启路线共享时,会使用共享路线。并且,搜索是基于一个或两个游戏刻前的世界状态进行的,而不是基于生物请求时的瞬间状态。第一种情况可能导致生物朝向距离其发送位置一个方块远的地方行进;后两种情况不会改变其试图前往的位置。
减少远处路径搜索的重算频率
0.9.0 新增功能,默认关闭。 当生物行走的路径上的某个方块发生变化时,游戏会重新计算该生物的全部路径搜索。虽然游戏已经限制对同一生物每秒不超过重算一次,但在地形持续变化的区域,所有路径穿过变化区域的生物都要承担这一成本,无论附近是否有人能观察到结果。
lodEnabled 扩大了距离所有玩家 64 个方块以外的生物的限制:改为每 40 个游戏刻进行一次搜索,而不是游戏的每秒一次。这两个数值都是可设置的,任何小于或等于 21 的数值都不会产生任何作用,因为那是游戏自身的下限。
此项默认关闭,因为它是这里唯一允许生物在地面发生变化后继续沿着原路径行走的功能。节流后的生物会更长时间地沿着这条过时的路径行走。对于刷怪塔、红石附近的圈养畜群或高模拟距离的情况,值得开启。
其中的数值仅为最佳情况估计。在一个有利于该功能的测试环境中,400 只距离玩家至少 70 个方块且周围地形不断变化的僵尸,使 PathWeaver 启动的路径搜索减少了 13% 到 19%,且未对游戏刻时间产生可测量的影响。它在你的服务器上节省多少取决于无人靠近的生物周围有多少地形发生变化,而对于处于安静环境中的生物,由于游戏根本不会重算其路径,因此不会节省任何资源。
路线共享
一只生物可以重用另一只生物已计算出的路线,但前提是搜索的所有输入完全相同:相同的起始位置、相同的目标、相同的大小、相同的地形成本、相同的移动标志。当缓存运行时,路径沿线的方块发生变化会导致存储的路线被丢弃。
仍有一个诚实的限制:沿路径之外的方块变化可能会开辟一条更短的路径,而重用的路线不会选择这条路,原版游戏对此也视而不见。
另一个问题在此处已修复。在 0.8.0 和 0.8.1 版本中,在路线的两秒生命周期内切换路线共享或主开关的开/关状态,可能会导致路线跨越在关闭期间做出的更改,因为 PathWeaver 在存储路线存活期间停止监控方块变化(直到服务器停止)。现在,两个开关都会丢弃旧设置下学到的所有内容,包括仍在进行中的搜索。
默认以监测模式而非服务模式下线。 生物重复搜索的频率取决于你的世界,而非本模组。在默认设置下,PathWeaver 会填充缓存,统计共享本可节省的内容,但不提供任何服务,因此 /pathweaver status 可在你投入资源前告诉你其在你的服务器上值不值得。当数值证明合理时,将 resultCacheMode 设置为 SERVE。立即生效。
在基准测试中,命中率约为 12% 到 16%。这究竟值多少尚存争议,本页面此前曾表述不同。 与关闭缓存相比,测得的差异约为采样寻路时间的 3%,且运行范围重叠,竞技场各臂并未运行相同数量的生物,且臂的顺序是固定的而非平衡的。这不足以确立节省效果。测试竞技场也是 200 只生物在不间断的情况下穿越走廊,接近该功能的极端最差情况;静止不动并重新请求的生物才是它真正帮助的对象,而这部分并未被测量。
这就是它默认以监测模式而非服务模式下线的原因。/pathweaver status 会统计在你的世界中提供服务本可找到的数量,这比这里的任何数字都更有参考价值。
兼容性
默认情况下,它在工作者线程上运行其他模组未经检查的寻路代码。
这是有意为之。compatibilityTier=AUDITED 这一检查层级仅信任字节码经过审计的模组,而在实际的整合包中,它会拒绝所有内容,导致该模组不执行任何操作。在包含 221 个 jar 包的测试环境中:在该层级下,187 种生物类型中仅有 0 种符合条件,而默认层级下有 184 种符合。如果将这种看似安全的层级设为默认,实际上等同于发布了一个与损坏无异的版本。
到目前为止实际发生的情况是:该模组已在包含 200 至 371 个模组的整合包上运行了数十万次搜索,未出现任何可追溯至它的损坏或崩溃。这属于“未报告问题”而非“证明无误”,这也正是故障罕见或静默时会出现的现象。建议在你打算丢弃的世界中进行测试。
如果发现异常,请切换至 compatibilityTier=AUDITED 并报告问题。需明确的是,在高负载整合包中启用此层级会完全关闭加速功能。这是该层级按设计运行的表现,而非故障。trustedMods 是中间选项,允许你指定已确认安全的特定模组,同时扫描继续检查其余模组。
检查层级取决于你安装的版本
每次审计都绑定到模组的确切字节及其验证所读取的原版类代码,因此一个 Minecraft 版本的构建无法为另一个版本背书。共有三个下载版本,它们在这一点上有所不同:
- 26.1.2 下载版(适用于 26.1.1 或 26.1.2):全部七项审计均通过验证。
- 26.2 下载版(适用于 26.2):在针对 26.2 发行版重新推导 Lithium 和 Diagonal Blocks 后,全部七项审计均通过验证。
- 26.3 下载版(适用于 26.3):除 Lithium 外,所有审计均通过验证。Lithium 的 26.3 版本更改了审计覆盖的代码,因此在相关更改被检查之前不会获得认证。当安装 Lithium 且设置为
AUDITED 时,PathWeaver 会停止运行,而不是在未检查的情况下运行。
请安装与你 Minecraft 版本相匹配的下载版。如果在不同版本上安装,校验锚点会拒绝通过,从而关闭加速功能,而不是在未检查的情况下运行任何内容。
无论哪种情况,只有当你选择加入 AUDITED 层级时,上述差异才有关联。默认的发货配置不使用其中任何一项。
无论你处于哪个版本,修改寻路的模组会在世界开始时列出名称,并附带 PathWeaver 对每个模组做出的判断。
设置
| 设置项 |
默认值 |
作用 |
|
enabled |
on |
主开关 |
|
compatibilityTier |
UNSAFE |
是否在非线程运行其他模组代码前进行检查 |
重启游戏 |
brainSinkAsync |
on |
村民类型寻路脱离主刻,延迟一个 tick |
|
resultCacheMode |
SHADOW |
路线共享。SHADOW 用于测量,SERVE 用于提供服务 |
|
repathToleranceBlocks |
1 |
当目标移动距离小于此数值时,复用生物当前路径 |
|
poolThreads |
auto |
工作线程数。自动模式下为 CPU 线程数的四分之一,最少两条 |
重启游戏 |
lodEnabled |
off |
降低远处生物寻路频率 |
|
lodMinDistanceBlocks |
64 |
启动远处的起始距离 |
|
lodIntervalTicks |
40 |
限速生物两次搜索之间的 tick 间隔。低于 21 时无效 |
|
所有这些设置都位于 config/pathweaver.json 文件中。如果你想在游戏中编辑它们,可以安装 ModMenu 和 Cloth Config;这两者都不是必需的,服务器端也不需要。标记为 重启游戏 的两项仅在启动时读取一次;其余设置在保存后立即生效。
检查其是否正在发挥作用
/pathweaver status 会报告正在分发的任务、成功着陆的任务以及路线共享能节省多少。/pathweaver mobs 会列出你的哪些生物类型符合条件。
路线共享以两个数字的形式报告。Searches skipped(跳过的搜索) 是指未执行的搜索次数,这就是节省的全部来源。Hits that saved nothing(未能节省任何东西的命中) 是指没有存储路线的真实缓存命中,这是在缓存进行测量期间会出现的情况。在 0.9.0 之前,这两者被合并显示在第一项标签下,因此你用来决定使用 SERVE 的数据偏大。
Eligible(符合条件)意味着没有任何因素阻止为该生物分发任务,并不代表它的所有移动都会脱离主线程处理。在默认的 221 个 jar 包环境中,有 184 种符合条件;剩下的三种由于使用了自定义寻路器而非原版寻路器而被保留。
实际使用的分发搜索数量取决于负载情况。在空闲服务器上约为 99%,正常游玩时约为 96%,在饱和的 1024 生物基准测试中约为 82%。在该基准测试中,模组会故意拒绝请求,而不是排队那些因落地太晚而无意义的请求。
更正
发布的声明不应悄悄改变,以下是此前存在的问题。原始基准测试产物在仓库中保持不变。
路线共享可能在设置切换期间保持一条路线不变。 在路线生命周期内,反复开启和关闭路由共享或主开关,可能会发出在地形变化之前计算的路线,而此时无人监视。在 0.8.0 和 0.8.1 中,可通过设置界面直接触发,无需重启。已在 0.9.0 中修复。仅当你开启了路线共享时才会影响你;发货默认配置仅为测量模式而非服务模式。
"Searches skipped(跳过的搜索)" 是两个数字相加的结果。 没有存储路线的缓存命中并未跳过任何搜索,但它们与真正未运行的搜索被计入了同一数据中。如果你在 0.7.0、0.8.0 或 0.8.1 中阅读该行数据来决定是否值得开启路线共享,你会发现该数值比实际节省的要大。现在分为两行显示,仅第一行为实际节省量。
0.8.x jar 包中的设置界面声称复用的路线“永远不会过时”。 页面编辑无法触及编译进发布版的文本。0.9.0 将其更改为实际情况:当路线上的方块发生变化时,路线会被丢弃;而偏离路线的变化则不会被注意到,这与原版行为一致。
一项被描述但从未存在过的权限检查。 /pathweaver mobs 会生成每种已注册生物类型的实例,以报告哪些生物符合条件,这在大整合包中大约需要五分之一秒,且运行在服务端线程上。它本应需要操作者(operator)权限:源代码注释如此说明,0.7.0 版本日志也如此声明。但实际上并没有此限制,因此任何服务器上的任何玩家都可以反复运行该命令。已在 0.8.1 中修复。/pathweaver status 对所有玩家开放,因为文档指导你运行的正是该命令。如果你使用的是 0.7.0 或 0.8.0 版本的多人服务器,这就是你需要更新的原因。
“CPU”与“A*”。 性能分析器每 4 毫秒采样一次线程堆栈,并统计某项内容出现在堆栈中的频率(包括等待状态)。它并不测量 CPU 时间,且分类器涵盖的是广泛的导航和寻路行为,而非仅限于 A* 搜索。先前标记为“总 CPU”和“服务端线程 A*”的数据实际上是采样的宽泛寻路数据,现已重新标记如上。村民结果的趋势和大致规模在重新标记后依然成立,但用词并未保留。
路线共享的节省。 本文档的早期版本曾将约 3% 呈现为实测收益。这一结论尚未确立。两组测试并未运行完全相同的生物种群,且测试顺序是固定的而非交叉平衡的,因此无法将一个带有重叠范围的微小差异归因于该特性。12% 到 16% 的命中率是真实的;但服务这些命中所带来的价值尚不明确。
繁忙服务器基准测试中并无玩家参与。 本页面的表格曾写道“僵尸追逐玩家”,但在那些九月的运行中,测试服务器上的另一个模组在玩家加入一秒后就将其移除,导致僵尸只是在游荡。该基准测试已于 2026-10-13 重新运行,此时玩家保持不动而僵尸真正进行追逐,上方的表格即为此次运行的结果。在 500 至 1000 只僵尸的情况下,增益幅度大致相同;而在 2500 只及以上时增益较小:旧表格显示为 5% 至 9%,现改为 4% 至 5.5%。
未发生变化的部分,因为这些是经过检查而非假设的:生物资格计数、审计与兼容性行为、刻间隔基准测试结果,以及在该基准测试中每一次开启模组的表现均优于关闭模组的事实。
已知局限
上述已检查的层级并不涵盖 Lithium 在 26.3 版本的情况。当生物脚下的方块正在改变时,路径质量未被测量。一千只或更多生物时的行为未被测量。
完整细节(包括尝试过但最终弃用的方案)请参阅 GitHub:README、changelog 和 roadmap。
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
|
|
| Install on |
The server, or your singleplayer world. Clients need nothing |
| Needs |
Fabric, Minecraft 26.1.1 / 26.1.2 / 26.2 / 26.3, Java 25 or newer |
| Also needs |
Fabric API. Nothing else |
| Optional |
Cloth Config and ModMenu, for the in-game settings screen |
| Then |
Play. Run /pathweaver status to see what it is doing |
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
|
|
| Mob farms and crowds |
Stutters cut roughly in half |
| Server thread |
Roughly half the sampled pathfinding work |
| Villages |
Villager pathing comes off the tick too |
| Mob behaviour |
Same routes in ordinary play. Villagers set off a tick later, and route sharing can hand one mob a route another computed |
| Quiet server |
No difference. This does nothing until mobs are actually pathing |
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:
| zombies |
without |
with |
gain |
| 500 |
10.1 ms |
8.9 ms |
12% |
| 1000 |
18.2 ms |
16.7 ms |
8% |
| 2500 |
45.8 ms |
43.3 ms |
5.5% |
| 5000 |
106.9 ms |
102.7 ms |
4% |
| 10000 |
258 ms |
246 ms |
4.5% |
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:
|
Off |
On |
| Mean tick |
88.5 to 96.6 ms |
50.0 to 50.3 ms |
| Worst 1% of ticks |
832 to 958 ms |
367 to 383 ms |
| Main-thread cost per search |
480 to 500 us |
195 to 202 us |
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
| Setting |
Default |
What it does |
|
enabled |
on |
Master switch |
|
compatibilityTier |
UNSAFE |
Whether to check other mods before running their code off-thread |
restart |
brainSinkAsync |
on |
Villager-type pathing off the tick, at one tick of delay |
|
resultCacheMode |
SHADOW |
Route sharing. SHADOW measures, SERVE spends it |
|
repathToleranceBlocks |
1 |
Reuse a mob's current path when its target moved less than this |
|
poolThreads |
auto |
Worker threads. Auto is a quarter of your CPU threads, minimum two |
restart |
lodEnabled |
off |
Redo distant mobs' path searches less often |
|
lodMinDistanceBlocks |
64 |
How far from a player that starts |
|
lodIntervalTicks |
40 |
Ticks between searches for a throttled mob. Below 21 does nothing |
|
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.
评论 0
登录后参与评分
还没有评论,来抢沙发吧