Skip to content
Download

Publishing

Lesson 11.3

Your mod works. Now other people should be able to find it, install it and trust it. This lesson goes from your project folder to a public page on the Celestial website.

Get the package ready

A mod is shared as one file, a .clmod package. Before you build it:

  • Raise the version in clight.mod.json if this isn’t the first release.
  • Fill in name, description, authors and license.
  • Add an icon.png to the top folder: a square PNG, 64 to 256 pixels, at most 256 KB. It shows in search, on the mod’s page and in the game’s Mods screen.
  • Add a LICENSE file with the licence text.
  • Remove test code, like commands and debug logging you only used while developing.

Then check it strictly. --strict treats warnings as errors:

> clight check --strict
ok: ruby_tools 1.0.0

And build a release:

> clight build --release
  compile main.c
  link    build\bin\ruby_tools.wasm
packed  C:\Projects\ruby_tools\build\ruby_tools-1.0.0.clmod (14 files, 21 KiB)

The package is build/<id>-<version>.clmod. It contains your manifest, the compiled bin/<id>.wasm, assets/, datapack/, the icon and the licence. Your src/ folder, the data/ folder and everything else in build/ are left out, so players get the compiled mod, not your source code. If you want to share the source too, publish it separately, for example on GitHub, and link it in the manifest’s links.

A release build is optimised and has no debug information, so it is smaller and faster. If a release build behaves differently from a development build, that usually points to a real bug in your code (often an uninitialised variable) that the optimiser exposed.

To try the package exactly as players get it, copy it into the mods folder of a Celestial installation and start the game normally.

One build for everyone

You build once, on your computer, and the same .clmod works for every player on every operating system. WebAssembly is not a Windows or Linux program; the game compiles it for the player’s computer when it loads (and keeps the result in its cache, so the next start is quick).

Because the CLight API only grows, you also don’t need to rebuild old versions when Celestial updates. A mod built for API 1 keeps working on every later build with API 1.

Create the project

Sign in on the Celestial website and open your dashboard (/dashboard). If you have no developer account yet, open Settings, then Developer (/settings/developer), and become a developer first.

  1. Click New project.
  2. Name: what players see, for example “Ruby Tools”.
  3. Address: the page’s URL. You can change it later.
  4. Mod id: must match id in clight.mod.json. It can’t change after the first upload.
  5. Summary: one sentence for search results, 10 to 160 characters.

A new project starts as a draft: only you and your team can see it.

Upload a version

On the project’s Versions tab, drop your .clmod file. The website reads the manifest and shows what it found before you publish:

  • the version number, which must match the manifest (the website refuses a number it has seen before),
  • a name for the version, like “Ruby Tools 1.0.0”,
  • a changelog: what is new, in a few lines,
  • the channel: release for normal versions, beta or alpha for test versions.

Then an automatic scan checks the package: the layout, the manifest, the capabilities it asks for, and the WebAssembly module. For a C mod, it reads which functions the module imports. Only the CLight API and the standard WASI functions the sandbox provides are allowed; anything else, like native code or a module that imports from unknown places, is flagged. Most findings come with a hint on how to fix them.

Licence

The licence tells people what they may do with your mod: use it, change it, put it in modpacks, share it.

  • Pick a common one on the project’s page, like MIT (do almost anything, keep the copyright notice) or All rights reserved (nothing without your permission).
  • Or write your own on Licences in the dashboard (/dashboard/licenses): start from a template or from scratch, in plain words and Markdown. Each licence gets its own page on the site, and you can pick it for any of your projects.

Put the same licence into license in the manifest and into the LICENSE file, so the package and the page agree.

Submit for review

The project’s Moderation tab has a checklist. Everything must be done before you can submit:

  • an icon,
  • a description of at least 200 characters: what the mod does and how to use it,
  • a listed version that passed the scan,
  • a licence,
  • at least one category.

Then click Submit for review. A moderator looks at every new project before it goes public, and you get a notification when they’re done. If they ask for changes, their message appears on the Moderation tab: fix what they mention and submit again. You can have only a few projects in review at the same time.

Once approved, the project is public and appears in search. You can also make it unlisted (anyone with the link can see it) or private again.

Updates

For every new release:

  1. Raise version in clight.mod.json (see The manifest for which number to raise).
  2. clight check --strict and clight build --release.
  3. Upload the new .clmod on the Versions tab, with a changelog.

The new version appears on the mod’s page straight away (or after a quick review, if moderators check updates too).

Try it

Before you upload, go through this list for your mod and fix what is missing: version raised, description written, icon.png (square, 64 to 256 px), LICENSE file, release build, clight check --strict passes. Which of these does the website check by itself?

Show a solution

The website checks most of them in some way: it refuses a version number that already exists, the checklist wants an icon, a description of at least 200 characters and a licence, the scan warns about a missing LICENSE file and an icon of the wrong size, and it repeats the package checks that clight check does. It can’t tell whether you uploaded a release or a development build; a development build works, but it is bigger and slower, so build with --release yourself.

Recap: clight check --strict and clight build --release make the .clmod with your compiled module (not your source); on the website, create a project, upload the version, pick a licence, finish the checklist and submit it for review.

Your mod keeps working

CLight promises that a mod written for API 1 keeps loading and behaving the same on every later Celestial with API 1: you don’t rebuild it when Celestial updates. If something you use gets a new name, the old name keeps working and the log shows one CLL-2010 warning that names the new one; switch when you next release. If your mod needs functions from a newer API, say so in the manifest with "api_version": ">=1.12", and older Celestial versions explain to the player that they need an update. Renamed your mod or its items? List the old names in "former_ids" and "id_aliases". The details are in ABI Stability and API Versioning.