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

****Modding****

## Guidelines

* **Create a mod for your modifications**: use a personal mod even for small changes, and never directly modify the game files in the Steam Stellaris folder, as they may be overwritten without warning.
* **Use a good text editor** (recommended: VSCodium or 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 at 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 also available 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 follows that pattern.
* **Use a proper merge tool** (like WinMerge, or the Visual Studio Code Extension L13 Diff ), 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.
	+ The Modding Git Guide is a community made guide for using Git, GitHub/GitLab, and related tools such as KDiff3. It can be a useful stop for questions beyond this wiki, and contains step by step guides for much of what is talked about here. Though the examples are HOI4 based, the principles apply equally well to any Paradox game mod.
* **Use UTF-8 encoding** for text and .mod files.
* **Use UTF-8 with BOM** for localization and name list 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 a # character, to remember your reasons for writing tricky stuff.

## A note for programmers

If a new modder has a programming background with languages like C, Java, and Python, they may find the structure of Stellaris script confusing. This is likely for two reasons:

* The Clausewitz Engine's scripting language doesn't separate basic syntax and keywords from game-specific structures and higher-level structures. For example, Triggers contains both the *`switch`* flow control structure and a conditional iteration *`any_playable_country`*, which are difficult to distinguish in form. Effects has both *`create_rebels`* and the *`while`* flow control.
* The scripting language uses the `=` operator for Boolean operations, assignments, scope changes, and for activating Triggers and Effects.

The following is a common example of valid structure:

```
capital\_scope = {							# change to the scope of the country's capital planet
	every\_deposit = {						# iterate through every deposit on the planet
		limit = {							# check each deposit for these conditions
			category = deposit\_cat\_blockers	# Boolean comparison using check the deposit's category
		}
		remove\_deposit = yes				# activate an Effect to cause a change
	}
}

```

For this reason, it is recommended that they follow the modding tutorial linked below and read the vanilla game files to better understand how the scripts function.

## Modding tutorial

There is a modding tutorial available which covers steps necessary to create a basic mod.

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

### Mod folder location

Mods from the Steam Workshop will be placed in `…\SteamLibrary\SteamApps\workshop\content\281990`, named by their Workshop ID.

Mods from Paradox Mods will be placed in the mod folder location, named `PDX_*MOD_ID*`.

### File and folder structure

Getting the structure set up correctly when creating a mod is essential 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. Ignored in the old launcher.
	+ `image.ext` – PNG and JPEG files are supported. With the new 2.4 launcher, must be a PNG named `thumbnail.png`

`modname.mod` and `descriptor.mod` both contain the mod information that the launcher uses when displaying the mod and uploading it.

The 2.4 launcher prefers `descriptor.mod` and will modify `modname.mod` to match the information in `descriptor.mod`, however if the file is not found, it'll use the information in `modname.mod`. The pre-2.4 launcher ignores it.

The `path="XXX"` is not needed in descriptor.mod.

Note that folder and file names are case sensitive on Mac OS X and Linux.

**modname.mod structure**

This also applies to `descriptor.mod`.

The data structure is similar to the proprietary Valve Data Format.

**Example modname.mod file `SomeMod.mod`**

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

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 512px × 512px at minimum, which is used by the workshop frontpage.

Additionally, the thumbnail file should be under **1 MB** in size, otherwise, it will not be uploaded.

Both JPEG and PNG are supported, and after 2.4, the image file must be named **thumbnail.png**.

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.png"` 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 (unless you are only a co-author).

### Creating a mod

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

 7 | Start modding!

### Uploading and updating a mod

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

Note that if you subscribe to an uploaded version of your mod while you still have the .mod file of your original mod in the mods folder, the uploaded mod will likely not work.

## Game data

* Console commands, useful for debugging mods.
* Defines, which allows you 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, listed alongside the modding guide for each.

## Overwriting specific elements

*See also: #Mod load order*

Occasionally, it is possible to overwrite a specific game element without needing to replace the entire vanilla file. In some cases adding an element with a similar identifier (id or key) 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 displayed order in the launcher (or loading template). Before patch 2.5 the load order was 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 arbitrary changes between versions.

### Common folder

FIOS – First in, only served.

LIOS – Last in, only served

DUPL – Duplicates

NO – Cannot individually overwrite

Please note that not everything could be tested extensively.

### Localisation folder

Localisation is likely LIOS

A guide for overwriting localisation can be found here.

### Events folder

Events are usually treated as FIOS (note: The error log will make it look like it is LIOS, but this is not true, it is definitely FIOS)

## Tools & utilities

### Tools

* Notepad++ – Powerful editor to change files.
* WinMerge – Contrasts the difference between two text files. Useful for updating mods.
* VSCodium – Powerful, hackable, free open source editor. Use with CWTools extension, powerful syntax checker for Paradox games.
* VS Code – Powerful, hackable, free editor from Microsoft (based on open source code). Use with CWTools extension, powerful syntax checker for Paradox games.
* Maya exporter – Clausewitz Maya Exporter to create your own 3D models.
* Spaceship Generator – A Blender script to procedurally generate 3D spaceships
* paint.net – Freeware software for digital photo editing
* Irony Mod Manager – Mod Manager with conflict solver for Paradox Games
* Stellaris Galaxy Generator – by BlackPhoenix134 (preview)
* Static Galaxy Generator – A static galaxy generator and editor for your mods. (How to use)
* Sublime Text – Powerful, moddable, hackable text editor. Install packages as your needs evolve.
* Random Empire Generator – by u/MarinusWA0.
* List of Stellaris triggers, modifiers and effects – for most game versions since launch, includes compare between Stellaris patches GitHub feature.

### Help links

* Steam Workshop – The place for where you can share your creations with other players.
* The Stellaris Modding Den – the central modding discord for Stellaris.
* Stellaris Modding Subreddit
* Paradox Graphics – A Comprehensive Guide – In-depth documentation for preparing 3d models for Clausewitz engine games like Stellaris.

## Advanced tips

* For the bigger mods using a source control management tool (Git, …), it is handy to create a symbolic link between Stellaris mod folder and the working directory of the local repository, especially if the mod also has sub-mods. Note that you'll still need to copy the .mod file(s) manually, but they rarely change. Run the following command from the parent directory of main git folder, replacing:
	+ <mod\_path\_name> by the value of `path` attribute from .mod file
	+ <git\_mod\_folder> by the name of the sub-folder that contain mod data (folders common, decisions, events, etc…)

```
mklink /J "%USERPROFILE%\Documents\Paradox Interactive\Stellaris\mod\<mod_path_name>" ".\<git_mod_folder>"

```

### Testing Mods

Certain, more obscure Console commands (that don't show up if you type 'help' in the console) are extremely useful in the process of testing a mod and more specific alterations.

* `observe` – switches you to Observer Mode. You will no longer play as any specific character – this will allow the game to run for a long period of time, uninterrupted. It also makes every invisible trait and secret religion visible.
* `run` <filename.txt> – runs script in a txt file located in the in the Documents install directory. It will be executed from the player’s scope. Useful for testing tricky scripts – you can just have the script open in a different window, run it, tweak the script, save it, and run it again – it will be recompiled every time.
* ~~`reloadevents` – reloads and recompiles every single event (may take a while depending on your hardware). Useful if you want to tweak an entire event or chain of events without rebooting the game every time.~~ not yet implemented
* ~~`reloadloc`~~`reload text` – reloads the entire localisation table. Useful if you spot a typo while testing your mod, or if you are trying to fit as much text in an event frame as possible.

### Troubleshooting mod installation

Multiplayer requires same mod list and load order for all players.

Try reload mods button in launcher. All installed mods > Reload installed mods.

Check if non-ASCII characters exist in the address of the mod folder.

Verify integrity of Stellaris installation files (for Steam right click on Stellaris > Properties > Local files > Verify). Warning: Verification tool does not check for any additional files put into the installation folder, and those might still alter the checksum. Check patch notes and compare your unmodded game (vanilla) with reference checksum.

Make sure your antivirus is not blocking the launcher. It might do so silently without a warning.

Check if your OneDrive ran out space or is disconnected if you are using it (you might not know that you are).

If you have a mod both as a local and as a workshop subscription game will refuse to load it. Remove or move one, including root `Stellaris/mod/*.mod` file.

If the local mod no longer appears in the launcher, a manual solution is to fix the overridden values (`dirPath` and `status`) in the `launcher-v2.sqlite`.
Delete Paradox Launcher database files as they might be corrupted (backup first):

1. Do the steps on point 5 at *#Purging all mods*.
2. In the Paradox Launcher use Mods > Reload installed mods.

If you are using Irony Mod Manager do not fire Conflict Solver unless you intend to use it. Conflict Solver creates list of conflicts and generates overwrites for each one based on your load order. So if you change mod composition of a collection or load order you have to rerun conflict solver each time (alternatively delete patch folder in /Stellaris/mod/)
You can purge Irony settings stored in .roaming/Mario/ if you ever need to.

### Purging all mods

This will reset your mod settings completely (nuclear option!):

1. Quit Stellaris and Stellaris (Paradox) Launcher
2. Unsubscribe from all mods. Stellaris Workshop -> Your files (under your avatar) -> Subscribed items – > Unsubscribe From All .
3. Quit Steam
4. Go to SteamLibrary\steamapps\workshop\content\281990 and delete everything.
5. Go to the Stellaris settings folder (one above the mod folder) and delete the following files (some of these might not be present in the actual version):
	* dlc\_load.json
	* game\_data.json (only pre 2.8 launcher)
	* mods\_registry.json (only pre 2.8 launcher)
	* launcher-v2.sqlite (since 2.8 beta launcher)
	* in settings.txt everything inside `last_mods={ }`
6. Restart Steam.
7. Open Paradox launcher.
8. Close Paradox launcher.
9. Resubscribe to your mods.
10. WAIT UNTIL ALL DOWNLOADS ARE DONE. DO NOT START PARADOX LAUNCHER UNTIL DOWNLOADS ARE COMPLETE.
11. Start Paradox Launcher.
12. Close Paradox launcher.

### Mod load order

Ordering mods incorrectly can lead to problems in game. Mods that edit the same game files will conflict. The following section will give general tips on load order and a general load order guide. Ordering mods correctly will reduce problems, but is not guaranteed to fix all problems.

*General Tips*
1. Mods at the top of the list are loaded first, mods lower down will overwrite.
2. Try to build a mod list around one or two large mods. Large mod examples are Gigastructural Engineering, ACOT, ZOFE, NSC, ESC, etc. Trying to make a mod pack function with many large mods requires advanced modding abilities such as custom coding/scripting. Load order correctness will only go so far.
3. Mods can be ordered in two ways.
	* Irony Mod Manager (IMM): In IMM mods can be ordered in the right hand Collection Mods panel. Mods can be moved by clicking and holding the left mouse button while dragging the mod up or down the list. A mod can also be moved by editing their order number, or moved to first/last position or moved up or down by one position using the arrow icons to the left and right of the mod number. Once ordering is done click apply.
	* Paradox Launcher: Similar to IMM you can drag a mod up or down, or renumber the mod to change its order.
4. Mods beginning with **~** go at the very top of the list.
5. Mods beginning with **!** go to the very bottom (some exceptions).
6. The more **!** a mod has the further down it goes (a **!!** mod will be below a **!** mod).
7. Mods that resolve conflicts (patch mods) between 2 or more mods go anywhere below the mods they patch. A section after all your normal mods is probably better for organization and visualization.
8. Mods that are submods go below the main mod. For example, Planetary Diversity would be higher in the load order, and the sub modules (such as Planetary Diversity – Exotic Worlds) go below Planetary Diversity main mod.

*General Order*
* Sort mods z to a – then move the mods around using the below list as a guide.
* The list is comprised of mod type categories. A mod category higher in the list has lower priority and will be overwritten by conflicting mods lower in the list. The numbers in the list do not indicate priority. For example, the mod category Unofficial patches is position 1. AI mods are position 2. AI mods are lower in the list, and as such will overwrite Unofficial patches if there is a conflict.
* Examples of mods that belong to a category will be given in brackets. The order of the mods in the bracket has nothing to do with load order, they are only examples of types of mods.

1. Unofficial patches always go at the very top (Ariphaos Unofficial Patch, Community Patch) (note that community flash patch reverts ariphaos fixes in a number of places. If not patching with Irony Conflict solver, don't use community patch.)
2. AI mods, which includes mods that edit AI economies (Starnet, Galvius, Better Ultimate Economic Plan, etc.)
	* It is highly inadvisable to use more than one AI mod, unless you know what you are doing.
3. Map generation mods (More Natural Looking Galaxies)
4. Prerequisite mods (Guillis Planetary Modifiers, Amazing Space Battles, SLEX)
5. Music mods (Space Ambient Music)
6. Namelist mods (Just Star Names, Lithoid Namelist)
7. Species mods (new species and edits to existing ones, such as Trace’s Better Necroids)
8. Trait and leader mods (Trait Diversity, Merged Leader Levels)
9. Content addition mods (Generally these are mods that add extra content to the game such as origins, events, archeology, stories. Examples include Precursor Story Pack, Origins Extended, More Events Mod)
10. Flag/Emblem mods (Just More Flags, StarClan Emblems)
11. Room/background mods (Diverse Rooms, Backgrounds Collection)
12. Cityscape mods (Collection of Cities, Interesting Cities)
13. Federation/Vassal mods (Exalted Domination – Vassals and Tributaries, Federation Expanded)
14. General gameplay mods that don't fit anywhere else (jump Gates, L-Cluster Access, Invasion! SA)
15. Shipset mods (Dark Necroid Ships, NSC and NSC submods. Put NSC below all other shipset mods)
16. Technology mods (Examples are Gigastructural Engineering, ACOT, ZOFE, Upper Limits, Technology Ascendant, Extra Ship Components (ESC) (if using ACOT and ZOFE, make sure to place the mod Acquisition of Technology (ACT) below them, and place ESC below ACOT, ZOFE and ACT)
17. Space affecting mods (Real space, Immersive Galaxy)
18. UI Overhaul mods (UI Overhaul Dynamic (UIOD), Tiny Ship Components)
19. Planetary Diversity and its submods
20. Tradition and ascension perk mods (Plentiful traditions, Expanded Stellaris Ascension Perks. These should go below UIOD but above their UIOD Patches)
21. Ethics & Civics mods (Ethics and Civics Redux, Civics Expanded – These should go below UIOD but above their UIOD Patches)
22. UIOD Overrides (Dark Blue UI Overhaul, Immersive Beautiful Stellaris/Universe)
23. Fix and tweak mods (Aggressive Crisis Engine, Necroids Bug Fix, Reduce Aura Graphics, Diplomacy Adjustments)
24. Patch mods (UIOD Patches, !Patch ESC Combined Ships in Scaling Lite, !Patch – Cubemap Fix, !!Universal Modifiers Patch, ! The Merger of Rules)
	* There are two types of patch mods. First are patch mods that resolve conflicts between several mods, for example Real Space (1) System Scale (2) Gigastructural Engineering (3) Patch.
	* Next, there are omnibus/general patch mods. These mods change game behaviour to account for many mods, for example The Merger of Rules, Universal Resource Patch.
	* Place omnibus/general patch mods BELOW patch mods that resolve conflicts for a few mods.

## External links

* Stellaris Dev Diary #31: Modding (Scripting Anomalies)
* Stellaris Dev Diary #32: Modding art
* Stellaris Dev Diary #182: The Perils of Scripting and How to Avoid Them
* Stellaris Dev Diary #204: Scripting Language and Moddability Improvements
* Stellaris Dev Diary #240: Scripting Improvements in 3.3

## References

1. ↑ VDF is a ad-hoc file format designed by Valve to support storage of hierarchical data, which is also used by Steam. Open VDF parser: https://github.com/rossengeorgiev/vdf-parser/, for .NET
2. ↑ forum:990537
3. ↑ Official SQLite site – DB Browser for SQLite

****Modding****