Modding

This page discusses the basics of modding. For information about using game mods, see Mod

Modding (using 'mods', short for modification) in Victoria 3 provides players with the ability to alter various aspects of the game or incorporate new features, enhancing the overall gaming experience. While certain elements remain hardcoded and cannot be modified, such as the Migration or Battle casualty logic or map modes, a wide range of options are available for customization.

Mods do not disable achievements in Victoria 3, as the game has a separate rule governing this aspect.

Getting started

Setting up the mod folder

Main article: Mod structure

• Create a new folder in Documents\Paradox Interactive\Victoria 3\mod, this new folder corresponds with the game folder in the base game.
  • Don't directly modify the game files, they will be overwritten with any game update.
• In the new folder, create your "common", "localization", etc. folders of your mod as needed.
  • Follow the same structure as found in Victoria 3\game folder.
• Place .txt and other files for the actual content inside the appropriate folder.
• Add a .metadata folder with a metadata.json file inside. The file may be bare bones, but is a requirement in order for the game to load your mod at all.
• Manually add your mod folder in the launcher with "Add more mods" in the playset.

Alternatively, use the Victoria 3 Mod Template from GitHub to set up the basic structure.

Basic tools and resources

File editors

• Utilize a source code editor with syntax highlighting and other helpful features, such as Code Search. Popular free programs for modding Victoria 3 include:
  • Sublime Text has the best supported plugin: Victoria 3 Tools
  • Visual Studio Code has the extension Paradox Highlight and CwTools(supports autocompletion, error checking, tooltips and more) available.
  • IntelliJ (The Community Edition is free) has the extension Paradox Language Support available.
  • Notepad++ is a less powerful choice, but may feel less overwhelming.
    • Select Perl as your language syntax for some syntax highlighting since there are no specific plugins for Victoria 3.

Debug mode

• Use debug mode in order to access hidden developer information and tools in game.
• This can be done by launching in debug mode from the launcher by going to "Game settings" on the left sidebar and scrolling to the bottom
• Alternatively, add the following launch option in Steam by right clicking on Victoria 3 in the game library, select Properties in the pop up, then at the bottom of the General tab add -debug_mode
  • This debug mode when launching from the main play button
• Debug mode also makes the game hotload most game files, letting you test changes more quickly without requiring relaunching the game.
  • A few folder/files are not covered, such as on_actions; others might require returning to the main menu and starting a new session.
• Alternatively, there are also mods that allow activating and deactivating debug mode in-game, though they don't have the file hotloading functionality.

Documentation

• Use script_docs and DumpDataTypes commands in the game console to generate other logs with event effects, triggers and scopes.
  • Access the console in-game with ^ when debug_mode is active.
  • Generated files are located in Documents\Paradox Interactive\Victoria 3\docs
  • This is the most reliable technical documentation you can get.
• Most of the documentation is also available on this wiki: see Effect, Trigger, Event target, and Data types for the main examples and see the navigation box at the bottom of this page for more documentation pages.
• The Modding Git Guide is a community made guide for using Git, GitHub/GitLab, and related tools such as KDiff3. It can be a useful stop for questions beyond this wiki, and contains step by step guides for much of what is talked about here. Though the examples are HOI4 based, the principles apply equally well to any Paradox game mod.

Best practices

• Use proper, tabbed indentation to ensure opening and closing brackets are on the same level. This allows for code folding, easier error spotting, and improved readability.
  • Consider using an automatic formatting extension for your editor.
• When uncertain about implementation, search the base game code for relevant keywords using your editor.
• Use comments, which always start with #, to document your script, to navigate easier, or to disable parts of code without deleting them.
• Avoid overwriting items you don't want to change to minimize conflicts and enhance clarity.

Priority of modded files

Main article: Mod files load order

• Using a filename that exists in vanilla will overwrite the original file completely.
  • If several files with the same name are used by different mods, the lowest modlist position in the launcher is relevant.
• If an item is modified by several mods, the game will choose from the file sorted last ASCII-wise by filename.
  • This takes priority over the position in the modlist in the launcher.

Debugging

• Read the error.log to find exceptions and warnings the game identified in Documents/Paradox Interactive/Victoria 3/logs
• Debug mode adds a button that opens the error.log for you and also shows its current number of errors since last open.
  • The default editor used for this in Windows is Notepad, but it is configurable.
  • You can either edit Documents/Paradox Interactive/Victoria 3/pdx_settings.json directly, adding the following keys under the System key:
    • "editor": "C:\\Program Files\\Sublime Text\\sublime_text.exe" - tells the game which editor to use, you can use any valid editor on your computer, just make sure to use the correct path.
    • "editor_postfix": ":$:1" - this is used when opening the editor, for example this Sublime Text specific postfix makes sure the editor is opened scrolled to the latest line.
  • Or you can use the ingame settings editor accessible through the in-game console, under the Settings button. Choose System in the Category selector and find the Editor key.

• Backup your work, things can go wrong and it is always good to have a backup.
  • Using a version control system like Git allows you to track your changes, revert to a working version and collaborate.
  • If you are part of a team, consider using GitHub for team collaboration. If you are new to Git, a program like Github Desktop is great for beginners.

• Set encoding to UTF-8 with BOM inside your editor for code files, especially for localization .yml files.
• For localization files, make sure your filenames end with l_language like foo_l_english.yml. Note the first character in the suffix is an ell (lowercase L), not the numeral 1 or uppercase i.
• Join the official discord and modding discord to ask other modders for help.

Overwriting game objects in 1.12

Version 1.12 brings a new method of overwriting and changing defined game objects. Mods that do not adopt these changes are likely to cause unexpected behavior.

Keywords

• INJECT – This mode tries to inject the script into an existing entry; the injected script is added to the end of the object. Errors if the respective entry does not exist.
• REPLACE – This mode replaces an existing entry with a new one. Errors if the respective entry does not exist
• TRY_INJECT – Same as INJECT but does not error if the entry does not exist
• TRY_REPLACE – Same as REPLACE but does not error if the entry does not exist
• REPLACE_OR_CREATE – Same as REPLACE but if the entry does not exist, it will create it
• INJECT_OR_CREATE – Same as INJECT but if the entry does not exist, it will create it

Behavior

REPLACE keywords overwrite the specified object as expected, replacing any previous definition with the new one. Note that this still occurs in the usual loading order, so if multiple mods are trying to replace an object entry, the last one loaded "wins".

INJECT keywords add the specified blocks to the object without changing any previous definition. Certain types of blocks cannot be injected this way if that type of block is already defined. Namely, most trigger and effect blocks. For example, trying to inject an is_visible block into a law fails if that law already has a defined is_visible block; however, if the law does not have a defined is_visible block, injecting a new one works as expected. Note that INJECT does not work for scripted effects and scripted triggers. Using INJECT for either of these will result in the original effect/trigger getting overwritten.

When injecting blocks that can be defined multiple times, INJECT keywords append their content to the end of the object's definition. For example, given a base game strategy such as:

ai_strategy_default = {
    #... some code
    wargoal_scores = {
        a = {
            # some score calc
        }
        b = {
            # some score calc
        }
        c = {
            # some score calc
        }
    }
    #... some code
}

Injecting the following from a mod:

INJECT:ai_strategy_default = {
    wargoal_scores = {
        d = {
            # some score calc
        }
    }
}

Effectively results in the following:

ai_strategy_default = {
    #... some code
    wargoal_scores = {
        a = {
            # some score calc
        }
        b = {
            # some score calc
        }
        c = {
            # some score calc
        }
    }
    #... some code
    wargoal_scores = {
        d = {
            # some score calc
        }
    }
}

This can result in unexpected behavior if the injected blocks and the previously defined blocks try to refer to the same elements. If the injected block referred to a for example, it might overwrite the base game calculation or not be read.

Types

Please add or remove folders from this list if you know of any undocumented differences

These files/types in the following folders – and only the following folders – support the new overwrite/extension functions.

• common/acceptance_statuses
• common/achievements
• common/ai_strategies
• common/alert_groups
• common/alert_types
• common/amendments
• common/battle_conditions
• common/building_groups
• common/buildings
• common/buy_packages
• common/character_interactions
• common/character_templates
• common/character_traits
• common/cohesion_levels
• common/combat_unit_experience_levels
• common/combat_unit_groups
• common/combat_unit_types
• common/commander_orders
• common/commander_ranks
• common/company_charter_types
• common/company_types
• common/country_creation
• common/country_definitions
• common/country_formation
• common/country_ranks
• common/country_types
• common/culture_graphics
• common/cultures
• common/decisions
• common/decrees
• common/diplomatic_actions
• common/diplomatic_catalyst_categories
• common/diplomatic_catalysts
• common/diplomatic_plays
• common/discrimination_trait_groups
• common/discrimination_traits
• common/dna_data
• common/dynamic_company_names
• common/dynamic_country_map_colors
• common/dynamic_country_names
• common/dynamic_treaty_names
• common/ethnicities
• common/flag_definitions
• common/game_concepts
• common/genes
• common/geographic_regions
• common/goods
• common/government_types
• common/harvest_condition_types
• common/ideologies
• common/institutions
• common/interest_group_traits
• common/interest_groups
• common/journal_entries
• common/journal_entry_groups
• common/labels
• common/law_groups
• common/laws
• common/legitimacy_levels
• common/liberty_desire_levels
• common/military_formation_flags
• common/mobilization_option_groups
• common/mobilization_options
• common/modifier_type_definitions
• common/objective_subgoal_categories
• common/objective_subgoals
• common/objectives
• common/parties
• common/political_lobbies
• common/political_lobby_appeasement (factor)
• common/political_lobby_appeasement (reason)
• common/political_movement_categories
• common/political_movement_pop_support
• common/political_movements
• common/pop_needs
• common/pop_types
• common/power_bloc_coa_pieces
• common/power_bloc_identities
• common/power_bloc_map_textures
• common/power_bloc_names
• common/power_bloc_principle_groups
• common/power_bloc_principles
• common/prestige_goods
• common/production_method_groups
• common/production_methods
• common/proposal_types
• common/religions
• common/script_values
• common/scripted_buttons
• common/scripted_effects (REPLACE only)
• common/scripted_guis
• common/scripted_lists
• common/scripted_modifiers
• common/scripted_progress_bars
• common/scripted_rules (REPLACE only)
• common/scripted_triggers (REPLACE only)
• common/social_classes
• common/social_hierarchies
• common/state_traits
• common/strategic_regions
• common/subject_types
• common/technology
• common/terrain
• common/terrain_manipulators
• common/themes
• common/treaty_articles
• common/tutorial_lesson_chains
• common/tutorial_lessons
• common/war_goal_types
• gfx/map/army_dioramas
• gfx/map/city_data/city_building_vfx
• gfx/map/fleet_dioramas
• gfx/map/fleet_entities
• gfx/map/front_entities
• gfx/portraits/accessories
• gfx/portraits/portrait_modifiers
• gui_animations
• modifier_icons
• music
• notifications
• sound/persistent_objects

Files/types in other folders have not changed their overwriting behavior and do not support this new replace/inject format.

Modding articles

• Country modding
• Event modding
• Journal modding
• Modifier modding
• Flag modding
• Model modding
• Goods modding
• Building modding

Tools and utilities

Name	Category	Link(s)	Description
Paradox Highlight	Editor (VS Code)	VS Code Marketplace	Up-to-date syntax highlighting for all Victoria 3 files. Other paradox games like Crusader Kings III are also supported.
CWTools - Paradox Language Services	Editor (VS Code)	VS Code Marketplace	For editing Paradox game files in Visual Studio Code. It has syntax-highlighting, error checking, auto-completion and more. Based on the Cwtools library for parsing, editing, and validating Paradox Interactive script files.
Victoria 3 Tools	Editor (Sublime Text)	GitHub	Victoria 3 Syntax for Sublime Text 4
Paradox Language Support	Editor (IntelliJ)	JETBRAINS Marketplace	The Intellij IDEA plugin for Paradox Interactive game modding. It has syntax-highlighting, error checking, auto-completion and more.
Victoria 3 Modding Support	Editor (IntelliJ)	JETBRAINS Marketplace	Adds support for the Victoria 3 definition and modding files. It has syntax-highlighting.
Tiger Mod Validator	General	GitHub	Tiger pounces on bugs. Checks Crusader Kings 3, Victoria 3, or Imperator: Rome user mod files for mistakes and warns about them. For example: missing localizations, or using a faith trigger on a character.
Tiger Mod Validator for VSCode	Editor (VSCode)	VS Code Marketplace	An extension for VS Code that integrates Tiger logs with Problems tab and allows to see issues directly in the IDE.
Tiger Mod Validator Github Action	General	GitHub	A base repo and guide on how to setup ck3-tiger as a GitHub workflow action.
Pdx-Unlimiter	General	GitHub	A powerful and smart savegame manager; it can edit save files and it can preview modded flags without starting the game.
Map data editor	General	GitHub	A mapdata editor to edit mapdata in common/history/states visually, it is helpful to edit the which provinces are which countries.
Vicky-Mapgen	General	GitHub	A Map Generator generates provinces by heightmap.png and boundaries.png
Music Mod Creation Tool	General	GitHub	As its name, it is for music mod, and now it supported Vic 3
UWPDumper	General	GitHub	A tool to extract files from Microsoft Store games.
Clausewitz Maya Exporter	General	Paradox Forums	A tool to create and export 3D models to use in vic3 and other Clausewitz games.
Jomini.js	General	GitHub	A powerful parsing library in javascript based on webassemby, has a C version named Rakaly.
Victoria 3 Mod Template	General	GitHub	A template to set up a GitHub repository for Victoria 3 mods.

Common problems

• Some local mod files fail to load.
  • Symptoms:
    • A mod is correctly shown up in the launcher, it is added to the playset, but some files do not have an effect.
    • error.log contains a line such as [virtualfilesystem.cpp:562]: Could not create lexer from file due to 'fopen() failed: 2' followed by a line about encoding.
    • Potentially also problems with opening error.log by clicking on the error deer in game launched with the -debug_mode flag.
  • Likely causes:
    • Permissions. The game could have trouble accessing the mod files due to broken permissions.
    • File path containing non-ASCII characters. Victoria 3 has troubles with this (similarly to other games such as Hearts of Iron IV). In Windows, this can happen due to the user's username, and therefore the user folder containing Documents/Paradox Interactive/Victoria 3/, containing non-ASCII characters. You can easily check whether this is the case by looking at your filepath.
  • Solutions:
    • You can change the location of local mods by editing Steam/steamapps/common/Victoria 3/launcher/launcher-settings.json, at the line "gameDataPath": "%USER_DOCUMENTS%/Paradox Interactive/Victoria 3",.
    • For example, if you change that line to "gameDataPath": "C:/Paradox Interactive/Victoria 3",, then the local mod folder would be at C:/Paradox Interactive/Victoria 3/mod instead of its default location.

Game object reference

Dependency and Folder Structure

If you want to add a new game object, you will need to keep in mind which more fundamental objects it depends on, and how to organize the files so the game recognizes it.

All paths are relative to the 'game' folder inside your Victoria 3 install directory, as that is where all scriptable parts of the game are located.

Note: objects with no dependencies may still reference primitive objects (numbers, strings etc) or core game concepts, but no object type that mods can edit or define, only change the parameter value of. Nested references, especially within modifiers, are generally also not counted, since modifiers can have arbitrary dependency relations.

Object type	Path	Dependencies
Professions	common/pop_types
Goods	common/goods
Needs	common/pop_needs	Trade goods, via 'default' Trade goods, via 'goods' inside 'entry'
Eras	common/technology/eras
Technologies	common/technology/technologies	Eras, via 'era' Technologies, via 'unlocking_technologies'
Institutions	common/institutions
Law groups	common/law_groups
Laws	common/laws	Institutions, via 'institution' Law groups, via group Laws, via 'disallowing_laws' Laws, via 'possible_political_movements'
Ideologies	common/ideologies	Law groups, as parameters Laws, via law group parameter mappings
Interest group traits	common/interest_group_traits
Interest groups	common/interest_groups	Interest group traits, via 'traits' Ideologies, via 'ideologies'
Production methods	common/production_methods	Technologies, via 'unlocking_technologies' Laws, via 'disallowing_laws' Production methods, via 'unlocking_production_methods'
Production method groups	common/production_method_groups	Production methods, via 'production_methods'
Building groups	common/building_groups	Building groups, via 'parent_group' Building, via 'default_building'
Buildings	common/buildings	Building groups, via 'building_group' Technology, via 'unlocking_technologies' Production method groups, via 'production_method_groups'

Parameters

When creating a scripted object, there are a number of required and optional elements. See the specific pages on each type of scripted object for details

See also

Console commands

Guides

• Grester's Compendium
• State modding guide

References

Modding

Map	Map • States

Audio

Music • Sound