Setting up

Part 1 taught you the Lua language. Now you put it to work inside the game. In this lesson you install the tools, make a new mod and look at what is inside it.

What you need

• Celestial itself. The download from the Celestial website is a folder with Celestial.exe in it.
• The CLight SDK. It ships with Celestial, in the clight-sdk folder next to Celestial.exe. CLight is the name of the modding system, and the SDK is its toolbox.
• A text editor. Any editor works. Visual Studio Code with the free Lua extension by sumneko is a good choice, because it understands the annotations the SDK comes with.

Lua mods need nothing else: no compiler and no build step.

Put the clight tool on your PATH

The SDK’s command-line tool is clight-sdk/bin/clight.exe. Add that bin folder to your PATH so you can type clight in any terminal:

1. Press the Windows key and search for Edit environment variables for your account.
2. Select Path, click Edit, then New, and paste the full path of the bin folder, for example C:\Games\Celestial\clight-sdk\bin.
3. Click OK and open a new terminal window.

Check that it works:

> clight --version
clight 0.1.0 (API 1.24, wasi-sdk-34)

clight doctor checks the rest of the installation. For Lua mods, the lines that matter are the SDK folder and Celestial:

> 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
  MISSING wasi-sdk (C/C++ mods)  run `clight setup`
  ok   Celestial  C:\Games\Celestial\Celestial.exe
  Lua mods need nothing else.

The wasi-sdk line is only for mods written in C or C++. You can ignore it.

Make a new mod

Go to the folder where you keep your projects and run clight new:

> clight new lua my_mod
created C:\Projects\my_mod (lua, 4 files)
next:  cd my_mod  &&  clight build  &&  clight run

my_mod is the mod’s id. Every mod has one, and it has to be unique. The rules: lowercase letters, digits and _, starting with a letter, 2 to 64 characters. ruby_tools is fine, RubyTools and 2cool are not.

The display name is made from the id (my_mod becomes “My Mod”). Pick another with --name:

> clight new lua ruby_tools --name "Ruby Tools"

What’s inside

my_mod/
  clight.mod.json            the manifest: id, version, name, licence, ...
  scripts/
    main.lua                 your code starts here
  assets/
    my_mod/
      lang/
        en_us.json           texts players see, by language
  .gitignore

A bigger mod adds more folders next to these:

Your first script

Open scripts/main.lua. The template already does something useful:

-- When a player joins, say hello.
cl.on("player.join", function(event)
  local player = event.player

  player:send_message("Welcome, " .. player.name .. "!")
end)

cl.log(mod.id, mod.version, "loaded")

Two names are there without you creating them:

• cl is the game API. Everything the game lets your mod do is a function inside cl.
• mod is your mod: mod.id is "my_mod", mod.version is "1.0.0".

The rest is the Lua you know: a function stored in a table, a call with a string and a function, string joining with ... cl.on says “when this happens, run this function”. You will meet it properly in Listening to events.

Editor help

The SDK has a file with a description of every API function: clight-sdk/lua/clight.d.lua. Point your editor’s Lua extension at it and you get completion and parameter hints for cl.. In VS Code, add this to .vscode/settings.json in your mod folder (change the path to yours):

{
  "Lua.runtime.version": "Lua 5.4",
  "Lua.workspace.library": ["C:/Games/Celestial/clight-sdk/lua"],
  "Lua.diagnostics.globals": ["cl", "mod"]
}

Try it

Make a mod called hello_world with the display name “Hello World”. Change the welcome message so it also says the mod’s version, for example “Welcome, Alex! Hello World 1.0.0 is installed.”

> clight new lua hello_world --name "Hello World"

cl.on("player.join", function(event)
  local player = event.player
  player:send_message("Welcome, " .. player.name .. "! Hello World " .. mod.version .. " is installed.")
end)

Recap: put clight-sdk/bin on your PATH, make a mod with clight new lua <id>, and write your code in scripts/main.lua using cl and mod.