Merge remote-tracking branch 'origin/main' into feat/server-mods-0.3
# Conflicts: # Cargo.toml # crates/cargo-horizon-mod/src/check.rs # crates/horizon-client/src/game/mods.rs # crates/horizon-mod-sdk/src/lib.rs # crates/horizon-mod-sdk/wit/horizon.wit # crates/horizon-mods/src/manifest.rs # crates/horizon-mods/src/runtime.rs # crates/horizon-mods/src/testing.rs # crates/horizon-mods/tests/sandbox.rs # docs/api/mods-reference.md # docs/api/mods.md # docs/mods.md
This commit is contained in:
+2
-1
@@ -51,5 +51,6 @@ Every page has the same parts: **Overview** (what you can build), **Guide** (whe
|
||||
**Examples**, **Stability** (the level of each part, per [stability.md](stability.md)), **Changelog** and
|
||||
**Not there yet** (what is planned, so nobody builds on a guess).
|
||||
|
||||
The website's summary for players and authors is [playhorizon.dev/docs/apis](https://playhorizon.dev/docs/apis)
|
||||
The website shows these pages at [playhorizon.dev/docs/api](https://playhorizon.dev/docs/api), built from this
|
||||
folder, and a summary for players and authors at [playhorizon.dev/docs/apis](https://playhorizon.dev/docs/apis)
|
||||
(`website/docs/apis.md`).
|
||||
|
||||
+16
-1
@@ -138,9 +138,24 @@ Unknown keys are refused. Its CI runs `cargo-horizon-mod` (`crates/cargo-horizon
|
||||
| `cargo horizon-mod check <file> [--json]` | A submission's checks: its kind's (above), its signature with `--key` and `--signature`, and for a mod a trial run in the sandbox (40 ticks, 120 frames, a chat line, each command). |
|
||||
| `cargo horizon-mod registry check <base> <head> --files <dir>` | `check` on each file `head` lists and `base` doesn't: a pull request's new files. |
|
||||
| `cargo horizon-mod registry list <checkout>` | `<sha256> <id> <version> <file>` per version: the files to download. |
|
||||
| `cargo horizon-mod registry build <checkout> --files <dir> --out index.json` | Reads every entry and its file (`<dir>/<sha256>`), lists every problem, and writes the index with URLs `<release>/<id>-<version>/<file>`. |
|
||||
| `cargo horizon-mod registry build <checkout> --files <dir> --out index.json` | Reads every entry and its file (`<dir>/<sha256>`), lists every problem, and writes the index with URLs `<release><id>-<version>/<file>` (`--release`, ending in `/`, defaults to the repository's releases). |
|
||||
| `cargo horizon-mod registry review <base> <head> --author <login>` | A pull request's changes: a published file never changes and is never removed (take it down in `revoked.toml`), a kind never changes; changes by a non-owner and to owners or keys are pointed out for the reviewers. |
|
||||
|
||||
How the repository runs (its workflows are in `.github/workflows/`):
|
||||
|
||||
- **A pull request** (`check.yml`) runs `registry review`, downloads each new file from the `staging` prerelease, runs
|
||||
`registry check` on it and builds the index it would publish; the report is the run's summary. The tool is
|
||||
`cargo-horizon-mod` from Horizon at the commit in the repository variable `HORIZON_REV`. The form's pull requests
|
||||
are opened with the token of the account in the variable `REGISTRY_BOT`; for those, the author is the login in the
|
||||
body's `<!-- submitted-by: … -->` line.
|
||||
- **Merging** needs the `check` run and a CODEOWNER's review. `publish.yml` then makes each new version a release
|
||||
`<id>-<version>` and deploys `index.json` and `icons/` to GitHub Pages:
|
||||
`https://ludovic111.github.io/horizon-mods/index.json`, served with `Access-Control-Allow-Origin: *`.
|
||||
- **Weekly**, `cleanup.yml` deletes staged copies of published files after 7 days and of files no open pull request
|
||||
lists after 30.
|
||||
- **Taking a file down** is a pull request adding it to `revoked.toml`. Removing an entry outright (a test, a project
|
||||
nobody installed) fails `registry review` on purpose and needs an administrator's merge.
|
||||
|
||||
Kinds open to submissions: `mod`, `modpack`, `resourcepack`. `shader` is in the schema and stays closed until
|
||||
Horizon's own shader pack format exists (Iris and OptiFine packs are for the Modrinth browser); its check will compile
|
||||
the pack in a headless Horizon. A new kind gets its own check before it opens.
|
||||
|
||||
+296
-1
@@ -11,14 +11,18 @@ The contract between Horizon and its mods: the WIT package `horizon:mods@0.1.0`,
|
||||
| `chat` | [`chat`](#chat) | show you chat messages |
|
||||
| `hud` | [`hud`](#hud) | draw text on your screen |
|
||||
| `storage` | [`storage`](#storage) | save its own settings to disk |
|
||||
| `command` | [`command`](#command) | run commands as you, with your permissions |
|
||||
| `registries` | data files (`assets/`, `data/`), no interface | add blocks and items to your worlds |
|
||||
| `ui` | [`ui`](#ui) | show its own screens and a settings page |
|
||||
| `render` | [`render`](#render) | draw on your screen, shake and zoom the camera |
|
||||
| `input` | [`input`](#input) | see the keys you hold and your clicks, take over the use button on its own items and the mouse wheel, and add keys |
|
||||
| `players` | [`players`](#players) | see who is on the server and message them |
|
||||
|
||||
## World `horizon-mod`
|
||||
|
||||
A client mod: runs in the player's game.
|
||||
|
||||
- Imports (what the game offers): `log`, `game`, `chat`, `hud`, `storage`
|
||||
- Imports (what the game offers): `log`, `game`, `chat`, `hud`, `storage`, `command`
|
||||
- Exports (what the mod provides): `events`
|
||||
|
||||
## World `horizon-server-mod`
|
||||
@@ -28,6 +32,27 @@ A server mod (manifest `side = "server"`, `api = "0.3"`, experimental): runs whe
|
||||
- Imports (what the game offers): `log`, `storage`, `players`
|
||||
- Exports (what the mod provides): `server-events`
|
||||
|
||||
## World `horizon-ui-mod`
|
||||
|
||||
A mod with widgets (capability `ui`): the SDK builds every mod against this world. Mods built for `horizon-mod` alone (no `ui-events` export) still load and simply hear nothing of their widgets.
|
||||
|
||||
- Imports (what the game offers): `ui`, `render`, `input`, `log`, `game`, `chat`, `hud`, `storage`, `command`
|
||||
- Exports (what the mod provides): `ui-events`, `events`
|
||||
|
||||
## World `ui-host`
|
||||
|
||||
The game's side of `horizon-ui-mod` beyond `horizon-mod`.
|
||||
|
||||
- Imports (what the game offers): `ui`
|
||||
- Exports (what the mod provides): `ui-events`
|
||||
|
||||
## World `render-host`
|
||||
|
||||
The game's side of capability `render` (imports only).
|
||||
|
||||
- Imports (what the game offers): `render`, `input`
|
||||
- Exports (what the mod provides):
|
||||
|
||||
## `log`
|
||||
|
||||
Access: always granted.
|
||||
@@ -127,6 +152,276 @@ Capability `storage`: a per-mod folder of small key/value files, quota'd (docs/m
|
||||
| `set` | `func(key: string, value: list<u8>) -> result<_, string>` | Errs on a malformed key or over quota (bytes for the whole mod). |
|
||||
| `delete` | `func(key: string)` | No error if `key` was already absent. |
|
||||
|
||||
## `command`
|
||||
|
||||
Access: capability `command`.
|
||||
|
||||
Capability `command`: vanilla commands run as the player, with the player's permissions, after the hook call returns (8 per call). A mod's own commands are not run this way.
|
||||
|
||||
| Function | Signature | What it does |
|
||||
| --- | --- | --- |
|
||||
| `run` | `func(line: string)` | `line` without its slash; its feedback goes to the chat as if typed. |
|
||||
|
||||
## `ui`
|
||||
|
||||
Access: capability `ui`.
|
||||
|
||||
Capability `ui`: widgets the game draws with its own menus' widgets, for a screen the mod owns and a settings page in Options > Mods. Layout and drawing are the game's: a mod says what its widgets hold, never where they sit or how they look, and the game clips everything it is handed.
|
||||
|
||||
### record `text-widget`
|
||||
|
||||
A line of text.
|
||||
|
||||
| Field | Type | |
|
||||
| --- | --- | --- |
|
||||
| `id` | `u32` | The mod's own name for the widget; `ui-events` calls echo it. |
|
||||
| `text` | `string` | Up to 256 characters. |
|
||||
| `color` | `u32` | 0xRRGGBB; 0 is the menus' white. |
|
||||
|
||||
### record `item-widget`
|
||||
|
||||
An item's icon and a name beside it, as recipe viewers show them.
|
||||
|
||||
| Field | Type | |
|
||||
| --- | --- | --- |
|
||||
| `id` | `u32` | The mod's own name for the widget. |
|
||||
| `item` | `string` | `minecraft:diamond`, `<mod>:<path>`; an unknown id draws a "?". |
|
||||
| `name` | `string` | The name shown beside the icon (empty: the item's own). |
|
||||
|
||||
### record `list-widget`
|
||||
|
||||
Rows the player picks one of, as an options page lists choices: a pick is `ui-events::select`, `selected` is the row to mark now.
|
||||
|
||||
| Field | Type | |
|
||||
| --- | --- | --- |
|
||||
| `id` | `u32` | The mod's own name for the widget; `ui-events::select` echoes it. |
|
||||
| `rows` | `list<string>` | The rows' texts, at most 512, each up to 256 characters. |
|
||||
| `selected` | `option<u32>` | The row to mark as the current choice, if any. |
|
||||
|
||||
### record `button-widget`
|
||||
|
||||
A thing on a mod's screen or settings page. A button as the options pages have them (200 × 20): a click is `ui-events::select(id, 0)`. Mods cycle its label for a choice ("Corner: Top Left").
|
||||
|
||||
| Field | Type | |
|
||||
| --- | --- | --- |
|
||||
| `id` | `u32` | The mod's own name for the widget. |
|
||||
| `label` | `string` | Up to 256 characters. |
|
||||
|
||||
### variant `widget`
|
||||
|
||||
| Case | Payload | |
|
||||
| --- | --- | --- |
|
||||
| `text` | `text-widget` | Text the player reads. |
|
||||
| `button` | `button-widget` | A button. |
|
||||
| `item` | `item-widget` | An item's icon and name. |
|
||||
| `list` | `list-widget` | Rows the player picks from. |
|
||||
|
||||
### record `screen`
|
||||
|
||||
A screen the mod owns: a title over widgets stacked down the middle, the Done button the game adds, and Esc to leave it.
|
||||
|
||||
| Field | Type | |
|
||||
| --- | --- | --- |
|
||||
| `title` | `string` | Its title, up to 256 characters. |
|
||||
| `widgets` | `list<widget>` | Its widgets, in order, at most 64. |
|
||||
|
||||
| Function | Signature | What it does |
|
||||
| --- | --- | --- |
|
||||
| `open-screen` | `func(screen: screen)` | Show `screen` over the game; a second call while it is open replaces it. Only the last call of one hook counts. |
|
||||
| `close-screen` | `func()` | Close the mod's screen when it is open (the mod hears no `closed` for this: it was its own doing). |
|
||||
| `set-settings` | `func(widgets: list<widget>)` | The mod's page in Options > Mods, reached from a settings button on its row: the widgets it shows, an empty list for no page. The player opening the page is `ui-events::settings-opened`: push fresh widgets then; later calls update the page while it shows. |
|
||||
|
||||
## `ui-events`
|
||||
|
||||
Access: exported by the mod: the game calls it.
|
||||
|
||||
What the game calls on a mod that shows widgets (capability `ui`): what the player did with them.
|
||||
|
||||
| Function | Signature | What it does |
|
||||
| --- | --- | --- |
|
||||
| `select` | `func(id: u32, row: u32)` | A row of one of the mod's `list` widgets was picked: the widget's `id` and the row, on the screen or the settings page that showed it. |
|
||||
| `closed` | `func()` | The player left the mod's screen (Esc or Done); not for a screen the mod closed itself or one that went away with the mod. |
|
||||
| `settings-opened` | `func()` | The player opened the mod's settings page in Options > Mods: call `ui::set-settings` now to fill it with fresh widgets. |
|
||||
|
||||
## `input`
|
||||
|
||||
Access: capability `input`.
|
||||
|
||||
Capability `input` (experimental: the manifest needs `experimental = ["input"]`): the use button on items the mod claims, and the mod's own keys. Events wait for `poll`, at most 256.
|
||||
|
||||
### record `held-item`
|
||||
|
||||
The main hand's stack.
|
||||
|
||||
| Field | Type | |
|
||||
| --- | --- | --- |
|
||||
| `id` | `string` | `minecraft:spyglass`, `<mod>:<path>`. |
|
||||
| `count` | `u32` | |
|
||||
| `slot` | `u32` | The hotbar slot, 0 to 8. |
|
||||
|
||||
### record `item-use`
|
||||
|
||||
| Field | Type | |
|
||||
| --- | --- | --- |
|
||||
| `item` | `held-item` | |
|
||||
| `ticks` | `u32` | Game ticks the button was held (0 on `use-start`). |
|
||||
|
||||
### variant `event`
|
||||
|
||||
| Case | Payload | |
|
||||
| --- | --- | --- |
|
||||
| `use-start` | `item-use` | The use button went down with a claimed item in the main hand. The game does nothing else with the click: no placing, no eating, no swing. |
|
||||
| `use-stop` | `item-use` | It came up again, or the item left the hand, or a screen opened. |
|
||||
| `key-down` | `string` | A key `register-key` named went down or up while playing (no screen open). The game's own mapping on that key still runs. A screen opening lets every held key up. |
|
||||
| `key-up` | `string` | |
|
||||
| `wheel` | `f32` | Mouse wheel steps while the mod holds the wheel (`claim-wheel`): positive away from the player, as the hotbar reads them. |
|
||||
|
||||
### record `mapping-state`
|
||||
|
||||
A mapping as the player has bound it.
|
||||
|
||||
| Field | Type | |
|
||||
| --- | --- | --- |
|
||||
| `label` | `string` | The bound key's name as Controls shows it: `W`, `Space`, `LMB`. |
|
||||
| `down` | `bool` | Held down now (as of this frame for a mod with a `frame` hook, else this tick). |
|
||||
|
||||
| Function | Signature | What it does |
|
||||
| --- | --- | --- |
|
||||
| `claim-items` | `func(ids: list<string>)` | The items whose use the mod handles instead of the game, by id (at most 64). Replaces the previous list. |
|
||||
| `register-key` | `func(name: string, label: string, key: string) -> result<_, string>` | A key of the mod's: `name` comes back in `key-down` and `key-up`, `label` says what it does, `key` is the key as options.txt writes it (`key.keyboard.r`), the default: the player can bind another one on the mod's page in Options > Mods, and that one wins. At most 16; an unknown key is an error. |
|
||||
| `held` | `func() -> option<held-item>` | The main hand's stack, as of this tick; none when it is empty. |
|
||||
| `poll` | `func() -> list<event>` | The events since the last call, oldest first. |
|
||||
| `claim-wheel` | `func(on: bool)` | Takes the mouse wheel while playing (true) or gives it back: while taken, its steps are the mod's `wheel` events and the hotbar doesn't move. The game gives it back when the mod stops. |
|
||||
| `mapping` | `func(name: string) -> option<mapping-state>` | A movement or click mapping as the player has bound it: `key.forward`, `key.left`, `key.back`, `key.right`, `key.jump`, `key.sneak`, `key.sprint`, `key.attack` or `key.use`. None for another name. |
|
||||
| `clicks-per-second` | `func() -> tuple<u32, u32>` | Clicks of the attack and use buttons in the last second. |
|
||||
|
||||
## `render`
|
||||
|
||||
Access: capability `render`.
|
||||
|
||||
Capability `render` (experimental: the manifest needs `experimental = ["render"]`): shapes the game draws for the mod with its own renderer, kept until the mod replaces them (no call per frame). A mod never supplies shader code.
|
||||
|
||||
### enum `corner`
|
||||
|
||||
A corner of the screen, as `hud`'s panels use them.
|
||||
|
||||
| Case | |
|
||||
| --- | --- |
|
||||
| `top-left` | |
|
||||
| `top-right` | |
|
||||
| `bottom-left` | |
|
||||
| `bottom-right` | |
|
||||
|
||||
### record `rect`
|
||||
|
||||
A rectangle in GUI pixels: the top left corner and the size.
|
||||
|
||||
| Field | Type | |
|
||||
| --- | --- | --- |
|
||||
| `x` | `f32` | |
|
||||
| `y` | `f32` | |
|
||||
| `w` | `f32` | |
|
||||
| `h` | `f32` | |
|
||||
|
||||
### record `point`
|
||||
|
||||
A point in GUI pixels from the screen's top left.
|
||||
|
||||
| Field | Type | |
|
||||
| --- | --- | --- |
|
||||
| `x` | `f32` | |
|
||||
| `y` | `f32` | |
|
||||
|
||||
### record `fill-shape`
|
||||
|
||||
| Field | Type | |
|
||||
| --- | --- | --- |
|
||||
| `rect` | `rect` | |
|
||||
| `color` | `u32` | 0xAARRGGBB. |
|
||||
|
||||
### record `quad-shape`
|
||||
|
||||
Any four-cornered shape (a wheel's segment, an arrow): the corners in order round it.
|
||||
|
||||
| Field | Type | |
|
||||
| --- | --- | --- |
|
||||
| `corners` | `tuple<point, point, point, point>` | |
|
||||
| `color` | `u32` | 0xAARRGGBB. |
|
||||
|
||||
### record `sprite-shape`
|
||||
|
||||
| Field | Type | |
|
||||
| --- | --- | --- |
|
||||
| `sprite` | `string` | One of the game's GUI sprites, as `gui/sprites/` names them (`hud/heart/full`, `widget/button`), the resource packs' versions included. An unknown one draws nothing. |
|
||||
| `rect` | `rect` | |
|
||||
| `color` | `u32` | A tint, 0xAARRGGBB: 0xFFFFFFFF draws it as it is. |
|
||||
|
||||
### record `item-shape`
|
||||
|
||||
| Field | Type | |
|
||||
| --- | --- | --- |
|
||||
| `item` | `string` | `minecraft:diamond`, `<mod>:<path>`; an unknown one draws nothing. |
|
||||
| `at` | `point` | The icon's top left. |
|
||||
| `scale` | `f32` | 1.0 is the hotbar's 16 × 16. |
|
||||
|
||||
### record `text-shape`
|
||||
|
||||
| Field | Type | |
|
||||
| --- | --- | --- |
|
||||
| `text` | `string` | Up to 256 characters, one line. |
|
||||
| `at` | `point` | |
|
||||
| `color` | `u32` | 0xRRGGBB, as `hud`'s lines. |
|
||||
| `centered` | `bool` | Centred on `at.x` instead of starting there. |
|
||||
| `shadow` | `bool` | |
|
||||
|
||||
### variant `shape`
|
||||
|
||||
| Case | Payload | |
|
||||
| --- | --- | --- |
|
||||
| `fill` | `fill-shape` | |
|
||||
| `quad` | `quad-shape` | |
|
||||
| `sprite` | `sprite-shape` | |
|
||||
| `item` | `item-shape` | |
|
||||
| `text` | `text-shape` | |
|
||||
|
||||
### record `frame-rate`
|
||||
|
||||
| Field | Type | |
|
||||
| --- | --- | --- |
|
||||
| `fps` | `u32` | Frames drawn in the last second. |
|
||||
| `min` | `u32` | The slowest frame's rate, and the 1% low (the 99th percentile frame time's rate), over the last 5 seconds. |
|
||||
| `low` | `u32` | |
|
||||
|
||||
### record `zoom`
|
||||
|
||||
| Field | Type | |
|
||||
| --- | --- | --- |
|
||||
| `factor` | `f32` | The field of view is divided by it: 1 is none, at most 10. |
|
||||
| `smooth` | `bool` | Ease in and out through the game's field-of-view easing, as the spyglass does, instead of at once. |
|
||||
| `turn` | `f32` | Mouse turning is multiplied by it while zoomed: 1 keeps the player's sensitivity, at least 0.05. |
|
||||
|
||||
### record `minimap`
|
||||
|
||||
| Field | Type | |
|
||||
| --- | --- | --- |
|
||||
| `corner` | `corner` | |
|
||||
| `size` | `f32` | Its side in GUI pixels, 16 to 256. |
|
||||
| `blocks-per-pixel` | `f32` | World blocks per map pixel, 0.5 to 4; the map is 128 × 128 pixels. |
|
||||
| `rotate` | `bool` | The map turns with the player, who faces up, and an N on its rim marks north. Otherwise north is up and the player's arrow turns. |
|
||||
| `round` | `bool` | Round, the corners left clear; otherwise square. |
|
||||
|
||||
| Function | Signature | What it does |
|
||||
| --- | --- | --- |
|
||||
| `set-hud` | `func(shapes: list<shape>)` | Replaces the mod's HUD shapes: up to 1024, drawn every frame in order over the HUD (after the hotbar, under chat and screens), hidden with the HUD (F1). An empty list removes them. |
|
||||
| `gui-size` | `func() -> tuple<f32, f32>` | The screen's size in GUI pixels (width, height), as of this tick. |
|
||||
| `shake` | `func(strength: f32, seconds: f32)` | Shakes the camera: a jolt of `strength` (0 to 1, 1 the hardest) that fades out over `seconds` (at most 10). Jolts add up to 1. The view turns, the player doesn't, and the player's Distortion Effects option scales it (0 turns it off). |
|
||||
| `set-corner` | `func(corner: corner, width: f32, height: f32, shapes: list<shape>)` | Replaces the mod's corner panel: shapes in GUI pixels from the top left of a `width` × `height` box that the game places in `corner`, stacked with the game's overlays and the other mods' panels (under the status effects at the top right), as `hud`'s panels are. |
|
||||
| `clear-corner` | `func()` | Removes the mod's corner panel. |
|
||||
| `text-width` | `func(text: string) -> f32` | The width of one line of text in GUI pixels, in the HUD's font: exact for Latin letters (U+0000 to U+024F), 6 per other character. |
|
||||
| `frame-stats` | `func() -> frame-rate` | The game's frame counter, recomputed twice a second. |
|
||||
| `set-zoom` | `func(zoom: zoom)` | Zooms the camera until the next call (`factor` 1 ends it), only while playing: a screen opening or the spyglass's own view (which wins) leave the camera vanilla's. With several mods, the strongest zoom counts. |
|
||||
| `set-minimap` | `func(minimap: option<minimap>)` | Shows a map of the world around the player in `corner`, stacked with the game's overlays and the mods' panels, until the next call (none hides it). It looks like a map item: vanilla's map colours with their height shading and water depth, and the player's arrow. Underground, under a roof and in the Nether it maps the floor around the player's height. The game keeps the map's tiles and refreshes them within its own frame budget; hidden, they are dropped. One map shows at a time: the first loaded mod's. |
|
||||
|
||||
## `events`
|
||||
|
||||
Access: exported by the mod: the game calls it.
|
||||
|
||||
+11
-1
@@ -19,11 +19,14 @@ the player before the mod is turned on, and checked against the component's real
|
||||
| Capabilities | 6: `game-read`, `chat`, `hud`, `storage`, `registries`, `players` |
|
||||
| Manifest `api` lines served | 3: `0.1` (code), `0.2` (content), `0.3` (server mods, experimental) |
|
||||
| SDK | the `Mod` trait (5 methods), `Registration` (4 builders), `export_mod!`, log helpers; `server::ServerMod` (8 methods), `server::Registration` (5 builders), `export_server_mod!` |
|
||||
| `cargo horizon-mod` | `new`, `build`, `run`, `test`, `check` |
|
||||
| `cargo horizon-mod` | `new` (templates `code` and `content`), `build`, `run`, `test`, `check` |
|
||||
| Example mods | `coords-hud` (code), `ruby-content` (content), `welcome` (server) |
|
||||
|
||||
## Guide
|
||||
|
||||
The step-by-step guide, from installing the tools to publishing on the registry, is
|
||||
[Make a mod](https://playhorizon.dev/docs/make-a-mod) on the website. In short:
|
||||
|
||||
1. `rustup target add wasm32-unknown-unknown`, `cargo install --git https://github.com/ludovic111/horizon
|
||||
cargo-horizon-mod`, then `cargo horizon-mod new my-mod` ([Making a mod](../mods.md#making-a-mod)).
|
||||
2. Implement `Mod` for your type, list the capabilities you import in `horizon-mod.toml`
|
||||
@@ -60,6 +63,7 @@ scripting runtime in the game.
|
||||
| Way in | For | Status | Template and example |
|
||||
| --- | --- | --- | --- |
|
||||
| Rust | most mods; the fastest | first-class: the SDK, `cargo horizon-mod` | `cargo horizon-mod new`, `coords-hud` |
|
||||
| Data only | blocks and items with no code | first-class: content mods (API 0.2) | `cargo horizon-mod new --template content`, `ruby-content` |
|
||||
| Lua scripts | people who don't want a compiler | planned: a script mod whose code is a `.lua` file, run by Horizon's own interpreter mod | planned, with the same example as Rust |
|
||||
| C, C++, Zig | authors of those languages | to evaluate: bindings generated from the WIT, built without WASI | one each if it passes |
|
||||
| Go (TinyGo), AssemblyScript, JavaScript / TypeScript | authors of those languages | to evaluate: each needs its toolchain to emit a component without WASI imports, or an interpreter mod as for Lua | one each if it passes |
|
||||
@@ -104,5 +108,11 @@ What real mods need next, in the order modpacks and servers need it:
|
||||
- API 0.3 (server mods, experimental): world `horizon-server-mod`, capability `players`, the `server-events`
|
||||
hooks; SDK `server::ServerMod`; example `welcome`.
|
||||
- SDK: `cargo horizon-mod test` and `horizon_mods::testing`, test scripts in TOML; the template has one.
|
||||
- Experimental: `ui` button widget; `render.set-corner`, `text-width`, `frame-stats`; `input.mapping`,
|
||||
`clicks-per-second` (what the official FPS, keystrokes and zoom mods need).
|
||||
- Experimental `input` (`experimental = ["input"]`): `claim-items`, `register-key`, `held`, `poll` (use-start,
|
||||
use-stop, key-down, key-up).
|
||||
- Experimental `render` (`experimental = ["render"]`): HUD shapes (fill, quad, sprite, item, text), `gui-size`, camera
|
||||
`shake`, drawn by the game's own renderer.
|
||||
- API 0.2 (content): data-driven blocks and items, tags, `horizon:add_to`, terrain adaptation.
|
||||
- API 0.1.0: `log`, `game`, `chat`, `hud`, `storage`; `init`, `tick`, `frame`, `command`, `chat`.
|
||||
|
||||
@@ -0,0 +1,162 @@
|
||||
# Shader API reference (0.1)
|
||||
|
||||
Generated from `crates/horizon-shader-api` (`HORIZON_WRITE_DOCS=1 cargo test -p horizon-shader-api --test reference`
|
||||
rewrites it; the test fails when it drifts). The API's design and pack format: [shaders.md](shaders.md).
|
||||
|
||||
A stage is a function your WGSL defines, with the signature below; Horizon puts the prelude (these structs, the
|
||||
resources and helpers) before your files and calls the function from its own pass. Your files declare no
|
||||
bindings and no entry points, and no names starting with `horizon_`.
|
||||
|
||||
## Stages
|
||||
|
||||
| Stage | In `horizon-shaders.toml` | Your function |
|
||||
| --- | --- | --- |
|
||||
| sky | `[sky]` | `fn sky(input: SkyInput) -> vec4<f32>` |
|
||||
| material | `[material]` | `fn material(input: MaterialInput) -> Surface` |
|
||||
| post | `[[post]]` | `fn post(input: PostInput) -> vec4<f32>` |
|
||||
|
||||
## sky
|
||||
|
||||
`fn sky(input: SkyInput) -> vec4<f32>`
|
||||
|
||||
### `SkyInput`
|
||||
|
||||
One direction of the sky, for `fn sky(input: SkyInput) -> vec4<f32>`. The sun, moon, stars and clouds are drawn over the result.
|
||||
|
||||
| Field | Type | Meaning |
|
||||
| --- | --- | --- |
|
||||
| `direction` | `vec3<f32>` | Unit view ray, camera-relative world axes. |
|
||||
| `color` | `vec4<f32>` | Vanilla's sky colour along the ray (sky, fog and sunrise). |
|
||||
|
||||
Resources (bind group 3):
|
||||
|
||||
| Binding | Declaration | Meaning |
|
||||
| --- | --- | --- |
|
||||
| 0 | `var<uniform> frame: Frame` | The frame (`Frame`). |
|
||||
|
||||
## material
|
||||
|
||||
`fn material(input: MaterialInput) -> Surface`
|
||||
|
||||
### `MaterialInput`
|
||||
|
||||
One point of a block's surface, for `fn material(input: MaterialInput) -> Surface`.
|
||||
|
||||
| Field | Type | Meaning |
|
||||
| --- | --- | --- |
|
||||
| `albedo` | `vec4<f32>` | The block texture's colour here (alpha 0..1). |
|
||||
| `tint` | `vec4<f32>` | The vertex colour: biome tint, face shade and ambient occlusion. |
|
||||
| `light` | `vec2<f32>` | Block and sky light, 0..1, smoothed over the face. |
|
||||
| `lightmap` | `vec3<f32>` | Vanilla's light colour for that light this frame. |
|
||||
| `position` | `vec3<f32>` | The point, camera-relative, in blocks. |
|
||||
| `uv` | `vec2<f32>` | The texture coordinate inside the block atlas. |
|
||||
| `translucent` | `bool` | Drawn in the translucent pass (water, stained glass, ice). |
|
||||
|
||||
### `Surface`
|
||||
|
||||
What `material` returns. Vanilla's own is `albedo * tint * vec4(lightmap, 1.0)`; Horizon then applies the alpha test (cutout and translucent) and fog.
|
||||
|
||||
| Field | Type | Meaning |
|
||||
| --- | --- | --- |
|
||||
| `color` | `vec4<f32>` | The lit colour, 0..1, with its alpha. |
|
||||
|
||||
Resources (bind group 3):
|
||||
|
||||
| Binding | Declaration | Meaning |
|
||||
| --- | --- | --- |
|
||||
| 0 | `var<uniform> frame: Frame` | The frame (`Frame`). |
|
||||
|
||||
## post
|
||||
|
||||
`fn post(input: PostInput) -> vec4<f32>`
|
||||
|
||||
### `PostInput`
|
||||
|
||||
One pixel of the picture, for `fn post(input: PostInput) -> vec4<f32>`.
|
||||
|
||||
| Field | Type | Meaning |
|
||||
| --- | --- | --- |
|
||||
| `uv` | `vec2<f32>` | Where the pixel is, 0..1 from the top left. |
|
||||
| `pixel` | `vec2<f32>` | The pixel's centre, in pixels from the top left of what the pass draws (the world's size; the window's for the last pass). |
|
||||
| `color` | `vec4<f32>` | The previous pass's colour here (the world's picture for the first pass). |
|
||||
| `depth` | `f32` | The world's depth here, reversed: 0 is the sky. |
|
||||
|
||||
Resources (bind group 3):
|
||||
|
||||
| Binding | Declaration | Meaning |
|
||||
| --- | --- | --- |
|
||||
| 0 | `var<uniform> frame: Frame` | The frame (`Frame`). |
|
||||
| 1 | `var scene_color: texture_2d<f32>` | The world's picture before any pass. |
|
||||
| 2 | `var scene_depth: texture_depth_2d` | The world's depth, reversed (1 near, 0 far and sky). |
|
||||
| 3 | `var previous: texture_2d<f32>` | The previous pass's output (`scene_color` for the first pass). |
|
||||
| 4 | `var linear_sampler: sampler` | Bilinear filtering, clamped to the edges. |
|
||||
| 5 | `var nearest_sampler: sampler` | Nearest texel, clamped to the edges. |
|
||||
|
||||
Helpers:
|
||||
|
||||
- `fn depth_at(uv: vec2<f32>) -> f32`: the world's depth at `uv`.
|
||||
- `fn view_position(uv: vec2<f32>, depth: f32) -> vec3<f32>`: the camera-relative position, in blocks, of
|
||||
the point at `uv` and `depth`.
|
||||
|
||||
## The frame
|
||||
|
||||
### `Frame`
|
||||
|
||||
The frame, as `frame` in every stage. Positions and directions are in world axes relative to the camera (x east, y up, z south), so they stay precise far from the world's origin; depth is reversed (1 near, 0 at the far plane and in the sky).
|
||||
|
||||
| Field | Type | Offset | Meaning |
|
||||
| --- | --- | --- | --- |
|
||||
| `view` | `mat4x4<f32>` | 0 | Camera-relative world to view space: the camera's rotation. |
|
||||
| `projection` | `mat4x4<f32>` | 64 | View to clip space (reversed depth, wgpu's clip space: z 0..1). |
|
||||
| `view_inverse` | `mat4x4<f32>` | 128 | View to camera-relative world space. |
|
||||
| `projection_inverse` | `mat4x4<f32>` | 192 | Clip to view space. |
|
||||
| `camera_position` | `vec3<f32>` | 256 | The camera's world position, in blocks (about a millimetre of precision 10 000 blocks out). |
|
||||
| `time` | `f32` | 268 | Seconds since the pack was loaded, wrapping to 0 every hour. |
|
||||
| `sun_direction` | `vec3<f32>` | 272 | Unit vector toward the sun (below the horizon at night). |
|
||||
| `day_time` | `f32` | 284 | The time of day, 0..1: 0 sunrise, 0.25 noon, 0.5 sunset, 0.75 midnight. |
|
||||
| `moon_direction` | `vec3<f32>` | 288 | Unit vector toward the moon. |
|
||||
| `game_time` | `f32` | 300 | Vanilla's GameTime: (game time % 24000 + partial tick) / 24000, 0..1. |
|
||||
| `sky_color` | `vec3<f32>` | 304 | Vanilla's sky colour this frame, 0..1. |
|
||||
| `rain` | `f32` | 316 | Rain strength, 0..1. |
|
||||
| `fog_color` | `vec3<f32>` | 320 | Vanilla's fog colour this frame (also the clear colour), 0..1. |
|
||||
| `thunder` | `f32` | 332 | Thunder strength, 0..1. |
|
||||
| `resolution` | `vec2<f32>` | 336 | The size of the world's picture, in pixels (the resolution scale applied). |
|
||||
| `eye_light` | `vec2<f32>` | 344 | Block and sky light at the camera, 0..1 (level / 15). |
|
||||
| `fog_start` | `f32` | 352 | Where vanilla's fog starts, in blocks from the camera. |
|
||||
| `fog_end` | `f32` | 356 | Where vanilla's fog is full, in blocks. |
|
||||
| `render_distance` | `f32` | 360 | The render distance, in blocks. |
|
||||
| `far` | `f32` | 364 | The far plane, in blocks. |
|
||||
| `night_vision` | `f32` | 368 | Night vision strength, 0..1. |
|
||||
| `blindness` | `f32` | 372 | Blindness strength, 0..1. |
|
||||
| `darkness` | `f32` | 376 | The darkness effect's strength, 0..1. |
|
||||
| `brightness` | `f32` | 380 | The Brightness option, 0..1 (Moody to Bright). |
|
||||
| `eye_in` | `u32` | 384 | What the camera is in: 0 air, 1 water, 2 lava, 3 powder snow. |
|
||||
| `dimension` | `i32` | 388 | 0 the Overworld, -1 the Nether, 1 the End, 2 any other dimension. |
|
||||
| `frame_index` | `u32` | 392 | Frames drawn since the pack was loaded (wraps). |
|
||||
| `hide_gui` | `u32` | 396 | 1 while F1 hides the HUD, else 0. |
|
||||
|
||||
## Options
|
||||
|
||||
Each `[[options]]` entry sets the WGSL `override` of the same name when the pipelines are built:
|
||||
|
||||
| `type` | Keys | The `override` |
|
||||
| --- | --- | --- |
|
||||
| `bool` | `default` | `override <id>: bool` |
|
||||
| `float` | `default`, `min`, `max`, `step` | `override <id>: f32` |
|
||||
| `int` | `default`, `min`, `max` | `override <id>: i32` |
|
||||
| `choice` | `values`, `default` (one of them) | `override <id>: u32`, the value's index |
|
||||
|
||||
## Limits
|
||||
|
||||
- 8 post passes, 64 options, `budget.gpu_ms` up to 16.
|
||||
- 256 KiB per WGSL file, 8 MiB per pack.
|
||||
- Per stage: 20000 naga expressions over all its functions, 64 texture reads (samples,
|
||||
gathers and loads, the prelude's included).
|
||||
|
||||
## The check
|
||||
|
||||
A pack runs only after it passes `horizon_shader_api::check` (the game when it loads a pack, the launcher before it
|
||||
installs one, the registry's CI): each stage is parsed and validated by naga, checked against its signature and
|
||||
the rules above, and translated for Vulkan (SPIR-V), Metal and DirectX 12 (HLSL) with its options at their
|
||||
defaults, minimums and maximums. Every option must be an `override` of its type in some stage; an `override`
|
||||
that is no option needs a default.
|
||||
+53
-3
@@ -34,10 +34,55 @@ how the world is fed to the GPU.
|
||||
benchmark ([benchmark-report.md](../benchmark-report.md)) records the pack and its cost, so "fast" stays measured.
|
||||
- **Off by default.** Without a pack the renderer is vanilla's look, and no pack code runs.
|
||||
|
||||
## The pack format (schema 1)
|
||||
|
||||
A pack is a folder, or the same files zipped as a `.hshader`, with `horizon-shaders.toml` at its root
|
||||
(crate `horizon-shader-api`; the sample with every key is
|
||||
`crates/horizon-shader-api/tests/samples/schema-1/`):
|
||||
|
||||
```toml
|
||||
schema = 1 # the manifest's format; a reader refuses schemas newer than it knows
|
||||
id = "soft_light" # [a-z0-9_]{1,64}: the settings key and the registry id
|
||||
name = "Soft Light"
|
||||
version = "1.0.0"
|
||||
api = "0.1" # the shader API line the WGSL is written for
|
||||
description = "..." # optional, like authors and license
|
||||
shared = ["common.wgsl"] # optional: WGSL put before every stage's file, in order
|
||||
|
||||
[sky] # each stage is optional, but a pack has at least one
|
||||
file = "sky.wgsl"
|
||||
|
||||
[material]
|
||||
file = "material.wgsl"
|
||||
|
||||
[[post]] # full-screen passes, in the order they run (8 at most)
|
||||
file = "post/grade.wgsl"
|
||||
name = "Colour grade" # optional: the GPU time overlay's label
|
||||
|
||||
[[options]] # 64 at most; `id` is the WGSL `override` it sets
|
||||
id = "saturation"
|
||||
name = "Saturation"
|
||||
type = "float" # bool, float (min, max, step), int (min, max), choice (values)
|
||||
default = 1.1
|
||||
min = 0.0
|
||||
max = 2.0
|
||||
step = 0.05
|
||||
|
||||
[budget]
|
||||
gpu_ms = 1.5 # optional: the GPU time the pack aims to add (0 to 16 ms)
|
||||
```
|
||||
|
||||
An option's `override` has the type of its kind: `bool`, `f32`, `i32`, or `u32` for a choice (the index of the
|
||||
value). The pack holds only the manifest, the `.wgsl` files it names (each used, UTF-8, 256 KiB at most),
|
||||
`README.md`, `LICENSE` (`.md`, `.txt`) and `icon.png`, under plain paths, 8 MiB in all. A `.hshader` is built
|
||||
the same way every time (files in path order, fixed dates), so a pack's SHA-256 depends only on its files.
|
||||
|
||||
## Guide, reference and examples
|
||||
|
||||
None yet. When the first stage lands: a guide here, a generated reference (`shaders-reference.md`) and an example pack
|
||||
in the repository that the renderer's tests load.
|
||||
- [shaders-reference.md](shaders-reference.md): every stage's signature, input and output structs, resources and
|
||||
helpers, the frame's fields with their units, option types and limits, generated from `crates/horizon-shader-api`.
|
||||
- [The guide](../shaders.md): making a pack with `horizon-shader new`, `check` and `pack`; the templates and the
|
||||
example pack (`crates/horizon-shader-api/packs/golden_hour`).
|
||||
|
||||
## Stability
|
||||
|
||||
@@ -46,9 +91,14 @@ pack exist ([stability.md](stability.md)).
|
||||
|
||||
## Not there yet
|
||||
|
||||
Everything on this page. The order: the renderer hooks shared with the format loader, then the material and post
|
||||
The stages and everything that runs a pack (the format above is read and checked). The order: the renderer hooks shared with the format loader, then the material and post
|
||||
stages with options and hot reload, then the overlay, lighting, sky and shadow stages.
|
||||
|
||||
## Changelog
|
||||
|
||||
- 2026-10-26: the post stage in the game (`HORIZON_SHADER_PACK`, hot reload with the last good pack kept).
|
||||
- 2026-10-25: `horizon-shader` (`new`, `check`, `pack`), three templates, the example pack and the guide.
|
||||
- 2026-10-25: the check (naga validation, signatures, options, budgets, SPIR-V/Metal/HLSL translation).
|
||||
- 2026-10-25: the stages of API 0.1 (sky, material, post), their inputs and the generated reference.
|
||||
- 2026-10-25: the pack format, schema 1: `horizon-shaders.toml` and the `.hshader` package.
|
||||
- 2026-10-24: the earlier shader pack code was removed; this API is designed from scratch.
|
||||
|
||||
+22
-5
@@ -26,12 +26,13 @@ promise, how something is deprecated and removed, and the tests that keep old mo
|
||||
## What counts as a breaking change
|
||||
|
||||
Breaking: removing or renaming anything; changing a type, a default, a unit or a meaning; making something optional
|
||||
required; refusing input that was accepted; a new case in a WIT `enum` or `variant` the game sends to mods (an older
|
||||
component cannot decode it); a JSON field that changes type.
|
||||
required; refusing input that was accepted; any change to a WIT type a function uses, a new `enum` or `variant` case
|
||||
included, in either direction (the runtime links a component only when each imported function's types match exactly:
|
||||
a mod built before the change no longer loads); a JSON field that changes type.
|
||||
|
||||
Not breaking: a new function, interface, capability, command, endpoint, tool or `server.toml` key; a new optional
|
||||
argument or JSON field (readers must ignore fields they don't know); a new WIT case the mod *sends* (the game decodes
|
||||
every case it ever served); faster, or fixing behaviour to what the reference already says.
|
||||
argument or JSON field (readers must ignore fields they don't know); a new WIT function or type (mods built earlier
|
||||
don't import it); faster, or fixing behaviour to what the reference already says.
|
||||
|
||||
## Stability levels
|
||||
|
||||
@@ -86,7 +87,10 @@ Deprecations and breaking changes are in bold. The release notes of the game rel
|
||||
|
||||
| Part | Level | Version |
|
||||
| --- | --- | --- |
|
||||
| Mod API: `log`, `game`, `chat`, `hud`, `storage`, `events` | preview | 0.1.0 |
|
||||
| Mod API: `log`, `game`, `chat`, `hud`, `storage`, `command`, `events` | preview | 0.1.0 |
|
||||
| Mod API: `ui`, `ui-events` (a mod's screens and settings page) | experimental | manifest `experimental = ["ui"]` |
|
||||
| Mod API: `render` (HUD shapes, camera shake and zoom; drawn by the game, no mod shaders) | experimental | manifest `experimental = ["render"]` |
|
||||
| Mod API: `input` (claimed items' use, the mod's keys, the mouse wheel) | experimental | manifest `experimental = ["input"]` |
|
||||
| Content mods (`registries`: data-driven blocks and items) | preview | manifest `api = "0.2"` |
|
||||
| Server mods: world `horizon-server-mod`, `players`, `server-events` | experimental | manifest `api = "0.3"` |
|
||||
| Script mods (Lua run by an interpreter mod, [mods.md](mods.md#ways-in)) | not started | |
|
||||
@@ -101,3 +105,16 @@ Deprecations and breaking changes are in bold. The release notes of the game rel
|
||||
| Telemetry batch and consent | stable | `"schema": 1`, consent `2` |
|
||||
| `horizon-graphics.txt`, `horizon-extras.txt`, `horizon-mods.txt` | preview | none |
|
||||
| `SHA256SUMS` and `SHA256SUMS.sig` | stable | |
|
||||
|
||||
### The experimental mod APIs' choices
|
||||
|
||||
- **What a mod may take from the game.** `input.claim-wheel` is the one input a mod consumes: while it holds the
|
||||
wheel, the steps are its `wheel` events and the hotbar doesn't move. `claim-items` takes the use button only on the
|
||||
items it names. A mod's keys (`register-key`) never consume: vanilla's mapping on the same key still runs. Whether
|
||||
keys may consume too is decided before `input` becomes preview.
|
||||
- **`input`'s `wheel` event** is a new case in a variant the game sends, so it breaks mods built before it (allowed
|
||||
because `input` is experimental): an `input` mod that calls `poll` needs a rebuild against the new WIT.
|
||||
- **`render.set-minimap`** draws a map the game makes, not one a mod composes: reading the blocks around the player
|
||||
for a map image costs too much through hook calls, so the game keeps the tiles (vanilla's map colours) and the mod
|
||||
picks the corner, side, scale and shape. One map shows at a time, the first loaded mod's. It is a new function and a
|
||||
new type, so mods built before it keep loading.
|
||||
|
||||
Reference in New Issue
Block a user