Modding Surviving Day! From Zero to Shipped Mod

🗺️ How Mods Work

A mod is a native shared library — .so on Linux, .dll on Windows — that the engine loads at startup with dlopen (Linux) or LoadLibrary (Windows). It looks for one exported C function:

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

The engine allocates a ModAPI struct, fills in about fifty engine-provided function pointers (things like getBlock, spawnNPC, giveItem), and passes it to your mod_init. Your job inside mod_init is two-fold:

1. Call the engine functions you need — e.g. api->registerBlock(&def) — to register content.
2. Fill in the mod-provided function pointers on the same struct — e.g. api->onBlockPlaced = myHandler; — so the engine can call back into your mod when something happens.

Because it's a flat C struct of function pointers, the ABI is compiler-agnostic: you can build with GCC, Clang, or MSVC and it'll still load correctly, as long as the struct layout matches field-for-field what the engine expects (more on this later — it's the single most common way mods break).

🛠️ Toolchain Setup

You need a C++17 compiler and one header file — include/ModLoader.h from the game's source tree. You do not link against the game binary or any other engine source file.

🚀 Your First Mod

A minimal mod that registers one block and logs a message whenever it's placed:

#include "ModLoader.h"

static uint16_t gGlowStoneId = 0;
static ModAPI* gApi = nullptr;

static void onPlaced(const ModBlockEvent* ev) {
    if (ev->blockType == gGlowStoneId) {
        char buf[64];
        snprintf(buf, sizeof(buf), "Glowstone placed at %d,%d,%d",
                 ev->x, ev->y, ev->z);
        gApi->logMsg(buf);
    }
}

extern "C" void mod_init(ModAPI* api) {
    gApi = api;

    api->modName        = "My First Mod";
    api->modVersion     = "1.0";
    api->modDescription = "Adds a glowing block";

    ModBlockDef def{};
    def.name        = "Glowstone";
    def.isSolid     = true;
    def.texturePath = "";  // "" = engine picks a placeholder texture
    gGlowStoneId = api->registerBlock(&def);

    api->onBlockPlaced = onPlaced;
}

Compile it as a shared library:

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

📦 Installing & Testing

1. Copy the built library

   Drop MyFirstMod.so (or .dll) into the mods directory for your platform.

2. Launch the game

   The modloader scans the directory on startup and calls mod_init for every library it finds. Check the game log for your mod's name to confirm it loaded.

3. Find your block in creative

   Registered blocks appear automatically in the creative inventory — no extra registration step needed.

4. Place it and watch the log

   Your logMsg calls show up in the game's console/log output in real time — this is your primary debugging tool since there's no attached debugger for a loaded .so by default.

🧱 Custom Blocks

ModBlockDef def{};
def.name        = "Reinforced Stone";
def.isSolid     = true;
def.texturePath = "textures/reinforced_stone.png";
uint16_t id = api->registerBlock(&def);

⚔️ Custom Items

ModItemDef sword{};
sword.name        = "Obsidian Blade";
sword.texturePath = "textures/obsidian_blade.png";
sword.maxStack    = 1;
sword.damage      = 14;
uint16_t swordId = api->registerItem(&sword);

⚗️ Crafting Recipes

registerRecipe takes a shaped 3×3 grid pattern (9 block/item IDs, row-major, 0 = empty slot), an output type, an output count, and a display name.

uint16_t pattern[9] = {
    swordId, 0, 0,
    0, (uint16_t)BlockType::Stick, 0,
    0, 0, 0
};
api->registerRecipe(pattern, swordId, 1, "Obsidian Blade");

💻 Terminal Commands

registerCommand adds a command players can type into any in-game Computer block. Your handler receives the raw argument string and returns a heap or static string to print back to the terminal.

static char* cmdHeal(const char* args) {
    gApi->setPlayerHP(100.f);
    static char buf[32] = "Healed to full.";
    return buf;
}

// In mod_init:
api->registerCommand("heal", cmdHeal);

🖼️ Custom GUI Panels

ModGuiPanel lets your mod draw a custom on-screen panel. The engine calls your onDraw every frame the panel is open (using the engine's own 2D draw calls), and onClose once when the player dismisses it.

static void drawPanel(int w, int h) {
    // Issue engine draw calls here using w/h as the panel size in pixels
}
static void closePanel() { /* cleanup */ }

static ModGuiPanel gPanel { "Shop", 320, 240, drawPanel, closePanel };

// In mod_init:
api->registerGuiPanel("shop_panel", &gPanel);

// Later, e.g. from a command handler or NPC interact hook:
api->openGuiPanel("shop_panel");
api->closeGuiPanel("shop_panel");

🌍 Reading & Writing Blocks

🐾 Spawning & Controlling NPCs

int idx = api->spawnNPC(KIND_WOLF, px, py, pz);
if (idx >= 0) api->setNPCCompanion(idx, true);

🧍 Player State API

🎒 Inventory API

🔔 UI, Sound & Waypoints

playSound ID reference

playSound maps a small set of documented string IDs onto the engine's procedural audio system — it does not accept arbitrary sample files:

Unrecognized IDs are silently ignored, so it's safe to call speculatively.

🌤️ Time, Season & Weather

💾 Saving Mod Data

This is intentionally a flat string key/value store — for structured data, serialize to JSON (or your own simple format) into a single string yourself.

const char* raw = api->loadData("kills");
int kills = raw ? atoi(raw) : 0;
kills++;
char buf[16];
snprintf(buf, sizeof(buf), "%d", kills);
api->saveData("kills", buf);

🌐 Multiplayer API

See Multiplayer Hooks for the receiving side and lifecycle events (join/leave/server tick).

🔁 Lifecycle Hooks

Every hook below is a field on the same ModAPI struct you fill in during mod_init. Leave any you don't need as nullptr — the engine checks before calling.

🧱 Block Hooks

Example — react only to your own block

static void onBroken(const ModBlockEvent* ev) {
    if (ev->blockType == gGlowStoneId) {
        // spawn particles, drop a custom item, etc.
    }
}
// api->onBlockBroken = onBroken;

🧍 Player Hooks

Example — 50% damage shield

static void shieldDamage(ModDamageEvent* ev) {
    *ev->hp += ev->dmg * 0.5f;  // refund half the incoming damage
}
// api->onPlayerDamage = shieldDamage;

💬 Chat Hook

static bool filterChat(const char* user, const char* msg) {
    if (strstr(msg, "badword")) return false;  // swallow it
    return true;
}
// api->onChatMessage = filterChat;

🐾 NPC Hooks

🌦️ World Hooks

🏆 Progression Hooks

🌐 Multiplayer Hooks

🛡️ Project: Damage Shield Mod

Combines onPlayerDamage, getPlayerMana/setPlayerMana, and showTitle: while the player has mana, incoming damage is absorbed from mana instead of HP.

#include "ModLoader.h"

static ModAPI* gApi = nullptr;

static void onDamage(ModDamageEvent* ev) {
    float mana = gApi->getPlayerMana();
    if (mana <= 0.f) return;  // no mana left — full damage applies

    float absorbed = std::min(mana, ev->dmg);
    gApi->setPlayerMana(mana - absorbed);
    *ev->hp += absorbed;  // refund the absorbed portion

    if (absorbed > 0.f)
        gApi->showTitle("Shield Absorbed", "", 0.6f);
}

extern "C" void mod_init(ModAPI* api) {
    gApi = api;
    api->modName    = "Mana Shield";
    api->modVersion = "1.0";
    api->onPlayerDamage = onDamage;
}

🐕 Project: Tameable Companion

Combines item registration, onItemUsed, spawnNPC/setNPCCompanion, and onNPCInteract — feed a wolf a custom treat item to tame it.

static uint16_t gTreatId = 0;
static const int KIND_WOLF = 7;  // example MobKind value

static void onNPCInteract(const ModNPCInteractEvent* ev) {
    if (ev->kind != KIND_WOLF || ev->button != 2) return;  // only on E-key
    if (gApi->getItemCount(gTreatId) > 0) {
        gApi->removeItem(gTreatId, 1);
        gApi->setNPCCompanion(ev->npcIndex, true);
        gApi->showTitle("Wolf Tamed!", "", 1.5f);
    }
}

💰 Project: Persistent Economy

Combines saveData/loadData, registerCommand, and onCraft — a per-save currency that's earned by crafting and spendable via a terminal command.

static int getGold() {
    const char* raw = gApi->loadData("gold");
    return raw ? atoi(raw) : 0;
}
static void setGold(int g) {
    char buf[16]; snprintf(buf, sizeof(buf), "%d", g);
    gApi->saveData("gold", buf);
}

static void onCraft(const ModCraftEvent* ev) {
    setGold(getGold() + ev->count);  // 1 gold per crafted item
}

static char* cmdBalance(const char*) {
    static char buf[32];
    snprintf(buf, sizeof(buf), "Gold: %d", getGold());
    return buf;
}

⚠️ Threading & Gotchas

• Struct layout drift is the #1 way mods break. ModAPI is a flat sequence of function pointers with no per-field versioning — only apiVersion at the top. If you vendor your own copy of the struct instead of including ModLoader.h directly, and your copy's field order, count, or types diverge even slightly from the engine's, every field after the divergence point silently reads as the wrong function pointer. This does not crash immediately — it corrupts behavior in ways that are hard to trace back to the cause. Always diff your vendored struct against the engine's include/ModLoader.h after any engine update, or just include the header directly.
• onChunkGenerate runs off the main thread. It's the only hook that does. Use getBlockGen/writeBlockGen there, never regular getBlock/setBlock, and never touch any other engine API from that hook — including your own mod's shared state without a lock, if onUpdate also touches it.
• onPlayerMove and onUpdate can fire very frequently. Keep these handlers allocation-free and branch-light; heavy work here is felt as frame stutter.
• NPC indices are not stable IDs. Re-validate before acting on a stored npcIndex across frames.
• Terminal command handlers must return stable pointers. Use static, heap, or literal storage — never a stack buffer.
• Mods share one process with the engine and each other. There's no sandboxing — a crash in your mod is a crash of the whole game, and two mods registering conflicting global state (e.g. the same save-data key) can interfere with each other.
• onChatMessage's return value matters. It's the only hook whose return value changes engine behavior — returning false swallows the message for every other mod and the player, not just yours.

🪟 Cross-Compiling for Windows

From Linux, using MinGW-w64

# Debian/Ubuntu
sudo apt install mingw-w64

x86_64-w64-mingw32-g++ -shared -fPIC -std=c++17 \
    -o mymod.dll mymod.cpp \
    -I/path/to/VoxelGame/include \
    -static-libgcc -static-libstdc++ \
    -Wl,--out-implib,mymod.lib

Native Windows — MSVC

cl.exe /std:c++17 /LD /EHsc ^
    /I"C:\VoxelGame\include" ^
    mymod.cpp ^
    /Fe:mymod.dll

Native Windows — MSYS2/MinGW

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

See the reference Modding Guide for the full ModAPI field table, permissions/roles, F3 admin console, portals, and world-gen documentation not covered in this tutorial.