Ferrous

Ferrous — write Minecraft mods in Rust

Ferrous turns Rust code into Minecraft mods. Put a Rust project or a ready .wasm file into the rust/ folder next to mods/, start the game, and it works like a mod: commands, events, blocks, items, creative tabs, recipes, world and player APIs — all running safely in a WebAssembly sandbox.

use ferrous::prelude::*;

script!(init);

fn init(ctx: &Ctx) {
    commands::register("heal [target:player]", |c| {
        let p = match c.player_arg("target") { Some(p) => p, None => c.require_player()? };
        p.set_health(p.max_health().unwrap_or(20.0));
        c.reply_text(Text::new(format!("{} healed", p.name())).green());
        Ok(1)
    });

    if ctx.is_registry_phase() { return; }

    on_block_break("minecraft:diamond_ore", |e| {
        e.player.actionbar(Text::new("Diamond!").aqua().bold());
    });
}

Highlights

• Plain Rust — no Java, Gradle or mappings. The mod builds your project with cargo on start.
• Hot reload — save the file while playing; the script rebuilds in the background and swaps live, keeping its data.
• Crash-proof — panics, endless loops and stack overflows stop only the call, never the server.
• Sandboxed — no access to files, network or game memory; per-call time budget and memory limit.
• Fast — WebAssembly is compiled to JVM bytecode; pure logic runs on par with Java, a call into Minecraft costs ~10 ns.

Features

• Content: blocks (hardness, light, sounds, tools, drops, shapes, block states, per-block data), items (food, weapons, durability, rarity), creative tabs, recipes, translations, textures. Models, blockstates, loot tables and lang files are generated for you.
• Commands: Brigadier commands from a one-line spec like tp <who:players> <to:pos> [dim:dim], with tab completion and permission levels.
• 26 events: players, blocks, entities, damage, death, chat, commands, explosions, ticks — cancel or modify them.
• World: single blocks and bulk operations (fill, read_grid / write_grid), heights, light, biomes, time, weather, explosions, ray casts, sounds, particles, spawning.
• Entities & players: teleport, health, effects, attributes, NBT, inventory, titles, action bar, boss bars.
• Infrastructure: tick scheduler, async tasks, message bus between scripts, persistent storage, config, logging, a mock host for cargo test.

Security

• Running server commands needs [permissions] commands = true in the script manifest. Without it, scripts cannot sneak commands in through command blocks, command block minecarts, NBT or run_command click events.
• Scripts cannot take over commands of the game or other mods.
• Limits (time per call, memory, tasks, storage) are configurable, with server-side caps.
• Server owners: building a Cargo project runs its build.rs and procedural macros natively, outside the sandbox. Only build sources you trust; on production servers use prebuilt .wasm files and set auto_build = false in config/ferrous.toml.

Getting started

1. Install NeoForge 21.1 (Minecraft 1.21.1) and put Ferrous into mods/.
2. For Rust scripts: install rustup and run rustup target add wasm32-unknown-unknown. Prebuilt .wasm scripts need no Rust.
3. In game run /ferrous new my_mod, restart, and try /hi. Then edit rust/my_mod/src/lib.rs.

Admin commands: /ferrous list, /ferrous info <script>, /ferrous reload [script], /ferrous profile <script> on|off, /ferrous new <name>.

Multiplayer

Scripts that add blocks or items must be installed on the server and on every client. Logic-only scripts (commands, events) are needed on the server only.

Requirements

Minecraft 1.21.1 · NeoForge 21.1.x · Java 21 · optional: Rust with the wasm32-unknown-unknown target