Stellaris – A step-by-step guide to creating your first mod

Hi everybody,

after downloading Stellaris, I started it up and immediately created a new “Space Viking” empire, because everything is better with Vikings. The tutorial started and everything was fine, but something felt a bit off. That’s when I noticed, that my general was called “François”! “FRANCOIS”! By Odin’s beard, he was supposed to be a Space Viking, not a gourmet chef. And suddenly, I decided to actually do something about it, which is to say: create a mod.

As a software developer by day, I’m no stranger to some kind of code, but this really was the first mod I’ve ever actually created for any game, so I had to do a little research and some trial-and-error experimenting. Also, the modding system of Stellaris is really easy to use and no coding skills are required at all. Therefore, after I read a request on Reddit about “how to get started” with this whole Stellaris modding business, I thought… well, maybe I could help with a small step-by-step tutorial for people who are not familiar with coding or modding and who just don’t know how to actually start. Who knows? It might actually help someone.

So, here we go…


Tutorial goal and preface

With this little guide, we will follow the steps I had to take when creating the first version of the Ironborn Empire mod. Working through these steps, we will create…

  • a new species: The Space Vikings
  • a new names list for said species
  • a new pre-defined empire inhabited by said species/li>
  • a new description and start screen for the empire
  • a new government type with new titles for our rulers
  • a (very rudimentary) new flag icon


Target audience:

This list should also give a hint at the target audience for this post. This mini tutorial is for people who haven’t created mods yet, who may have no experience with coding (which is not necessary for this at all) and who – given the easy moddability of Stellaris – want to create something but just can’t figure out where to start.


General stuff



This tutorial was written with the game version 1.0.1 and the language set to English.

Also, we’ll edit some YAML, which are simple text files, but have to be encoded in a UTF-8 format. Consequently, you’ll need a text editor that can save your files as UTF-8 encoded text files. The standard Windows notepad can not do this. You can figure out a way how to change that or simply use a better text editor like Notepad++, Sublime Text 3 or something similar.



Before we start, there are some general resources for how to create a mod and sooner or later you might want to look at some of them:



Also you have to be aware of two locations that we use to a) reference what’s possible (i.e. already in the game) and b) create our new mod.

You’ll find the Stellaris installation folder (Steam) at

and the user data folder, where we’ll create our mod at
%HOMEPATH%∖Documents∖Paradox Interactive∖Stellaris


1. Step: Creating the mod

Ah, we’re finally going to get started. First of all, we will create the mod, i.e. the folder structure. But we don’t have to do it on our own – we simply use the mod tools from the Stellaris launcher.

  • Start Stellaris (the launcher opens)
  • In the launcher select the tab “Mods” on the right
  • You should then see a button named “Mod tools” in the upper right. Click it.
  • In the following mask, fill in a name for your mod, a folder name and feel free to choose some tags (see picture below)


Create a new mod


The “Supported version” field should already have the current version of your game. At the time of writing, the first patch was just released, so it’s 1.0.1.
After you’re satisfied with your very few initial settings, click the “Create Mod” button. The mod tolls will now create a .mod file and an empty folder in the user data folder that I mentioned above. If you want to check it, it should pretty much look like this:


Initial mod folder


The .mod file includes only some meta data about our mod and after uploading it to the Steam, it will also include the id of our mod in the Steam Workshop. There are a few settings that you can set manually, but for this tutorial, we won’t need that. If you want, you can read up a small description over at the CK2 Wiki.

Now, we are able to basically create altered versions of everything that’s in the game: Species, empires, governments, traits, ships, you name it. A lot of new modders also seem to directly change the actual game files in order to change some values (which of course gets reverted with every update). With this simple setup, we don’t need to do that anymore and can treat all the game files as “read only”.


2. Step: Creating the name list

To start off easy, we will create the new name list first. This is one of the easiest things to do and we can later attach it to our empire.

As said above, our mod can create nearly all types of things that are in the game. The game itself uses a certain folder structure to organize its data and if we want to add anything to it, we have to use the same folder structure in our mod. Since most of the data (including the name lists) is found in the commons folder, this will be our first one to recreate in our mod.


Stellaris folder structure


  • In our mod folder “ironborn”, create a new folder “common”
  • Within that common folder, create a new folder “name_lists”
  • Copy the file Stellaris∖common∖name_lists∖Human.txt from the Stellaris installation folder over to the folder “name_lists” in our mod directory
  • Rename the file to “name_list_spaceVikings.txt”

If you open up the copied text file, you’ll see a lot of names in there. They are organised in categories and sub-categories that are divided by curly brackets. Lines that start with a hash are only comments. Our first step is to clean this file and throw out everything, we don’t need. As you can see, the list is named “Human” – we’ll replace this with “SpaceVikings”. Then we’ll simply delete everything that’s in between two curly brackets that looks like a name. Don’t delete brackets or assignments like sequential_name = "%O% Frontier Outpost".

After that simply put in some names that you think would fit for a certain category. For example, since we’re creating f*ing Vikings, we might want to call our planets after the nine realms. For this, search the category “planet_names” and enter your names in the subcategory “generic” (or, since Niflheim is supposed to be a cold place, you may want to put it in the sub-category “pc_arctic”). You will notice that there are several lists for character names: “names1” to “names11”. At the moment we can safely delete all except the first – adding additional lists can be done later, of course.

At the end, your file might look a bit like this:


Caveats / Notes

  • The names are simply separated by spaces – if your name has more than one word, you have to put it in quotation marks.
  • “sequential_name” simple means that, if no name is given or we have run out of names, the game will provide a numbered name. In the example above, our outposts may be called “1. Frontier Outpost”, “2nd Frontier Outpost”, “3rd Frontier Outpost” and so on.
  • The “weight” value given in the names list decides how often the names occur. The Stellaris Wiki even provides a formula to calculate this, but in general: a list with higher “weight” is used more often


3. Step: Creating a name for the name list

At this moment, you are already able to start the game (with your mod activated in the launcher), create a new empire and use our new name list! Try it, it’s awesome! Unfortunately, it is still called “name_list_SpaceVikings”


We have our name list in the game!


To change this, we need to set up some text. In the Stellaris installation directory you will see a folder called “localisation” on the same level as “common” and in there are a lot of .yml files (simple text files with a YAML syntax) and a lot of text in them. Well, if it’s in the installation directory, we need this folder in our mod directory as well:

  • Create a folder named “localisation” in our mod folder “ironborn” (on the same level as “common” – not in common)
  • We’ll only provide English text, so copy the file “l_english.yml” over to our new “localisation” directory
  • Rename the file to “svi_l_english.yml” and open it

Search the file for “name_list_” and you’ll find the actual names for all the name lists in the game. There are always two entries for each list, so we need to create those two entries for our list as well. Since we want to start with a clean file for our new stuff, delete everything except the first line and add the following entries:

Done. After this, you can start the game and our name list will actually be called “Space Vikings” now.


Caveats / Notes

  • In the .yml file the name after “name_list_” has to be the same as your list definition at the start of the text file. In our example, you’ll see it in the second line, where it says “SpaceVikings = {“
  • The .yml files have to be saved with a UTF-8 encoding. Otherwise, Stellaris can’t serialize them!


4. Creating a predefined empire

At this point, further additions and adjustments basically come down to two (repeating) steps:

  • finding out where something is defined in the Stellaris installation folder
  • copy it to our mod folder and rewrite it

Therefore, for our next step, we have to know that the predefined empires you can select from the start, are defined in the folder “prescripted_countries”. Knowing this, we follow the same steps as before:

  • Create a folder named “prescripted_countries” in our mod folder “ironborn” (again on the same level as “common” – not in common)
  • Copy the file “00_prescripted_countries.txt” over to our new “localisation” directory
  • Rename the file to “ironborn_dominion.txt” and open it

In the file, delete everything except the first section named “humans1”. This will be our template. Of course, we aren’t humans anymore so we rename “humans1” to “ironborn”. This name will again used in other files as a point of reference, so be careful how you name it. We now can change all the data inside our “ironborn” section and adjust everything we want.



A lot of this configuration is easier done in the empire editor in the actual game. Fortunately, your creations will be stored in this simple text file: %HOMEPATH%∖Documents∖Paradox Interactive∖Stellaris∖user_empire_designs.txt. Just start Stellaris, create the empire that you like in the empire designer, save it and then copy the contents you need from “user_empire_designs.txt” to your new “ironborn_dominion.txt”.


At the end, I arrived at something like like this:

Voilà, you can now start up the game and actually see and select your empire on the bottom of your list. While the basics are there, our creation still seems a bit bland with that large black box where a description should be, but already we have a fully playable new empire with our own species (which is just a name) and an own name list. Huzzah!


Caveats / Notes

  • The entry flags = { space_vikings custom_start_screen } is needed in a later step and will be explained there.


5. Creating a description for the empire selection screen

Again, we want to write some texts. Fortunately for us, we already created a .yml file in our mod and we can simply use that to add further texts to the game. The only thing we have to figure out is how our new texts have to be named in the file. If we want to look at how it’s done for the original ten empires, we have to search the localisation folder of Stellaris again. Since there are so many different files it helps if you have some tool to search for text in a lot of files – I’m simply using grep on the “git bash” that came with git.

In this case we find the variables we need to look at in the file “prescripted_l_german.yml” (again, in the Stellaris localisation folder). For each empire we can see two variables there: One for the name and one for the description. Again, we have to create exactly those two variables, but for our own empire. That’s why we’ll add the following two lines to our “svi_l_english.yml”:


Caveats / Notes

  • Make sure the new lines are on the same indentation level as the “name_list_” entries and thus “in” the “l_english” list (that’s a YAML thing)
  • Again the name after “EMPIRE_DESIGN_” has to be the same as the one we used in our empire definition “ironborn_dominion.txt”


Our new Empire now has a description


6. Creating a start screen message

At this point, we have a description in the empire selection screen, but if you actually start the game, you will be met with a pretty blank black field where our funny little background story should be. This is where the “flags” entry in out “ironborn_dominion.txt” comes in that I mentioned earlier.

Again, our first step is to simply search for the current texts of the start screen and we’ll find them in our old friend “l_english.yml”, all starting with “START_SCREEN_”. For example, if you start with the United Nations of Earth, the start screen will display the text that you’ll find in the variable “START_SCREEN_UNE”. That’s what we need for our empire as well. Open up “svi_l_english.yml” in our mod folder and add the following line:

Unfortunately, that’s not enough. If you’d start a game with our new empire, the start there’s still be no text in the start screen. But, since we know the name of the text definitions (e.g. START_SCREEN_UNE), we can search the files in the “common” folder for that name and indeed, we’ll find it referenced in the file “00_start_screen_messages.txt” (of course, you’re able to find that file, because it’s in the folder “start_screen_messages”, which might give a hint that there are start screen messages to be found here. But I wanted to describe the process from seeing a text in the game to finding references in the localisation and common files).

We’ll continue with our usual two steps:

  • create a folder “start_screen_messages” in our common folder of our mod
  • copy “00_start_screen_messages” from the game to our newly created “start_screen_messages” folder and rename it to “start_screen_spaceVikings.txt”

To get a starting point, we can delete everything except the entry below the comment # United Nations of Earth. As we just created the localisation text called “START_SCREEN_SVI”, we put it in as value for “localization”. You will also notice the part inside “trigger”. This is used by the game to determine, which start screen text to display. If your empire definition (“ironborn.txt”) defines the flag that you can see in the start screen definition (“start_screen_spaceVikings.txt”), then it will display the text, that’s provided by the value set for localization. Since the respective line in “ironborn.txt” says: flags = { space_vikings custom_start_screen }, we put that name (i.e. “space_vikings”) as value behind “has_country_flag”).

In the end, your “start_screen_spaceVikings.txt” should look like this:

If you start a game with our Space Vikings now, there should be a start screen:


Our empire now has a start screen. HUZZAH!


Caveats / Notes

  • Make sure, your newly created folder “start_screen_messages” is not on the same level as but a subfolder of “common”
  • You will notice that our “ironborn.txt” defines a second “flag” called “custom_start_screen”. But if you took a closer look at the file “00_start_Screen_messages.txt” that we copied, you have seen that this flag is checked for all the default starting messages you get shown depending on your starting planet. In short: Having that flag in your empire definition prevents the game from using default start messages.


7. Creating our own government type

In this step, we’ll create a new government type. Most of it is just like before and in this case, we’re just using blatant copies of previously defined governments, but we will at least change the title of our ruler. This is very much connected, because – as I found out the hard way – you can’t simply change the title without creating a new government type.

If you have tried several government types when starting a game, you surely have noticed, that the title changes depending on what you have selected. In our example “ironborn.txt”, we set our government to military dictatorship ( government="military_dictatorship" ) and therefore, we’re correctly being addressed as “Grand Marshall”.


The title of our emperor's ruler is "Grand Marshall"


Of course, as Space Vikings, we should really have a better title and thanks to Skyrim, everybody knows what a “Jarl” is. From the previous steps, we know that we will find the definition of this text in the “localisation” folder, more specifically in “l_english.yml”:


Caveats / Notes

  • At this point, my first thought was to simply redefine that variable in our own language file “svi_l_english.yml” and assign a different value. Unfortunately, this does not work – nothing will happen. As far as I know, you can’t actually override existing values in our mod structure. You can only add to it.


So to actually do this, we have to create our own government. Well, nothing easier than that:

  • create a folder “governments” as a subfolder of “common” in our mod
  • copy the file “00_governments.txt” from the “governments” folder of the game to our newly created “governments” folder and rename it to “gov_spaceVikings.txt”

The the file, we have to search two entries that define the government types “military_republic” and “martial_demarchy”. We’re going to keep those two entries and delete the rest. The reason, we’re keeping the second one is, that it’s referenced in the first one as “upgrade”. As we want to add those two government types, we have to rename them. For our new empire, “military_dictatorship” will be called “space_vikings_government” whereas “martial_demarchy” is now “space_vikings_government_2” (yeah… it was late when I renamed that). Of course, we have to change the value of “upgrade” in the “space_vikings_government” section. Similarly, our empire definition (“ironborn.txt”) still says, we’re a military dictatorship, so make sure the value of “government” is changed there as well:

For comparison, the first entry of our “gov_spaceVikings.txt” should look like this now:

Now that we have created new governments (that work exactly like the ones we copied), we can now change wht the respective rulers are called. We can simply search for the use of “RT_GRAND_MARSHAL” and we’ll find the definitions of the government’s ruler title in the line ruler_title = RT_GRAND_MARSHAL. We already established that we can’t override it, so we change the value to “RT_JARL”. The second government actually has two of those entries – one for male, one for female. We’ll set those two values to “RT_KONUNG” and “RT_DROTTNING” respectively.

Now that we’ve told the government, which text it should use to display the ruler title, we have to add the actual text to our localisation file “svi_l_english.yml”:


Caveats / Notes

  • If you change the name of a variable or redefine it, make sure to look for references! In this case, we changed “martial_demarchy” to “space_vikings_government_2” in our copied file and so, we also had to change the value for “upgrade” in the other government definition and the value for “government” in our empire definition!

Our new governments are lacking title and description


This caveat is also the reason, why our new governments currently won’t have any title or description. The government itself is simply called “space_vikings_government” and “space_vikings_government_desc”. As you can see, the name of our new government is part of those names and the game searches its localisation files for those definitions. The definitions for the already existing governments can again found in “l_english.yml” – and indeed it’s worth to look in there again, because then you’ll find that there are actually three text definitions that are used for a government: “<name of the government definition>”, “<name of the government definition>_desc” and “<name of the government definition>_special”.

Knowing this we simply need to add those three definitions for our two governments to our localisation file “svi_l_english.yml” (remember – we defined two, because the second one is the upgrade for the first one):


Interim Conclusion: We created an empire!

We did it! We created our first mod!




If you start up Stellaris now, you can select a new predefined empire with a name list for a new species, a description, a start screen message and even a new government with special ruler titles. We’re ready to raid, pillage and plunder the galaxy!

If something’s not working, simply compare your files to mine:

Folder structure of our mod

This is how your mod folder should look like:


Your mod folder should look like this



If you want to compare the actual code, you can find it over here:


8. The cream topping: Adding a new flag symbol



Let me start out by saying that I don’t know anything about graphics. Let me then say, that we can add a new flag symbol anyway! But we need a bit of help. Stellaris uses a .dds format for its graphics and we need to be able to work with that. Fortunately, NVIDIA released some tools to do exactly that. Both are simple .exe files that don’t need any installation:

We also need a some kind of graphic that we want to use as a symbol. I simply used the google image search, asked for a “Viking raven symbol” and found one that looked like the one from CK2. Note: You need to get this graphic to have a transparent background – not white. Transparent! I won’t explain how to do that. There are a lot of guides out there that will explain this a lot better than I ever could. I don’t know jack, but even I was able to do that using GIMP.


Our new banner



If you look at the Stellaris installation folder, you’ll find one folder called “gfx”. As you can easily guess, that’s where the graphics are. And similar to adding new common data by creating a common folder in our mod, we can add new graphics by adding this “gfx” folder to our mod. In this case, this is a red herring though. Sorry. The flag symbols aren’t actually in there, but in another folder on the same level called “flags”. That said, the principle remains and as a first step, we have to recreate the folder structure:

  • create a new folder “flags” as a direct subdirectory of our mod folder “ironborn”
  • inside this folder “flags”, create a new folder “zoological” (it’s a raven… so… zoological)
  • inside this folder “zoological” create two new folders: “map” and “small”

As said above, you need to create the raven with a transparent background. In my case, I also chose to colour it white instead of black. Yes, that means, you won’t see a lot, if you open that picture with a normal image viewer, but we won’t do that, will we? From the original “flags” folder you can see that each flag symbol needs three graphics:

  • the “normal” image in the main folder: 128x128px
  • a bigger one in the folder “map”: 256x256px
  • a small one in the folder “small”: 24x24px

Adjust your image as you like, make sure the background is transparent and then use your graphics program to export three graphics in the given sizes in some format that supports an alpha channel (for instance png). Put those three graphics in one directory and start up your DDS Converter tool. Select “DXT5” as an output format, check the “Alpha” box, select source and target folders and press the big “convert” button.


The three converted .dds files


The tool should then create three .dds files that you can copy in the respective folders in your mod directory. Make sure that they all have the same name and are placed in the correct folder. That’s basically it. You should now be able to select your raven as a flag symbol in the game when creating a new empire.


The Space Viking Raven


If we want to have this symbol be part of our predefined empire, we have to add it to our empire definition in “ironborn.txt”. In there you’ll find a section called “empire_flag” that defines the icon, the background and the colours of our flag. Simply change the “file” of the “icon” and our raven will be the default flag symbol for the Ironborn Dominion.



The end

As a final note, let me tell you that modding the game has its costs. I’m still not sure how exactly the system works, but your mod can change the checksum of the game and if it does that, the game basically can’t tell if you’re cheating and won’t reward you with any achievements. And yes… I think this mod already does that (not 100% sure, though).

Apart from that…
If you finished this tutorial, you have actually created your first mod for Stellaris and in my opinion, this is a decent peace of work for a first mod as we included quite some features. Thank you for your patience and reading through my jabber and I sincerely hope that I could help you a bit along your way. If you have any questions, feel free to add a comment on the actual mod page in the Steam Workshop or somewhere below.


Thanks a lot and cheers,


/tehK aka Tehed


4 thoughts to “Stellaris – A step-by-step guide to creating your first mod”

  1. 2016-05-13 17:50:

    Updated with corrections for spelling mistakes and info about the UTF-8 encoding of the .yml files

Comments are closed.