Building and running

Status: Implemented. Commands marked planned are not in the SDK yet.

The clight CLI

Command	Does
clight new <lua|c|cpp> <id> [--name N] [--dir D]	Creates a project from a template (Project layout and templates)
clight build [project] [--release] [-v]	C/C++: compiles every source under src/ to WebAssembly with the SDK’s wasi-sdk (incremental: only changed files and their headers are recompiled), links build/bin/<id>.wasm. Every language: validates the manifest and packs build/<id>-<ver>.clmod.
clight run [project] [--game <dir>] [--no-build] [--wait] [-- <game args>]	Builds, then starts Celestial with --clight-dev --clight-mod <project>: the game loads the project folder itself (so saving a Lua script hot-reloads it), in addition to the game’s mods/ folder, which is never modified. In this dev mode bin/ falls back to build/bin/ and the mod’s data/ folder is build/run/<id>/data/ (it survives between runs)
clight pack [project] [-o file]	Packs without compiling (Lua and data mods, or a prebuilt build/bin/)
clight check [project | file.clmod] [--strict]	Manifest schema, package paths and layout, runtime entry present. --strict fails on warnings too.
clight setup [--force]	Downloads the official wasi-sdk into the SDK (Installing the CLight SDK)
clight doctor	Checks the SDK, wasi-sdk and the game
clight test, clight sign, clight publish, clight bindgen	planned

Arguments after -- go to the game, for example clight run -- --background for a hidden, silent test instance.

Build modes

Mode	Flags (from clight-sdk/wasm/flags.txt)
dev (default)	-O1 -g: debug info for symbolized traps
--release	-O2 -DNDEBUG, debug info stripped. Use it for publishing.

Always added: --target=wasm32-wasip1 -mexec-model=reactor -Wl,--export-table -Wl,--gc-sections and the CLight exports. C uses -std=c17, C++ -std=c++23 -fno-exceptions. Extra per-project flags go in the manifest:

"custom": { "clight_build": { "cflags": ["-DMY_FEATURE=1"], "ldflags": [] } }

Building with CMake (optional)

The templates include a CMakeLists.txt for IDEs:

cmake -B build/cmake -G Ninja -DCMAKE_TOOLCHAIN_FILE=<clight-sdk>/cmake/wasi-sdk.cmake -DCMAKE_BUILD_TYPE=Release
cmake --build build/cmake

clight_add_mod(<id> SOURCES …) uses the same flags file, writes build/bin/<id>.wasm, and adds a <id>_clmod target that runs clight pack.

Installing into a real game

Copy the .clmod (or the mod folder) into <game dir>/mods/. With the Celestial launcher every instance has its own game folder: use the instance’s Mods tab (Add → a .clmod file) or install from the Celestial website’s mod list. On the next start the mod is unpacked into mods/<id>/ and listed on the Mods screen. A file renamed to .clmod.disabled is not loaded (that is how the launcher turns a mod off). If the mod asks for permissions, they are listed under Mods → Permissions, where you allow or deny each one.

Continuous integration

# example CI step (Windows runner)
- run: clight setup
- run: clight build --release
- run: clight check --strict build/my_mod-1.0.0.clmod