Docs
The V3X documentation
V3X is a native loader, a stable plain-C plugin API and an SDK. Plugins run inside the game's program, so they can change how the engine loads, uses memory, saves and fails, which script mods cannot.
Quick start
You need Windows x64, Python and Git Bash. The compiler is zig from pip, so no Visual Studio. The last line builds the template plugin and tests it offline against the real victoria3.exe.
cd "<Steam>/steamapps/common/Victoria 3"
git clone --recursive https://github.com/kleeedolinux/v3x.git && cd v3x
pip install ziglang && ./build.sh install # loader + bundled plugins into ../binaries
python sdk/build_plugin.py templates/plugin_template --test ../binaries/victoria3.exeWalkthrough, about 10 minutes: Getting started. Read the safety rules before you change game state.
For players
Installing, settings, what each plugin does, and what to do when something goes wrong. The plain-language version is the players' guide.
| Document | What it covers | File dated |
|---|---|---|
| Players' guide | Install, the V3X button, plugins on and off, troubleshooting, in plain words. Also in português. | site |
| Installing V3X (players) | V3X-Setup.exe: download, install, what it changes, repair, uninstall. | 2026-11-13 |
| FAQ | Common questions, from multiplayer to which compilers work. | 2026-11-13 |
| Troubleshooting | Save the evidence, read v3x.log and crash.log, hangs, build problems. | 2026-11-13 |
| Configuration reference | v3x.ini and every plugin's ini keys with their defaults. | 2026-11-13 |
| Plugin catalog | The catalog: every bundled plugin, its class, default, test and history. | 2026-11-13 |
For modders
Writing a plugin: from the 10-minute first build to the full API, the rules that keep the game alive, script files from C, and testing without the game.
| Document | What it covers | File dated |
|---|---|---|
| Getting started: install V3X and write your first plugin in 10 minutes | Install the loader, build the template plugin and run it, in about 10 minutes. | 2026-11-13 |
| Plugin template | The minimal plugin that follows every safety rule, with its source and offline test. | 2026-11-13 |
API reference (include/v3x.h, API v5, loader 0.5.0) | Every field of V3X_API, thread rules, the manifest, events, return codes. | 2026-11-13 |
| API stability contract | What a plugin can rely on when V3X, the game, or both are updated. | 2026-11-13 |
| include/v3x.h | The API header itself: plain C, versioned, append-only. | 2026-11-13 |
| Safety rules | The rules that keep the game alive. Each one was learned from a crash. | 2026-11-13 |
| Extending game script from a V3X plugin | Ship game script, localization and GUI files from a native plugin. | 2026-11-13 |
| Building and testing | Build, repository layout, the offline SDK testkit and end-to-end tests. | 2026-11-13 |
| Console commands and events | Every V3X console command and the events between plugins. | 2026-11-13 |
Engine notes
What has been learned about the Victoria 3 engine, how it was found, and a measured play session.
| Document | What it covers | File dated |
|---|---|---|
| Reverse-engineering guide | The RE workflow: strings, xrefs, functions, profiles, anchors, offline checks. | 2026-11-13 |
| Engine map (Victoria 3 1.15.1) | What is known about the engine: tick, threads, memory, rendering, saves, VFS. | 2026-11-13 |
| Session 2026-11-13 evening (16:26-18:10): what the player felt, what changed, what to flip | A measured 1 h 44 m play session: what the player felt and what to flip. | 2026-11-13 |
| Maturity assessment | How mature V3X is as a platform, area by area, with the evidence for each score. | 2026-11-13 |
process_exit, and which thread runs which callback. Diagram from the V3X repository.
victoria3.exe loads binaries/version.dll, which forwards the 17 real functions to System32 and starts the V3X core before the game's own startup code. Diagram from the V3X repository.