PathWeaver

PathWeaver

生物寻路在服务器线程上运行,会导致 tick 尖峰。PathWeaver 将其迁移到空闲 CPU 核心:1024 个生物时平均 tick 约减半,最差 1% tick 下降 55-61%。仅服务端生效,客户端无需任何操作。安装前请阅读警告。

优化

PathWeaver

Minecraft 在主线程上计算生物寻路。本模组将这项工作移出主线程。

每当生物决定往哪走时,服务器线程会停下来做数学计算。几百个生物同时做决定,就意味着这一 tick 要等待几百次搜索,而你能感受到的正是这种等待。

PathWeaver 改为在空闲核心上运行这些搜索。生物得到的路径与原本会得到的相同(下方列出的少数例外除外);只是 tick 不再等待它。

实际价值(经过测量而非断言):在数百到数千只僵尸追逐玩家时,约占服务器 tick 时间的 4% 到 12%;如果你的生物不断重新寻路,收益会大得多。 寻路在负载服务器 tick 中只占几个百分点,而本模组将其约四分之三移出主线程。这些数字背后的运行记录链接如下。

这是真实的节省,但并非救星。如果你的服务器每 tick 耗时 200 ms,这救不了你,而且本页面会告诉你在安装任何东西之前如何查明你自己的数字。

免费,且不会改变你的生物所走的路径。

它只需要 Fabric API,别无其他。Cloth Config 是可选的,仅用于绘制设置界面;没有它,模组读写同一个 config/pathweaver.json,行为完全相同。专用服务器从不显示设置界面,所以它本来就不应该需要安装一个。

为什么一个 6% 的模组值得安装

你收回的 tick 时间就是你可以支配的预算。把一项固定开销从主线程移走的重点不在于百分比本身,而在于这项工作不再必须廉价:一旦路径搜索不再阻塞 tick,服务器就能负担比之前更多的生物,或更昂贵的寻路。

这是计划中一系列模组中的第一个,每个模组都以相同方式从 tick 中移走一项固定开销,以相同方式测量,使节省叠加而不是互相竞争。如果某项工作无法安全地移出 tick,我们会如实说明,而不是照样发布。


入门

安装位置 服务器,或你的单人世界。客户端无需安装任何东西
需要 Fabric、Minecraft 26.1.1 / 26.1.2 / 26.2 / 26.3、Java 25 或更新版本
还需要 Fabric API。别无其他
可选 Cloth Config 和 ModMenu,用于游戏内设置界面
然后 开始游玩。运行 /pathweaver status 查看它的运行情况

大多数主机商仍默认使用 Java 21,所以提交 bug 前请检查你的版本。

安装前值得花十分钟: 寻路真的是你的瓶颈吗? 本模组只对 tick 时间花在生物路径搜索上的服务器有帮助,而许多卡顿的服务器慢是另有原因。

它发布时关闭了兼容性检查,这意味着它在工作线程上运行其他模组的寻路代码。请备份你在意的世界,并在将世界托付给它之前阅读兼容性部分。


你能得到什么

生物农场和生物群 卡顿大约减半
服务器线程 采样到的寻路工作大约减半
村庄 村民寻路也移出 tick
生物行为 正常游玩中路线相同。村民晚一 tick 出发,且路线共享可能把某个生物计算的路线交给另一个生物
空闲服务器 没有区别。在生物实际寻路之前,本模组不会做任何事

这是削减尖峰,而非免费 TPS。 一个停留在“20 TPS”的服务器,当每一百个 tick 中有一个耗时 80 ms 时仍会卡顿,而这正是本模组要挪动的数字。只有当寻路本身已经超出 50 ms 的 tick 预算且你有空闲核心时,平均吞吐量才会上升。

在只有两个或更少核心的机器上,PathWeaver 会在世界启动时提示你保持关闭。四个或更少核心时会警告收益很小。它从不自行关闭。


数字

两个场景,因为诚实的答案是这取决于你的服务器实际做了多少寻路,而只引用好看的那个正是本页面过去自我吹嘘的方式。

繁忙服务器:tick 时间的 4% 到 12%

僵尸追逐一个每 11 秒被传送一次的玩家,因此整群僵尸必须同时寻找新路线,在一个装有 219 个模组的服务器上,在你下载的 jar 上测量。tick 中位数,每种配置三次运行的中位:

僵尸数 无模组 有模组 收益
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 只僵尸的分析中,寻路约占服务器 tick 时间的 6%,PathWeaver 将其约四分之三移出了 tick(6.12% 降至 1.55%)。收益由此而来,不可能大很多。该分析是在九月进行的,当时僵尸在游荡而非追逐。

不断重新寻路的生物:幅度大得多

1024 只僵尸在围墙迷宫中,目标每 6 tick 移动一次,因此每个生物几乎持续重新计算:

关闭 开启
平均 tick 88.5 到 96.6 ms 50.0 到 50.3 ms
最差 1% 的 tick 832 到 958 ms 367 到 383 ms
每次搜索的主线程开销 480 到 500 us 195 到 202 us

这是刻意偏向寻路的重负载场景。这就是生物农场或大型敌对生物群追踪移动玩家时的样子,如果你的服务器是这样,第一张表低估了你得到的收益。它不是普通服务器的样子,而本页面早先的版本却把它当成了普通情况来呈现。

什么决定你落在哪一端

你 tick 中寻路所占的份额,仅此而已。docs/IS-IT-YOUR-BOTTLENECK.md 是一个用 spark 进行的十分钟检查,能在你安装任何东西之前告诉你自己的数字。如果寻路占你 tick 的 1%,本模组最多能为你赢得 1%。

两件可能让你的结果与我们的不同的事

核心数。 这些是在一台有富余核心的 32 核机器上测量的。PathWeaver 不删除工作,而是移动它:搜索仍然发生,在工作线程上,而 tick 不再等待它们。这种交易需要工作有地方可去。在只有 2 到 4 个核心、其他一切已经在争抢这些核心的主机上,收益会比我们的小,而我们没有测量那种情况。在空闲核心比我们多的机器上,收益可能更大。

你的模组。 我们的测量在一个装有 219 个模组的服务器上运行,因此分母包含该组合的一切。更轻量的服务器在生物上花费 tick 的更大份额,这会把百分比推高。

方法、设置、对照组和原始数据行在仓库的 docs/evidence/perf-2026-10/ 下,解读规则在第一次运行前就已写明。如果数字看起来不对,计算过程就在那里可供核查。


你的生物会发生什么变化

村民和其他由 brain 驱动的生物比过去晚一 tick 出发。 在它们的搜索被派发的那个 tick,它们的行为被告知“还没有路径”,路线在下一个 tick 到达。其他方面没有区别。

这是一个真实的行为变化,所以它是一个设置项,而不是你无论如何都会得到的东西。brainSinkAsync=false 会关闭它。监守者两种情况都不涵盖,因为它的导航构建了自定义寻路器。

其他一切保留原本会得到的路径,只有三个例外。目标移动不超过一个方块的生物保留已有路径,而不是获取新路径:repathToleranceBlocks,默认 1,设为 0 可关闭。本页面早先的版本遗漏了这一项。在开启路线共享时会使用共享路线。搜索针对的是世界在一两个 tick 之前的状态,而不是生物请求的瞬间。第一项可能让生物前往距离其目标位置一个方块的地点;后两项不会改变它试图去的地方。

减少远处路径搜索的频率

0.9.0 新增,默认关闭。 当生物行走路线上的方块发生变化时,游戏会重做该生物的全部路径搜索。它已经拒绝为任何单个生物每秒做超过一次。但在一个地形不断变化的地方,每个路线穿过变化的生物都要付出这个代价,无论附近是否有人能看到结果。

lodEnabled 为距离所有玩家超过 64 个方块的生物放宽限制:每 40 tick 搜索一次,而不是游戏原本的每秒一次。这两个数字都是设置项,任何等于或低于 21 tick 的值都完全不起作用,因为那是游戏自己的下限。

它默认关闭,因为这是这里唯一会让生物在脚下地面改变后仍继续走旧路线的东西。被限流的生物会沿着那条过时的路线走更久。对于生物农场、红石附近的圈养畜群或高模拟距离值得开启。

它唯一的数字是最好情况。在一个为它量身定制的测试中,400 只僵尸距离玩家至少 70 个方块,且它们周围的地形不断变化,它把 PathWeaver 发起的路径搜索减少了 13% 到 19%,且没有可测量的 tick 时间变化。它在你的服务器上节省多少,取决于无人站立处的生物周围地形变化有多频繁;对于处于安静环境中的生物,它什么也节省不了,因为游戏根本不会重做它的搜索。

路线共享

一个生物可以复用另一个生物已计算出的路线,但仅当搜索的每个输入都完全相同时:相同起点、相同目标、相同体型、相同地形代价、相同移动标志。当缓存运行期间路线上的方块发生变化时,存储的路线会被丢弃。

仍有一个诚实的限制:偏离路线的方块变化可能开辟一条更短的通道,而复用的路线不会走它,原版游戏也不会注意到。

另一个问题已在此修复。在 0.8.0 和 0.8.1 中,在路线两秒生命周期内关闭再开启路线共享或总开关,可能会保留一条跨越关闭期间所做变化的路线,因为 PathWeaver 在该功能开启期间停止监视方块变化,而存储的路线一直存活到服务器停止。现在两个开关都会丢弃在旧设置下学到的内容,包括仍在进行中的搜索。

它以测量而非服务模式发布。 生物重复搜索的频率取决于你的世界,而不是本模组。在默认设置下,PathWeaver 填充缓存,统计共享本可节省多少,但不发放任何东西,因此 /pathweaver status 会在你花费它之前告诉你它在你服务器上的价值。当数字足以证明时,将 resultCacheMode 设为 SERVE。立即生效。

在基准测试中命中率为 12% 到 16%。其价值尚未确定,而本页面此前有过相反的说法。 与关闭缓存相比的实测差异约为采样寻路的 3%,运行范围有重叠,且该竞技场各组的生物数量并不相同,组别顺序也是固定的而非平衡的。这不足以确立节省。测试竞技场还是 200 只生物不停地走走廊,接近该功能的最差情况;原地站立并反复询问的生物才是它帮助的对象,而那恰恰不是被测量的内容。

这就是它以测量而非服务模式发布的原因。/pathweaver status 统计的是服务模式在 YOUR 世界上本会找到的结果,这比这里的任何数字都更好。


兼容性

默认会在工作线程上运行其他模组未经检查的寻路代码。

这是有意为之。受检查层级 compatibilityTier=AUDITED 只信任其字节码已被审计的模组,在真实的模组包上它会拒绝一切,模组什么也不做。在一个 221 个 jar 的包上测量:该层级下 187 种生物类型中 0 种合格,而默认下 187 种中有 184 种合格。默认发布看起来安全的层级,等于发布一个与损坏无法区分的东西。

实际发生的情况:这已在 200 到 371 个模组的包上运行了数十万次搜索,没有追溯到它的损坏或崩溃。这是没有报告问题,而非证明,而且如果故障罕见或安静,你看到的也会是这样。请在一个你可以丢弃的世界里试用。

如果确实看起来有问题,切换到 compatibilityTier=AUDITED 并报告。请清楚说明它在重负载包上的作用:它完全关闭加速。这是该层级按设计工作,而不是失败。trustedMods 是中间选项,指定你已决定信任的特定模组,同时扫描继续检查其余模组。

受检查层级取决于你拥有哪个下载

每次审计都固定到模组的精确字节及其证明所读取的原版类,因此为一个 Minecraft 版本构建的版本无法为另一个版本担保。有三个下载,它们在这方面不同:

  • 26.1.2 下载,在 26.1.1 或 26.1.2 上:全部七项审计通过验证。
  • 26.2 下载,在 26.2 上:全部七项审计通过验证,此前 Lithium 和 Diagonal Blocks 已针对随 26.2 发布的构建重新推导。
  • 26.3 下载,在 26.3 上:除 Lithium 外每项审计都通过验证。Lithium 的 26.3 构建更改了审计覆盖的代码,在该更改被检查之前它未获认证。在安装 Lithium 且开启 AUDITED 的情况下,PathWeaver 会退避而不是在未检查的情况下运行它。

安装与你的 Minecraft 版本匹配的下载。在不同版本上安装,固定检查会拒绝,从而关闭加速而不是运行任何未检查的东西。

无论如何,只有你选择启用 AUDITED 时这才会重要。发布的默认设置完全不咨询它。

无论你使用哪个版本,修改寻路的模组会在世界启动时被列出,并附上 PathWeaver 对每个模组的决定。


设置

设置 默认 作用
enabled 开 总开关
compatibilityTier UNSAFE 是否在将其他模组的代码移出线程之前检查它们 重启
brainSinkAsync 开 村民类寻路移出 tick,延迟一 tick
resultCacheMode SHADOW 路线共享。SHADOW 测量,SERVE 花费
repathToleranceBlocks 1 当目标移动小于此值时复用生物当前路径
poolThreads 自动 工作线程。自动为 CPU 线程数的四分之一,最少两个 重启
lodEnabled 关 降低远处生物路径搜索频率
lodMinDistanceBlocks 64 从距离玩家多远开始
lodIntervalTicks 40 被限流生物两次搜索之间的 tick 数。低于 21 不起作用

它们都位于 config/pathweaver.json。安装 ModMenu 和 Cloth Config 以便在游戏内编辑;两者都不是必需的,服务器两者都不需要。标记为重启的两个在启动时读取一次;其余在你保存后立即生效。


检查它是否在起作用

/pathweaver status 报告正在派发什么、正在落地什么,以及路线共享会节省什么。/pathweaver mobs 列出你的哪些生物类型合格。

路线共享以两个数字而非一个报告。跳过的搜索是没有运行的搜索,也就是全部节省。未节省任何东西的命中是没有存储路线在背后的真实缓存命中,这就是缓存测量期间得到的结果。在 0.9.0 之前,它们被加在一起归在第一个标签下,因此你用来决定 SERVE 的数字太大了。

合格意味着没有东西阻止该生物的派发,而不是它的每次移动都走非主线程。在一个 221 个 jar 的包上以发布默认设置,是 187 种中的 184 种;被扣留的三种使用自定义寻路器而非标准寻路器导航。

派发的搜索有多少被使用取决于负载。空闲服务器上约 99%,正常游玩下 96%,在饱和的 1024 生物基准测试中约 82%,此时模组会刻意拒绝请求,而不是排队那些会来得太晚而不值得拥有的请求。


更正

已发布的声明不应悄悄改变,所以以下是曾经错误的地方。它们所来自的原始基准测试产物在仓库中未变。

路线共享可能在设置切换时保留路线。 在路线生命周期内关闭再开启它或总开关,可能会发放一条在地形变化前计算、而当时没有任何东西在监视的路线。在 0.8.0 和 0.8.1 中,可从设置界面触发,无需重启。0.9.0 已修复。仅当你开启路线共享时才会影响你;发布默认是测量而非服务。

“跳过的搜索”曾是两个数字相加。 没有存储路线在背后的缓存命中什么也没跳过,它们却与真正没有运行的搜索计入同一数字。如果你在 0.7.0、0.8.0 或 0.8.1 中读到那一行来决定路线共享是否值得开启,那个数字比节省大。现在它是两行,只有第一行是节省。

0.8.x jar 内的设置界面说复用的路线“永远不是过时的”。 页面编辑无法触及编译进发布版的文本。0.9.0 将其改为成立的说法:当路线上的方块发生变化时路线被丢弃,而偏离路线的变化不会被注意到,与原版相同。

一个被描述但从未存在的权限检查。 /pathweaver mobs 会为每种注册的生物类型构建一个,以报告哪些合格,在一个大包上要在服务器线程上花费约五分之一秒。它本应需要管理员等级:源代码注释这么说,0.7.0 的说明也这么说。它并不需要,因此任何服务器上的任何玩家都可以反复运行它。0.8.1 已修复。/pathweaver status 仍对所有人开放,因为那是文档让你运行的那一个。如果你在 0.7.0 或 0.8.0 上托管多人服务器,这就是更新的理由。

“CPU”和“A*”。 分析器每 4 ms 采样线程栈,统计某物在栈上的频率,包括等待。它不测量 CPU 时间,分类器覆盖的是广泛的导航和寻路,而非仅 A* 搜索。曾被标为“总 CPU”和“服务器线程 A*”的数字是采样的广泛寻路,已在上文重新标注。村民结果的方向和大致幅度在重新标注后仍然成立。用词则不然。

路线共享的节省。 本页面早先的版本将约 3% 呈现为实测收益。它并未确立。两组没有运行相同的生物数量,组别顺序是固定的而非平衡的,因此范围重叠的微小差异不能归因于该功能。12% 到 16% 的命中率是真实的;服务这些命中值多少则未知。

繁忙服务器基准测试中没有玩家。 本页面上的表格过去说“僵尸追逐玩家”,但在那些九月的运行中,测试服务器上的另一个模组在测试玩家加入一秒后将其移除,所以僵尸在游荡。基准测试于 2026-10-13 在玩家保持不动且僵尸真正追逐的情况下重新运行,上表就是那次运行。在 500 到 1000 只僵尸时收益大致相同,在 2500 及以上更小:4% 到 5.5%,而旧表说 5% 到 9%。

没有改变的内容,因为这是经过核查而非假设的:生物合格计数、审计和兼容性行为、tick 间隔基准测试,以及在该基准测试上每次开启模组的运行都胜过每次关闭模组的运行。


已知限制

受检查层级在 26.3 上不覆盖 Lithium,见上文。方块在生物脚下不断变化时的路径质量未被测量。一千只或更多生物时的行为未被测量。

完整细节,包括尝试过并丢弃的内容,在 GitHub 上:README、更新日志 和 路线图。