Choosing a language and runtime
Status: Implemented. All three runtimes ship. Rows that mention planned APIs say so.
Every CLight mod is sandboxed. You choose between three ways of writing one: data only, Lua, or C/C++ compiled to WebAssembly. None of them needs a trust prompt, and none of them can harm the player’s computer.
Decision table
| You are making… | Recommended | Why |
|---|---|---|
| Recipes, loot tables, tags, advancements, enchantments, textures, models, sounds | Data | No code. The mod’s datapack/ and assets/ folders load like vanilla packs. |
| A server mod (chat, commands, shops, kits, minigames) | Lua | Instant reload, short code. Vanilla clients can join. |
| Quick client tweaks (HUD info, keybind actions, screens) | Lua | Small and hot-reloadable |
| A content mod (blocks, items with behaviour) | Lua or C++ | Both use the same registries; C++ when the logic is heavy |
| Heavy computation (big simulations, large data) | C++ → WebAssembly | AOT-compiled, close to native speed |
| A library other mods use | Any | Other mods depend on it through depends; a services API for direct calls is planned |
Runtime comparison
| Data | Lua | WebAssembly | |
|---|---|---|---|
| Languages | JSON, PNG, OGG | Lua 5.4 | C, C++ (others that target wasm32-wasip1 work but have no SDK templates) |
| Speed | native | slower for heavy maths; fine for handlers | close to native (Wasmtime, compiled ahead of time and cached) |
| Files | — | cl.fs: own folder read-only, own data/ read/write |
cl_fs_* and WASI: own folder read-only as /, own data/ read/write as /data |
| Network | — | payloads to its own other side; HTTPS with net.http:<host> |
payloads to its own other side; HTTPS with net.http:<host> |
| One file for all OSes | ✔ | ✔ | ✔ |
| Hot reload | ✔ (resources) | ✔ (on save, in dev mode) | ✔ (on rebuild, in dev mode; state through CLIGHT_MOD_HOT_STATE) |
Why there is no native or .NET tier
A native DLL runs with all of the player’s rights: it can read any file, start programs and download anything, and no in-process check can stop it. CLight therefore runs all code in a sandbox. C and C++ keep near-native speed through WebAssembly with ahead-of-time compilation, and the API is identical: the same clight.h/clight.hpp calls become WebAssembly imports.
Mixing languages
A mod has exactly one runtime, but a project can consist of several mods: for example a C++ ruby_core (heavy logic) and a Lua ruby_tweaks (commands, config, client UI) that lists ruby_core in depends. They share registries, events and payload channels; a services API for calling each other directly is planned.