Sources: 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: zero to running¶

CCB currently supports Lua Platform v1 only. The old Lua API v5, global game.* table, capability manifest, and JSON Manifest have been removed. Do not use the old pages for new MODs.

Minimal MOD¶

Create a directory containing only main.lua:

local ccb = require("ccb")

ccb.runtime.handler("welcome", function()
    ccb.services.message("My first CCB Lua MOD is running")
end, 1)

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

An optional mod.lua declares the name, version, and dependencies:

local ccb = require("ccb")

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

The resulting directory is:

my_first_mod/
├── main.lua
└── mod.lua        # optional

You do not need modinfo.json, manifest.json, or a lua/ subdirectory.

Install and check¶

Place the directory under mods/ in the CCB user directory, then run:

cataclysm-tiles --userdir /path/to/your/CCB-user-directory/ --check-mods my_first_mod

If you see Checking mod My First MOD [my_first_mod] and the process exits normally, CCB found the MOD and completed its data-load check. You can also install catalog MODs directly with Catapult.

Where the API is documented¶

Complete LuaLS declarations: functions, parameters, returns, and types;
Machine-readable API contract: generator input and change checks;
Platform design and lifecycle: loading, isolation, state, and safety boundaries;
Complete example MOD: a runnable example split by game domain;
CCB-MOD: registration, maintenance, and publishing for external MODs.

When using LuaLS, add ccb_platform_v1.d.lua to the workspace library to enable completion. If the documentation disagrees with runtime behaviour, treat declarations, native registrations, and tests in the CCB repository as authoritative and report the problem there.

Recommended first-version baseline¶

Use 0.Ag-Candidate-2026-09-05-0219 with Lua API 1. Select that exact tag in Catapult's Experimental / Candidate list. It is not yet Stable. The declarations and examples below are pinned to this Candidate rather than moving master.

Create the user directory's config/ before running a command-line check:

mkdir -p /tmp/ccb-mod-check/config /tmp/ccb-mod-check/mods
# Place the extracted hello_ccb folder in /tmp/ccb-mod-check/mods/
./cataclysm-tiles --userdir /tmp/ccb-mod-check/ --check-mods hello_ccb

Exit code 0 confirms data loading. Also enable the MOD in a new world and check its runtime effect.

Version rules¶

A MOD declares the integer Lua API version it requires; the current version is 1;
public MOD-facing APIs freeze when a CCB RC is published;
existing public APIs are not removed or renamed during a Stable cycle;
unavoidable compatibility breaks require Platform v2;
new APIs on Experimental are not a Stable promise.