Permissions

Lesson 15.2

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 mod can:

use the whole game API: events, items, blocks, commands, screens, sounds,
read its own files (scripts/, assets/, …),
keep its own data in its data/ folder and its config in config/<mod id>.json.

A mod can never: read other folders (your saves, screenshots or other mods), start programs, load native code, open raw network connections, or read your account’s login tokens. These aren’t permissions you can grant; the sandbox simply doesn’t have them.

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:

Capability	Lets the mod	Shown as
`net.http:<host>`	Talk HTTPS to one host, like `net.http:api.example.com` (`*.example.com` for subdomains)	neutral
`net.http:*`	Talk HTTPS to any host	highlighted
`os.open_url`	Open a link in the browser, after the player confirms	neutral
`os.clipboard`	Read the clipboard (writing is always allowed)	highlighted
`os.notifications`	Show system notifications while the game is in the background	neutral
`input.synthesize`	Send chat, commands, key presses or movement on the player’s behalf	highlighted
`packets.raw`	Read and replace raw network packets	highlighted
`ui.inject`	Change other screens’ layouts	neutral

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

What works today

HTTP requests behind net.http:<host> work (see Files and the web), and cl.permission and cl.request_permission check and ask for any capability from code. The functions behind the other capabilities, such as opening links and the clipboard, are still being built. Declare only what your mod uses today.

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 raise a permission_denied error, which you can catch with pcall (see Error handling) and answer kindly, for example with a chat message that explains what the player is missing.

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.

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?

Show a solution

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

Fetching the forecast needs net.http for that one host. Copying to the clipboard is writing, which is always allowed, so os.clipboard (reading) isn’t needed at all.

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 raises permission_denied.