Hi folks! I'm Mike, one of the Game Designers who specializes in content for V3, and today we're going to talk about the delights of modding.
Modding is a whole world of things in Paradox games. Some mods are total overhauls, some are just simple little tweaks. I've seen sweet little mods that just add a person's pet as a graphic, or even one that I spotted on Hearts of Iron's workshop page as I wrote this that added in a dearly-departed office cat as a replacement for Joseph Stalin. There's all sorts of mods out there! And, hopefully, by the time you've finished reading this dev diary, you'll know how to create the start of your own mod for Victoria 3, too.
Starting with the launcher
First thing's first: the way the innards of Victoria 3 operate is similar, but not exactly the same as, Crusader Kings 3 and Imperator, since they're all derived from the Jomini engine we also use. If you know how those games tick scripting-wise, you're 90% of the way to knowing how to make a V3 mod. If not, I will happily let Crusader Kings 3 explain a bit about how scripting in Jomini works.
If that stuff still leaves you a little baffled, don't worry about it! We're gonna walk through the basics of making a whole mod, from the first point of creation to actually running the darn thing.
So! Let's start from the top. When you fire up Victoria 3, you'll be greeted by the game's launcher. If you look in the upper-left of the launcher, you'll see four little options: Home, DLC, Mods, and Game settings. Click the Mods one. Go on. You know you want to.
From the Mods menu, you'll be greeted with three buttons. If you click "Mod tools" in the middle, you'll be greeted with a prompt to create a new mod if you haven't got any yet, otherwise you'll have to find the button on the menu and click it to bring up the Create new mod prompt.
Let's make something simple, shall we? How's about we make a country out of Ohio. Yeah, let's just make one country and make it show up in-game, that'll be a good test of all this stuff.
Slam that create button, and the launcher will create a new directory in your mod folder wherever your savegames and such are stored. In my case, and in most of your cases, that'll be in some place like
Found the directory? Good. Inside that directly, you're gonna find a folder named ".metadata", with a single file inside that, called "metadata.json". That folder and file is where all the data is stored that the launcher reads when checking out the mod, including the mod's name, version number if you wanna be fancy, and so forth. If you want to tinker with that stuff later, go on ahead, but we're not gonna touch it for this. Go back to the main directory, so that you're looking at "[...]\Paradox Interactive\Victoria 3\mod\It's Ohio!"
Mucking with files
Let's start defining Ohio. The key thing with how to set up a mod is that you have to essentially copy the paths used in the main game, so the game reads everything right. In V3, country definitions are stored at "Victoria 3\game\common\country_definitions", so in our "It's Ohio!" directory we're going to make a "common" folder, and then a "country_definitions" folder within that. This mimics the path of the base game (that "Victoria 3\game" bit), so when the game reads this mod and tries to figure out how it interacts with the base game, it doesn't scream and die.
Inside our mod's "common\country_definitions" folder, we're going to make a little file I've arbitrarily called "ohio.txt". Open it up, and we'll paste text like this bad boy into it:
Wow! We've defined Ohio. Now let's tinker with history files so Ohio appears in-game.
Country control of a state is defined in a couple history files, found in the following directories:
- common\history\buildings
- common\history\pops
- common\history\states
All three of these will need the base game files copied over- we sadly can't just add a new entry in a new file, because we also need to remove/replace the USA-related data in these as well. Make sure you duplicate these folder paths in the It's Ohio! mod folder, like you did with common\country_definitions.
Starting with the buildings directory, what we do is find "STATE_OHIO" among the buildings files- turns out it's in 05_north_america.txt. Copy that file and plop it into your mod's history\buildings folder, open it up there, then search for STATE_OHIO. You'll find a section that starts off with
and goes on from there. What's happening there is that we've declared that within the state region of Ohio (that is, "s:STATE_OHIO"), there should be a state controlled by the USA ("region_state:USA") that constitutes American Ohio. But we're making an independent Ohio, so all the data referring to American Ohio is useless and will confuse the game. All we're going to do is change that "region_state:USA={ " line to "region_state:OSU={ " so the same section now reads
Now, instead of telling the game that within the state region of Ohio we want to create a state controlled by the USA filled with the following buildings, we've told the game to create a state in Ohio that is just… Ohio, and that should be filled with the following buildings.
The same thing applies for common\history\pops. There's a 05_north_america.txt file we're gonna copy over, and we're going to find the STATE_OHIO entry, and change USA control to OSU.
State history is all saved in a single file, so in common\history\states\ you're just going to copy over the entire 00_states.txt file into your mod directory, and again crack open the file and search for STATE_OHIO. There, you'll find this entry:
A state is created out of provinces, which are all just x + whatever the hex code (a color expressed as six characters) for their province color is in the province map we used to create the whole map. In places like Ohio, there's only one state created per state region, but in places like Germany this section looks far more chaotic, as it is possible to create multiple states within a single state region. Don't think about Germany though, think about Ohio.
Hopefully you've picked up on the pattern of changes we've been doing- here again, we're just going to change that "country = c:USA" bit to "country = c:OSU", so that the whole STATE_OHIO section becomes
Exciting! I wonder what happens if we start up the game now?
Checking our work
First, we need to get the darn thing enabled in the launcher. Open up the launcher, add a new playset, and call it "ohio!" or the name of your choice.
The launcher's going to say that the playset looks empty, so click the "ADD MODS" button that appears, so you can add mods, and then add “It's Ohio!”
Make sure the playset is enabled, and then let's play the game and see what happens.
Hold on… something feels wrong here. Let's quit out of the game, right-click on Vicky 3 in Steam, open up properties, and change the launch settings by plugging in "-debug_mode".
This enables the error log to appear in game. Let's see what happens when we load up the game now.
We have errors! We'll open up the error log, which can be found at "...\Paradox Interactive\Victoria 3\logs\error.log", and let's take a look at the error messages. Any time you're working on a mod, I cannot emphasize enough how useful it is to run the game with debug mode on and do your best to resolve any issues reported in the error log.
Please read the error log and fix errors reported there. I'm not even talking to just potential V3 modders now. Please, I beg you… read the error logs and fix the errors reported there.
Anyways! In our case, there's four sources to these errors:
- By removing Ohio from the USA, we've reduced wine consumption enough that a scripted trade route that the USA starts with needs to be changed or removed. Easy enough, I'll copy the trade route history file over and remove that entry outright so I don't have to think about it anymore.
- I didn't localize the Ohio tag (OSU)! I'll get around to localization after fixing the next two items.
- I've completely forgotten to add country history, so Ohio's technological know-how hasn't been defined at all.
- Starting pop prosperity, located in a separate "populations" file, hasn't been defined for Ohio.
Country histories cover technology and politics. To make this easy on myself and avoid scripting everything from scratch, I'm going to copy the country history of Ohio's natural counterpart at vanilla game start: Belgium. All I'm going to do is get to "common\history\countries\bel - belgium.txt" in the base game, copy that file over to the same path in the mod, rename it to "osu - ohio.txt", and open it up real quick. Inside, the file has a whole section enclosed within "c:BEL". That section contains several effects that set the starting laws and ruling interest groups of the country. I'm just gonna change that c:BEL there to c:OSU, so all those effects regarding politics and technology now apply to our OSU tag, then I'm gonna save the file and close out there.
The other history file I need to add is a population file. The population file contains some scripted effects which distribute health and literacy rates among a country's starting pops. We're going to find the Belgian one at "common\history\population\bel - belgium.txt". Like with the country history stuff, we're going to rename our copy to "osu - ohio.txt" (as long as it's named anything other than an existing history file, it won't accidentally overwrite anything, but keeping the same naming convention in place is useful for organization), and inside that file change the scope from c:BEL to c:OSU so the effects of the population file actually apply to Ohioans.
Speaking of "Ohioans", let's get that localization sorted. Base game localization is stored at "Victoria 3\game\localization" and further divided into the various languages the game is available in. I'm an Anglophone, so I'm going to default to English for this stuff. We're going to recreate the whole English-language localization folder path in our mod (so "It's Ohio!\localization\english"), then we're going to create our own little loc file to throw in there- let's call it ohio_l_english.yml just to stick to the theme. Now, all we need to add in that file is
And now our country should have a name and an adjective!
Some of you folks with modding experience may have noticed that existing localization in our games tends to have a number after the colon in these localization entries (like 'FRA:0 "France" ', for example). Those numbers are just there to help us and our translators keep track of when entries are changed and require revised translations- they have no functional purpose beyond that, and if you're just modding in one language and don't intend to translate your mod with the same tools we use, there's no need for you to include that number bit after the colon.
With those errors hopefully fixed, let's start up V3 again.
Ladies and gentlemen, we have Ohio. It still doesn't have a scripted flag- you can read more about how those work and are scripted here - but it's a country that functions. You could select Ohio and play as Ohio now, if you wanted, or you could elaborate further, and start writing events and journal entries. You could script up individual characters, or replace all Yankee pops in Ohio with your own bespoke Ohioan culture where everyone has names like "Bud" and "Janet". Explore the game itself, and the insides that make it all work!
In our Dev Diary next week, Paul will be talking about Data Visualization!