Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

模组包格式(format 1 和 2)

一个包 = 一个文件夹;本地化可选,不写也能用。

hello_mod/                 # 文件夹名 = 模组 id
├── mod.json               # 清单(必需)
├── main.lua               # 入口(必需)
├── lang/                  # 本地化(可选)
│   ├── en.json
│   └── zh-CN.json
└── ...                    # 其余 Lua 模块、数据文件,随意
  • 分发形式:把文件夹里的内容打成 zip,扩展名改成 .kmod,详见打包。
  • 安装:解压到 kmod/mods/<id>/;直接放一个文件夹进去效果一样。包视为只读,升级 = 整个替换。
  • 用户数据:kmod/data/<id>/settings.json,和包分开,升级不会丢。

mod.json

{
  "format": 2,
  "platform": ["Windows", "Android"],
  "id": "hello_mod",
  "name": "Hello Mod",
  "version": "1.0.0",
  "author": "kmod",
  "description": "A demo mod.",
  "depends": ["kmod>=0.2.0", "kards>=1.61"],
  "settings": [
    {"id":"verbose","type":"bool","label":"Verbose log","default":false},
    {"id":"scale","type":"number","label":"Scale","min":0.5,"max":2,"step":0.25,"default":1},
    {"id":"mode","type":"choice","label":"Mode","options":["low","medium","high"],"default":"medium"},
    {"id":"nick","type":"string","label":"Nickname","default":"Bob","maxlen":12}
  ]
}
字段必需说明
format是包格式版本:1 或 2。用了 platform(或原生库)的包写 2,只认识 1 的旧加载器会直接拒绝它,而不是在错误的平台上运行
platform否支持的平台:"Android"、"Windows" 或列表 ["Windows", "Android"](不区分大小写)。没有这个字段 = 所有平台,纯 Lua 模组一般不用写。当前平台不在列表里时,模组不会加载,Mods 页显示“不适用于本平台“,也不能启用。带原生库的模组必须声明它为哪些平台编译
id是小写字母、数字、下划线(^[a-z0-9_]+$);必须和文件夹名一致
version是版本号,供依赖检查和显示
name否默认显示名(通常英文);缺省用 id
author否作者
description否说明,显示在 Mods 页该模组的版本行上方;有 lang 翻译时用翻译
api否需要的加载器接口级别,高于当前(kmod.api)就拒绝加载。新模组建议改用 kmod>=x.y.z
depends否依赖列表,见依赖与版本条件
native否C++ 模组的库文件名,在包里的 native/arm64-v8a/ 下找。必须同时是 "format": 2 并写 platform;有 native 时 main.lua 可以没有。见 C++ 模组
permissions否权限声明列表。目前只有 "network":允许使用 Http、WebSocket 与 Socket;"game_network":允许使用 Net(观察和修改游戏自己的 WebSocket 消息)。不认识的权限会被忽略并警告
settings否设置项,见设置项

从旧布局迁移

加载器会自动兼容并迁移:

旧布局新格式说明
Scripts/main.luamain.lua没有根目录 main.lua 时仍读 Scripts/main.lua,并警告
<mod>/enabled.txtstate.json 的 enabled首次启动自动迁移,然后删除旧文件
<mod>/settings.jsondata/<id>/settings.json首次启动自动搬移
choice 保存选项文字保存稳定值旧值等于某个选项时沿用
mod.json 无 id必须有 id缺省时取文件夹名并警告