Minecraft Horizon is an independent Rust-based implementation of Minecraft: Java Edition, with its own modding system. Ordinary Fabric, Forge and NeoForge Java .jar mods cannot simply be installed in Horizon: their code targets a different runtime.
Reviewed: October 29, 2026. Horizon’s documentation describes data-driven content mods (.hmod), native Rust mods (.hnmod) and a separate WebAssembly SDK. These approaches have different build processes and security implications. This guide explains how to choose a format and work through the native development workflow.
Choose the right type of mod
| What you want to build | Recommended format | Programming required? |
|---|---|---|
| Items, blocks, recipes, textures, loot tables or structures | Content mod (.hmod) | No — data and assets |
| HUD widgets, an FPS counter, keybinds, commands or new client behaviour | Native mod (.hnmod) | Yes — Rust |
| Server events or commands exposed by an SDK | Experimental server Mod API | Yes — subject to API and version limits |
Do not mix the toolchains. The current native mod guide describes .hnmod and horizon-mixins; the separate Mod API documentation discusses WebAssembly, cargo horizon-mod and capabilities. Commands from one workflow may not apply to the other. Verify your exact Horizon and SDK release before building.
1. Set up your development tools
For native mods, install Horizon Launcher and prepare the game at least once. You also need stable Rust, Git, Python 3.11 or later and rsync. On Windows, the official guide recommends WSL for command-line checks; on Linux and macOS, use a regular terminal.
Verify the tools:
rustc --version
cargo --version
git --version
python3 --version
rsync --versionIf a command is missing, install the relevant package. Get Rust from rustup.rs and use the maintained Horizon repositories for code and examples.
2. Build your first native mod from Playtime
A native mod is inserted into Horizon’s source before compilation. It is not sandboxed and can run with the user's privileges. Never compile third-party native code you have not reviewed.
Clone the examples:
git clone https://github.com/horizon-rust/horizon-mods
cd horizon-modsThe native/ directory contains examples such as playtime (time played) and fps-overlay. Start with one maintained example and make incremental changes.
A typical project includes:
playtime/
├── Cargo.toml
├── compatibility.json
└── mixins/playtime/
├── horizon-mixin.toml
├── runtime.rs
├── tick.rs
└── hud.rsFile roles: Cargo.toml defines the Rust project and tests. compatibility.json records which Horizon revision and hooks were checked. horizon-mixin.toml describes the injections. runtime.rs implements the logic, while tick.rs and hud.rs connect it to game hooks. Check the current repository for any layout changes.
3. Check the code before compiling
From your horizon-mods clone, point the checker at the mod directory:
python3 native/tools/native.py check /absolute/path/to/playtimeThe checker applies the bundle to the expected Horizon source and runs cargo check. Manifest and hook mismatches produce horizon-mixins errors; Rust errors identify source files and lines. The first check can take longer because dependencies are downloaded and compiled.
Checkpoint: do not proceed until check passes.
4. Compile and launch the native build
The official native workflow documents this launcher command:
horizon-launcher native-build /absolute/path/to/playtime/mixins/playtime --trust-native-codeThe launcher builds a separate Native mods game instance. Select it and press Play. Your launcher may also require Native mods (experimental) to be enabled. The first build downloads additional tools; subsequent builds can reuse compiled dependencies.
The --trust-native-code flag is an explicit decision to run unsandboxed code. Use it only with trusted sources.
5. Native hooks and how they work
A *hook* is an integration point at which Horizon calls mod code. Documented examples include:
| Hook | Trigger | Typical use |
|---|---|---|
native_tick() | Each game tick | Counters and state updates |
native_frame(elapsed) | Each rendered frame | Animation and timing |
native_hud(batch, corners) | HUD rendering | Text, panels and indicators |
native_key(key, pressed) | Key press or release | Keyboard shortcuts |
native_command(command, ran) | A command is entered | Custom commands |
native_wheel(steps, claimed) | Mouse wheel input | Custom scroll handling |
native_zoom(zoom) | Zoom calculation | Custom zoom behaviour |
For instance, a playtime counter can update during native_tick() and display the result through native_hud(). Use the maintained Playtime sample rather than copying unverified code from comments.
See the official hook points and helpers and native bundle specification.
6. Add blocks or items without native Rust
For blocks, items, recipes, models, textures and other data-driven features, a content mod is usually the better starting point. It contains assets and data rather than arbitrary native executable code. The .hmod package is not interchangeable with a native .hnmod bundle.
A content project generally needs a unique namespace, JSON definitions, any necessary textures and models, recipes and names. Start with Horizon's maintained ruby-content example and the content mods guide. Match your folder structure to your specific release; an old Java mod is not a plug-and-play template.
7. WebAssembly Mod API and Cargo
A separate Mod API describes an SDK for Rust modules compiled to WebAssembly, with explicitly declared *capabilities*. That is distinct from building an unsandboxed native .hnmod into the game.
Its documented capability areas include:
game— limited information about the player and game time;chat— local messages and chat events;hud— on-screen text and panels;storage— mod-specific persistent data;log— diagnostic output;players— experimental server-side features.
The WebAssembly SDK documentation provides commands such as:
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 testImportant: these are SDK/WebAssembly commands, not instructions for compiling a native .hnmod using horizon-mixins. Availability depends on the actual toolchain and release. Confirm your version before following them.
The SDK describes client events including init, tick, frame, command and chat, as well as experimental server events. Requested permissions are declared in a manifest. Do not assume the familiar Fabric/Forge APIs for entities, inventory, advanced interfaces or networking exist in the same form.
The sandbox places limits on storage and output. Consult the Mod API reference for the exact limits, structures and types supported by your release.
8. Test the mod before sharing
For native mods, run cargo test in the Rust project, followed by native.py check, then test the resulting launcher instance. The WebAssembly SDK separately provides cargo horizon-mod test for scripted checks without starting the game. See the official testing instructions.
Your checklist: the mod compiles cleanly, its HUD does not cover important controls, settings survive a restart, the unmodified game still runs and no unexpected permissions or side effects appear.
9. Troubleshooting
cargo: command not found — Rust is not installed or is missing from your shell's PATH. Reopen the terminal and check cargo --version.
python3: command not found — install Python 3.11 or later. On Windows, use WSL for native tooling checks as described above.
rsync: command not found — add rsync to your development environment.
horizon-launcher: command not found — check the launcher installation and shell path. If the CLI command is absent in your build, consult the current documentation or use the supported graphical workflow.
Errors in horizon-mixin.toml or compatibility.json — compare your manifest and compatibility metadata with a working official sample and verify the referenced Horizon revision.
A Java .jar does not load — that is expected. Port suitable assets or rewrite the logic against Horizon's supported hooks or SDK.
10. Publishing and security
After testing, prepare the mod for the Horizon registry. Include its version, licence, source repository and a clear description of permissions and risks, then follow the current publishing process. Native code is particularly sensitive because it is not sandboxed.
Do not download suspicious archives or run someone else's build scripts with administrator privileges. Back up your world and track your source with Git.
Quick reference
For a HUD or custom gameplay behaviour: clone horizon-mods → begin with Playtime or FPS Overlay → edit Rust → run native.py check → build with horizon-launcher native-build → test in the separate Native mods instance.
For blocks, recipes, models and textures: choose a content mod and follow the .hmod guide.
For experimental server logic: inspect the Mod API reference for your release and verify that the required hook or capability actually exists.
Official documentation and examples
- Make a mod: step-by-step guide
- Mod API and permissions
- Hook points and the Playtime example
- Content mods: blocks and items
- Testing
- Publishing
- Horizon source code
- Official native mod examples
Horizon is changing rapidly. Always check the documentation for the release you use before treating commands and compatibility notes as current.