Modding

Version

This article is timeless and should be accurate for any version of the game.

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.

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!

Modding

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 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

• 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 structure

Mods are located in the folder:

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

which must contain:

• the .mod file, to tell the launcher what to do with the mod-folder.
• the mod folder or zip containing the mod data. The mod data must have the same file and folder structure as if it was along with stellaris.exe in the game directory.

(Subscribed and downloaded mods from the steam workshop are in .../Paradox Interactive/Stellaris/workshop/content/281990 or ...\SteamLibrary\SteamApps\workshop\content\281990)

Note that folder and file names are case sensitive on Mac OS X and Linux. Additionally, the path has to be relative to the .../Paradox Interactive/Stellaris folder; absolute path to another directory will not work.

For example, a new text file called test1.mod can be created in the .../Paradox Interactive/Stellaris/mod folder, alongside a new 'test1' folder.

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.

It is important that your thumbnail image is in the ".jpg" format, otherwise steam gives an error during upload.

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
   test1.mod
   test1 (dir)
     test1.jpg
     descriptor.mod
     common (dir)
       traits (dir)
         00_species_traits.txt

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)

trait_super = {
	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'. Here is an example:

name="999 Core Planets - All your planets are belong to you"
archive="workshop/content/281990/678893824/999cores.zip"
tags={
	"Balance"
	"Gameplay"
	"Utilities"
}
remote_file_id="678893824"
supported_version="1.0.0"

This directory is based off the Stellaris directory in your documents folder, for instance this zip file is:

C:\Users\<Username>\Documents\Paradox Interactive\Stellaris\workshop\content\281990\678893824\999cores.zip

Here is an example of how to make a .mod file for a Sub Mod (Mod for a Mod)

name="Fight For Universe: Infinite Legacy - No Maintenance"
path="mod/ffu_ilno"
dependencies={
	"Fight For Universe: Infinite Legacy"
}
replace_path="Fight For Universe: Infinite Legacy"
tags={
	"Balance"
	"Overhaul"
	"Graphics"
	"Gameplay"
}
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 flavour 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 .../Stellaris/mod/[Mod Name] using Notepad++ or likewise.
  • Insert line picture="picturename.jpg" beneath the tags line, with the appropriate name of your image.
  • Save the modified .MOD file.
  • Place your image within your mod folder, .../Stellaris/mod/[Mod Name].
  • Double check whether the image name and the name you identified in picture="picturename.jpg" 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 .../Stellaris/mod/[Mod Name] using Notepad++ or likewise.
  • Edit line picture="picturename.jpg" beneath the tags line, to reflect the name of your new image; for example, picture="picturename_2.jpg"
  • Save the modified .MOD file.
  • Place your new image in your mod folder alongside your old image, .../Stellaris/mod/[Mod Name]. 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 picture="picturename.jpg" 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

• Console commands, useful for debugging mods.
• Defines, which allow to influence some hardcoded vanilla behaviors
• Scopes, Conditions, and Commands used for scripting
• Modifiers, used to influence calculations made by the game
• Events, used to define popups with decisions
• Map, used for pre-generated galaxy maps

Game structure

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

Stellaris/common/

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 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
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/

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

Stellaris/flags/

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/

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

Stellaris/gfx/

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/

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

Stellaris/localisation/

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/

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/

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/

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/

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

Overwriting Specific Elements

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. . 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

Agendas - Observation
Station Missions

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]
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	LIOS	Object key already exists	Possibly breaks district capacity
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
Observation Station Missions

On Actions -
War Goals

File Type	Overwrite Type	Error Log	Notes
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	LIOS	Object key already exists	Breaks bonus trait points
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)	NO	[none]	Duplicate Terraforming links
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	NO	[none]	Creates duplicate traits
War Goals	LIOS	Object key already exists

† Not extensively tested

Localisation Folder

Localization is treated as LIOS

Events Folder

Events are treated as FIOS

Tools & utilities

• Notepad++ - Powerful editor to change files.
• WinMerge - Contrasts the difference between two text files. Useful for updating mods.
• VS Code - Powerful, hackable, free open source editor from Microsoft.
• Maya exporter - Clausewitz Maya Exporter to create your own 3D models.
• Spaceship Generator - A Blender script to procedurally generate 3D spaceships
• Static Galaxy Generator - A static galaxy generator and editor for your mods. (How to use)
• Steam Workshop - The place for where you can share your creations with other players.
• Sublime Text - Powerful, moddable, hackable text editor. Install packages as your needs evolve.
• Stellaris Modding Subreddit
• The Stellaris Modding Den - the central modding discord for Stellaris.

External links

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

See also

• Mods

References

Modding