Installing the CLight SDK

Status: Implemented. The SDK ships with every Celestial client build.

Where the SDK is

The SDK ships with Celestial, in the clight-sdk folder next to Celestial.exe. With the Celestial launcher, the client build lives in the launcher’s client folder; each instance has its own game folder with its own mods/.

Celestial/
├── Celestial.exe
├── mods/                        installed mods (.clmod files or folders; per instance with the launcher)
└── clight-sdk/
    ├── bin/clight.exe           the CLI: new, build, pack, check, run, setup, doctor
    ├── include/
    │   ├── clight.h             the C API (for WebAssembly: every function is a "clight" import)
    │   └── clight.hpp           the header-only C++ wrapper
    ├── idl/clight.idl           the single source of truth for the API
    ├── templates/               project templates: lua, c, cpp
    ├── examples/                one complete example mod per language
    ├── cmake/                   wasi-sdk.cmake (toolchain) and CLightMod.cmake (clight_add_mod), optional
    ├── wasm/flags.txt           the compiler and linker flags for WebAssembly mods
    ├── schema/clight.mod.schema.json   for editor completion in clight.mod.json
    ├── docs/                    this documentation
    └── wasi-sdk/                created by `clight setup` (C and C++ only)

Add clight-sdk\bin to your PATH, or call it with its full path.

Requirements

For	You need
Lua mods	Nothing else. VS Code with the Lua (LuaLS) extension is recommended.
C and C++ mods	The official wasi-sdk (clang for WebAssembly). clight setup downloads it into clight-sdk/wasi-sdk. CMake is optional.

You never need a native compiler, Visual Studio or a .NET runtime: C and C++ mods compile to WebAssembly.

Set up C and C++ (once)

clight setup

This downloads the pinned official release (wasi-sdk-34 from github.com/WebAssembly/wasi-sdk, about 590 MB), checks its SHA-256 against the value built into clight, and unpacks it into clight-sdk/wasi-sdk. It uses the curl and tar programs that come with Windows 10 and 11. To use a wasi-sdk you already have, set WASI_SDK_PATH instead.

Check the installation

> clight doctor
CLight SDK 0.1.0 (API 1.24)
  ok   SDK folder  C:\Games\Celestial\clight-sdk
  ok   clight.h  C:\Games\Celestial\clight-sdk\include
  ok   wasi-sdk (C/C++ mods)  C:\Games\Celestial\clight-sdk\wasi-sdk wasi-sdk-34.0
  ok   Celestial  C:\Games\Celestial\Celestial.exe
  Lua mods need nothing else.

clight run finds the game next to the SDK. Use --game <folder> or the CLIGHT_GAME environment variable for another install.

The game assets

Celestial never ships Mojang assets. The game imports them from your own copy of the 26.3 game on first start; mods use the same imported assets.

Editor setup

Editor	Setup
VS Code	Open the project folder. Lua: install the “Lua” extension. C/C++: point the C/C++ extension at clight-sdk/include and the compiler clight-sdk/wasi-sdk/bin/clang.exe with --target=wasm32-wasip1.
Visual Studio / CLion	Open the project’s CMakeLists.txt with the toolchain file clight-sdk/cmake/wasi-sdk.cmake (see Building and running).

Updating

The SDK is updated together with Celestial. A project names the API major in its manifest ("api": 1), so updates within a major version never break it.