Permissions

Every Celestial mod runs in a sandbox. A mod can use the game API and its own folder, and nothing else. For the few things beyond that, a mod has to ask, and the player decides.

What every mod may do

Without asking, a C mod can:

• use the whole game API: events, items, blocks, commands, screens, sounds,
• read its own files (assets/, datapack/, its manifest) with fopen,
• keep its own files in its data/ folder, and its config in config/<mod id>.json through the config functions.

A mod can never: read other folders (your saves, screenshots or other mods), start programs, load native code (DLLs), open sockets or raw network connections, or read your account’s login tokens. These aren’t permissions you can grant. The WebAssembly sandbox simply doesn’t have them: there is no function a C mod could call to do it, whatever it is compiled with.

Asking for more

Extra abilities are called capabilities. A mod lists the ones it needs in clight.mod.json:

{
  "permissions": ["os.open_url"],
  "optional_permissions": ["os.notifications"]
}

• permissions are the ones the mod needs to work.
• optional_permissions are nice to have; the mod works without them.

The capabilities that exist:

clight check rejects names that aren’t on this list.

What the player sees

The first time the game starts with a mod that needs capabilities, it shows the mod’s Permissions screen before the title screen. Each capability has a line in plain words and an Allowed / Denied switch. “Highlighted” capabilities are shown in yellow, so players look twice.

Players can change their answer any time in Mods, then the mod, then Permissions. The choices are saved in config/clight/permissions.json.

A denied capability doesn’t crash your mod. The functions behind it return CL_E_PERMISSION_DENIED. Check for it and answer kindly, for example with a chat message that explains what the player is missing.

CL_E_PERMISSION_DENIED also shows up in one more place: when your mod tries to use another mod’s namespace, like registering other_mod:thing or sending on another mod’s channel. That isn’t a capability; it is never allowed.

On the website

When you upload a mod, the Celestial website reads its capabilities and lists them on the mod’s page, so players know before they download. Highlighted capabilities are checked during review; say in your description why you need each one. A mod with several highlighted capabilities gets a closer look.

The website’s scan also checks the WebAssembly file itself: it must only import the CLight API and the standard WASI functions the sandbox provides.

Good manners

• Ask for as little as you can. A mod that wants nothing is installed without a second thought.
• Prefer a single host (net.http:api.example.com) over net.http:*.
• Put things that are only nice to have into optional_permissions, and let the mod work without them.

Try it

Your mod shows a weather forecast from weather.example.org, and can copy it to the clipboard. Which lines go into the manifest?

{
  "permissions": ["net.http:weather.example.org"],
  "optional_permissions": []
}

Recap: mods are sandboxed; extra capabilities go into permissions or optional_permissions in the manifest, the player allows or denies each one, and a denied capability returns CL_E_PERMISSION_DENIED.