Quilt Bisect
一款用于 Quilt 的模组与加载器插件,通过基于二分搜索算法衍生出的搜索算法来查找导致问题的模组。这包括以崩溃或用户检测到的问题形式表现的 n-way 模组不兼容情况。
警告
Quilt Bisect 仍处于实验阶段。不过我认为它已适用于大多数用例。部分功能尚未经过测试(Realms 支持),并且它依赖于 Quilt 加载器中的实验性 API。在向其他项目报告问题之前,请在没有 Quilt Bisect 的情况下测试所有问题(尤其是与 Quilt Loader 相关的问题)。或者,加入我的 Discord 并在那里获取支持。
使用方法
- 此项目使用加载器插件,需要在 JVM 参数中添加
-Dloader.experimental.allow_loading_plugins=true。
- 安装此模组
- 如果你的游戏崩溃,将弹出一个对话框询问你是否要进行二分排查;否则点击屏幕顶部的“开始二分排查”按钮,系统将提示你为你的问题命名。
- 游戏将自动重启。尝试重现之前遇到的问题。
- 如果一切正常,点击
No Issue(无问题)按钮
- 如果有问题,点击
Manual Issue(手动问题)按钮,选择你所遇到的问题或创建新问题
- 注意:建议在一个二分排查过程中保持问题数量较少,而是应用之前的修复后运行多个二分排查。参见“同时排查多个问题”
- 一旦定位到问题,bisect 将验证解决方案并继续排查其他问题
- 当二分排查完成时,它将提供所遇到问题和解决方案的摘要。但由于二分排查的工作原理,请谨慎对待这些信息
配置
文件 <config>/quilt_bisect/main.json 包含用户可能希望配置的大部分内容,请参阅 MainConfig.java 了解更多信息。
文件 <config>/quilt_bisect/active_bisect.json 包含有关当前活动二分排查的信息,包括设置、所有尝试过的模组集及其各自的日志,以及问题信息。
文件 <config>/quilt_bisect/modSet.txt、<config>/quilt_bisect/sections.txt 和 <config>/quilt_bisect/lastActiveJoin.txt 包含内部信息,不应修改。
工作原理
同时排查多个问题
虽然 bisect 支持同时排查多个问题,但在存在多个问题时,bisect 做出了一些基本假设:
- 只有移除模组才能解决问题,而不是添加模组
- 一个常见的例子是 indium,它可以解决 sodium 与其他模组之间的兼容性问题,前提是这些模组未自行声明解决该兼容性
- 问题之间存在固定的优先级顺序
- 如果具有问题 A 的模组集的子集 B 出现了不同于问题 A 的问题,那么问题 A 不会出现在 B 的任何子集中。这意味着问题(即使由用户标记)必须始终以相同的顺序进行测试
自动标记为正常工作
在开始新的二分排查时,你可以配置 bisect 以:
- 自动加入世界、服务器、Realm 或上次加入的世界(注意:Realms 依赖 ID 而非名称)
- 在经过给定时间后自动接受某个模组集为正常工作状态
- 时间单位为 1/20 秒,如果启用自动加入,则从加入世界时开始计时,否则从显示标题画面时开始。如果在单人游戏中,它还会等待足够的刻数过去
- 在自动加入后自动运行命令或发送聊天消息。
- 它们将被视为从聊天中发送,并且客户端命令也能正常工作
- 禁用世界保存
- 这是为了帮助复现与世界状态相关的问题。如果启用此选项,重新登录后任何单人世界都不会被更改。它还允许测试内容模组
- 为了获得最大兼容性,目前它是通过备份 worlds 文件夹并在启用时重置已备份的世界到启动前存储的状态来实现的
处理崩溃
作为加载器插件,bisect 在非常早期的阶段挂钩到 Quilt 的加载过程。
在那里,它可以创建一个实际运行游戏的新进程,并等待该进程结束。
之后,bisect 通过搜索新的崩溃日志来检查 Minecraft 是否崩溃,复制 latest.log,并更新 config/quilt_bisect/active_bisect.json。
(如果没有活动的二分排查且发生崩溃,它会询问是否应启动一个新的二分排查)
如果 Minecraft 没有正常退出(无论是通过崩溃还是通过 bisect 菜单)且存在活动的二分排查,父进程将重启游戏。
幕后 发生了更多事情,以确保例如杀死父进程或子进程时它们能按预期行为。
检测问题
Bisect 将:
- 处理崩溃
- (待办事项)使用正则表达式检查日志消息(如果可能)
- 依赖用户输入
选择下一个要测试的模组集合
Bisect 使用扩展的二分搜索算法:
- 首先,选择一个具有(未修复)问题的最小模组集合
- 对于该模组集合的每个部分(见最后一行)
- 如果某个部分仅包含一个模组,则该模组是必需的,无需对该部分进行更多操作
- 将该部分一分为二
- 检查这些部分
- 如果其中一部分存在问题,它将成为下一轮迭代中问题模组集合的一部分
- 如果所有部分都能正常工作,则意味着两部分中都存在导致问题出现的必要模组
- => 将这些部分存储为独立的部分,并按照步骤 3 的方式对这些部分进行二分搜索
- 如果所有部分仅包含一个元素,则已隔离出最小复现条件。使用得到的模组集合标记相应的问题为已修复,并移除当前模组中的一个,调试下一个问题
- 完成以上所有操作后,显示最终摘要屏幕。
加载正确的模组集合
此类二分搜索算法面临的主要问题之一是依赖关系。
理想情况下,二分搜索方法应了解依赖关系并基于此进行搜索。
然而,这将极大地增加算法的复杂性,而本项目目前已经足够复杂。
因此,Quilt Bisect 在其搜索算法中简单地忽略依赖关系,并将所有模组提供给 Quilt 加载器。
不过,它仅强制加载模组集合中的模组(即你的 mods 文件夹中的模组),并将其他模组作为可选模组提供,仅在依赖项需要时才会加载它们。
在解决依赖问题的同时,这也带来了一些影响:
- 如果需要,不在模组集合中的模组仍然可以被加载
- 这意味着当二分搜索确定最小复现条件时,该复现集实际上可能只包含一个依赖于真正罪魁祸首的模组
- 这意味着模组集无法显示哪个模组是有问题的,因此在指责某个模组之前必须进行更好的测试
开发
对于测试,我还推荐 Quilt Crasher,这是我开发的用于启用此类模组测试的工具。
许可协议
虽然代码采用 ARR 许可证,但这仅是为了防止移植到其他模组加载器或低质量复制品。你可以自由地复制部分代码用于你的模组。如果你的模组与此模组功能相似,请注明出处。你也可以向我申请许可。如果不是移植到其他模组加载器,我可能会同意。
致谢
PluginLogger、MinecraftServerMixin 和 GracefulTerminator 主要取自 。
BisectPluginProcessManager 也包含了来自该仓库的 ModvotePlugin 的大量代码。
所有这些内容均在 MIT 许可证 下(由 comp500 提供)
IconStore 包含来自 的代码,特别是来自 FabricIconHandler 和 FabricMod#getIcon 的代码。java_icon.png、minecraft_icon.png 和 unknown_icon.png 也取自此处。Mod Menu 同样采用 MIT 许可证(由 Prospector 提供)
Quilt Bisect
A Quilt mod & loader plugin for finding mods responsible for issues using a search algorithm derived from binary search. This includes n-way mod incompatibilities in the form of crashes or user-detected issues.
A word of warning
Quilt Bisect is still experimental. However, I consider it ready for most use cases. Some functions are untested (Realms support), and it depends on an experimental API in quilt loader. Please test all issues (especially with Quilt Loader) without Quilt Bisect before reporting them to other projects. Alternatively, join my discord and get support there.
Usage
- This project uses Loader Plugins,
-Dloader.experimental.allow_loading_plugins=true needs to be added to your JVM arguments.
- Install this mod
- If your game crashes, a dialog will open asking if you want to bisect, else click the start bisect button at the top of your screen, and you will be prompted to give your issue a name.
- The game will automatically restart. Try to reproduce the issues you had before.
- If everything is fine, click the
No Issue button
- If you have an issue click the
Manual Issue button, and select the issue you are having or create a new one
- Note that it is recommended to keep the number of issues in one bisect down, and instead run multiple bisects with previous fixes applied. See Bisecting multiple issues at once
- once an issue is isolated, bisect will verify the solution(s) and continue bisecting the other issues
- once bisect is done, it will provide a summary of issues and solutions encountered. Please treat those with care though, due to the way bisect works
Configuring
The file <config>/quilt_bisect/main.json contains most things a user may want to configure, see MainConfig.java for now.
The file <config>/quilt_bisect/active_bisect.json contains information about the active bisect, including the settings, all tried mod sets and their respective log, and issue information.
The files <config>/quilt_bisect/modSet.txt, <config>/quilt_bisect/sections.txt, and <config>/quilt_bisect/lastActiveJoin.txt contain internal information and shouldn't be modified.
How does it work
Bisecting multiple issues at once
While bisecting multiple issues works, there are a few assumptions bisect makes that are essential when multiple issues are present:
- Only removing a mod can fix an issue, not adding one
- A common example for this would be indium, which fixes compatibility issues between sodium and other mods, if it wouldn't be declared by the other mods involved
- There is a constant priority order between issues
- If a subset B of a mod set with issue A has an issue different from issue A, issue A won't occur on any subset of B. This means that issues (even if marked by the user) must always be tested for in the same order
Automatically mark things as working
When starting a new bisect, you can configure bisect to
- automatically join a world, server, realm, or the last joined one (Note that realms rely on ids and not on names)
- automatically accept a mod set as working after a given time
- The time is in 1/20 seconds, and will start on world join if auto join is active, else when the title screen shows. If in single player, it will also wait for enough ticks to pass
- automatically run commands or sending chat messages after auto joining.
- It will be treated as if you sent them from chat, and also work with client side commands
- disable world saving
- This is to help reproduction of issues where the state of the world is relevant. No single player world will be changed after a relaunch if this is active. It also allows for testing content mods
- For maximum compatibility it is currently implemented by making a backup of the worlds folder and resetting the worlds that have been backed up to the stored state before launch if active
Handling crashes
Being a loader plugin, bisect hooks into the Quilt's loader process at an incredibly early stage.
There, it can create a new process that is actually running the game, and wait for that process to end.
After that bisect checks if minecraft crashed by searching for a new crash log, copies the latest.log, and updates config/quilt_bisect/active_bisect.json.
(if no bisect is active and it crashed it asks if a new one should be started)
If minecraft didn't quit normally (either through a crash or through the bisect menu) and a bisect is active, the parent process will restart the game.
Behind the scenes there is a lot more stuff going on making sure that for example killing the parent or child process makes them behave as expected.
Detecting issues
Bisect will
- Handle crashes
- (TODO) Check for log messages using regexes (if possible)
- Rely on user input
Selecting the next mod set to test
Bisect works using an extended version of binary search:
- First, select the smallest mod set with an (unfixed) issue
- For each section of that mod set(see last row)
- If a section simply includes one mod, that mod is required and no more work needs to be done on that section
- Divide that section into half
- Check those halves
- if one has an issue, it becomes a part of the issue mod set in the next iteration
- if all halves are working this means that in both halves are mods required for the issue to arise
- => store those halves as separate sections and bisect those like in step 3
- if all sections only contain one element, a minimal reproduction has been isolated. Mark the corresponding issue as fixed with the resulting mod set and debug the next issue, with one of the current mods removed
- Once all of this is done, display the final summary screen.
Loading the right mod set
One of the main problems such a bisect algorithm faces are dependencies.
Ideally, a bisect method would be aware of dependencies and bisect based on those.
However, this would immensely inflate the complexity of the algorithm, and this project is complex enough right now.
Instead, Quilt Bisect simply ignores dependency in its search algorithm and provides all mods to quilt loader.
However, it only force-loads mods in the mod set (this is what happens to mods in your mods folder) and provides the other mods as optional mods which are only loaded when a dependency requires it.
While solving the dependency issue, it has a few implications:
- If required, a mod not in the mod set still can be loaded
- This means that it can happen that when bisect identifies a minimal reproduction, that reproduction set actually only includes a mod which depends on the real culprit
- This means that the mod set can not show which mod is at fault and that before blaming a mod some better tests must occur
Development
For testing, I also recommend Quilt Crasher, which I developed to enable testing of this kind of mod.
Licensing
While the code is ARR, this is only to prevent ports to other mod loaders or low-effort copies. Feel free to copy parts of the code for your mod. If your mod does similar things to this mod, credit me. You can also ask for me for permission. If it's not a port to another mod loader, I'll likely agree.
Credit
PluginLogger, MinecraftServerMixin and GracefulTerminator were mostly taken from .
BisectPluginProcessManager also contains large parts of ModvotePlugin from that repo.
All of these are under the MIT license (by comp500)
IconStore contains code from , specifically from FabricIconHandler and FabricMod#getIcon. java_icon.png, minecraft_icon.png and unknown_icon.png were also taken from there. Mod Menu is also licensed under the MIT license (by Prospector)
评论 0
登录后参与评分
还没有评论,来抢沙发吧