巫师3模组配置加载器

[center][size=6][b][color=#c84b43]Witcher 3 Mod Config Loader[/color][/b][/size]
[size=3][color=#d8d8d8]更简洁的模组设置管理方式。[/color][/size]

[color=#c6aa76][b]W3MCL - 公开测试版[/b][/color][/center]

《巫师 3》的模组制作已经发展了很长一段时间，如今的事情确实比以前容易多了。不过，管理设置、按键绑定和菜单文件仍然有些麻烦，尤其是当你经常安装、更新或移除模组时。

[color=#b6d7a8]这正是我想通过 W3MCL 简化的部分：让模组能够添加自己的设置，而无需不断编辑游戏的配置文件。[/color]

已经有一些很出色的工具让《巫师》的模组制作轻松了许多，我并不是想取代它们。我希望将模组设置与游戏的原始文件分开保存，由加载器在游戏启动时把所有内容整合起来。我主要是针对 [b]MO2 及其虚拟文件系统[/b] 来构建的，但手动安装同样可行。

灵感来源于 [b]Jack Humbert[/b] 制作的 [url=https://www.nexusmods.com/cyberpunk2077/mods/4575][b]Input Loader for Cyberpunk 2077[/b][/url]。感谢他提供了这个想法。我想要为《巫师 3》做一个类似的东西，但除了按键绑定之外，还要覆盖设置和菜单。

[quote][color=#e3b08b][b]这是一个测试版本。[/b][/color]到目前为止，我主要在 Windows 上使用重制版 5.01、DX12 和 MO2 进行了测试。还有很多模组组合我没有尝试过，因此可能存在 bug。如果你遇到任何问题，请报告。这包括加载器本身、MO2 插件或转换器的问题。其他游戏版本尚未经过验证。[/quote]
[size=5][b][color=#c84b43][font=Courier New]工作原理[/font][/color][/b][/size]

当你启动游戏时，W3MCL 会从已准备好的模组（你在 MO2 中安装或启用的模组）中收集设置、按键绑定和菜单。它按加载顺序合并这些内容，并将结果放入一个单独的缓存中。

当游戏需要这些文件时，加载器会让它改为读取缓存的版本。你在游戏内更改的任何设置也会保存到那里。无需将任何内容复制到游戏的原始配置文件或你的 Documents 文件夹中。

当缓存重建或模组更新时，只要该模组仍然启用，你自己的设置和按键绑定就会被保留。新选项使用其默认值。禁用或移除一个模组后，其设置会在下次启动时从缓存中移除。如果你使用 MO2，每个配置文件都有各自的缓存和已保存的设置。

你可以在 [font=Courier New]mods/w3mcl/[/font] 中找到缓存和日志。使用 MO2 时，请检查 Overwrite 或 W3MCL 模组文件夹。

[b]脚本冲突仍然需要使用 Script Merger。[/b] W3MCL 只处理设置、输入和菜单。脚本、纹理和其他游戏文件仍按常规方式安装和处理。

[size=5][b][color=#c84b43][font=Courier New]为什么模组需要准备？[/font][/color][/b][/size]

你可能会想，为什么加载器不能自己查找每一个设置或 XML 文件。问题在于，许多模组使用相同的文件名，并将它们安装到相同的位置。[font=Courier New]input.xml[/font] 就是一个很好的例子。在手动安装的情况下，一个模组可能会覆盖另一个模组。MO2 会保留两个文件，但游戏只能看到冲突中获胜的那个。无论哪种方式，在 W3MCL 读取它们之前，某些设置可能就已经丢失了。

其他模组管理器通常通过在安装过程中合并这些文件来处理这个问题。W3MCL 的做法不同：准备脚本会将每个模组的配置移动到各自的 [font=Courier New]merge/[/font] 文件夹中。这样，加载器就能找到所有文件，并在游戏启动时将它们合并，而不会触及游戏的原始设置。

你不必手动执行此操作。MO2 插件可以在你安装模组时准备它们，此外还有一个独立的转换器。模组作者也可以从一开始就以 W3MCL 格式打包他们的模组。目的只是确保一个模组的文件不会隐藏或覆盖另一个模组的文件。

[color=#e3b08b][b]致模组管理器和插件作者：[/b]欢迎你在自己的模组管理器中，或在 MO2、Vortex 或其他管理器的插件中使用准备脚本的代码，以添加对 W3MCL 就绪模组的支持。[/color]

[size=5][b][color=#c84b43][font=Courier New]安装[/font][/color][/b][/size]

[color=#e5cf91][b]重要：从干净的游戏设置开始。[/b]如果另一个工具/模组管理器已经将模组设置合并到你的游戏文件中，你需要先撤销那些旧的合并。如果你有备份，请从备份恢复干净的文件。否则，关闭游戏，删除受影响的设置文件，并在不启用 W3MCL 的情况下启动一次，以便游戏创建新的文件。如果你使用 MO2 的配置文件专属设置，请在当前活动的配置文件中执行此操作。否则，请检查 Documents/The Witcher 3。[b]请先备份你的设置[/b]，因为这会重置保存在这些文件中的偏好设置和按键绑定。不要动你的存档。W3MCL 不会自动清理旧的合并。[/color]

[b][color=#c6aa76]使用 MO2[/color][/b]

[list]
[]从 Files 选项卡单独下载 [b]MO2 插件[/b]。关闭 MO2，然后将 [font=Courier New]MO2/plugins/w3mcl_installer[/font] 文件夹复制到 MO2 的 [b]plugins[/b] 文件夹中。[/]
[]启动 MO2，并在安装或准备模组之前，确保在 [b]Settings -> Plugins[/b] 下启用了 [b]Witcher 3 Mod Config Loader[/b]。[/]
[]通过 MO2 下载你偏好的版本，[b]Proxy[/b] 或 [b]ASI[/b]，并像安装其他模组一样安装它。ASI 需要 ASI Loader（见下文）。压缩包已经包含正确的文件夹结构。你也可以安装手动下载的压缩包，或者创建一个名为 W3MCL（或你喜欢的任何名称）的空模组，并将内容解压到其中。启用 W3MCL 模组。[/]
[]安装 W3MCL 就绪的模组，或者让插件在你安装普通模组时准备它们。对于你已经拥有的模组，在 MO2 的左侧面板中选择它们，右键单击并选择 [b]W3MCL -> Prepare selected mods[/b]。重新安装它们也可以。[/]
[][color=#e5cf91][b]MO2 + Proxy 的重要提示：[/b]打开 [b]Modify Executables[/b]，选择游戏并启用 [b]Force load libraries[/b]。点击 [b]Configure libraries[/b]，添加一行，[b]Process: witcher3.exe[/b] 和 [b]Library: winmm.dll[/b]。只输入这些名称，[b]勾选新行旁边的复选框[/b]，然后保存两个对话框。[/color][/]
[]模组准备就绪后，通过 MO2 启动游戏。[/]
[/list]
MO2 插件负责准备；加载器本身在游戏中运行。更新模组时，请选择 [b]Replace[/b] 而不是 Merge，因为 Merge 可能会留下旧文件。

将 W3MCL 保留在其 MO2 模组文件夹中。如果你之前将其直接复制到游戏目录中，请先删除该副本。这样，在 MO2 中禁用 W3MCL 模组也会禁用加载器。

确保在游戏的 [b]Options -> Gameplay[/b] 设置中启用了模组和本地模组。如果你在游戏运行时打开它们，请重新启动游戏，以便 W3MCL 能够加载它们的配置。

[b][color=#c6aa76]不使用模组管理器[/color][/b]

下载你偏好的版本，[b]Proxy[/b] 或 [b]ASI[/b]，并将压缩包的内容复制到你的《巫师 3》安装文件夹中，保持文件夹结构。你会在 [font=Courier New]bin/x64_dx12/[/font] 中找到 [b]winmm.dll[/b]（Proxy）或 [b]w3mcl.asi[/b]（ASI），就在 [b]witcher3.exe[/b] 旁边。在启动游戏之前，请安装你的模组的 W3MCL 就绪版本，或使用下面描述的独立转换器准备它们，并安装转换后的副本。

[b][color=#c6aa76]选择 Proxy 还是 ASI[/color][/b]

[b]Proxy[/b] 无需单独的 ASI Loader 即可工作。[b]ASI[/b] 需要一个 ASI Loader，如果你已经安装了一个，或者另一个模组使用了 [b]winmm.dll[/b]，那么它是一个有用的选择。我使用其默认设置与 [url=https://github.com/ThirteenAG/Ultimate-ASI-Loader][b]Ultimate ASI Loader[/b][/url] 进行了测试。其他 ASI Loader 尚未经过验证。不要同时安装两个 W3MCL 版本，也不要覆盖另一个模组的 [b]winmm.dll[/b]。

如果这是一个全新的游戏安装，请启动游戏一次以便它创建设置，关闭它，然后再次启动以应用模组设置。

[size=5][b][color=#c84b43][font=Courier New]如何准备模组[/font][/color][/b][/size]

如果作者提供了 W3MCL 就绪的下载，请使用那个。否则，你可以在启动游戏之前自行准备普通版本。

[b][color=#c6aa76]使用 MO2[/color][/b]

启用 W3MCL 插件后，像往常一样安装模组。插件会自动准备其配置文件。对于已安装的模组，在左侧面板中选择一个或多个，右键单击并选择 [b]W3MCL -> Prepare selected mods[/b]。检查结果中是否有任何警告。没有设置、按键绑定或菜单的模组不需要转换。

[b][color=#c6aa76]使用独立转换器[/color][/b]

[list]
[]安装 [b]Python 3.10 或更新版本[/b]，并从 Files 选项卡下载 [b]转换脚本[/b]。[/]
[]将模组解压到其自己的文件夹中，例如 [b]My Mod[/b]。将 [b]convert_mod.py[/b] 放在该文件夹旁边，然后在那个位置打开终端。[/]
[]运行下面的命令。转换器会显示计划的更改并要求确认。输入 [b]y[/b] 以创建准备好的副本。[/]
[/list]
[code]python convert_mod.py "My Mod" --output "My Mod - W3MCL"[/code]
如果它询问某个配置属于哪个模组文件夹，请选择匹配的模组或查看建议的名称。在安装结果之前检查任何警告；转换器无法处理的文件可能仍需注意。

按照模组通常的安装说明安装 [b]My Mod - W3MCL[/b] 的内容，然后启动游戏。使用准备好的副本而不是原始包。转换器不会改动你的原始文件夹。请将其指向解压的模组，[b]而不是你的游戏目录或 Documents 文件夹[/b]。如果下载包含多个可选版本，请在转换前选择你想要的版本。

[size=5][b][color=#c84b43][font=Courier New]其他模组管理器[/font][/color][/b][/size]

[color=#e3b08b][b]Vortex 尚不支持。[/b][/color]它的《巫师 3》集成会自动将模组设置合并到游戏的常规配置文件中。这与 W3MCL 背后的整个理念相悖：保持这些文件干净，让你能够添加或移除模组而无需编辑它们。[color=#c6aa76][i]我正在研究一种让它们协同工作的方法。[/i][/color]

如果你使用其他管理器，其自动的 [b]设置、输入和菜单合并[/b] 也需要禁用。这些是 W3MCL 的职责。你仍然可以使用 Script Merger 处理脚本。

当然，Vortex 并不是唯一会合并这些文件的管理器。我希望它们的作者能够愿意添加一个开关，为 W3MCL 就绪的模组关闭该功能，或者使用 W3MCL 附带的准备脚本在安装过程中自动准备模组。这样，管理器负责安装，W3MCL 负责游戏启动时的配置合并。

[size=5][b][color=#c84b43][font=Courier New]你可以更改的设置[/font][/color][/b][/size]

你可以在 [font=Courier New]mods/w3mcl/config.json[/font] 中找到 W3MCL 的选项。对于大多数设置来说，默认值应该就可以了。如果你想更改某些内容，请先关闭游戏。你的更改会在下次启动时生效。

[list]
[][b]cache.rebuild[/b]：[b]always[/b] 会在每次启动游戏时重建缓存。目前我建议保持这种方式。[b]on_change[/b] 仅在相关模组、文件、设置或加载顺序发生变化时重建。[/]
[][b]conflicts.definitions[/b]：当两个模组对同一设置或选项的定义不同时会发生什么。[b]priority[/b] 遵循加载顺序，[b]preserve[/b] 保留较早的定义，[b]error[/b] 停止合并。检查日志以查看涉及哪些模组以及使用了哪个定义。[/]
[][b]input.conflict_policy[/b]：[b]additive[/b] 允许不同的操作使用同一个按键，并向日志写入警告。有些模组会故意这样做。[b]error[/b] 则会拒绝这些重叠。[/]
[][b]input.preserve_player_bindings[/b]：如果你想保留你在游戏内更改的按键绑定，请保持为 [b]true[/b]。将其设置为 [b]false[/b] 以从原始设置和已启用模组的默认值重建它们。你更改的其他设置仍然会被保留。[/]
[][b]merge[/b]：四个开关，用于控制 W3MCL 处理的内容：[b]inputs[/b]（按键绑定）、[b]settings[/b]（游戏和模组设置）、[b]menus[/b]（菜单文件）和 [b]input_xml[/b]（输入菜单定义）。将其中任何一个设置为 [b]false[/b] 以将该类别交给游戏的常规文件处理。在大多数情况下，你会希望四个都启用。[/]
[][b]menu.generate_filelists[/b]：创建旧版游戏用于查找模组菜单的文件列表。默认为 [b]true[/b]，但重制版 5.01 DX12 已在将其设置为 [b]false[/b] 的情况下进行了测试。关闭它不会禁用菜单合并，也不会移除其他模组添加的文件列表。[/]
[][b]logging.verbose[/b]：默认为 [b]false[/b]。如果某些功能不正常工作，并且你需要在日志中获取更多信息，请启用它。警告和错误无论如何都会被记录。[/]
[/list]
MO2 插件还有一个 [b]auto_convert_mods[/b] 选项，用于控制是否自动准备新安装的模组。如果你关闭它，你仍然可以使用右键菜单准备模组。配置文件支持也继续有效。

[size=5][b][color=#c84b43][font=Courier New]报告问题和卸载[/font][/color][/b][/size]

如果你发现 bug，请包含你的游戏和 W3MCL 版本、你使用的模组管理器、涉及哪些模组以及如何重现该问题。日志位于 [font=Courier New]mods/w3mcl/logs/w3mcl.log[/font]。如果可能，请启用 [b]logging.verbose[/b] 并尝试再次重现问题。在 MO2 中，你还可以在模组列表中右键单击并选择 [b]W3MCL -> Export diagnostics[/b]，将有用的文件收集到一个 ZIP 中。上传前请检查其中的内容。

要卸载，请关闭游戏并从 MO2 中移除 W3MCL 模组和插件。对于手动安装，请根据你安装的版本移除 W3MCL 的 [b]winmm.dll[/b] 或 [b]w3mcl.asi[/b]。你也可以移除 [font=Courier New]mods/w3mcl/[/font]，但请记住 [b]删除缓存也会删除你保存的模组设置和按键绑定[/b]。为 W3MCL 准备的模组需要以正常格式重新安装。如果其他模组使用了你的 ASI Loader，请保留它。

[size=5][b][color=#c84b43][font=Courier New]致模组作者[/font][/color][/b][/size]

你不需要更改你的主下载，也不需要要求所有人以不同方式安装你的模组。如果你想支持 W3MCL，你只需提供一个 [b]单独的可选版本[/b]，就像一些作者为其他《巫师》模组管理器所做的那样（或者曾经这样做过？我记得当时在很多模组页面上看到过那些版本）。玩家可以选择适合他们的版本，Files 选项卡中有一个 [b]转换脚本[/b] 可以帮助你准备一个。

下面的文件夹布局在 W3MCL 之外也可能有用。它将你模组的所有配置文件集中在一个地方，与脚本和其他文件分开，使整个包更整洁一些。如果你的模组管理器能够找到并合并这些文件，无论它们存储在哪里，它也应该能很好地配合这种布局。当然，请先检查你的工具是否支持。这只是一个建议，不是任何人都必须遵循的。

安装 Python 3.10 或更新版本后，解压你的模组并运行：

[code]python convert_mod.py "My Mod" --output "My Mod - W3MCL"[/code]
脚本会向你显示它将要移动的内容，并在创建新包之前询问。你的原始模组文件夹保持不变。如果某个共享配置文件可能属于多个模组文件夹，它会询问你将其放在哪里。在上传结果之前，请查看任何警告。

[b][color=#c6aa76]布局[/color][/b]

对于大多数模组，你只需要在模组文件夹内有一个 [font=Courier New]merge/[/font] 文件夹。将你的模组使用的配置文件放在那里，保持这些名称：

[code]mods/
modExample/
content/
scripts/...
merge/
input.settings
user.settings
dx12user.settings
input.xml
menus/modExample.xml[/code]
只包含你的模组使用的配置文件，遵循上面的布局。保留原始菜单文件名，并将脚本、包和翻译保留在它们通常所属的位置。

W3MCL 通过文件夹名称（在此示例中为 [font=Courier New]modExample[/font]）来识别每个模组。在更新之间保持该名称不变，以便玩家不会丢失他们保存的模组设置。转换器也理解这种布局，并且不会更改已经准备好的模组。

[color=#e3b08b]正如我上面提到的，这只是一个建议的布局，不是每个人都要遵循的新标准。我认为它在 W3MCL 之外也可能有用，我很乐意听取模组作者、玩家和模组管理器开发者的想法。也许我们最终能就一些简单且能与其他工具良好配合的方案达成一致。如果你的模组使用不同的布局，没问题。这正是转换器的用途。[/color]

[b][color=#c6aa76]一个真实的例子：Friendly HUD[/color][/b]

以下是我准备我的 [url=https://www.nexusmods.com/witcher3/mods/7290][b]Friendly HUD[/b][/url] 副本的方式。它有按键绑定、设置、输入定义和一个菜单：

[code]mods/
modFriendlyHUD/
content/
scripts/...
en.w3strings
ru.w3strings
merge/
input.settings
dx12user.settings
input.xml
menus/modFHUDConfig.xml[/code]
就是这样。脚本和翻译保持在原来的位置。这只是我转换后的副本，因此不同版本的 Friendly HUD 布局可能有所不同。

[i]Friendly HUD 由 wghost81 / Wasteland Ghost 及其贡献者制作。我只是将其作为示例使用。没有 HUD 受到伤害。[/i]

[size=5][b][color=#c84b43][font=Courier New]源代码和后续计划[/font][/color][/b][/size]

等我稍微清理一下之后，我会发布源代码。在构建 W3MCL 时，我复用了我的 [url=https://www.nexusmods.com/stalker2heartofchornobyl/mods/1493][b]S2AE[/b][/url] 项目的一些部分：它已经有钩子、日志、补丁工具和其他现成的辅助工具，这让我省去了重新构建所有这些的工作。我想在把代码发布出去之前先把那些部分整理好。

目前，我会继续开发加载器并修复出现的问题。真实的模组列表往往会发现测试环境遗漏的问题，所以非常欢迎 bug 报告。如果你正在开发模组管理器并想添加 W3MCL 支持，请随时联系我。

[center][color=#c6aa76][b]感谢试用！[/b][/color][/center]