C++ Module SDK

Native server modules are optional C++ extensions: .dll (Windows) / .so (POSIX) dropped into modulesDir. The host loads them through the versioned varion_module.h C ABI, optionally ticks them each server frame, and unloads them on shutdown.

Use native modules only for functionality that truly needs C++. Regular gameplay should live in C#, JavaScript or Go resources.

Runtime config

modulesDir = "modules"
modules = []

modulesDir (default modules) is the folder modules are loaded from. The loader loads EVERY .dll (Windows) / .so (POSIX) in that folder. The modules key in server.toml is parsed but the loader does NOT use it as a filter — everything in modulesDir is loaded.

Modules load last — after every subsystem and the network are already up — so varion_module_init can call the host API immediately.

ABI

Versioning is mandatory: VARION_MODULE_ABI_VERSION (currently 1). The host rejects any module whose varion_module_abi() does not match the host version.

Exported entry points (resolved by name):

Symbol	Required	Purpose
varion_module_abi	required	uint32_t — the ABI the module was built against
varion_module_init	required	int(const VarionModuleApi*) — return non-zero for success (0 → module rejected and unloaded)
varion_module_name	optional	const char* — name (logged)
varion_module_version	optional	const char* — version (logged)
varion_module_tick	optional	called each server tick
varion_module_shutdown	optional	called once before unload

Host API table

varion_module_init receives a pointer to VarionModuleApi — the host function table. The first argument of every function is host (the opaque context from the table):

• log / logWarn / logError — logging
• getServerTimeMs / getPlayerCount / getTickCount — read-only server state
• callApi(host, fn, argsJson) — call the host API by the same names and JSON args as the JS host, e.g. callApi(host, "world.setTime", "[13,37]"). Requires a running JS host (>=1 js resource).

Every table function may be called ONLY from varion_module_init / varion_module_tick / varion_module_shutdown (the server main thread).

Minimal module

#include "varion_module.h"

VARION_MODULE_EXPORT uint32_t VARION_MODULE_CALL varion_module_abi(void) {
    return VARION_MODULE_ABI_VERSION;
}
VARION_MODULE_EXPORT const char* VARION_MODULE_CALL varion_module_name(void) {
    return "my-native-module";
}

static const VarionModuleApi* g_api = 0;

VARION_MODULE_EXPORT int VARION_MODULE_CALL varion_module_init(const VarionModuleApi* api) {
    g_api = api;
    api->log(api->host, "my-native-module up");
    return 1;
}
VARION_MODULE_EXPORT void VARION_MODULE_CALL varion_module_shutdown(void) {}

Boundary

C++ modules are a server-side extension point. The public runtime does not ship a client module SDK and does not require developers to touch protected client internals.

Source Backing

This page is derived from server/src/CModuleLoader.h, server/src/CModuleLoader.cpp, the ABI header varion_module.h (server/sdk/varion_module.h), config parsing in server/src/CServerConfig.cpp, and the load sequence in server/src/CServer.cpp.