Making a mod

Mods add features to The Blockheads: chat commands, new rules, tools for server admins and, later, changes that players see in the game. You can browse what others made on the Mods page.

What works today

bhmod (create, check, pack) works, and the Blockheads Server runs Lua and WASM (Rust) mods in its development builds. Client mods run with the mod loader of the PC Port and the Patcher's Android mod loader patch; both are in development builds too and arrive with the next releases.

Start here

1. Your first Lua mod, from bhmod new to a running server.
2. Events, commands and timers, storage.
3. Working with other mods: services, custom events, channels.
4. Hot reload and timings: change a mod without restarting the world.
5. Publishing on the public list.

Prefer Rust? See your first Rust mod. Every function is in the API reference.

Sides

A mod runs on one or both sides:

• server: runs on the server.
• client: runs in the game on a player's device (needs the mod loader).
• both: has a server part and a client part. It can be marked client-required, so players without it cannot join.

Languages

Lua (Luau) is the easiest. Rust compiled to WebAssembly (WASM) also works; C, Zig, Go and others that build WASM components will follow. Java (and Kotlin, or any JVM language) works too: run bhmod new my-mod --lang java. Mods in different languages can call each other.

Java and native mods are not sandboxed

Java (JVM) mods and native mods (they hook the game itself) run with the full rights of the server or the game. They need the native permission, are shown with a red warning, and are off unless you turn them on: JVM support is a switch (server: Settings > Java mods; PC Port: the launcher's mod settings; Android: the Java mods switch in the Mods screen). Native mods are only loaded from the reviewed public list. Details: JVM mods, native mods.

mod.toml

Every mod has a mod.toml file. The main fields:

Field	Meaning
id, version, name, description	Who the mod is. The id is lowercase letters, digits, - and _.
authors, license	Who made it and under which licence.
api	The mod API versions it works with, for example ^0.2 (API versions).
[sides], [entry]	Where it runs and which file starts it.
[dependencies]	Other mods it needs.
[permissions]	What it is allowed to do (below).

The full format is in the SDK docs.

Permissions

A mod can only do what its permissions allow, and the server owner must grant each one:

• world: none, read or write.
• players: any of chat, teleport, kick, ban, inventory, health.
• net-http: websites it may contact.
• channels: its own messages between server, clients and other mods.
• native: native code outside the sandbox. This is shown with a red warning and is reviewed by hand.

Ask only for what you need. What server owners see: Mods on your server.

Publish it

Mods are listed by a pull request to Blockheads-Club/mods. The steps, rules and checks are on the Submit a mod page, and in short in Publishing.