| name | vic3-modding |
| description | Victoria 3 modding assistant covering buildings, production methods, goods, pops, laws, interest groups, journal entries, events, decisions, diplomatic plays, power blocs, companies, technology, localization, GUI, mod setup, validation, and debugging. Use this skill whenever the user mentions Victoria 3 or Vic3, or works on files under a Victoria 3 mod's common/, events/, localization/, gui/, or map_data/ folders, including .metadata/metadata.json, script_docs dumps, error.log problems, on_actions, or _l_english.yml localization. Also use it for questions like "why does my mod do nothing", "how do I override X", or "set up a new Victoria 3 mod" when the context is Victoria 3 game files. For Crusader Kings III use the ck3-modding skill instead: the two games differ in descriptor format, folder names, encoding rules, and script vocabulary, so CK3 habits produce silently broken Victoria 3 mods. |
| allowed-tools | Bash(python ${CLAUDE_SKILL_DIR}/scripts/vic3_docs.py *) |
Victoria 3 Modding
Victoria 3 mods are Paradox (Jomini) script: .txt databases under common/ and events/,
.yml localization, and PdxGui .gui files. The default failure mode is silent. A wrong
encoding, a folder typo, or an unbalanced brace makes the game ignore the file with no error.
Victoria 3 documents itself better than most Paradox games. Three first-party sources cover
almost every factual question, so answer from them rather than from memory.
Step 0: resolve this machine's paths
Detect these once per session. Ask the user only when detection fails. Everywhere below,
<game>, <docs>, <logs>, <mods> and <tiger> mean these.
| Placeholder | What | Typical location |
|---|
<game> | Base game data, the primary source of truth | <steam library>\steamapps\common\Victoria 3\game. Default library C:\Program Files (x86)\Steam; others are listed in <steam>\steamapps\libraryfolders.vdf. Linux: ~/.local/share/Steam/... |
<docs> | script_docs dumps | <user documents>\Paradox Interactive\Victoria 3\docs. Not the logs folder. Documents is often redirected to another drive or OneDrive, so resolve it rather than assuming C:. |
<logs> | error.log, database_conflicts.log, data_types/ | <user documents>\Paradox Interactive\Victoria 3\logs |
<mods> | Where mods are developed | <user documents>\Paradox Interactive\Victoria 3\mod |
<tiger> | vic3-tiger validator executable | Wherever the user installed it. Releases at github.com/amtep/tiger |
Confirm the build before trusting any version-specific claim:
python ${CLAUDE_SKILL_DIR}/scripts/vic3_docs.py stats
That prints the resolved paths, the build number, folder and schema-doc counts, how many
identifiers each dump holds, and how stale the dumps are. Run it at the start of a session.
The three sources of truth
1. The 91 *.md schema docs shipped inside <game>. These are Paradox's own annotated
schemas, the Victoria 3 equivalent of CK3's _*.info files, and they sit inside the folder they
document (common/buildings/buildings.md, common/journal_entries/journal_entries.md). They
give the legal keys of a definition, each key's type, its default, and often the scope it runs
in. Read the doc before scripting a system. Their filenames follow no single rule, so find them
with:
python ${CLAUDE_SKILL_DIR}/scripts/vic3_docs.py folders <folder-name-fragment>
Only 75 of the 135 common/ subfolders ship one, and events/ ships none. Notably decisions,
interest_groups, scripted_effects, state_traits and subject_types are undocumented, so
for those a vanilla .txt in the folder is the reference. decisions is a special case: it has
no .md but does ship common/decisions/000_decisions_help.txt.
Where a doc and a vanilla file disagree, the vanilla file wins. These docs do contain errors:
buildings.md documents a construction_points field that live building files replace with
required_construction.
2. The script_docs dumps in <docs>. Roughly 12,800 identifiers: every effect, trigger,
modifier, event target, on_action and custom localization key the installed build knows, with
its supported scopes. This is the vocabulary. Never invent an effect or trigger name; check it:
python ${CLAUDE_SKILL_DIR}/scripts/vic3_docs.py find add_modifier
python ${CLAUDE_SKILL_DIR}/scripts/vic3_docs.py find -s power_bloc
find exits non-zero when an identifier does not exist, which makes it a usable gate. The six
dump files use four different internal formats, so a plain grep across them returns wrong or
empty answers. Use the script.
If <docs> is missing or stale, ask the user to launch with -debug_mode and run script_docs
and dump_data_types in the console, then read the files yourself.
3. Vanilla files. Copy a working vanilla definition and modify it. This is faster and safer
than writing from scratch, and it is the only reference for the 62 undocumented folders.
Golden rules
- Copy a working vanilla example and edit it. Do not write script from a blank file.
- Verify every effect, trigger and modifier name with
vic3_docs.py find before writing it.
Inventing a plausible identifier is the single most common and most expensive failure.
- Encoding: UTF-8 with BOM for both script
.txt and localization .yml. Every vanilla
file of both kinds ships a BOM (byte-checked on 1.13.10), so match vanilla. CK3 habits are
wrong here: CK3 script files carry no BOM.
- A mod is identified by
.metadata/metadata.json. Victoria 3 does not use CK3's
descriptor.mod.
- The on_action folder is
common/on_actions/, plural. CK3's is singular.
- Never redefine a vanilla on_action's contents. Append your own:
on_monthly_pulse_country = { on_actions = { my_mod_pulse } }. This is the top compatibility bug.
- Event ids are
namespace.number and their localization keys use dots:
my_events.1.t, .d, .f, .a. The file needs a namespace = my_events header line.
- Localization lives flat in
localization/english/, filename ends _l_english.yml, first line
is l_english:. Keys may live in any file, so filename does not bind to namespace. Add a key
for every new name, or the raw key shows in-game.
- Victoria 3 has no flags.
set_country_flag and friends do not exist. Use set_variable,
has_variable, and save_scope_as. Ported CK3 flag logic silently does nothing.
- Mod folder layout mirrors
<game> exactly. A folder-name typo means the file is ignored
with no error. No non-ASCII characters anywhere in a mod's file paths: the game cannot load
those mods at all.
- Override direction is inverted between script and GUI. Files load in ASCII order and for
script the last one loaded wins, but a GUI type or template cannot be overwritten once
loaded, so for GUI the first wins. A CK3 modder's instinct is wrong here.
- Prefer
REPLACE:my_object = { ... } or INJECT:my_object = { ... } over copying a whole
vanilla file. These key prefixes patch one object and leave the rest of the file alone.
Victoria 3 has them and CK3 does not.
Workflow
- Identify the system the task touches, then read the matching reference file below.
- Read that system's schema doc (
vic3_docs.py folders <name>) and open a vanilla example.
- Verify every identifier you intend to write with
vic3_docs.py find.
- Write a new file carrying the mod's prefix, in the correct folder, UTF-8 with BOM.
- Add localization for every new key.
- Run vic3-tiger. Fix Fatal and Error, then Warning.
- Ask the user to test in-game, then read
<logs>\error.log yourself. Do not ask them what it says.
Routing table
| Task involves | Read |
|---|
Mod setup, .metadata/metadata.json, folder layout, load order, override and conflict rules, encoding | references/setup.md |
Script syntax, scopes, triggers vs effects, iteration, variables, scripted effects/triggers/values, prefixes like c: and law_type: | references/language.md |
| Buildings, production methods, goods, pops, technology, companies, trade | references/economy.md |
| Events, on_actions, journal entries, decisions | references/content.md |
| Laws, law groups, interest groups, political movements, diplomacy, power blocs, subject types | references/politics.md |
| Writing localization, formatting markers, data functions, customizable and trigger localization | references/localization.md |
Custom UI, .gui files, scripted widgets, scripted GUIs, buttons, progress bars | references/gui.md |
| Running vic3-tiger, reading logs, the console, debugging a mod that does nothing | references/validation.md |
Read more than one when the task spans systems. Most content work also needs localization.
Silent-failure checklist
When the user says "it does nothing", work through: missing BOM on a .txt or .yml file ·
folder name typo · on_action written singular instead of on_actions · unbalanced braces, which
abort the rest of the file · an effect used in a trigger block or the reverse · an identifier that
does not exist in this build (vic3_docs.py find settles it) · missing localization key · event
loc keys written with underscores instead of dots · missing namespace header · a vanilla
on_action overwritten instead of appended to · descriptor.mod used instead of
.metadata/metadata.json · a GUI override that lost because GUI is first-wins · a non-ASCII
character somewhere in the mod's path · a modifier that turned out to be a "potential dynamic"
key with no display name, which the engine accepts and then ignores. Then run vic3-tiger, read
<logs>\error.log, and check <logs>\database_conflicts.log to see which file won each override.
