a6f951e126
Six pages under a "Make a mod" group of the docs: set up and see a mod in the game (the launcher's Game arguments or cargo horizon-mod run), the manifest and every capability, the hooks and calls with a worked example (Playtime, built and checked), content mods, testing and check, and publishing (minisign signing, the submit form, review, updates). /mods, the submit page, the docs index, Mods and data packs and the Mod API link to it. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
61 lines
4.1 KiB
Markdown
61 lines
4.1 KiB
Markdown
# The manifest and capabilities
|
|
|
|
Every mod has a `horizon-mod.toml` at its root. It names the mod, says which version of the mod API it was made for, and lists its capabilities: what it may do. Players read that list before they turn the mod on, and the game holds the mod to it.
|
|
|
|
## The manifest
|
|
|
|
```toml
|
|
id = "playtime"
|
|
name = "Playtime"
|
|
version = "0.1.0"
|
|
description = "How long you have played, in a corner of the screen"
|
|
authors = ["You"]
|
|
api = "0.1"
|
|
side = "client"
|
|
capabilities = ["hud", "chat", "storage"]
|
|
```
|
|
|
|
| Key | What it is |
|
|
| --- | --- |
|
|
| `id` | The mod's id: 1 to 64 characters of `a-z`, `0-9` and `_`. It names the mod's setting, its log lines, its storage folder and, for content, its namespace. Keep it once you have published the mod. |
|
|
| `name` | The name players see. |
|
|
| `version` | Your mod's version, such as `0.1.0`. Each version you publish needs a new one. |
|
|
| `description` | One or two sentences for the Mods screen. |
|
|
| `authors` | A list of names. |
|
|
| `api` | The mod API line the mod was made for: `"0.1"` for code, `"0.2"` for content. The game refuses a line it doesn't serve, with a message that says so. |
|
|
| `side` | `"client"` for a mod that runs in the player's game. Content mods use `"both"`. |
|
|
| `capabilities` | What the mod may do: the list below. |
|
|
| `namespaces` | Content mods only: extra namespaces the mod's files use (see [Content mods](/docs/content-mods#namespaces)). |
|
|
|
|
Unknown keys are refused, so a typo is an error, not a permission that silently does nothing.
|
|
|
|
## Capabilities
|
|
|
|
A capability is a part of the API the mod may use. Each one shows on the Mods screen as a sentence that starts with "May". Writing to the game log needs no capability.
|
|
|
|
| Capability | The player reads | What the code can do |
|
|
| --- | --- | --- |
|
|
| `game-read` | May see your position, health and the time | `game::get_player()`: position, facing (yaw and pitch), health, food and dimension. `game::get_clock()`: the game time and the time of day. |
|
|
| `chat` | May show you chat messages | `chat::show(text)`: a chat line only this player sees, after the mod's name. At most 8 per call into the mod. |
|
|
| `hud` | May draw text on your screen | `hud::set_panel(corner, lines)` and `hud::clear()`: a panel of up to 16 coloured lines of 256 characters in one corner. The game keeps drawing it until you change it. |
|
|
| `storage` | May save its own settings to disk | `storage::get`, `set` and `delete`: small files in a folder of the mod's own. Up to 64 files and 4 MiB in all, and at most 1 MiB written per call. Keys are 1 to 64 characters of `a-z`, `0-9`, `_`, `.` and `-`. |
|
|
| `registries` | May add blocks and items to your worlds | Content mods: blocks and items from the mod's data files. No code. |
|
|
|
|
Ask only for what the mod uses: players are more likely to turn on a mod that asks for little.
|
|
|
|
**The game checks.** When you build, and again when a game loads the mod, the compiled code's imports are compared with the manifest. A mod whose code calls `chat::show` without `chat` in its capabilities is refused (`uses capability chat, missing from horizon-mod.toml`). The list players read is what the code can do, not a promise.
|
|
|
|
## What no mod can do
|
|
|
|
A mod runs in a WebAssembly sandbox. Whatever its capabilities:
|
|
|
|
- It cannot open files (apart from its own storage), the network, other programs or the clock.
|
|
- It sees the game only through the snapshot the game gives it once a tick, and changes it only through the calls above. It cannot patch the game's code.
|
|
- It has 64 MiB of memory and a time budget for each call. A mod that runs past its budget, runs out of memory or crashes is switched off, with the reason on its row of the Mods screen. The game goes on.
|
|
|
|
## API versions
|
|
|
|
The mod API is versioned apart from the game. A mod made for API `0.1` keeps loading on every game that serves `0.1`, and new functions arrive as additions. A change that would break mods comes as a new line, served beside the old one for at least one release cycle. The [stability page](/docs/api/stability) has the whole policy, and the [Mod API's changelog](/docs/api/mods#changelog) what each line added.
|
|
|
|
Next: [write the code](/docs/mod-code).
|