PathWeaver

模组

· 作者 CasualZ

生物寻路在服务器主线程上运行,会导致 Tick 时间波动。PathWeaver 将其移至其他 CPU 核心处理:在 1024 个生物的情况下,平均 Tick 时间大致减半,最差 1% 的 Tick 时间下降 55-61%。此模组仅在服务端运行,客户端无需安装。安装前请阅读警告说明。

0 本站下载 0 关注 更新于 1 个月前

需要前置:Fabric API

最新 0.9.0+26.3 · 26.3 · Fabric

一键开服(送7天)

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。

你是这个资源的作者?登录后可认领此资源。

评论 0

0.0
暂无评分
5 星
0
4 星
0
3 星
0
2 星
0
1 星
0
我的评分

登录后参与评分

还没有评论,来抢沙发吧

评论配图

相似资源