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/SurvivingDay/mods
cp my_first_mod.so ~/.config/SurvivingDay/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 Surviving Day! 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

About 30 event hooks let your mod react to blocks, players, NPCs, chat, weather, chunks, crafting, and multiplayer events in real time. The three most commonly used are shown below — for the complete hook-by-hook reference (every signature, exact fire condition, and thread-safety notes) see Lesson 4 of the Modding Tutorial.

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(ModDamageEvent* ev) {
    // Refund half the incoming damage back onto HP
    *ev->hp += ev->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.