clight.mod.json manifest schema (schema 1)

Status: Implemented. clight check, the loader and the website validate these rules; fields marked planned are accepted but not acted on yet.

Every .clmod has a clight.mod.json at its root. clight check validates it. A JSON Schema file (clight.mod.schema.json) ships with the SDK for editor completion.

Full example

{
  "schema": 1,
  "id": "ruby_tools",
  "version": "1.2.0",
  "name": "Ruby Tools",
  "description": "Ruby gear, an infuser and a mana bar.",
  "authors": ["Jane Doe <[email protected]>"],
  "contributors": ["Sam"],
  "license": "MIT",
  "icon": "icon.png",
  "links": { "homepage": "https://example.com/ruby", "sources": "https://git.example.com/ruby", "issues": "https://git.example.com/ruby/issues" },

  "api": 1,
  "game": ">=26.3 <26.4",

  "side": "both",
  "sync": "required",

  "runtime": { "type": "wasm", "entry": "bin/ruby_tools.wasm" },

  "depends":  { "mana_core": ">=2.0 <3" },
  "optional": { "recipe_viewer": "*" },
  "breaks":   { "old_rubies": "*" },
  "load":     { "after": [], "before": [] },

  "permissions": [],
  "optional_permissions": [],

  "limits": { "memory_mb": 256 },
  "hot_reload": true,
  "critical": false,
  "custom": { "clight_build": { "cflags": ["-DRUBY_DEBUG=0"] } }
}

Fields

Field	Type	Required	Description
schema	int	✔	Always 1 for this spec
id	string	✔	^[a-z][a-z0-9_]{1,63}$. Also your namespace. minecraft, seecraft, clight, c and java are reserved.
version	string	✔	SemVer 2.0 (1.2.0, 2.0.0-beta.3)
name	string	✔	Display name
description	string		Short description
authors, contributors	string[]		Name <email>
license	string	✔	An SPDX id, or "All-Rights-Reserved"
icon	string		A square PNG in the package (64 to 256 px)
links	object		homepage, sources, issues, donate
screenshots	string[]		API 1.21: up to 8 PNG files in the package, shown in the Mods screen (16:9 looks best)
categories	string[]		API 1.21: what the mod is about (hud, utility, visual, social, gameplay, library, …), for the Mods screen’s filter
api	integer	✔	The CLight API major (1). Engines with the same major load the mod; newer minors add functions you can probe with cl.has().
api_version	range		API 1.19: the API versions the mod needs (">=1.12", or "1.12" = >=1.12 <2). An engine below the lower bound refuses it (CLL-2003); an upper bound inside the major is ignored with a warning. Gives the major when api is missing; both must agree.
former_ids	string[]		API 1.19: the mod’s earlier ids. Dependencies on them, cl_mod_is_loaded and <old_id>:* registry ids resolve to this mod.
id_aliases	object		API 1.19: {"my_mod:old_sword": "my_mod:ruby_sword"}, renamed blocks / items / entity types of this mod (only its own ids or former ids).
clight	range		Deprecated, use api. The old API range (">=1.0 <2") still loads: it is mapped to a major with a warning (0.x ranges mean API 1). If both are given, the range can still exclude engine versions.
game	range		Supported game versions (default: the one the SDK targets)
side	enum	✔	client, server, both
sync	enum	✔	required, optional, client_only, server_only
runtime.type	enum	✔	data, lua, wasm. Every mod is sandboxed: native and dotnet are rejected.
runtime.entry	string	lua, wasm	Lua entry script under scripts/ (scripts/main.lua) or the module under bin/ (bin/<id>.wasm)
depends, optional, breaks	object		Mod id → version range
load.after, load.before	string[]		Ordering hints without a dependency
permissions	string[]		Capabilities (Capability list); each is allowed or denied by the player on the Permissions screen
optional_permissions	string[]		Capabilities the mod can live without (shown as optional on the Permissions screen)
provides	string[]		planned: virtual ids this mod satisfies
services	string[]		planned: services provided (id@version)
packs	object[]		planned: optional built-in packs
vanilla_clients	enum		planned: allow or deny vanilla clients on a server
threading	enum		WASM: serial (default) or parallel (planned)
limits	object		memory_mb (default 256, 1 to 4096 for WASM and Lua); tick_ms, frame_ms planned (Permissions and security)
mixins	object[]		Mixins registered before the entry point runs (Mixins): target, at (head, return, wrap, overwrite, point:<name>, value:<name>, call:<name>), handler (Lua "scripts/<file>.lua#<function>", WASM an export name), optional priority (number or first…monitor), filter, before / after (mod ids), optional, exclusive, receive_cancelled, once. The old hooks key is an error that points here.
hot_reload	bool		Lua hot reload outside dev mode (in dev mode it is always on)
critical	bool		planned: stop the game when this mod fails to load
custom	object		Free-form data for tools. Ignored by the loader. custom.clight_build.cflags / ldflags (string arrays) are extra compiler and linker flags for clight build.

Version ranges

Syntax	Meaning
*	any
1.2.0	exactly
>=1.2 <2	space-separated comparators (AND)
^1.2.0	>=1.2.0 <2.0.0
~1.2.0	>=1.2.0 <1.3.0
>=1.0 <1.5 || >=2.0	OR of ranges

Pre-release versions only match ranges that mention a pre-release of the same major.minor.patch.