Docs: the players' Mods page and the overview pages for the two kinds

Mods and data packs explains content and native mods, and how a native mod
is installed, built (the notice, the warning, the Native mods instance) and
set up in Options > Mods. The APIs, How Horizon is built, Modpacks and the
docs index stop calling mods sandboxed WebAssembly, and no page links the
Mod API pages that go with it any more.

Co-Authored-By: Claude Opus 5.5 <[email protected]>

docs/apis.md

@@ -6,14 +6,14 @@ Horizon is built to be built on. Mods, shaders, agents, server panels, launchers
 
 | Surface | For | Today | Stability |
 | --- | --- | --- | --- |
-| **Mods** | mod authors | Rust compiled to sandboxed WebAssembly: read the player and the clock, chat, a HUD panel, storage, commands, tick and frame hooks; data-driven blocks and items. Lua scripts, run in the same sandbox, are planned | preview |
+| **Mods** | mod authors | Native mods: Rust on the game's hook points (tick, frame, HUD, keys, the wheel, commands, zoom, minimap, settings pages), compiled into the game by the launcher. Content mods: data-driven blocks, items, recipes and structures | experimental |
 | **Shaders** | shader authors | a new shader API in WGSL is being designed: stages with typed inputs, options, reload on save, a debug overlay | planned |
 | **Agent control** | AI agents, scripts, tests | `horizon-ctl` and its MCP server: 96 commands to watch and play the game | preview |
 | **Servers** | hosts, panels, bots | `horizon-server`'s commands, `server.toml` and a local HTTP control API | stable |
 | **Launcher** | your agent, pack makers | `horizon-launcher`'s 46 commands and its MCP server | preview |
 | **Data formats** | tools that read Horizon's files | benchmark reports, telemetry, settings, release checksums; worlds are vanilla's format | per format |
 
-The full pages, one per surface, with their references: [the API portal](/docs/api), starting with [the Mod API](/docs/api/mods). Mods for players: [Mods](/docs/mods). Agents: [Control Horizon with your AI agent](/docs/agents). Hosting: [Host a server](/docs/hosting).
+The full pages, one per surface, with their references: [the API portal](/docs/api). Mods: [hook points and helpers](/docs/mod-code) and [content mods](/docs/content-mods). Mods for players: [Mods](/docs/mods). Agents: [Control Horizon with your AI agent](/docs/agents). Hosting: [Host a server](/docs/hosting).
 
 ## What the levels mean
 
@@ -21,14 +21,14 @@ The full pages, one per surface, with their references: [the API portal](/docs/a
 - **Preview**: documented and tested. It may change at a new line (0.1 to 0.2), after a deprecation of at least 30 days during which old and new both work.
 - **Experimental**: opt-in only, and it may change in any release.
 
-Every API has its own version (the mod API is `horizon:[email protected]`, the server's control API is `/api/v1`), separate from the game's release number. The whole policy: [stability and versioning](https://github.com/horizon-rust/horizon/blob/main/docs/api/stability.md).
+Every API has its own version (the native hook points are version 1, the server's control API is `/api/v1`), separate from the game's release number. The whole policy: [stability and versioning](https://github.com/horizon-rust/horizon/blob/main/docs/api/stability.md).
 
 ## How they are designed
 
-Each API starts from what its users need to do, and from how Horizon is built: Rust, wgpu, WebAssembly and a server thread that runs every world. Horizon's APIs are its own: they are not modelled on another mod loader's, renderer's or server platform's. Vanilla Minecraft 26.3 is the reference for game concepts such as ids, commands and data packs.
+Each API starts from what its users need to do, and from how Horizon is built: Rust, wgpu and a server thread that runs every world. Horizon's APIs are its own: they are not modelled on another mod loader's, renderer's or server platform's. Vanilla Minecraft 26.3 is the reference for game concepts such as ids, commands and data packs.
 
-They are safe by default (mods run in a sandbox with the permissions you allow; control sockets only listen on your computer, behind a token) and cost nothing when unused.
+They are safe by default (content mods are data only, native mods build only after a warning and play in a game of their own; control sockets only listen on your computer, behind a token) and cost nothing when unused.
 
 ## References that can't drift
 
-Each reference is written by code from the source it describes, and a test fails when the two differ: the mod API from its WIT contract, `horizon-ctl` and the launcher from their command tables, the server from its settings template and route table. A change to an API changes its reference in the same pull request.
+Each reference is written by code from the source it describes, and a test fails when the two differ: `horizon-ctl` and the launcher from their command tables, the server from its settings template and route table. A change to an API changes its reference in the same pull request.

docs/how-horizon-is-built.md

@@ -23,7 +23,7 @@ Not every line is read by a person. Instead, every change is checked against the
 - **Built from the public code.** Releases are built by GitHub Actions, the build service of GitHub, from the public source. Linux and Windows are built on GitHub's machines, and macOS on Ludovic's Mac mini, which runs GitHub Actions jobs. Every build log is [public](https://github.com/horizon-rust/horizon/actions/workflows/release.yml).
 - **Signed checksums.** Every release has a `SHA256SUMS` file, a fingerprint of each download, and `SHA256SUMS.sig`, a signature of that list made with Horizon's release key, which only release builds from main can use. The launcher and `horizon-server update` check both before they install anything, and refuse a file that does not match. The very first server install with `install.sh` checks the fingerprint but not the signature.
 - **Not yet signed by Apple or Microsoft.** The macOS app is not notarized by Apple, because it is not signed with a paid Apple developer account, so macOS asks you to confirm the first time ([Install](/docs/install#download-the-launcher) shows how). The Windows programs are not code-signed either, so Windows may warn you too.
-- **Mods run in a sandbox.** Horizon mods are WebAssembly programs with no access to your files, the network or other programs. A mod lists what it needs, you see that list before you turn it on, and it can do nothing else. See [Mods and data packs](/docs/mods).
+- **Mods are off until you choose them.** A content mod is data only: blocks, items, recipes, textures. A native mod is code with your rights on the computer, so the launcher builds it only after a warning that names it, into a game of its own with its own worlds, and the registry lists one only after a maintainer has read its source. See [Mods and data packs](/docs/mods).
 - **Nothing collected unless you say yes.** Data collection is off until you turn it on, with four separate switches. The one exception is an anonymous "I'm playing" ping for the launcher's player count, which holds nothing about you. See [Privacy](/privacy).
 
 ## What it doesn't contain

docs/index.md

@@ -30,5 +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).
+- **Making mods:** [make a mod](/docs/make-a-mod), content or native, from the first file to the registry.
 - **Helping out:** [contribute](/docs/contributing) and the [FAQ](/docs/faq).

docs/modpacks.md

@@ -21,7 +21,7 @@ Nothing is uploaded or shared. The mod jars and what is made from them stay on y
 
 **Not yet:**
 
-- **Mods with Java code:** machines, magic, new mob behaviour, anything that needs the mod's own logic. Each of these must be ported by hand to Horizon's mod system (Rust compiled to WebAssembly), and checked against the original mod running in a Java test instance. That work is under way; none of it is something you can install yet.
+- **Mods with Java code:** machines, magic, new mob behaviour, anything that needs the mod's own logic. Each of these must be ported by hand as a Horizon [native mod](/docs/make-a-mod), and checked against the original mod running in a Java test instance. That work is under way; none of it is something you can install yet.
 - **World generation written in code:** custom biomes, terrain shaping and structure types that are Java classes.
 - **Scripts** such as KubeJS, and recipe viewers and map mods that are built around Java.
 

docs/mods.md

@@ -1,38 +1,38 @@
 # Mods and data packs
 
-Horizon has its own mod system, written for Horizon and not compatible with Java mods. Data packs work in part. This page says what you can do with each today.
+Horizon has its own mods, made for Horizon and not compatible with Java mods. Data packs work in part. This page says what you can do with each today.
 
 ## Mods
 
-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.
+Horizon has two kinds of mod:
 
-> **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.
+- **Content mods** (`.hmod`) add blocks and items from data and assets: models, textures, recipes, loot tables, tags and structures, with no code. They work in single player today. This is also what the launcher's [modpack](/docs/modpacks) carry-over produces.
+- **Native mods** (`.hnmod`) are Rust code built into the game: a HUD, keys, commands, settings, new behaviour. Horizon's own Zoom, FPS Counter, Keystrokes and Minimap are native mods. They work in single player, on LAN and on servers (only what runs in your own game, on a server you join).
 
-**Playing with mods**
+> **Early.** Reviewed mods are listed at [playhorizon.dev/mods](/mods) and on the launcher's Mods page.
 
-1. Put the mod's `.hmod` file in the `horizon-mods` folder of the game folder (see [Install](/docs/install#first-launch) for where that is), or use the **Open Mod Folder** button on the Mods screen.
-2. Open **Options, Mods...**. Each mod is listed with what it may do ("May see your position, health and the time, draw text on your screen…") and a switch. Mods start off. Turn on the ones you trust.
-3. A mod that failed to load shows why, in red, on its row.
+**Content mods**
 
-**What a mod can do today**
+1. Install one from the launcher's **Mods** page (pick **Horizon** beside Modrinth), or put its `.hmod` file in the `horizon-mods` folder of the game folder (see [Install](/docs/install#first-launch) for where that is).
+2. Open **Options, Mods...**. Each mod is listed with what it may do ("May add blocks and items to your worlds") and a switch. Content mods start off.
+3. Start the game again after a switch: content loads when the game starts. A mod that failed to load shows why, in red, on its row.
 
-- **Client mods** read the same things the F3 screen shows (your position, health, food, the time), draw text panels on the HUD, show chat lines only you see, and add chat commands. They work in single player and on any server, and a server cannot see them.
-- **Content mods** add blocks and items from data and assets: models, textures, recipes, loot tables and tags, with no code. They work in single player today. This is also what the launcher's [modpack](/docs/modpacks) carry-over produces.
-- **Server mods**, which run where the world is simulated, are planned.
+**Native mods**
+
+A native mod is code, not sandboxed: it can do anything you can on your computer. So the launcher builds it into a game of its own, and only when you say so:
+
+1. Install it from the launcher's **Mods** page. The first time, the launcher says what native mods are and turns on **Settings > Native mods (experimental)**.
+2. There, press **Build**. The launcher names the mods and warns you in red; **I trust these mods: build** starts it. The first build downloads Rust and takes 20 to 30 minutes and a few GB of disk; later builds take a few minutes.
+3. Play the **Native mods** instance. It has its own worlds and options, so your other worlds never run the mods.
+4. In the game, **Options > Mods** lists each native mod with a switch and, when it has some, a **Settings** page and keys to rebind. Turn one off there and the next build leaves it out.
+
+Install only mods whose authors you trust. The registry lists a native mod only after a maintainer has read its source, and each one's page links it. Horizon's own mods say "Made by Horizon"; every other mod's page says who made it.
 
 **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:
+[Make a mod](/docs/make-a-mod) is the full guide, for both kinds: the tools, your mod in the game, the hook points with a worked example, content mods, testing, and publishing on [the registry](/mods).
 
-```sh
-rustup target add wasm32-unknown-unknown
-cargo install --git https://github.com/horizon-rust/horizon cargo-horizon-mod
-cargo horizon-mod new my-mod
-cd my-mod
-cargo horizon-mod build
-```
-
-`cargo horizon-mod test` runs the mod's test scripts (`tests/*.toml`: ticks, commands and the player's position in, chat and HUD lines checked) with no game open. 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)).
+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