vvar(3)

A modern C++17 port of the Quake III Arena cvar and command system, extracted as a lightweight, header-friendly library. If you know what a cvar is, you know what this does.

Components

veCVar: Console variables with full flag support (archive, latch, ROM, cheat-protected, userinfo/serverinfo/systeminfo propagation, range validation).
veCmd: Command buffer with tokenisation, deferred execution (wait), glob filtering, and tab-completion hooks.
veIVar: Key/value info strings with Q3-style \key\value serialization/parsing helpers.

Default commands wired up via veCmd_InitDefaultFunctions(): alias, exec, set, seta, setu, sets, reset, toggle, print, cvarlist, cvar_modified, cvar_restart, echo, wait, cmdlist.

Requirements & Build

C++17
CMake 3.20+
Ninja and clang-cl are supported.

cmake -B build
cmake --build build
ctest --test-dir build

The header provides default dinfo(...), derr(...), and derr_fatal(...) fallbacks that write to stderr and abort on fatal errors. To override logging, define these macros before including vvar.h, or define VVAR_NO_DEFAULT_LOGGING.

Usage

Include vvar_impl.h in exactly one translation unit. Include vvar.h everywhere else.

Register and use a cvar

// Register (creates if absent, ORs flags if already exists)
veCVar* r_fullscreen = veCVar::get("r_fullscreen", "1", VE_CVAR_ARCHIVE);

// Read
int fs = veCVar::variableIntegerValue("r_fullscreen");

// Write
veCVar::set("r_fullscreen", "0");

Lazy cvar refs

veCVarRef resolves on first use and caches the pointer after that. Call veCVar::init() before first dereference.

veCVarRef r_mode("r_mode", "3", VE_CVAR_ARCHIVE | VE_CVAR_LATCH);
int mode = r_mode->getInteger();

Register and dispatch commands

veCmd_InitDefaultFunctions(); // wire up built-ins

veGetCmd().addCommand("quit", []() {
    // handle quit
});

veGetCmd().executeString("set r_fullscreen 0; quit");
veGetCmd().execute(VE_CMD_EXEC_NOW);

Latched cvars

Changes are staged and applied the next time veCVar::get() is called for that variable. Useful for settings that require a restart to take effect.

veCVar* vid_restart = veCVar::get("r_mode", "3", VE_CVAR_LATCH | VE_CVAR_ARCHIVE);

Info strings

veIVar::fromString("userinfo", "\\name\\Player\\rate\\25000");
const char* info = veIVar::toString("userinfo");

Cvar Flags

Flag	Description
VE_CVAR_ARCHIVE	Saved to config on writeVariables
VE_CVAR_LATCH	Change takes effect on next get() call
VE_CVAR_ROM	Display only, not user-settable
VE_CVAR_INIT	Set from command line only
VE_CVAR_CHEAT	Locked when cheats are disabled
VE_CVAR_PROTECTED	Cannot be set from VMs or remote
VE_CVAR_USERINFO	Sent to server on connect/change
VE_CVAR_SERVERINFO	Sent in response to frontend requests
VE_CVAR_SYSTEMINFO	Replicated to all clients
VE_CVAR_ALLOW_SET_INTEGER	Allows explicit getInteger() writes to be synced back to string form

Notes

reset respects normal cvar protections and latch behaviour; forceReset bypasses them.
veq3_va() uses a thread-local ring buffer, making it safe across threads while supporting a small amount of nesting.