Modding Guide

🗺️ Overview

VoxelGame's modloader scans two directories on startup and loads every .so (Linux) or .dll (Windows) it finds. Each mod exports a single C function — mod_init — which receives a pointer to a ModAPI struct pre-filled with engine callbacks.

🚀 Quick Start

The fastest way to get a mod running — a block that logs when placed.

#include "ModLoader.h"

extern "C" void mod_init(ModAPI* api) {

    // ── Identity ──────────────────────────────────────────
    api->modName    = "My First Mod";
    api->modVersion = "1.0";

    // ── Register a block ─────────────────────────────────
    ModBlockDef stone {
        "Neon Stone",   // display name
        true,           // isSolid
        ""              // no custom texture (uses fallback)
    };
    uint16_t stoneId = api->registerBlock(&stone);

    // ── Event hook: log every block placement ────────────
    api->onBlockPlaced = [](const ModBlockEvent* ev) {
        // handler must be a plain function pointer, not a capturing lambda
    };
    api->onBlockBroken  = nullptr;
    api->onPlayerDamage = nullptr;

    api->logMsg("My First Mod loaded!");
}

# Compile as a shared library
g++ -shared -fPIC -std=c++17 \
    -o my_first_mod.so my_first_mod.cpp \
    -Iinclude

# Install to the primary mod directory
mkdir -p ~/.config/VoxelGame/mods
cp my_first_mod.so ~/.config/VoxelGame/mods/

# Launch the game — you should see in stderr:
# [ModLoader] Loaded: My First Mod v1.0

📁 Mod Structure

Every mod is a single .so file. It must export exactly one symbol:

extern "C" void mod_init(ModAPI* api);

Inside mod_init you must do three things:

• Set api->modName and api->modVersion
• Set each callback pointer (onBlockPlaced, onBlockBroken, onPlayerDamage) to a function or nullptr
• Call any api->register* functions you need

🔨 Building Your Mod

Mods are compiled as position-independent shared libraries. You only need ModLoader.h from the VoxelGame source tree — no linking against the game binary.

g++ -shared -fPIC -std=c++17 \
    -o mymod.so mymod.cpp \
    -I/path/to/VoxelGame/include

CMakeLists.txt template

cmake_minimum_required(VERSION 3.16)
project(MyMod)

add_library(MyMod SHARED mymod.cpp)
target_compile_features(MyMod PRIVATE cxx_std_17)
target_include_directories(MyMod PRIVATE
    /path/to/VoxelGame/include
)
set_target_properties(MyMod PROPERTIES PREFIX "") # removes "lib" prefix

🪟 Cross-Compiling (Linux → Windows & native Windows)

VoxelGame supports mods as .dll on Windows. The same ModLoader.h header works on both platforms — the C ABI is identical.

Option A — Cross-compile on Linux (MinGW-w64)

# Install MinGW-w64 cross-compiler (Debian/Ubuntu)
sudo apt install mingw-w64

# Build a Windows .dll from Linux
x86_64-w64-mingw32-g++ -shared -fPIC -std=c++17 \
    -o mymod.dll mymod.cpp \
    -I/path/to/VoxelGame/include \
    -Wl,--out-implib,mymod.lib

# The .dll is ready to copy to the Windows mod directory

Option B — Native Windows (MSVC / Visual Studio)

rem Compile as a DLL using MSVC cl.exe
cl.exe /std:c++17 /LD /EHsc \
    /I"C:\VoxelGame\include" \
    mymod.cpp \
    /Fe:mymod.dll

Option C — Native Windows (MinGW / MSYS2)

g++ -shared -std=c++17 \
    -o mymod.dll mymod.cpp \
    -I/c/VoxelGame/include

CMakeLists.txt — cross-platform template

cmake_minimum_required(VERSION 3.16)
project(MyMod)

add_library(MyMod SHARED mymod.cpp)
target_compile_features(MyMod PRIVATE cxx_std_17)
target_include_directories(MyMod PRIVATE
    /path/to/VoxelGame/include
)
# Remove "lib" prefix on Linux, keep clean name on Windows
set_target_properties(MyMod PROPERTIES PREFIX "")

# Cross-compile to Windows from Linux:
# cmake -DCMAKE_TOOLCHAIN_FILE=mingw-w64-x86_64.cmake ..

MinGW-w64 toolchain file

set(CMAKE_SYSTEM_NAME Windows)
set(CMAKE_C_COMPILER   x86_64-w64-mingw32-gcc)
set(CMAKE_CXX_COMPILER x86_64-w64-mingw32-g++)
set(CMAKE_RC_COMPILER  x86_64-w64-mingw32-windres)
set(CMAKE_FIND_ROOT_PATH /usr/x86_64-w64-mingw32)
set(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER)
set(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY)
set(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY)

Windows installation path

📋 ModAPI Reference

The ModAPI struct is the complete interface between the engine and your mod. The engine fills its function pointers before calling mod_init; you fill the rest.

Engine-provided — call these

Mod-provided — set these

🧱 ModBlockDef

Passed to api->registerBlock() to define a new block type.

Texture format

┌────────────┬────────────┬────────────┐
│  Top face  │ Side faces │Bottom face │
│  (16×16)   │  (16×16)   │  (16×16)   │
└────────────┴────────────┴────────────┘
  col 0–15     col 16–31    col 32–47

🔔 ModBlockEvent

Passed to onBlockPlaced and onBlockBroken callbacks.

🧱 Register Blocks

Call api->registerBlock() for each block type you want to add. Block IDs are assigned sequentially starting at 342 (BlockType::COUNT). Save the returned ID — you'll need it for recipes and to compare against ModBlockEvent.blockType.

// Globals so callbacks can use them
static uint16_t gNeonStoneId = 0;
static uint16_t gVoidGlassId = 0;

extern "C" void mod_init(ModAPI* api) {
    api->modName    = "Neon Blocks";
    api->modVersion = "2.1";

    // Solid opaque block with a custom texture
    ModBlockDef neonStone {
        "Neon Stone",
        true,
        "/home/user/mods/neon_stone.png"
    };
    gNeonStoneId = api->registerBlock(&neonStone);  // → 342

    // Transparent / non-solid block
    ModBlockDef voidGlass {
        "Void Glass",
        false,   // not solid — won't cull adjacent faces
        ""
    };
    gVoidGlassId = api->registerBlock(&voidGlass);   // → 343

    api->onBlockPlaced  = nullptr;
    api->onBlockBroken  = nullptr;
    api->onPlayerDamage = nullptr;
}

⚗️ Register Recipes

Recipes use a flat 9-element array of uint16_t block IDs representing a 3×3 grid in row-major order (index 0 = top-left, index 8 = bottom-right). Use 0 (Air) for empty slots.

// Pattern visualised:
//   [ NS ][ NS ][ -- ]
//   [ NS ][ NS ][ -- ]
//   [ -- ][ -- ][ -- ]
uint16_t pattern[9] = {
    gNeonStoneId, gNeonStoneId, 0,
    gNeonStoneId, gNeonStoneId, 0,
    0,            0,            0
};

api->registerRecipe(
    pattern,
    gNeonBricksId,   // output block ID
    4,               // output count
    "NEON BRICKS"    // display name
);

Using vanilla block IDs in patterns

You can reference vanilla blocks by casting their BlockType enum value to uint16_t. Key IDs to know:

See the Blocks & Recipes reference for the complete ID table.

💻 Terminal Commands

Register commands that players can type into any Computer block terminal. The command name is the first word typed; the remainder of the line is passed as args.

// Handler must be a plain function (not capturing lambda)
static char* handlePing(const char* args) {
    // malloc the response — engine will free() it
    const char* msg = "PONG! Mod is alive.\n";
    char* buf = (char*)malloc(strlen(msg) + 1);
    strcpy(buf, msg);
    return buf;
}

// In mod_init:
api->registerCommand("ping", handlePing);

// Player types: ping
// Terminal shows: PONG! Mod is alive.

Parsing arguments

static char* handleSpawn(const char* args) {
    // args = "dragon 3"  when player typed: spawn dragon 3
    std::string s(args);
    std::ostringstream oss;
    oss << "Spawning: " << s << "\n";
    std::string result = oss.str();
    char* buf = (char*)malloc(result.size() + 1);
    memcpy(buf, result.c_str(), result.size() + 1);
    return buf;
}

api->registerCommand("spawn", handleSpawn);

🔔 Event Hooks

Three event hooks let your mod react to world and player state changes in real time.

Example: detect when your custom block is broken

static uint16_t gMyBlockId = 0;

static void onBroken(const ModBlockEvent* ev) {
    if (ev->blockType == gMyBlockId) {
        // React to our specific block being broken
    }
}

extern "C" void mod_init(ModAPI* api) {
    api->modName    = "Block Detector";
    api->modVersion = "1.0";

    ModBlockDef def{ "Detector Block", true, "" };
    gMyBlockId = api->registerBlock(&def);

    api->onBlockPlaced  = nullptr;
    api->onBlockBroken  = onBroken;
    api->onPlayerDamage = nullptr;
}

Example: damage shield

static void shieldDamage(float* hp, float dmg) {
    // Halve the damage by adding back half of it to HP
    *hp += dmg * 0.5f;
}

// In mod_init:
api->onPlayerDamage = shieldDamage;

📂 Installation & Paths

The modloader scans two directories in order. A mod found in the primary path will not be loaded again from the fallback, even if both directories contain the same filename.

# Primary location (recommended)
mkdir -p ~/.config/VoxelGame/mods
cp mymod.so ~/.config/VoxelGame/mods/

# Development / testing alongside game binary
mkdir -p mods
cp mymod.so mods/

📖 Full Examples

Complete mod: Neon Block Pack

#include "ModLoader.h"
#include <cstdlib>
#include <cstring>
#include <cstdio>

static uint16_t gNeonStoneId = 0;
static uint16_t gNeonBricksId = 0;
static int gPlacedCount = 0;

static void onPlaced(const ModBlockEvent* ev) {
    if (ev->blockType == gNeonStoneId) gPlacedCount++;
}

static char* neonStats(const char*) {
    char* buf = (char*)malloc(128);
    snprintf(buf, 128, "Neon Stone placed: %d times\n", gPlacedCount);
    return buf;
}

extern "C" void mod_init(ModAPI* api) {
    api->modName    = "Neon Blocks";
    api->modVersion = "1.2";

    ModBlockDef stone { "Neon Stone",  true,  "" };
    ModBlockDef bricks{ "Neon Bricks", true,  "" };
    gNeonStoneId  = api->registerBlock(&stone);
    gNeonBricksId = api->registerBlock(&bricks);

    // 2×2 Neon Stone → 4 Neon Bricks
    uint16_t pat[9] = {
        gNeonStoneId, gNeonStoneId, 0,
        gNeonStoneId, gNeonStoneId, 0,
        0,            0,            0
    };
    api->registerRecipe(pat, gNeonBricksId, 4, "NEON BRICKS");

    api->registerCommand("neonstats", neonStats);

    api->onBlockPlaced  = onPlaced;
    api->onBlockBroken  = nullptr;
    api->onPlayerDamage = nullptr;

    api->logMsg("Neon Blocks loaded!");
}

🛡️ Permissions & Roles

VoxelGame includes a built-in six-tier permission system enforced server-side. Roles are persisted to saves/roles.json and loaded on server start.

Role hierarchy

roles.json format

{
    "Alice":   "OWNER",
    "Bob":     "ADMIN",
    "Charlie": "MODERATOR",
    "Dave":    "MEMBER",
    "Eve":     "BANNED"
}

Role strings are case-insensitive. Unrecognised strings default to PLAYER. The file is written automatically whenever a role changes via the F3 console.

Server enforcement

• Block place/break packets are rejected server-side if the sender's role is below Member.
• A Banned player's connection is refused immediately at the JoinInfo packet stage.
• Kick/ban/promote commands only work when the issuer's role is high enough (Moderator+ for kick/ban; Admin+ for promote).

💻 F3 Admin Console

Press F3 while hosting or connected to a server (Moderator role or above) to open a terminal-style overlay console. It slides over the centre of the screen and accepts commands while the game continues running.

Opening condition

• Must be in an active server session (hosting or connected).
• Local player role must be Moderator or higher.
• Pressing F3 again closes the console.

Available commands

> list
  Alice   [OWNER]   connected
  Bob     [MEMBER]  connected
  Grieger [PLAYER]  connected

> ban Grieger
  Grieger banned and kicked.

> promote Bob MODERATOR
  Bob promoted to MODERATOR.

> broadcast Server restarting in 5 minutes!
  Broadcast sent.

🪄 NPC Edit Wand

The NPC Edit Wand (items: NpcWand and NpcWand2) lets staff right-click any NPC or mob to open an NBT-style editor panel, similar to Minecraft's NPCEdit. Available in singleplayer always; in multiplayer requires Moderator role or above.

How to use

1. 1
   Obtain the wand

   Find NpcWand or NpcWand2 in the Items tab of the creative inventory.

2. 2
   Right-click an NPC

   Aim at any NPC or mob within 8 blocks and right-click. The editor panel opens.

3. 3
   Navigate fields

   Use ↑/↓ or Tab to move between fields.

4. 4
   Edit a field

   Press Enter to begin editing the selected field. Type the new value, then Enter again to confirm or Esc to cancel.

5. 5
   Close

   Press Esc or right-click away from any NPC to close the panel.

Editable fields

🌀 Portals & Gateways

Four teleportation block types allow dimension-like travel. All are placed from the creative inventory and interact on player contact or right-click.

Block types

Gateway activation

A GatewayBlock must be surrounded by 6 adjacent GoldBlocks (one on each face: top, bottom, north, south, east, west) to become active. Once the frame is complete:

1. First right-click: charges the gateway (status: Charged).
2. Second right-click: transports the player to the pocket world.

Pocket worlds

Each Gateway generates a unique procedural world when first entered. The terrain config is randomised per biome theme associated with the gateway's location:

Return shrine

A return shrine is automatically built at the pocket world's spawn point on first entry. It consists of a stone platform, four corner columns capped with GoldBlocks, and a central GatewayBlock surrounded by its own gold frame — right-clicking it returns the player to the main world.

🌲 World Generation

VoxelGame procedurally generates terrain using a multi-pass noise pipeline. Understanding the biome and generation system is useful if your mod places blocks via event hooks.

Biomes

JungleForest sub-types

The JungleForest biome is divided into regional sub-types based on a per-16-block hash. Each sub-type has a distinct tree mix:

WorldConfig terrain sliders

When creating a world, the following parameters are exposed as menu sliders:

Sea level

The default sea level is Y = 96. Beach biomes span Y = 96–102 (shallow). Ocean biomes sit below Y = 88. When a mod places blocks via event hooks and needs to know if a position is underwater, compare against WorldConfig::waterLevel.

Ore Generation (v1.3+)

As of v1.3, ores are distributed through solid rock using 3D scatter veins rather than clustering exclusively on cavern walls. Veins are placed at biome-appropriate depth ranges and embedded throughout the rock mass. Mod blocks registered via registerBlock are not placed by world generation automatically — use onUpdate or a custom world pass to scatter your mod's ore blocks.

New Blocks in v1.3 (IDs 328–341)

Fourteen new vanilla blocks were added in v1.3, occupying IDs 328–341. Mod-registered block IDs now start at 342. The new blocks include the farming system (FarmLand, crop growth stages), decoration (Campfire, GraveMarker), and the magic crafting station (SpellForge):

⚡ Tips & Gotchas

• Save returned block IDs. Store them in static globals so callbacks and recipe patterns can reference them.
• No capturing lambdas. The callback slots are raw function pointers. Use static functions instead.
• malloc your command responses. The engine calls free() on the pointer. Returning a string literal will crash.
• Returning nullptr from a command handler is treated as "this command doesn't handle this" and falls through to the engine's "Unknown command" message.
• Block IDs ≥ 342 are dynamic. Don't hardcode them — always use the value returned by registerBlock.
• Load order matters for block IDs. If your mod B needs mod A's block IDs, name the files so A loads first (00_a.so, 01_b.so).
• Texture PNG must be 48×16 pixels exactly. Passing a wrong-size image may result in incorrect display or a crash on some drivers.
• All event callbacks execute on the main thread — keep them fast. Do not do heavy I/O or blocking calls inside event handlers.