模组生命周期
加载
启动时(引擎就绪、Lua 虚拟机建好之后):
- 读
state.json,迁移旧布局,把kmod/mods/同步到应用的私有目录:模组文件夹有变化就复制,.kmod文件有变化就解压;已经不在kmod/mods/里的模组,私有副本会删除。模组从私有目录加载。 - 读取游戏版本,扫描私有目录里的模组并校验每个包。
- 按依赖做拓扑排序(先加载被依赖的)。
- 对每个已启用且校验通过的模组:建一个独立的环境,运行
main.lua。
模组之间的全局变量互不干扰;require 只读本模组目录里的文件。
重新加载
进入 Mods 页发现有新包、在 Mods 页启用或禁用模组、控制台里 reload、模组被自动禁用时,都会触发重新加载:
- 所有模组注册的钩子、定时器、新对象监听、控制台指令全部撤销;
- 然后重新扫描并加载一遍。
所以 main.lua 里注册的东西不需要手动清理,但 你自己保存在全局里的游戏对象引用会因为环境重建而丢掉。
禁用
在 Mods 页取消勾选、disable 指令、或被自动禁用,都会把模组从 state.json 的 enabled 里去掉并重新加载。设置值保留在 data/<id>/。
自动禁用
模组在钩子、ExecuteWithDelay / LoopAsync、NotifyOnNewObject 的回调里,同一次运行内累计抛出 10 次错误,加载器会禁用它(写入 state.json)并重新加载全部模组。原因写进日志,并显示在 Mods 页的状态里。用户重新勾选启用后,错误计数清零。
- 控制台指令出错、
main.lua加载出错不计入这个数;加载出错会直接显示load error。 LoopAsync的回调一抛错,这个循环就停止,不会重复。