Difference between revisions of "Modding"

From Stellaris Wiki
Jump to navigation Jump to search
(Adding Steam Thumbnails: IT MUSH NOW READ "THUMBNAIL.JPG")
(Common Folder: More Info)
 
(12 intermediate revisions by 6 users not shown)
Line 1: Line 1:
{{version|2.3.3}}
+
{{version|2.3}}
  
 
'''Modding''', or creating [[mods]], is the act of modifying the behavior of the base game (often referred to as ''vanilla''), either for personal use, or to release publicly to other players, for instance via the [[Steam Workshop]].
 
'''Modding''', or creating [[mods]], is the act of modifying the behavior of the base game (often referred to as ''vanilla''), either for personal use, or to release publicly to other players, for instance via the [[Steam Workshop]].
  
As for all Paradox games, [[Stellaris]] is moddable to a great extent. Motivations of modders may vary widely; better translation to native language, more events or decisions, better map, major overhaul, etc.
+
As for all Paradox games, [[Stellaris]] is moddable to a great extent. Motivations of modders may vary widely; better translation to native language, more events or decisions, better map, major overhaul, shameless cheating, etc.
  
 
This guide is intended to lower the entry barriers to the world of Stellaris modding. However, there is still a learning curve to it, and it cannot replace the need to read some working vanilla code, and do lots of trial and error experimentation!
 
This guide is intended to lower the entry barriers to the world of Stellaris modding. However, there is still a learning curve to it, and it cannot replace the need to read some working vanilla code, and do lots of trial and error experimentation!
Line 10: Line 10:
  
 
{{Template:ModdingNavbox}}
 
{{Template:ModdingNavbox}}
 
==Step by Step Guide==
 
 
Mod creation on Windows:
 
* Start the game
 
* In the launcher, go to the Mod Tab.
 
* click on "Mod tools".
 
* click on "Create Mod"
 
* select a name, a foldername and at least one Tag for the mod. This will create the empty mod file and folder
 
* close the Game/Launcher. It will only detect mods during startup. The actual parsing of the code can happen at a later time.
 
* Find the ([[#Mod_structure|mod location]]). You will find one pre-created .mod file and Folder with the same name.
 
* Copy the relevant part of the game structure. Assume that the content of your modfolder is inside the Stellaris game folder.
 
* Copy the initial gamefile you want to overwrite or create the gamefile you want to add, in the appropriate folder.
 
* Start the game and select your mod in the launcher, to be loaded on this and all further starts.
 
 
Mod Uploading on Windows:
 
* Start the game
 
* In the launcher, go to the Mod Tab.
 
* click on "Mod tools"
 
* click on "Upload Mod"
 
* select the mod you want to upload in the list
 
* click on "Fetch Info". This will try to find the mod and it's Mod ID on the Steam Workshop. If you have not uploaded the mod or are not logged in as uploader, the action will fail with "Mod not found. Will create new mod."
 
* click upload.
 
* wait for the message saying the upload was successful
 
  
 
==Guidelines==
 
==Guidelines==
Line 49: Line 25:
 
*'''Use comments''' starting with # character, to remember reasons for writing tricky stuff.
 
*'''Use comments''' starting with # character, to remember reasons for writing tricky stuff.
  
==Mod structure==
+
==Mod management==
 
+
The first steps of modding is getting to know where the mods are located, how they're structured and what to do when uploading your first mod!
Mods are located in the folder:
 
  
 +
===Mod folder location===
 
{| class="wikitable"
 
{| class="wikitable"
 
| '''OS''' || '''Path'''
 
| '''OS''' || '''Path'''
Line 62: Line 38:
 
| Mac OS ||<code>~/Documents/Paradox Interactive/Stellaris/mod</code>
 
| Mac OS ||<code>~/Documents/Paradox Interactive/Stellaris/mod</code>
 
|}
 
|}
which must contain:
 
  
* the .mod file, to tell the launcher what to do with the mod-folder.
+
Mods from the Steam Workshop will be placed in <code>...\SteamLibrary\SteamApps\workshop\content\281990</code>, sorted by their Workshop ID.<br>
* the mod folder or zip containing the mod data. The mod data must have the same [[#Game structure|file and folder structure]] as if it was along with stellaris.exe in the game directory.
+
Mods from Paradox Mods will be placed in the mod folder location, named as <code>PDX_*MOD_ID*</code>.
  
(Subscribed and downloaded mods from the steam workshop are in <code>.../Paradox Interactive/Stellaris/workshop/content/281990</code> or <code>...\SteamLibrary\SteamApps\workshop\content\281990</code>)
+
===File and folder structure===
 +
Getting the structure set up correct when creating a mod is quintessential for it to run properly.
  
Note that folder and file names are case sensitive on Mac OS X and Linux. Additionally, the path has to be relative to the <code>.../Paradox Interactive/Stellaris</code> folder; absolute path to another directory will not work.
+
This is the required structure inside the main mod folder:
 +
* <code>modname.mod</code> - Includes the information used by the Stellaris launcher
 +
* <code>modname</code> - Folder where all the modified files are placed, in the same [[#Game structure|file and folder structure]] as the game folder
 +
** Mod contents
 +
** <code>descriptor.mod</code> - Required for the [[Patch_2.4|new launcher]] added in patch 2.4
 +
** <code>thumbnail.png</code> - Must be named thumbnail, only PNG files supported
  
For example, a new text file called ''test1.mod'' can be created in the <code>.../Paradox Interactive/Stellaris/mod</code> folder, alongside a new 'test1' folder.
+
<code>modname.mod</code> and <code>descriptor.mod</code> both contains the mod information that the launcher uses when displaying the mod and uploading it.<br>
 +
These files are best kept identical to prevent any missing data.<br>
 +
Note that folder and file names are case sensitive on Mac OS X and Linux.
  
name="Test1"
 
path="mod/test1"
 
tags={
 
"Economy"
 
}
 
picture="test1.jpg"
 
supported_version="1.0.3"
 
  
In the ''test1'' folder, the ''test1.mod'' file should be copied and can be renamed to ''descriptor.mod''.
+
'''modname.mod structure'''<br>
 +
This also applies to <code>descriptor.mod</code>.
  
It is important that your thumbnail image is in the ".jpg" format, otherwise Steam gives an error during upload. Note also that it must be within your mod's directory (as specified by "path"), and you don't need to prefix the "picture" path with the "path".
+
{| class="wikitable"
 +
!Name
 +
!Required
 +
!Description
 +
!Example
 +
|-
 +
| name
 +
| '''Yes'''
 +
| Name of your mod.
 +
| name="My Stellaris Mod"
 +
|-
 +
| path
 +
| '''Yes'''
 +
| Defines which folder is the mod's folder. It is relative to ''...\Documents\Paradox Interactive\Stellaris\'' folder.
 +
| path="mod/MyStellarisMod"
 +
|-
 +
| dependencies
 +
| No
 +
| Specifies if the mod should be loaded after the listed mod(s), if they exist.<br>Very useful for submods or compatibility patches to make sure they overrule certain mods.
 +
| <pre>dependencies={
 +
"My Other Stellaris Mod"
 +
"Not My Stellaris Mod"
 +
}</pre>
 +
|-
 +
| picture
 +
| No
 +
| Specifies the mod thumbnail used on [[Steam Workshop]]. Must be a PNG file.
 +
| picture="thumbnail.png"
 +
|-
 +
| tags
 +
| No
 +
| List of tags for [[Steam Workshop]]. Warning: don't forget quotes for tags that contain spaces.
 +
| <pre>tags={
 +
"Tag1"
 +
"Tag2"
 +
}</pre>
 +
|-
 +
| supported_version
 +
| Recommended
 +
| Specifies what game version the mod supports.<br>The last number can be replaced with the asterisk (*) symbol to tell the launcher that mod supports any value, like 2.4.*.<br>Only the last number supports this.
 +
| supported_version="2.4.1"
 +
|-
 +
| remote_file_id
 +
| No
 +
| Property added by the launcher that includes the Steam Workshop ID. Ignore it.
 +
| remote_file_id="1234567890"
 +
|}
  
Game files can now be replaced using the same structure as the game directory. Here, a ''common'' folder was created, with a ''traits'' subfolder that contains the ''00_species_traits.txt'' from the game folder.
 
The structure now looks like the following:
 
  
  ''C:\Users\Jason\Documents\Paradox Interactive\Stellaris\mod''
+
'''Example modname.mod file:'''<br>
    test1.mod
+
<pre>name="Somemod"
    test1 (dir)
+
path="mod/somemod"
      test1.jpg
+
dependencies={
      descriptor.mod
+
"othermod"
      common (dir)
+
"another mod"
        traits (dir)
+
}
          00_species_traits.txt
+
tags={
 +
"Graphics"
 +
"Economy"
 +
"Overhaul"
 +
}
 +
picture="thumbnail.png"
 +
remote_file_id="1234567890"
 +
supported_version="2.4.*"</pre>
  
A new trait with various bonuses called ''trait_super'' can be added. It has a high cost so the AI does not use it, but the user could load it using the console commands. (Using ''is_ai = no'' also seems to do the trick)
+
===Adding a thumbnail===
 +
The Steam Workshop allows for a preview thumbnail picture that'll be displayed when searching for mods and as a preview picture if you haven't uploaded any, otherwise it'll be placed to the right of the preview pictures.<br>
 +
It's recommended to make the thumbnail at minimum 512px × 512px, which is used by the workshop frontpage.<br>
 +
Both JPEG and PNG are supported, and after 2.4, the image file must be named '''thumbnail'''.
 +
# Make sure the Stellaris launcher is closed, so that it doesn't revert your changes
 +
# Open up <code>modname.mod</code> and <code>descriptor.mod</code> files
 +
# Make sure <code>picture="thumbnail.jpg"</code> exists, if not, add it
 +
# Add your image file in your mod folder
 +
# Start up the launcher and update your mod
 +
# Thumbnail should now show up at the [[Steam Workshop]] mod page
  
trait_super = {
+
You can always update the thumbnail at any time by updating the mod.
cost = 1000
 
modifier = {
 
tile_resource_food_mult = 10
 
tile_resource_energy_mult = 10
 
tile_resource_minerals_mult = 10
 
}
 
}
 
  
In addition, downloaded mods will use content in zip files. Their '.mod' files will contain lines defining the 'remote_file_id' and 'archive'.
+
===Creating a mod===
Here is an example:
+
You can use the game launcher to set up a the mod structure for you by following these simple steps according to your launcher of choice:
 +
{| style="text-align:center;" class="wikitable"
 +
!#
 +
!Launcher v1 (<=2.3.3)
 +
!Launcher v2 (>=2.4.0)
 +
|-
 +
|1||colspan="2"| Launch the game
 +
|-
 +
|2||colspan="2"| Navigate to the mods tab
 +
|-
 +
|3||colspan="2"| Click '''Mod Tools'''
 +
|-
 +
|4||Click '''Create Mod'''
 +
|-
 +
|5||colspan="2"| Insert the relevant information and click '''Create Mod''' at the bottom
 +
|-
 +
|6||colspan="2"| Navigate to the [[#Mod_folder_location|mod folder]] and locate your mod folder
 +
|-
 +
|7||colspan="2"| Start modding!
 +
|}
  
name="999 Core Planets - All your planets are belong to you"
+
===Uploading and updating a mod===
archive="workshop/content/281990/678893824/999cores.zip"
+
Uploading and updating a mod follows the the same procedure, depending on your launcher of choice:
tags={
+
{| style="text-align:center;" class="wikitable"
"Balance"
+
!#
"Gameplay"
+
!Launcher v1 (<=2.3.3)
"Utilities"
+
!Launcher v2 (>=2.4.0)
}
+
|-
remote_file_id="678893824"
+
|1||colspan="2"|Launch the game
supported_version="1.0.0"
+
|-
 
+
|2||colspan="2"|Navigate to the mods tab
This directory is based off the Stellaris directory in your documents folder, for instance this zip file is:
+
|-
 
+
|3||colspan="2"|Click '''Mod Tools'''
C:\Users\<Username>\Documents\Paradox Interactive\Stellaris\workshop\content\281990\678893824\999cores.zip
+
|-
 
+
|4||Click '''Upload Mod'''||Click '''Upload a Mod'''
Here is an example of how to make a ''.mod file'' for a Sub Mod (Mod for a Mod)
+
|-
 
+
|5||colspan="2"|Select your mod from the list
name="Fight For Universe: Infinite Legacy - No Maintenance"
+
|-
path="mod/ffu_ilno"
+
|6||Click '''Fetch Info''' and wait for a response||Select mod site
dependencies={
+
|-
"Fight For Universe: Infinite Legacy"
+
|7|| ||Insert description<sup>'''*'''</sup>
}
+
|-
replace_path="Fight For Universe: Infinite Legacy"
+
|8||Click '''Upload'''||Click '''Upload Mod'''
tags={
+
|-
"Balance"
+
|9||colspan="2"|The launcher will now upload your changes and inform when completed, or if something erroneous happened
"Overhaul"
+
|-
"Graphics"
+
|10||colspan="2"|Navigate to the mod service of choice and locate your mod;<br>'''Steam Workshop''', visit the [https://steamcommunity.com/app/281990/workshop/ Workshop] page, and locate the "Files you've posted" button by hovering over "Your Files" on the right<br>'''Paradox Mods''', visit the [https://mods.paradoxplaza.com/ Mods] page, login, and click "My uploaded mods" in the dropdown menu that appears when hovering over your name
"Gameplay"
+
|-
}
+
|+ style="caption-side:bottom;|* - The inserted description will replace the current one used on the mod page!
picture="NoMaintenance.png"
+
|}
remote_file_id="911971558"
 
supported_version="1.5.1"
 
 
 
==Adding Steam Thumbnails==
 
The Steam Workshop allows you to add small images ("thumbnails") next to your mod and are the first thing people see when browsing the Workshop. Although these are optional and not required, they add some flavor and make mods very recognizable. It is best to add thumbnails to your mods as the final step before uploading it to the Steam Workshop.
 
Procedure:
 
* '''Adding Thumbnail'''
 
** Make sure the Stellaris launcher is closed, otherwise it'll revert any changes made to .MOD file on "Fetch Mod" or "Upload Mod".
 
** Open .MOD file of your mod located in <code>.../Stellaris/mod/[Mod Name]</code> using Notepad++ or likewise.
 
** Insert line <code>picture="thumbnail.jpg"</code> beneath the tags line, with the appropriate name of your image. '''''IT MUST READ "THUMBNAIL"'''''.
 
** Save the modified .MOD file.
 
** Place your image within your mod folder, <code>.../Stellaris/mod/[Mod Name]</code>.
 
** Double check whether the image name and the name you identified in <code>picture="thumbnail.jpg"</code> are exactly the same.
 
** Close Notepad++.
 
** Start Stellaris Launcher
 
** Via "Manage Mods" tab, select your mod and click '''Fetch'''
 
** You receive a message that no mod was found on the Steam Workshop, which makes sense as your mod hasn't not been uploaded yet.
 
** Click on '''Upload Mod'''
 
** You receive a message that the Mod Upload was successful!
 
** Check in your Workshop whether the thumbnail was correctly uploaded.
 
* '''Updating Thumbnail'''
 
** Make sure the Stellaris launcher is closed, otherwise it'll revert any changes made to .MOD file on "Fetch Mod" or "Upload Mod".
 
** Open .MOD file of your mod located in <code>.../Stellaris/mod/[Mod Name]</code> using Notepad++ or likewise.
 
** Save the modified .MOD file.
 
** Place your new image in your mod folder, in <code>.../Stellaris/mod/[Mod Name]</code>. Leave the old image within the mod.
 
*** Nothing happens to the old image when uploading a new mod version but it is good practice to have a back-up if it fails.
 
** Double check whether the image name and the name you identified in <code>picture="thumbnail.jpg"</code> are exactly the same.
 
** Close Notepad++.
 
** Start Stellaris Launcher
 
** Via "Manage Mods" tab, select your mod and click '''Fetch'''
 
** You receive a message the mod was found on the Steam Workshop. If not, you probably made a typo within the .MOD file, so check the file again and save!
 
** Click on '''Upload Mod'''
 
** You receive a message that the Mod Upload was successful!
 
** Check in your Workshop whether the new thumbnail was correctly uploaded.
 
  
 
==Game data==
 
==Game data==
Line 860: Line 875:
 
|-
 
|-
 
| Component Sets
 
| Component Sets
| FIOS†
+
| FIOS
 
| Object key already exists
 
| Object key already exists
 
|  
 
|  
Line 870: Line 885:
 
|-
 
|-
 
| Component Templates
 
| Component Templates
| FIOS†
+
| FIOS
 
| Object key already exists
 
| Object key already exists
 
|  
 
|  
Line 920: Line 935:
 
|-
 
|-
 
| style="height: 43px" | Districts
 
| style="height: 43px" | Districts
| LIOS
+
| Dupl (Last)
 
| Object key already exists
 
| Object key already exists
| Possibly breaks<br/>district capacity
+
| Breaks max<br/>districts modifier
 
|-
 
|-
 
| Economic Categories
 
| Economic Categories
Line 940: Line 955:
 
|-
 
|-
 
| Event Chains
 
| Event Chains
| FIOS†
+
| FIOS
 
| {{small|''[none]''}}
 
| {{small|''[none]''}}
 
|  
 
|  
Line 1,093: Line 1,108:
 
|-
 
|-
 
| Scripted Variables
 
| Scripted Variables
| FIOS†
+
| FIOS
 
| Variable name taken
 
| Variable name taken
 
|  
 
|  
 
|-
 
|-
 
| Section Templates
 
| Section Templates
| FIOS†
+
| FIOS
 
| Duplicate section template found
 
| Duplicate section template found
 
|  
 
|  
Line 1,113: Line 1,128:
 
|-
 
|-
 
| Ship Behaviors
 
| Ship Behaviors
| FIOS†
+
| FIOS
 
| Behavior name already exists
 
| Behavior name already exists
 
|  
 
|  
Line 1,128: Line 1,143:
 
|-
 
|-
 
| Special Projects
 
| Special Projects
| FIOS†
+
| FIOS
 
| Object key already exists
 
| Object key already exists
 
|  
 
|  
 
|-
 
|-
 
| Species Archetypes
 
| Species Archetypes
| LIOS
+
| Dupl (Last)
 
| Object key already exists
 
| Object key already exists
| Breaks bonus<br/>trait points
+
| Breaks bonus<br/>trait points modifier
 
|-
 
|-
 
| Species Classes
 
| Species Classes
Line 1,153: Line 1,168:
 
|-
 
|-
 
| Star Classes
 
| Star Classes
| FIOS†
+
| FIOS
 
|  
 
|  
 
|  
 
|  
Line 1,188: Line 1,203:
 
|-
 
|-
 
| Strategic Resources
 
| Strategic Resources
| FIOS†
+
| FIOS
 
| {{small|''[none]''}}
 
| {{small|''[none]''}}
 
|  
 
|  
Line 1,213: Line 1,228:
 
|-
 
|-
 
| Terraform (Links)
 
| Terraform (Links)
| NO
+
| Dupl
 
| {{small|''[none]''}}
 
| {{small|''[none]''}}
| Duplicate<br>Terraforming links
+
|  
 
|-
 
|-
 
| Trade Conversions
 
| Trade Conversions
Line 1,233: Line 1,248:
 
|-
 
|-
 
| Traits
 
| Traits
| NO
+
| Dupl
 
| {{small|''[none]''}}
 
| {{small|''[none]''}}
| Creates duplicate traits
+
|  
 
|-
 
|-
 
| War Goals
 
| War Goals
Line 1,243: Line 1,258:
 
|}
 
|}
 
{{end box wrapper}}
 
{{end box wrapper}}
† Not extensively tested
+
FIOS - First in, only served
 +
 
 +
LIOS - Last in, only served
 +
 
 +
Dupl - Duplicates
 +
 
 +
Dupl (Last) - Technically duplicates, however only last is used (breaks autogenerated modifiers)
 +
 
 +
Dupl (First) - Technically duplicates, however only first is used (breaks autogenerated modifiers)
 +
 
 +
 
 +
Please note that these have not been extensively tested; Entries listed as FIOS or LIOS might actually be Dupl, Dupl (First), or Dupl (Last)
  
 
====Localisation Folder====
 
====Localisation Folder====
Localization is treated as LIOS
+
Localisation folder is not consistent.
 +
 
 +
It's possible to overwrite by LIOS ''and'' FIOS.
 +
 
 +
A more sure-fire way to overwrite localization is to add a "replace" folder inside and add the parts your mod is trying to overwrite there.
  
 
====Events Folder====
 
====Events Folder====

Latest revision as of 13:39, 10 November 2019

Version

Outliner top.png
This article may contain outdated information that is inaccurate for the current version of the game. It was last updated for 2.3.

This article is for the PC version of Stellaris only.

Modding, or creating mods, is the act of modifying the behavior of the base game (often referred to as vanilla), either for personal use, or to release publicly to other players, for instance via the Steam Workshop.

As for all Paradox games, Stellaris is moddable to a great extent. Motivations of modders may vary widely; better translation to native language, more events or decisions, better map, major overhaul, shameless cheating, etc.

This guide is intended to lower the entry barriers to the world of Stellaris modding. However, there is still a learning curve to it, and it cannot replace the need to read some working vanilla code, and do lots of trial and error experimentation!


Guidelines[edit]

  • Create a mod for your modifications: use a personal mod even for small changes, and never modify directly game files in Steam Stellaris folder, as they may be overwritten without warning.
  • Use a good text editor (recommended: Visual Studio Code) to edit files and search into multiple files. A good text editor can also format the displayed text so that braces can be collapsed if complete, and complete/incomplete pairs are highlighted.
  • Use the Error.log file to get execution errors: The log folder can be found right next to the mod folder. Good Editors usually have the ability to track changes to files from outside the program and prompt for a reload, thus showing you errors with one glance onto the file. Note that some modifications need a game to be loaded or even the option to be used on screen/in the back-end before their code will run.
  • Use CWTools for advanced validation and auto-complete: CWTools is a syntax validator for Stellaris modding, developed as an extension for Visual Studio Code and available as well for Sublime. Read the forum post by the developer for more info.
  • Minimize overwrites of vanilla files, unless that is your main goal or somehow necessary (on_action triggers). Adding separate files and use loading from folders whenever possible, to improve mod compatibility and maintenance. Your files can have any name, all files in the folder will be loaded by the game. So choose a prefix no one else will ever use like the name of your mod. Even DLC follow that pattern.
  • Use a proper merge tool (like WinMerge), to merge between folders, and update modified vanilla files to a new vanilla patch.
  • Backup your work to avoid losing everything. Consider using a source control system like Git and a collaborative forge like GitHub to manage team collaboration.
  • Use UTF-8 encoding for text files.
  • Use UTF-8 with BOM for localization, name list, and .mod files.
  • Indent properly and, again, use a good text editor, to easily spot unclosed curly braces. Vanilla uses 1 tab for indentation rather than spaces.
  • Use comments starting with # character, to remember reasons for writing tricky stuff.

Mod management[edit]

The first steps of modding is getting to know where the mods are located, how they're structured and what to do when uploading your first mod!

Mod folder location[edit]

OS Path
Linux ~/.local/share/Paradox Interactive/Stellaris/mod
Windows C:\Users\<Username>\Documents\Paradox Interactive\Stellaris\mod
Mac OS ~/Documents/Paradox Interactive/Stellaris/mod

Mods from the Steam Workshop will be placed in ...\SteamLibrary\SteamApps\workshop\content\281990, sorted by their Workshop ID.
Mods from Paradox Mods will be placed in the mod folder location, named as PDX_*MOD_ID*.

File and folder structure[edit]

Getting the structure set up correct when creating a mod is quintessential for it to run properly.

This is the required structure inside the main mod folder:

  • modname.mod - Includes the information used by the Stellaris launcher
  • modname - Folder where all the modified files are placed, in the same file and folder structure as the game folder
    • Mod contents
    • descriptor.mod - Required for the new launcher added in patch 2.4
    • thumbnail.png - Must be named thumbnail, only PNG files supported

modname.mod and descriptor.mod both contains the mod information that the launcher uses when displaying the mod and uploading it.
These files are best kept identical to prevent any missing data.
Note that folder and file names are case sensitive on Mac OS X and Linux.


modname.mod structure
This also applies to descriptor.mod.

Name Required Description Example
name Yes Name of your mod. name="My Stellaris Mod"
path Yes Defines which folder is the mod's folder. It is relative to ...\Documents\Paradox Interactive\Stellaris\ folder. path="mod/MyStellarisMod"
dependencies No Specifies if the mod should be loaded after the listed mod(s), if they exist.
Very useful for submods or compatibility patches to make sure they overrule certain mods.
dependencies={
	"My Other Stellaris Mod"
	"Not My Stellaris Mod"
}
picture No Specifies the mod thumbnail used on Steam Workshop. Must be a PNG file. picture="thumbnail.png"
tags No List of tags for Steam Workshop. Warning: don't forget quotes for tags that contain spaces.
tags={
	"Tag1"
	"Tag2"
}
supported_version Recommended Specifies what game version the mod supports.
The last number can be replaced with the asterisk (*) symbol to tell the launcher that mod supports any value, like 2.4.*.
Only the last number supports this.
supported_version="2.4.1"
remote_file_id No Property added by the launcher that includes the Steam Workshop ID. Ignore it. remote_file_id="1234567890"


Example modname.mod file:

name="Somemod"
path="mod/somemod"
dependencies={
	"othermod"
	"another mod"
}
tags={
	"Graphics"
	"Economy"
	"Overhaul"
}
picture="thumbnail.png"
remote_file_id="1234567890"
supported_version="2.4.*"

Adding a thumbnail[edit]

The Steam Workshop allows for a preview thumbnail picture that'll be displayed when searching for mods and as a preview picture if you haven't uploaded any, otherwise it'll be placed to the right of the preview pictures.
It's recommended to make the thumbnail at minimum 512px × 512px, which is used by the workshop frontpage.
Both JPEG and PNG are supported, and after 2.4, the image file must be named thumbnail.

  1. Make sure the Stellaris launcher is closed, so that it doesn't revert your changes
  2. Open up modname.mod and descriptor.mod files
  3. Make sure picture="thumbnail.jpg" exists, if not, add it
  4. Add your image file in your mod folder
  5. Start up the launcher and update your mod
  6. Thumbnail should now show up at the Steam Workshop mod page

You can always update the thumbnail at any time by updating the mod.

Creating a mod[edit]

You can use the game launcher to set up a the mod structure for you by following these simple steps according to your launcher of choice:

# Launcher v1 (<=2.3.3) Launcher v2 (>=2.4.0)
1 Launch the game
2 Navigate to the mods tab
3 Click Mod Tools
4 Click Create Mod
5 Insert the relevant information and click Create Mod at the bottom
6 Navigate to the mod folder and locate your mod folder
7 Start modding!

Uploading and updating a mod[edit]

Uploading and updating a mod follows the the same procedure, depending on your launcher of choice:

# Launcher v1 (<=2.3.3) Launcher v2 (>=2.4.0)
1 Launch the game
2 Navigate to the mods tab
3 Click Mod Tools
4 Click Upload Mod Click Upload a Mod
5 Select your mod from the list
6 Click Fetch Info and wait for a response Select mod site
7 Insert description*
8 Click Upload Click Upload Mod
9 The launcher will now upload your changes and inform when completed, or if something erroneous happened
10 Navigate to the mod service of choice and locate your mod;
Steam Workshop, visit the Workshop page, and locate the "Files you've posted" button by hovering over "Your Files" on the right
Paradox Mods, visit the Mods page, login, and click "My uploaded mods" in the dropdown menu that appears when hovering over your name
* - The inserted description will replace the current one used on the mod page!

Game data[edit]

Game structure[edit]

Below is a list of game files and folders, with associated modding guide.

Stellaris/common/[edit]

Folder/File Summary Guides
agendas Agendas are given to leader-candidates in Oligarchic government-forms Agendas
ambient_objects References used by code to spawn ambient objects Models
anomalies Events that occur for research ships Anomalies
armies Definitions for army types Armies
army_attachments Definitions for attachments that can be added to armies Armies
attitudes Definitions containing the restrictions for each attitude used by the AI AI
buildable_pops Definitions for buildable pops. i.e. Robots Pops
buildings Setup for buildings constructable on planets, and those given through events Buildings
colors Color definitions used for the country color selection Countries
component_flags List of flags used by the AI for selecting components Ships
component_sets List of the sets of components used by ships Ships
component_tags Used to group components together for common modifiers Ships
component_templates Attribute setup for each weapon and the templates used for ships Ships
country_types Rules for each country within the game. Countries
defines Basic game behaviors and settings Defines
deposits Setup for the deposits of resources found on planets Planets
diplo_phrases Setup for the logic behind the diplomatic phrases used between countries. AI
diplomatic_actions Setup for the rules for diplomatic actions. Gameplay
edicts Setup for the edicts used by planets and countries. Edicts
ethics Setup for ethics, controlling their modifiers and categories Ethics
event_chains Setup for the event chains used in the events folder Event chains
fallen_empires Sets up the countries and system initializer used for fallen empires Systems
game_rules Logic used for various game actions, i.e. can_enslave_pop. Logic here does not override hardcoded rules. Gameplay
global_ship_designs Designs used by the ship designer for each species Ships
governments Setup for the governments. Governments
graphical_culture Controls the lightning used for ships, which differs between graphical cultures. Species
mandates Controls the mandates used by factions Mandates
name_lists Sets up the names used for each species. Species
observation_station_missions Actions that can be done with observation stations depending on ethic choices. Gameplay
on_actions Events and actions that happens when you move, or do anything. Events
opinion_modifiers Opinion of Empires on other Empires depending on Political status and Ethics. Opinion Modifiers
personalities Shows the personalities of Empires AI traits and of Fallen Empires and enables editing them. AI
planet_classes The setup for all the planets and stars in the game. Planets
planet_modifiers Spawn chances planet modifiers (f.e. lush, hazardous weather, etc.). Planets
policies AI Policy grabbing (What order they take policies in) Policies
pop_faction_types Population faction types and personalities? Pops
precursor_civilizations Precursor civilisation weightings Planets
random_names Lists of random names for Empires Gameplay
scripted_effects Events that give buffs or de-buffs (effects). Gameplay
scripted_triggers Scripted events and how they trigger. Gameplay
section_templates Different Ship AI and how it acts. Ship
sector_types Types of sectors and how they act. Gameplay
ship_behaviours Standard ship behaviours. Ship
ship_sizes Sizes of the Ships. Ship
solar_system_initializers Defines starting systems for players, AI, event systems, hostile systems, etc. Systems
spaceport_modules Planets
special_projects Special Projects
species_classes Species
star_classes Types of solar systems (NOT individual stars themselves!) Systems
start_screen_messages Gameplay
static_modifiers Gameplay
strategic_resources Planet
subjects Gameplay
technology Technology
terraform Planets
tile_blockers Planets
traits Traits
triggered_modifiers Gameplay
war_demand_counters Wars
war_demand_types Wars
achievements.txt None
alerts.txt Gameplay
message_types.txt Gameplay

Stellaris/events/[edit]

Folder/File Summary Guides
example_events.txt Contains the event code for a set of events. Events

Stellaris/flags/[edit]

Folder/File Summary Guides
*.dds A flag image file. Flags
colors.txt Sets up the allowed colors for flags and the randomizable combos. Flags

Stellaris/fonts/[edit]

File Summary Guides
fonts.asset Sets up the fonts used by the game. Fonts

Stellaris/gfx/[edit]

Folder/File Summary Guides
advisorwindow Sets up the 3D view for the advisor Graphics
arrows Contains the images used by various arrows ingame. Graphics
cursors Contains the cursor files/images used ingame. Graphics
event_pictures Contains the pictures used in events. Events
fonts Contains the font files used ingame. Fonts
FX Contains the FX shaders used ingame. Graphical Effect
interface/ Contains the images used for interfaces ingame. Graphics
interface/anomaly Contains the images used for the anomaly mechanic Graphics
interface/buttons Contains the images used for buttons Graphics
interface/diplomacy Contains the images used for the diplomacy interface. Graphics
interface/elections Contains the images used for the election interface. Graphics
interface/event_window Contains the images used for the event window. Graphics
interface/flags Contains the image masks used for flags. Graphics
interface/fleet_view Contains the images used for fleets. Graphics
interface/frontend Contains the images used for the frontend interface. Graphics
interface/government_mod_window Contains the images used for the government modification interface. Graphics
interface/icons Contains the icons used for everything in the game. Graphics
interface/main Contains the images used for generic actions. Graphics
interface/old Contains the images used from EU4 Graphics
interface/outliner Contains the images used for the outliner interface. Graphics
interface/planetview Contains the images used for the planet view interface. Graphics
interface/progressbars Contains the images used for progress bars ingame. Graphics
interface/ship_designer Contains the images used for the ship designer interface. Graphics
interface/situation_log Contains the images used for the situation log interface. Graphics
interface/sliders Contains the images used for sliders ingame. Graphics
interface/system Contains the images used for the system view interface. Graphics
interface/tech_view Contains the images used for the technology view interface. Graphics
interface/tiles Contains the images used for the tile view interface. Graphics
interface/topbar Contains the images used for the topbar interface. Graphics
interface/waroverview Contains the images used for the war view interface. Graphics
keyicons Contains the images used for button presses ingame. Graphics
lights Contains the logic used for the light effects ingame. Graphical Effect
loadingscreens Contains the images used for loadscreens. Graphics
models Contains the model .mesh files and images. Models
models/portraits Contains the portrait .mesh files and images. Portraits
particles Contains the logic and images used for particles. Graphics
pingmap Contains the logic used for pings. Graphics
portraits Contains the logic used for portrait images. Portraits
projectiles Contains the logic used for projectiles. Graphics
shipview Contains the logic used for ship view. Graphics
worldgfx Contains the logic and images used for world graphic effects. Graphics

Stellaris/interface/[edit]

Folder Summary Guides
*.gfx Controls the assignment of image to interface variable. Interfaces
*.gui Controls the visual logic of an interface. Interfaces

Stellaris/localisation/[edit]

File Summary Guides
*l_english.yml Contains English localisation Localisation
*l_french.yml Contains French localisation Localisation
*l_german.yml Contains German localisation Localisation
*l_polish.yml Contains Polish localisation Localisation
*l_russian.yml Contains Russian localisation Localisation
*l_spanish.yml Contains Spanish localisation Localisation
*l_braz_por.yml Contains Brazilian/Portuguese localisation Localisation

Stellaris/map/[edit]

Folder/File Summary Guides
galaxy Contains the galaxy options. You cannot add new ones currently. Galaxies
setup_scenarios Controls the logic for different sizes of galaxies. Galaxies

Stellaris/music/[edit]

Folder/File Summary Guides
*.ogg A music file. Music
songs.asset Controls the assignment of music to a code name, and sets the volume of playback. Music
songs.txt Music

Stellaris/prescripted_countries/[edit]

Folder/File Summary Guides
*.txt Contains a pre-scripted setup for a country. Listed on the side ingame. Galaxies
setup_scenarios Controls the logic for different sizes of galaxies. Galaxies

Stellaris/sound/[edit]

Folder/File Summary Guides
*.asset Sets up sounds. Sound
*.wav A sound file. Sound

Overwriting Specific Elements[edit]

Occasionally, it is possible to overwrite a specific game element, without needing to replace the entire vanilla file. In some cases adding a similar identifier element into another file will duplicate that element for the game. But in other cases, the version that comes first (First in, only Served; FIOS)/last (Last in, only Served; LIOS) will be used instead. [1]. The order in which files are processed is based on ASCIIbetical order of the filenames. If the names are the same, they'll be processed based on the reverse-ASCIIbetical order of the mod display name, with vanilla always being first (if it's at the top of the mod list, it'll be loaded last). Note that if there are multiple mods with the same display name, only the one, whose mod file comes first, will be used.

Note that this feature is not documented and thus might be subject to arbitrarily changes between versions.

Common Folder[edit]

A-N (Agendas -
Notification Modifiers)
File Type Overwrite
Type
Error Log Notes
Agendas LIOS Object key already exists
AI Budget
Ambient Objects
Anomalies LIOS Object key already exists
Armies LIOS Object key already exists
Ascension Perks LIOS Object key already exists
Asteroid Belts
Attitudes LIOS Object key already exists
Bombardment Stances LIOS Object key already exists
Buildings LIOS Object key already exists
Button Effects
Bypass LIOS Object key already exists
Casus Belli LIOS Object key already exists
Colony Types LIOS Object key already exists
Colors
Component Sets FIOS Object key already exists
Component Tags
Component Templates FIOS Object key already exists
Country Customization
Country Types LIOS Object key already exists
Decisions LIOS Object key already exists
Defines LIOS [none] The block the define is
in must be included as well.
E.g: NGameplay = {
POLICY_YEARS = 10 }
Deposit Categories
Deposits LIOS Object key already exists
Diplomatic Phrases
Diplomatic Economy LIOS Object key already exists
Diplomatic Actions LIOS Object key already exists
Districts Dupl (Last) Object key already exists Breaks max
districts modifier
Economic Categories
Edicts LIOS Object key already exists
Ethics LIOS [none] Might break "selected
ethic" graphic
Event Chains FIOS [none]
Fallen Empires
Game Rules LIOS [none]
Global Ship Designs
Governments LIOS Object key already exists
├───Authorities LIOS Object key already exists
└───Civics LIOS Object key already exists
Graphical Culture
Leader Classes LIOS Object key already exists
Mandates LIOS Object key already exists
Map Modes LIOS Object key already exists
Megastructures LIOS Object key already exists
Name Lists
Notification Modifiers
O-Z (Observation Station
Missions - War Goals)
File Type Overwrite
Type
Error Log Notes
Observation Station Missions
On Actions NO [none] Cannot modify
existing entries
Opinion Modifiers LIOS [none]
Personalities LIOS† Object key already exists
Planet Classes LIOS [none]
Planet Modifiers LIOS Object key already exists
Policies LIOS Object key already exists
Pop Categories LIOS Object key already exists
Pop Faction Types LIOS Object key already exists
Pop Jobs N/A [none] Neither entries used
Precursor Civilizations
Random Names
Scripted Effects LIOS Object key already exists
Scripted Localisation
Scripted Triggers LIOS Object key already exists
Scripted Variables FIOS Variable name taken
Section Templates FIOS Duplicate section template found
Sector Focuses LIOS Object key already exists
Sector Types
Ship Behaviors FIOS Behavior name already exists
Ship Sizes LIOS Object key already exists
Solar System Initializers Initializer already exists
Special Projects FIOS Object key already exists
Species Archetypes Dupl (Last) Object key already exists Breaks bonus
trait points modifier
Species Classes LIOS Object key already exists
Species Names
Species Rights LIOS Object key already exists Effect tooltips are
independent of the effects
Star Classes FIOS
Starbase Buildings LIOS Object key already exists
Starbase Levels LIOS Object key already exists
Starbase Modules LIOS Object key already exists
Starbase Types LIOS Object key already exists
Start Screen Messages
Static Modifiers FIOS [none]
Strategic Resources FIOS [none]
Subjects LIOS Object key already exists
System Types LIOS Object key already exists
Technology LIOS Duplicate technology
└───Tiers LIOS
Terraform (Links) Dupl [none]
Trade Conversions LIOS Object key already exists Trade Policy
Tradition Categories LIOS Object key already exists
Traditions LIOS Object key already exists Effect tooltips are
independent of the effects
Traits Dupl [none]
War Goals LIOS Object key already exists

FIOS - First in, only served

LIOS - Last in, only served

Dupl - Duplicates

Dupl (Last) - Technically duplicates, however only last is used (breaks autogenerated modifiers)

Dupl (First) - Technically duplicates, however only first is used (breaks autogenerated modifiers)


Please note that these have not been extensively tested; Entries listed as FIOS or LIOS might actually be Dupl, Dupl (First), or Dupl (Last)

Localisation Folder[edit]

Localisation folder is not consistent.

It's possible to overwrite by LIOS and FIOS.

A more sure-fire way to overwrite localization is to add a "replace" folder inside and add the parts your mod is trying to overwrite there.

Events Folder[edit]

Events are treated as FIOS

Tools & utilities[edit]

External links[edit]

Stellaris Dev Diary #31 - Modding (Scripting Anomalies)
Stellaris Dev Diary #32 - Modding art

See also[edit]

References[edit]