Distribution
Status: Implemented on the Celestial website and in the Celestial launcher: projects, versions, review, licences, downloads, the signed mod index and installing mods into launcher instances.
clight publishand a Get Mods page in the game’s Mods screen are Planned; publishing from CI works through the website API.
A .clmod is one self-contained file. The normal way to share it is the Celestial website: players find it there and install it with the Celestial launcher.
1. Create a project
On the website, sign in with a developer account and open Dashboard → Projects → New project (/dashboard):
| Field | Notes |
|---|---|
| Name | Shown everywhere |
| Address | The project page’s URL (/mods/<address>); can be changed later |
| Mod id | Must match the id in clight.mod.json, and is fixed once a version exists |
| Summary | One sentence for search results and cards, 10-160 characters |
Projects start as private drafts. On the project’s pages you then add an icon, a description (Markdown, at least 200 characters), categories, links, gallery images and team members.
2. Choose a licence
Every project needs a licence: a common one (an SPDX id such as MIT, Apache-2.0, GPL-3.0-only, or All-Rights-Reserved), any other SPDX id or LicenseRef-..., or your own licence. Write your own under Dashboard → Licences (/dashboard/licenses): start from a template or from scratch, in Markdown; each licence gets a public page at /licenses/<slug> and can be picked for any of your projects. Put the same terms in the package’s LICENSE file and the manifest’s license field.
3. Upload a version
Project → Versions: drop a .clmod (built with clight build or clight pack). The site checks the package at once (Packaging a .clmod) and shows what it read: mod id, runtime, where it runs (side), multiplayer (sync), the API and game ranges, the licence, capabilities and dependencies. Then fill in the release details:
| Field | Notes |
|---|---|
| Version number | From the manifest (version); each upload needs a new one |
| Name | The release title |
| Channel | release, beta or alpha; beta and alpha are only offered to players who opt in |
| Visibility | Listed, Unlisted (link only) or Draft (team only) |
| Changelog | Markdown |
In the background the site scans the file and builds a compact .clpk download next to the original.
4. Submit for review
Submit for review is available when the checklist is done: an icon, a description of 200+ characters, a listed version that passed the scan, a licence and at least one category. A moderator checks every new project before it is public (a developer can have up to 3 projects in review at once). You get a notification when they are done; if they ask for changes, fix them and submit again. Messages with the moderators are on the project’s Moderation page. Once approved, you can publish it, keep it unlisted or private.
5. How players get it
| Way | How |
|---|---|
| Celestial launcher | Each instance has its own game folder and mods/. The instance’s Mods tab browses the website’s mods, installs them with their required dependencies, shows updates, and turns mods on and off (a turned-off mod is renamed to .clmod.disabled). It can also add a .clmod file from disk. |
| Website | The project page (/mods/<address>) has the versions with downloads, hashes and the permissions each version asks for |
| Manual | Put the .clmod into the game’s mods/ folder; the Mods screen shows it on the next start |
| Servers | Operators put the .clmod into the server’s mods/ folder and update deliberately |
The mod index and the API
The website serves a signed index that launchers and tools read:
| URL | Content |
|---|---|
/api/clight/index.json |
Every public mod with a downloadable version: id, name, summary, latest version, side, sync, icon, authors, licence, links, page, StarRinth flag |
/api/clight/mods/<id>/versions.json |
All public releases of one mod |
/api/clight/mods/<id>/<version>/release.json |
One release: files, hashes, manifest values, dependencies |
/api/clight/key |
The site’s public key for the signatures |
The JSON API at /api/v1 has project search, versions and categories, and lets you publish from CI: create an API token under Settings → API tokens, then POST /api/v1/projects/<mod id>/versions with the file, the changelog and the channel (multipart).
Your project page
Help players and server operators decide quickly:
- Side and sync in plain words: “client only, works on any server”, “required on both sides”, “server mod, vanilla players can join”.
- The capabilities you ask for, and why for each “warn” one.
- Dependencies and known incompatibilities (
breaks). - Source link and licence.
Licensing reminders
- Include the
LICENSEfile in the package (the website warns without one). - If your mod contains third-party code or assets, follow their licences and list them.
- Never include the game’s own assets or code. Celestial imports vanilla assets from each player’s own game files; your mod ships only your files and references vanilla content by id.
Planned
clight publish (upload from the command line with a project config), a Get Mods page in the in-game Mods screen, and fetching the exact mod versions a server requires when joining fails.