热重载 - 无需重启即可更改模组代码

热重载 - 无需重启即可更改模组代码

《七日杀》模组热重载:重新编译C#并加载到运行中的游戏,无需重启。游戏内页面、控制台命令、可选快捷键。适用于任何选择启用的模组。面向模组作者。

[size=4][b]更改模组的 C# 代码,并把新构建加载到正在运行的游戏里。无需重启。[/b][/size]

现在,改动一行 C# 的代价是:关闭游戏、重新构建、启动、等过加载画面、加载世界、走回你刚才测试的位置。两分钟。一个开发时段四十次。

装上这个之后,代价是一次按键。在编辑器里重新构建,Alt-Tab 切回来,按下一行,新构建就在你站着的世界里生效了。

[size=4][b]一个游戏内页面[/b][/size]

[b]Esc -> Hot Reload。[/b]

[list]
[]你正在开发的每个模组,以及它的加载次数。[b]按下一行即可重新加载它。[/b][/]
[][b]Reload all[/b] 和 [b]Rescan[/b] —— Rescan 会拾取自游戏启动以来你新建的模组文件夹,所以一个全新的模组也不需要重启。[/]
[][b]Open log[/b] —— 打开真正的 Player.log。它位于 AppData\LocalLow 下,而那不是大多数人会去找的地方。[/]
[]核心启动失败的模组会以红色列出并附上原因,而不是悄无声息地消失。[/]
[/list]
[size=4][b]默认不绑定任何热键[/b][/size]

每一个空闲按键都是某个其他模组里某人的绑定,而一个悄悄偷走按键的开发工具,比一个根本没有按键的开发工具更糟。想要的话,在页面里绑定你自己的键——它按机器存储而非存在模组里,所以更新后依然保留。还有一个 [b]modreload[/b] 控制台命令,页面上的每个按钮都有对应的控制台动词。

[size=4][b]强烈推荐:添加 DevLink[/b][/size]

Hot Reload 本身只做一件事——C#。这确实有用,但它只是开发循环的一半,而你在 7 Days to Die 模组里改动的大部分内容并不是 C#。

安装配套的 [b][url=https://www.nexusmods.com/7daystodie/mods/12652]DevLink[/url][/b],页面会长出完整的第二个区域:

[list]
[][b]Reload XML[/b] —— 任何配置文件,[i]并应用你自己的 XPath 补丁[/i]。物品、方块、增益、配方、进度、战利品、entityclasses。(这不是引擎自带的 reloadxml,后者直接读取 Data/Config 并会悄悄还原每个模组补丁。)[/]
[][b]Reload bundle[/b] —— 就地重新加载模组 AssetBundle:网格、预制体、材质[/]
[][b]Localization[/b] —— Localization.csv,原版加上每个模组的补丁文件[/]
[][b]UI atlases[/b] —— 物品图标和 HUD 精灵,引擎刻意拒绝在游戏内重新加载这些[/]
[][b]Re-mesh world[/b] —— 让方块和材质编辑显示在已存在的地形几何体上,而无需删除已保存的区块[/]
[/list]
没有 DevLink 时,那五个按钮会被隐藏而不是失效,这个模组的其他一切都不变。

[b]DevLink 也远不止那几个按钮。[/b]它会打开一个回环 TCP 端口,好让脚本——或一个 AI 编程助手——能够驱动并检查运行中的游戏:截图、读取实时 CVar 或物品属性以证明某个 XML 编辑确实生效、检查某个增益是否被解析、询问为什么手持物品无法开火,以及移动玩家。它还附带一个为配合 Claude Code 使用而构建的大型 7 Days to Die 模组开发知识库。

两者合在一起就是那个循环:改动任何东西,重新加载它,验证它生效——而游戏始终不必关闭。

[size=4][b]为什么普通模组 DLL 无法被重新加载,以及这个模组改用了什么方法[/b][/size]

游戏用 [b]Assembly.LoadFrom[/b] 加载模组程序集,这会让文件在整个进程生命周期内保持打开——所以在游戏运行时重新构建模组 DLL 会直接失败。游戏的模组扫描也是非递归的,因此子文件夹里的任何东西它都看不见。

把这两点放在一起,技巧就浮现出来了。你的代码放在 [b]YourMod/Reloadable/YourModCore.dll[/b],游戏从不打开或锁定它,这个模组则以字节形式读取它。Assembly.Load(byte[]) 会复制映像且不持有文件句柄,所以你下一次构建可以就地覆盖该文件。

[size=4][b]让你自己的模组可重新加载[/b][/size]

一个全名以 [b].CoreEntry[/b] 结尾的类型,带公共静态成员。无需引用这个模组——契约按名称查找。

[code]
namespace MyMod
{
    public static class CoreEntry
    {
        public static string Boot(string modFolder) { return "ok"; }
        public static string Shutdown() { return "ok"; }

        // 可选
        public static string Invoke(string command) { return "(unknown)"; }
        public static void Update() { }
        public static void LateUpdate() { }
        public static void OnGUI() { }
    }
}[/code]
Boot 会收到你的模组文件夹,因为按字节加载的程序集其 Location 为空,否则无法找到自己的数据文件。

有 [b]三条你不可打破的规则[/b],每条都是引擎强加的,而非出于偏好:

[list=1]
[][b]核心中不能有 MonoBehaviour。[/b] Unity 会静默拒绝为来自字节数组加载程序集的类型调用 AddComponent——它返回 null,没有异常也没有日志行,于是你的 Boot 看起来成功了,而实际什么都没运行。使用普通类;这个模组会替你驱动你的 Update / LateUpdate / OnGUI,且在其他所有逻辑之后运行,因此逐帧工作可以胜过 Mecanim 和相机控制器。[/]
[][b]核心之外的任何东西都不得持有对核心类型的编译时引用。[/b] 重新加载时它们会被整体替换,而同名程序集两次加载产生的类型尽管名称相同却不可互换。用字符串与核心通信。[/]
[][b]控制台命令必须位于根模组 DLL 中。[/b] ConsoleCmdAbstract 子类只有在游戏自身加载的程序集里才会被发现。[/]
[/list]
附带的 [b]docs/HOT_RELOAD.md[/b] 包含完整契约、迫使每条规则成立的引擎细节、限制与故障排查。契约按名称查找且无需引用这个模组,因此你的模组不会因此产生任何依赖。

[size=4][b]需求[/b][/size]

[list]
[][b]关闭 EasyAntiCheat[/b] —— 这个模组包含 DLL,而游戏在开启 EAC 时会静默跳过 DLL 模组[/]
[]没有其他需求。它没有依赖——可以独立正常运行。[/]
[/list]
[b]可选但推荐:[/b][url=https://www.nexusmods.com/7daystodie/mods/12652]DevLink[/url],用于上面那一节所述的一切。

7 Days to Die [b]V 3.2.0 (b10)[/b]。

[size=4][b]安装[/b][/size]

[list=1]
[]关闭 EasyAntiCheat。[/]
[]下载并解压。[/]
[]把 [b]HotReload[/b] 文件夹放进你的 Mods 文件夹:%APPDATA%\7DaysToDie\Mods\ 或 <game folder>\Mods\[/]
[]启动,加载一个世界,按 Esc。[/]
[/list]
[size=4][b]它做不到的事[/b][/size]

在你依赖它之前值得了解。

[list]
[][b]它无法重新加载自己。[/b] 编辑这个模组意味着重启。这就是设计:它刻意保持极小且稳定,好让其他一切变得可重新加载。[/]
[][b]它无法重新加载 XUi 控制器类。[/b] 重新加载后会有两个同名的字节加载程序集,而 Type.GetType 会在 AssemblyResolve 被触发之前就从域中已有的程序集得到满足——所以最旧的副本获胜。你的 XUi controller= 绑定会继续指向旧核心。保持控制器轻薄,把逻辑放在最新核心所拥有的位置。[/]
[][b]Mono 无法卸载程序集[/b],所以每次重新加载都会泄漏之前的映像。对于一个使用几十次的开发时段来说没问题;绝不要在已发布的模组中带上这种行为。[/]
[][b]它不会替你构建任何东西。[/b] 它会再次从磁盘读取 DLL——请先在编辑器里重新构建。从游戏模组里启动构建进程不是它会做的事。[/]
[][b]它不会自行重新加载数据。[/b] XML、bundle、本地化和图标是 DevLink 的那一半——见上文。[/]
[/list]
[size=4][b]不面向玩家[/b][/size]

它包含 DLL,按设计会泄漏内存,并且会加载游戏自身加载器刻意看不见的代码。[b]在发布模组之前移除它。[/b]不要让你的模组依赖它,也不要把它打包在模组里发布。

[size=4][b]许可[/b][/size]

用它开发任何你喜欢的东西,包括你以商业方式发布的模组。你用它所制作的东西不受其许可证约束,也无需署名。文档中的可重新加载核心契约可自由实现——你自己的模组从不引用这个模组。请不要重新上传它、分发修改副本,或将其打包进整合包。见 LICENSE.txt。