来源: data/lua/README.md data/lua/LUA_FIRST_PLATFORM.md data/lua/types/ccb_platform_v1.d.lua tools/create_lua_mod.py commit 73432156f423 api-contract

Lua Platform v1：从零到运行¶

CCB 当前只支持 Lua Platform v1。旧的 Lua API v5、game.* 全局表、权限清单和 JSON Manifest 已经移除，不要照旧页面编写新 MOD。

最小 MOD¶

新建一个目录，只放 main.lua：

local ccb = require("ccb")

ccb.runtime.handler("welcome", function()
    ccb.services.message("我的第一个 CCB Lua MOD 已运行")
end, 1)

ccb.runtime.on("world_ready", "welcome")

可选的 mod.lua 用来声明名称、版本和依赖：

local ccb = require("ccb")

return ccb.ModDefinition {
    id = "my_first_mod",
    name = "My First MOD",
    version = "0.1.0",
    dependencies = { "dda" },
}

最终目录如下：

my_first_mod/
├── main.lua
└── mod.lua        # 可选

不需要 modinfo.json、manifest.json 或 lua/ 子目录。

安装和检查¶

把目录放到 CCB 用户目录的 mods/ 下，然后运行：

cataclysm-tiles --userdir /你的/CCB用户目录/ --check-mods my_first_mod

看到 Checking mod My First MOD [my_first_mod] 且程序正常退出，表示 MOD 已被发现并通过数据加载检查。也可以使用 Catapult 从 CCB MOD 目录直接安装。

API 在哪里¶

LuaLS 完整声明：函数、参数、返回值和类型说明；
机器可读 API 契约：可用于生成工具和检查变更；
平台设计与生命周期：加载、隔离、状态和安全边界；
完整示例 MOD：按领域拆分的可运行示例；
CCB-MOD：登记、维护和发布外部 MOD。

编辑器使用 LuaLS 时，把 ccb_platform_v1.d.lua 加入工作区库即可获得补全。遇到 API 缺失或文档与运行结果不一致时，以 CCB 主仓库的声明、原生注册和测试为准，并在 CCB 主仓库报告问题。

第一版推荐版本¶

当前适配基线为 0.Ag-Candidate-2026-09-05-0219，Lua API 为 1。在 Catapult 的“实验版 / 候选版”列表选择该完整版本号；它尚不是 Stable。下面的声明和示例链接固定到这个 Candidate，不随 master 的后续开发变动。

命令行验证时先创建用户目录中的 config/，再运行：

mkdir -p /tmp/ccb-mod-check/config /tmp/ccb-mod-check/mods
# 将解压后的 hello_ccb 文件夹放入 /tmp/ccb-mod-check/mods/
./cataclysm-tiles --userdir /tmp/ccb-mod-check/ --check-mods hello_ccb

退出码 0 表示加载检查通过；仍需在新世界启用 MOD，确认进入世界后的实际效果。

版本规则¶

MOD 写明所需的 Lua API 整数版本，当前为 1；
CCB RC 发布后冻结会影响 MOD 的公共 API；
Stable 周期内不删除或改名现有公共 API；
必须破坏兼容时才提升为 Platform v2；
Experimental 上的新接口不能视为 Stable 承诺。