diff --git a/docs/api/mods.md b/docs/api/mods.md index bec03e84e..3e6108c70 100644 --- a/docs/api/mods.md +++ b/docs/api/mods.md @@ -24,6 +24,9 @@ the player before the mod is turned on, and checked against the component's real ## 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` diff --git a/website/build.mjs b/website/build.mjs index 4045297fb..d92f452ed 100644 --- a/website/build.mjs +++ b/website/build.mjs @@ -411,7 +411,7 @@ const modsTemplate = await readFile(join(site, "src", "mods.html"), "utf8"); const modsList = `

ModsMade for Horizon, reviewed

Horizon mods

Mods, modpacks and resource packs made for Horizon. Each one was reviewed before it was listed, and the launcher checks every file before it installs it. Mods run in a sandbox and can only do what their page says.

-

Submit yours Make a mod

+

Submit yours Make a mod

diff --git a/website/docs/content-mods.md b/website/docs/content-mods.md new file mode 100644 index 000000000..1ad8cd5fb --- /dev/null +++ b/website/docs/content-mods.md @@ -0,0 +1,114 @@ +# Content mods + +A content mod adds blocks and items to the game with data files only: no Rust, no compiler. Each new block or item copies a vanilla one (its template) and changes what differs, and comes with its recipes, loot table, tags, model, textures and name, in the same formats as vanilla's data packs and resource packs. + +## What a content mod is + +A folder (while you work on it) or a `.hmod` zip (to share it) holding a manifest, `assets/` and `data/`. This is the SDK's [`ruby-content`](https://github.com/ludovic111/horizon/tree/main/crates/horizon-mod-sdk/examples/ruby-content) example, a ruby gem and a block of ruby: + +``` +ruby/ +├── horizon-mod.toml +├── data/ruby/horizon/block/ruby_block.json the block: a template and what differs +├── data/ruby/horizon/item/ruby.json the item +├── data/ruby/recipe/ruby_block.json recipes, as in a data pack +├── data/ruby/recipe/ruby_from_ruby_block.json +├── data/ruby/loot_table/blocks/ruby_block.json what the block drops +├── data/minecraft/tags/block/mineable/pickaxe.json added to vanilla's tags +├── data/minecraft/tags/block/needs_iron_tool.json +├── assets/ruby/blockstates/ruby_block.json models and textures, as in a resource pack +├── assets/ruby/models/block/ruby_block.json +├── assets/ruby/models/item/ruby.json +├── assets/ruby/items/ruby.json +├── assets/ruby/items/ruby_block.json +├── assets/ruby/textures/block/ruby_block.png +├── assets/ruby/textures/item/ruby.png +└── assets/ruby/lang/en_us.json the names players see +``` + +Its manifest asks for API `0.2` and the `registries` capability. It has no code, so it needs no `Cargo.toml` and no `mod.wasm`: + +```toml +id = "ruby" +name = "Ruby" +version = "0.1.0" +description = "A ruby gem and a block of ruby" +authors = ["You"] +api = "0.2" +side = "both" +capabilities = ["registries"] +``` + +## Blocks + +A block is a file `data//horizon/block/.json`. It becomes the block `:`, with the template's behaviour, states and shapes: + +```json +{ + "template": "minecraft:iron_block", + "properties": { "hardness": 4.0, "light": 3, "sounds": "minecraft:amethyst_block", "map_color": 28 } +} +``` + +| Key | Meaning | +| --- | --- | +| `template` | The vanilla block it copies, such as `minecraft:iron_block`, `minecraft:oak_door` or `minecraft:diamond_ore`. A door copies a door's states and shape, an ore an ore's. | +| `properties.hardness` | How long it takes to mine (vanilla's destroy time; `-1` cannot be broken). | +| `properties.explosion_resistance` | How well it stands up to explosions. | +| `properties.light` | The light it gives, 0 to 15. | +| `properties.requires_tool` | `true`: it drops nothing unless mined with the right tool (the tags say which). | +| `properties.friction` | How slippery it is (ice is `0.98`). | +| `properties.map_color` | Its colour on maps, a vanilla map colour id from 0 to 61. | +| `properties.sounds` | A vanilla block whose sounds it uses. | +| `item` | `false` for a block with no item. By default the block gets an item of the same id. | + +Every property you leave out is the template's. + +## Items + +An item is a file `data//horizon/item/.json`, copying a vanilla item: + +```json +{ "template": "minecraft:diamond", "rarity": "uncommon" } +``` + +It may change `max_stack_size` (1 to 99) and `rarity` (`common`, `uncommon`, `rare` or `epic`, the colour of its name). + +## Recipes, loot, tags, models and names + +Everything else uses vanilla 26.3's own formats, so the [Minecraft Wiki's](https://minecraft.wiki/w/Data_pack) pages on data packs and resource packs apply: + +- **Recipes** in `data//recipe/`, **loot tables** in `data//loot_table/`. +- **Tags**: your own in `data//tags/`. To add to vanilla's (which pickaxe mines the block, for example), put a tag file in `data/minecraft/tags/`; to add to the convention tags NeoForge and Fabric mods share, in `data/c/tags/`. They add to the tag as a data pack does; `"replace": true` drops what came before it, and the log says so. +- **Block states, models, item models and textures** in `assets//`, as in a resource pack. Models can use vanilla's parents, such as `minecraft:block/cube_all`. +- **Names** in `assets//lang/en_us.json`: `"block.ruby.ruby_block": "Block of Ruby"`, `"item.ruby.ruby": "Ruby"`. + +**Structures.** A content mod can also carry structures, template pools and structure sets in its namespace, and add its own pieces to vanilla's villages or to another mod's pools. The [mod design page](https://github.com/ludovic111/horizon/blob/main/docs/mods.md#content-mods-api-02) has the details. + +## Namespaces + +Your files go under your mod's id (`assets/ruby/`, `data/ruby/`), plus vanilla's and the convention tags (`data/minecraft/tags/`, `data/c/tags/`). Tags are the only files a mod may put under `minecraft`. + +A mod made from a Java mod whose files use other names lists them in its manifest: `namespaces = ["kaisyn", "towns_and_towers"]`. A listed namespace is the mod's own, as its id is, but blocks and items are still declared under `data//horizon/`. `minecraft`, `c` and `horizon` can't be listed, and two mods that are on can't own the same namespace: the game keeps the first and logs the clash. + +## Limits + +- A mod's files use vanilla's resource-name characters: at most 65,536 files, 16 MiB each and 512 MiB in all. +- A file the game can't read (a block model that doesn't parse, a recipe with a typo) is logged and skipped, as vanilla does: the rest of the mod still loads. Read the log while you work. +- Unknown keys in a block or item file are refused, and the mod stays off with the reason on its row. +- Content mods work in single player today. Playing them together on a server is planned. + +## Try it and share it + +While you work, give the game the folder as a dev mod ([how](/docs/make-a-mod#see-it-in-the-game)): `--dev-mod "/path/to/ruby"`. The first start with a new set of mods takes a little longer while the game adds their content to its tables; after a change to the files, start the game again. + +To share it, zip the folder's contents, with `horizon-mod.toml` at the top of the zip, and name the file `.hmod`: + +```sh +cd ruby +zip -r ../ruby.hmod horizon-mod.toml assets data +``` + +Players put that file in their `horizon-mods` folder and turn it on in **Options, Mods...**. The registry doesn't take content-only mods yet: its checks (`cargo horizon-mod check`) expect code in the file. That is coming next. + +Next: [test it](/docs/test-a-mod). diff --git a/website/docs/index.md b/website/docs/index.md index 2b16c4db9..24f969840 100644 --- a/website/docs/index.md +++ b/website/docs/index.md @@ -30,4 +30,5 @@ There is no build for Intel Macs, 32-bit systems, or ARM Linux and Windows. The - **Playing:** [install and first launch](/docs/install), [settings worth knowing](/docs/settings), [multiplayer](/docs/multiplayer) and [what to do when something breaks](/docs/troubleshooting). - **Hosting:** [host a server](/docs/hosting), from the launcher or the command line. - **Going further:** [modpacks](/docs/modpacks), [mods and data packs](/docs/mods) and [performance](/docs/performance). +- **Making mods:** [make a mod](/docs/make-a-mod), from the first line of code to the registry, and the [Mod API](/docs/api/mods). - **Helping out:** [contribute](/docs/contributing) and the [FAQ](/docs/faq). diff --git a/website/docs/make-a-mod.md b/website/docs/make-a-mod.md new file mode 100644 index 000000000..94c3deca2 --- /dev/null +++ b/website/docs/make-a-mod.md @@ -0,0 +1,88 @@ +# Make a mod + +This guide takes you from nothing to a mod that other players can install from [playhorizon.dev/mods](/mods). You write the mod in Rust. It is compiled to WebAssembly and runs in a sandbox, so a player can see what it may do before turning it on. You need no Minecraft modding experience. + +## The path + +1. **Set up** (this page): install Rust and `cargo horizon-mod`, make your first mod and see it in the game. +2. **[The manifest and capabilities](/docs/mod-manifest)**: the file that names your mod and lists what it may do. +3. **[Write the code](/docs/mod-code)**: the hooks the game calls, what your code can call, and a worked example. +4. **[Content mods](/docs/content-mods)**: blocks, items, recipes and textures from data files, with no code at all. +5. **[Test it](/docs/test-a-mod)**: unit tests, the game's dev mode and the registry's own checks. +6. **[Publish it](/docs/publish-a-mod)**: package, sign and submit it to the registry. + +The [Mod API](/docs/api/mods) lists everything a mod can do today, and its [reference](/docs/api/mods-reference) has every function and type. + +## What a mod can do today + +- **Client mods** run in the player's game. They read what the F3 screen shows (position, facing, health, food, dimension, the time), draw a text panel on the screen, show chat lines only that player sees, add chat commands, and keep small files of their own. They work in single player and on any server, and a server cannot see them. +- **Content mods** add blocks and items copied from vanilla templates, with their recipes, loot tables, tags, models, textures and names. They need no code. +- **Server mods** (rules, world events, server commands) are being built. The [Mod API](/docs/api/mods#not-there-yet) says what comes next. + +A Horizon mod is not a Java mod. Fabric, NeoForge and Forge jars don't run in Horizon, and Horizon mods don't run in Java Minecraft. + +## Install the tools + +You need [Rust](https://rustup.rs) (the stable toolchain), its WebAssembly target and `cargo horizon-mod`, the tool that makes, builds and checks mods. On Windows, macOS or Linux: + +```sh +rustup target add wasm32-unknown-unknown +cargo install --git https://github.com/ludovic111/horizon cargo-horizon-mod +``` + +The second command builds the tool from source, which takes a few minutes the first time. Run it again later to update the tool. + +You also need Horizon itself, installed with the launcher ([Install](/docs/install)), and prepared at least once so the game has its files. + +## Make your first mod + +```sh +cargo horizon-mod new my-mod +cd my-mod +``` + +`new` makes a folder with a working mod in it: a `/hello` command that answers in chat. `--name "My Mod"` sets the name players see. The folder holds: + +``` +my-mod/ +├── Cargo.toml the Rust crate (a cdylib depending on horizon-mod-sdk) +├── horizon-mod.toml the manifest: id, name, version, what the mod may do +├── .gitignore +└── src/lib.rs the code +``` + +Build it: + +```sh +cargo horizon-mod build +``` + +This compiles the crate, checks that the code uses nothing its manifest doesn't declare, and writes `target/horizon-mod/my_mod.hmod`. A `.hmod` is a zip file holding the manifest and the compiled code (`mod.wasm`). It is the one file you give players: the same file runs on Windows, macOS and Linux. + +## See it in the game + +A **dev mod** is a mod the game loads from a path you give it. It is always on, and the game looks at its file once a second: build again and the game reloads it, saying "Mods reloaded" in chat. Its memory starts over; what it saved to its storage stays. + +**From the launcher.** Open the launcher's **Settings** and put this in **Game arguments**, with the full path to your file: + +``` +--dev-mod "/path/to/my-mod/target/horizon-mod/my_mod.hmod" +``` + +Then press **Play**, open a world and type `/hello world` in chat. Leave the setting there while you work on the mod, and clear it when you are done. The launcher's command line does the same: `horizon-launcher play --arg --dev-mod --arg /path/to/my_mod.hmod`. + +**With `cargo horizon-mod run`.** If you have a `horizon-client` you built from source, `cargo horizon-mod run` builds the mod and starts that game with it. It looks for `horizon-client` on your `PATH`, or takes `--game ` or the `HORIZON_CLIENT` variable; anything after `--` goes to the game: + +```sh +cargo horizon-mod run --game ../horizon/target/fast/horizon-client -- --resources ../horizon/.local/horizon-client/26.3 +``` + +Either way, edit `src/lib.rs`, run `cargo horizon-mod build`, and the game picks up the new file. + +## Where things go + +- **Your mod's messages** go to the game log as `[mod my_mod] …` (the `logs/latest.log` file in the game folder), and the game prints them in its terminal too. +- **Mods players install** go in the `horizon-mods` folder of the game folder (Linux `~/.local/share/horizon`, macOS `~/Library/Application Support/horizon`, Windows `%APPDATA%\horizon`). **Options, Mods...** in the game lists them, each with what it may do and a switch. They start off. +- **A mod that fails** to load, or that breaks while running, is switched off with the reason in red on its row of the Mods screen. It never takes the game down with it. + +Next: [the manifest and capabilities](/docs/mod-manifest). diff --git a/website/docs/mod-code.md b/website/docs/mod-code.md new file mode 100644 index 000000000..42cc6f04b --- /dev/null +++ b/website/docs/mod-code.md @@ -0,0 +1,190 @@ +# Write the code + +A mod is a Rust type that implements the `Mod` trait from `horizon-mod-sdk`. The game calls its methods, the hooks, at fixed points, and the mod calls back into the game through the parts of the API its capabilities allow. This page explains both, then builds a complete mod step by step. + +## The shape of a mod + +```rust +use horizon_mod_sdk::{Mod, Registration, chat}; + +struct Hello { + greeted: u32, +} + +impl Mod for Hello { + fn init() -> Result<(Self, Registration), String> { + Ok((Hello { greeted: 0 }, Registration::new().command("hello"))) + } + + fn command(&mut self, _name: &str, args: &str) -> Result, String> { + self.greeted += 1; + chat::show(&format!("Hello {args}! ({} so far)", self.greeted)); + Ok(None) + } +} + +horizon_mod_sdk::export_mod!(Hello); +``` + +- **The state lives in your type.** `init` creates it, and every hook gets `&mut self`. +- **`export_mod!`** connects the type to the game. A mod has exactly one. +- **The game calls only the hooks you ask for.** `init` returns a `Registration` that lists them. The other methods keep their default, empty bodies, and a hook you didn't ask for costs nothing. + +## Hooks + +| Hook | Ask for it with | When the game calls it | +| --- | --- | --- | +| `init() -> Result<(Self, Registration), String>` | always called | Once, when the mod loads. An `Err` keeps the mod off and shows the message on its row. | +| `tick(&mut self, tick: u64)` | `.on_tick()` | Every game tick while the player is in a world: 20 times a second. | +| `frame(&mut self, seconds: f32)` | `.on_frame()` | Every frame the game draws, with the time since the last one. | +| `command(&mut self, name: &str, args: &str)` | `.command("name")` | When the player types `/name …` in chat. `args` is everything after the name. | +| `chat(&mut self, text: &str)` | `.on_chat()` | For each chat line the player receives, as plain text. | + +**Commands.** Ask for as many as you like with `.command("…")`, without the slash. The chat box colours them and completes them with Tab, like vanilla's commands. Vanilla's names win: a mod can't take `/give`, and when two mods ask for the same name, the first one loaded keeps it. The game logs both cases. The return value says what happens next: + +- `Ok(None)`: nothing more. Use it when the mod already answered with `chat::show`. +- `Ok(Some(text))`: the game shows `text` to the player. +- `Err(text)`: the game shows `text` in red, as a failed command. + +**Prefer ticks to frames.** A tick happens 20 times a second whatever the frame rate. The HUD panel is kept by the game and drawn every frame for you, so most mods never need `frame`. + +## What your code can call + +Each module of the SDK is one part of the API, and each needs its capability in the manifest ([the list](/docs/mod-manifest#capabilities)): + +| Module | Capability | Calls | +| --- | --- | --- | +| `game` | `game-read` | `get_player() -> Option` (`x`, `y`, `z`, `yaw`, `pitch`, `health`, `food`, `dimension`), `get_clock() -> Option` (`game_time`, `day_time`). `None` outside a world. | +| `chat` | `chat` | `show(text)` | +| `hud` | `hud` | `set_panel(Corner, &[Line])` (`Line { text, color }`, colour as `0xRRGGBB`; corners `TopLeft`, `TopRight`, `BottomLeft`, `BottomRight`), `clear()` | +| `storage` | `storage` | `get(key) -> Option>`, `set(key, &[u8]) -> Result<(), String>`, `delete(key)` | +| `log` | none | `horizon_mod_sdk::info(text)` and `warn(text)`: lines in the game log | + +What the game reads for you (`game`) is a snapshot taken once a tick, and again before a command runs. It never changes in the middle of a call. Everything else is plain Rust: your own types, maths and text, and the crates you add to `Cargo.toml`, as long as they build for `wasm32-unknown-unknown` without the operating system (no files, threads, network or clock). + +## A worked example: Playtime + +This mod counts how long you play, shows it in the top-right corner, and keeps the count when you quit. `/playtime` says it in chat; `/playtime hide`, `show` and `reset` do what they say. It uses three capabilities (`hud`, `chat`, `storage`) and two hooks (`tick`, `command`). + +**1. Make the mod.** + +```sh +cargo horizon-mod new playtime --name "Playtime" +cd playtime +``` + +**2. Declare what it may do.** In `horizon-mod.toml`, set the description and the capabilities: + +```toml +description = "How long you have played, in a corner of the screen" +capabilities = ["hud", "chat", "storage"] +``` + +**3. The state and a helper.** Replace `src/lib.rs` with the code below, in parts. First the imports, the state and a function that turns ticks into hours and minutes. It touches no API, so an ordinary unit test can check it (step 7). + +```rust +use horizon_mod_sdk::{ + Mod, Registration, chat, + hud::{self, Corner, Line}, + storage, +}; + +/// Ticks played, kept across sessions in the mod's storage. +struct Playtime { + ticks: u64, + shown: bool, +} + +/// `1h 05m` from a number of ticks (20 a second). +fn format(ticks: u64) -> String { + let minutes = ticks / 20 / 60; + format!("{}h {:02}m", minutes / 60, minutes % 60) +} +``` + +**4. Saving and drawing.** `storage::set` writes bytes under a key of your choice; it can fail when the mod is over its quota, so the error goes to the log. The panel is set once and the game draws it until it changes, so redraw only when there is something new to show. + +```rust +impl Playtime { + fn save(&self) { + if let Err(e) = storage::set("ticks", &self.ticks.to_le_bytes()) { + horizon_mod_sdk::warn(&format!("could not save: {e}")); + } + } + + fn draw(&self) { + if self.shown { + let line = Line { text: format!("Played {}", format(self.ticks)), color: 0xFFFF55 }; + hud::set_panel(Corner::TopRight, &[line]); + } else { + hud::clear(); + } + } +} +``` + +**5. The hooks.** `init` reads what an earlier session saved, draws the panel and asks for one command and the tick hook. `tick` counts, and once a minute redraws and saves. `command` reads its arguments. + +```rust +impl Mod for Playtime { + fn init() -> Result<(Self, Registration), String> { + // What an earlier session saved, or 0 the first time. + let ticks = storage::get("ticks") + .and_then(|bytes| bytes.try_into().ok()) + .map_or(0, u64::from_le_bytes); + let state = Playtime { ticks, shown: true }; + state.draw(); + Ok((state, Registration::new().command("playtime").on_tick())) + } + + fn tick(&mut self, _tick: u64) { + self.ticks += 1; + // Once a minute: redraw the panel and save. + if self.ticks % (20 * 60) == 0 { + self.draw(); + self.save(); + } + } + + fn command(&mut self, _name: &str, args: &str) -> Result, String> { + match args.trim() { + "" => chat::show(&format!("You have played {}", format(self.ticks))), + "hide" | "show" => { + self.shown = args.trim() == "show"; + self.draw(); + } + "reset" => { + self.ticks = 0; + self.save(); + self.draw(); + return Ok(Some("Playtime reset".into())); + } + other => return Err(format!("Unknown option {other}: use hide, show or reset")), + } + Ok(None) + } +} + +horizon_mod_sdk::export_mod!(Playtime); +``` + +**6. Try it.** `cargo horizon-mod build`, then start the game with it as a dev mod ([how](/docs/make-a-mod#see-it-in-the-game)). Open a world: "Played 0h 00m" sits in the top-right corner and goes up each minute. Type `/playtime`, then `/playtime hide`. `/playtime foo` answers in red. Quit and come back: the count goes on from where it was. + +**7. Test the helper.** At the end of `src/lib.rs`: + +```rust +#[cfg(test)] +mod tests { + #[test] + fn formats_hours_and_minutes() { + assert_eq!(super::format(0), "0h 00m"); + assert_eq!(super::format(20 * 60 * 65), "1h 05m"); + } +} +``` + +`cargo test` runs it on your computer, with no game. [Test it](/docs/test-a-mod) covers the rest. + +**Where to go from here.** The SDK's examples are complete mods to read: [`coords-hud`](https://github.com/ludovic111/horizon/tree/main/crates/horizon-mod-sdk/examples/coords-hud) (coordinates, facing and the time on the HUD, `/where` and `/coords`) and [`ruby-content`](https://github.com/ludovic111/horizon/tree/main/crates/horizon-mod-sdk/examples/ruby-content) (a content mod). The [reference](/docs/api/mods-reference) lists every type and function, with its limits. + +Next: [content mods](/docs/content-mods), or straight to [testing](/docs/test-a-mod) if your mod has no blocks or items. diff --git a/website/docs/mod-manifest.md b/website/docs/mod-manifest.md new file mode 100644 index 000000000..c0e0e4b51 --- /dev/null +++ b/website/docs/mod-manifest.md @@ -0,0 +1,60 @@ +# 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). diff --git a/website/docs/mods.md b/website/docs/mods.md index 77a1734fd..405c62976 100644 --- a/website/docs/mods.md +++ b/website/docs/mods.md @@ -6,7 +6,7 @@ Horizon has its own mod system, written for Horizon and not compatible with Java Horizon mods are written in Rust, compiled to WebAssembly and run in a sandbox. A mod can only do what it asks for and you allow, and a mod that crashes is switched off without taking the game down. -> **Early.** The mod system is new. There is no store for Horizon mods yet: they are files to put in a folder. The launcher's **Mods** page (see below) finds resource packs and modpacks, not `.hmod` mods. +> **Early.** The mod system is new. Reviewed mods are listed at [playhorizon.dev/mods](/mods), and any `.hmod` file can be put in the folder by hand. **Playing with mods** @@ -22,15 +22,17 @@ Horizon mods are written in Rust, compiled to WebAssembly and run in a sandbox. **Making a mod** +[Make a mod](/docs/make-a-mod) is the full guide: the tools, your first mod in the game, the manifest and capabilities, the code with a worked example, content mods, testing, and publishing on [the registry](/mods). In short: + ```sh rustup target add wasm32-unknown-unknown cargo install --git https://github.com/ludovic111/horizon cargo-horizon-mod cargo horizon-mod new my-mod cd my-mod -cargo horizon-mod run +cargo horizon-mod build ``` -`run` builds the mod and starts the game with it. After an edit, `cargo horizon-mod build` rebuilds it and the running game reloads it. The [Mod API](/docs/api/mods) lists what a mod can do today, its [reference](/docs/api/mods-reference), the [ways in](/docs/api/mods#ways-in) (Rust today, Lua scripts planned) and what comes next; the full guide, with the manifest and the runtime, is [docs/mods.md](https://github.com/ludovic111/horizon/blob/main/docs/mods.md). Java mod jars don't run in Horizon: their code calls and patches Minecraft's Java classes, and Horizon has none. What carries over is the data and assets inside a jar ([modpacks](https://github.com/ludovic111/horizon/blob/main/docs/modpacks.md)). +The [Mod API](/docs/api/mods) lists what a mod can do today and what comes next, and its [reference](/docs/api/mods-reference) every function. Java mod jars don't run in Horizon: their code calls and patches Minecraft's Java classes, and Horizon has none. What carries over is the data and assets inside a jar ([modpacks](/docs/modpacks)). ## Finding resource packs and modpacks diff --git a/website/docs/nav.json b/website/docs/nav.json index 18eab69fd..76c06dc47 100644 --- a/website/docs/nav.json +++ b/website/docs/nav.json @@ -3,6 +3,7 @@ { "group": "Playing", "pages": ["settings", "multiplayer", "troubleshooting"] }, { "group": "Hosting", "pages": ["hosting"] }, { "group": "Going further", "pages": ["modpacks", "mods", "performance", "agents"] }, + { "group": "Make a mod", "pages": ["make-a-mod", "mod-manifest", "mod-code", "content-mods", "test-a-mod", "publish-a-mod"] }, { "group": "Build on Horizon", "pages": ["apis", "api", "api/stability"] }, { "group": "API reference", "pages": ["api/mods", "api/mods-reference", "api/mod-index", "api/server", "api/server-reference", "api/agent-control", "api/launcher", "api/data-formats", "api/shaders"] }, { "group": "Project", "pages": ["contributing", "faq"] } diff --git a/website/docs/publish-a-mod.md b/website/docs/publish-a-mod.md new file mode 100644 index 000000000..c24a77a2f --- /dev/null +++ b/website/docs/publish-a-mod.md @@ -0,0 +1,57 @@ +# Publish a mod + +Horizon's registry lists mods, modpacks and resource packs made for Horizon. Players find them at [playhorizon.dev/mods](/mods) and on the launcher's Mods page, which checks every file before it installs it. Each project is reviewed by a person before it is published. This page takes your mod from a file on your computer to the registry. + +## Before you submit + +1. **Choose a version.** Set `version` in `horizon-mod.toml` (such as `1.0.0`). Every version you publish needs a new one, and a published file never changes. +2. **Build it for release.** `cargo horizon-mod build` (release is the default; `--debug` is for quick local builds) writes `target/horizon-mod/.hmod`. That file is what you submit. +3. **Check it.** `cargo horizon-mod check target/horizon-mod/.hmod` must pass ([Test a mod](/docs/test-a-mod#check-it-as-the-registry-does)). +4. **Publish the source.** Put the mod's source in a public repository, under a licence that lets players use it (MIT, Apache-2.0, GPL and so on, as an [SPDX](https://spdx.org/licenses/) name). Reviewers read it, and the file must be built from it. + +## Sign it + +Signing is optional and recommended. When your project has a public key, every later version must be signed with the matching secret key, so nobody else can publish an update in your name, even with access to your GitHub account. + +Horizon uses [minisign](https://jedisct1.github.io/minisign/) signatures. Install minisign (`brew install minisign`, `scoop install minisign`, or your Linux distribution's package), then make a key pair once: + +```sh +minisign -G -p horizon-mods.pub -s horizon-mods.key +``` + +Keep `horizon-mods.key` and its password private and backed up: losing it means changing the project's key by hand, through the registry's maintainers. The public key is the last line of `horizon-mods.pub` (it starts with `RW`). + +Sign each file you publish, and check the signature as the registry will: + +```sh +minisign -S -s horizon-mods.key -m target/horizon-mod/playtime.hmod +cargo horizon-mod check target/horizon-mod/playtime.hmod --key "RW…your public key…" --signature target/horizon-mod/playtime.hmod.minisig +``` + +The report then says "signature verified". + +## Submit it + +Open [playhorizon.dev/mods/submit](/mods/submit) and sign in with GitHub. The page reads only your public profile. Then fill in: + +- **The file**: the kind (mod), the `.hmod`, its id (the manifest's `id`), its version, the Minecraft version (26.3) and what changed. +- **Its page**: the name, a one-line summary for the list, a description (Markdown), the authors, the licence, the source address and, optionally, a square PNG icon (at most 256 KiB). +- **Signature**: your public key (for a new project) and the file's `.minisig`. + +**Submit for review** checks the file again and opens a pull request in [ludovic111/horizon-mods](https://github.com/ludovic111/horizon-mods). It adds `mods/.toml`, with you as the project's owner. The repository's checks run the file in the sandbox and post their report on the pull request. + +## Review and publication + +A reviewer reads the pull request, your source and the checks' report. Questions and requests for changes come as comments on the pull request: answer them there, and submit a new version from the form when the file must change. + +When the reviewer merges it, the file becomes a release of horizon-mods within minutes, and the project gets its page at `playhorizon.dev/mods/` and shows in the launcher. The page lists what the mod may do, as the game's Mods screen does, with your source, licence and the file's SHA-256. + +## Updates + +An update is the same form with a new version: it adds the version to your project's entry. The project's owners publish updates without a reviewer's extra look, and if the project has a key, the new file must be signed with it. + +Without the form, you can open the pull request by hand: the [horizon-mods README](https://github.com/ludovic111/horizon-mods) says how. The registry's file formats are in [the mod index reference](/docs/api/mod-index). + +## Reports and takedowns + +Anyone can report a project from its page (**Report it**). A project that does harm is taken down: the launcher then refuses its files and turns installed copies off, telling players why. diff --git a/website/docs/test-a-mod.md b/website/docs/test-a-mod.md new file mode 100644 index 000000000..650810963 --- /dev/null +++ b/website/docs/test-a-mod.md @@ -0,0 +1,59 @@ +# Test a mod + +Three kinds of checks catch most mistakes before players see them: unit tests for your own logic, the game's dev mode for how the mod looks and feels, and `cargo horizon-mod check`, which runs the same checks as the registry. + +## Unit tests for your logic + +Code that doesn't call the game (formatting, maths, parsing a command's arguments) is ordinary Rust. Put it in plain functions and test it with `#[test]`, as the [Playtime example](/docs/mod-code#a-worked-example-playtime) does with its `format` function: + +```sh +cargo test +``` + +The tests run on your computer, with no game and no WebAssembly. Keeping the hooks thin and the logic in functions makes most of a mod testable this way. + +## In the game, as a dev mod + +Start the game with your mod as a dev mod ([how](/docs/make-a-mod#see-it-in-the-game)) and keep it running. After each edit: + +```sh +cargo horizon-mod build +``` + +The game sees the new file within a second, says "Mods reloaded" in chat and starts the mod over. What it saved with `storage` stays. Things to try each time: + +- Every command, with no arguments, with good ones and with wrong ones. An `Err` should say what to type instead. +- Leaving the world and opening another: `game::get_player()` is `None` on the title screen. +- Quitting and starting again, for a mod that saves. +- **Options, Mods...**: the mod's row lists what it may do. If it says the mod stopped, the reason is there. + +The game log (`logs/latest.log` in the game folder) has your mod's `info` and `warn` lines as `[mod ]`, and the reason when the game refused or stopped the mod. + +**Why a mod stops.** A mod that panics, runs past its time budget for one call (an endless loop, for example) or uses more than 64 MiB of memory is switched off. The rest of the game carries on. Fix the cause and build again: a dev mod starts over with the new file. + +## Check it as the registry does + +Before you publish, run what the registry runs on every submission: + +```sh +cargo horizon-mod check target/horizon-mod/playtime.hmod +``` + +``` +playtime 0.1.0 (mod, API 0.1, client) + 12424 bytes, SHA-256 6561…ac13, unsigned + may draw text on your screen + may show you chat messages + may save its own settings to disk + trial run: started, 40 ticks, 120 frames, a chat line, /playtime: ok +``` + +It reads the manifest, refuses code that uses a capability the manifest doesn't list, then plays the mod in the sandbox, as the game does: 40 ticks with a moving player, 120 frames, a chat line and each of its commands once with no arguments. The mod must start and must never crash or overrun its budget. It fails with the reason when one of those goes wrong. + +- `--json` prints the report as JSON, for scripts. +- `--key --signature .minisig` also checks your signature ([Publish](/docs/publish-a-mod#sign-it)). +- It checks modpacks (`.hpack`) and resource packs (`.zip`) too; `--kind mod|modpack|resourcepack` when the file's extension doesn't say which. + +A mod that passes `check` passes the registry's automatic checks. A person still reviews it (see [Publish](/docs/publish-a-mod)). + +Next: [publish it](/docs/publish-a-mod). diff --git a/website/src/mods.js b/website/src/mods.js index 4819af374..a597e2847 100644 --- a/website/src/mods.js +++ b/website/src/mods.js @@ -121,6 +121,7 @@ export function submitHtml() { return `

ModsSubmit

Submit to the registry

A mod, a modpack of registry mods, or a resource pack made for Horizon. The form checks the file and opens a pull request; a reviewer reads it, its source and the checks' report, and merging publishes it to this site and the launcher.

+

First time? Publish a mod walks through building, checking and signing the file, and Make a mod starts from the beginning.

The form needs JavaScript. You can also open a pull request by hand.