Modding

From Stellaris Wiki
Jump to navigation Jump to search

Version

Outliner top.png
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!

Guidelines[edit | edit source]

  • 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[edit | edit source]

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[edit | edit source]

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

Mod management[edit | edit source]

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 | edit source]

OS Path
Linux ~/.local/share/Paradox Interactive/Stellaris/mod
Windows …\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, 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[edit | edit source]

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.

Name Required Description Example
name Yes Name of your mod. name="My Stellaris Mod"
path modname.mod: Yes

descriptor.mod: No (Ignored)

Defines which folder is the mod’s folder. It can be an absolute directory or relative to the …\Documents\Paradox Interactive\Stellaris directory.
The Paradox Launcher will automatically correct a relative path to the corresponding absolute path.
Note: Stellaris uses (Unix) slash / instead of (Microsoft) backslash \ (or \\).
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. With the new 2.4 launcher, this must be a PNG file named thumbnail.png. picture="thumbnail.png"
tags No List of tags for Steam Workshop. Using tags besides the predefined ones may prevent uploading on Paradox Mods.
Warning: Maximal 10 are allowed (at least since launcher version 2022.10). Don't forget quotes for tags that contain spaces.
tags={
	"Tag1"
	"Tag2"
}
version No Specifies what the launcher will show as the version of the mod.
(Not the version of the game it’s meant for). Any string is accepted.
version="v.4.5"
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"

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

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[edit | edit source]

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[edit | edit source]

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:

# Launcher v1 (<=2.3.3) Launcher v2 (>=2.4.0) Launcher v⁇⁇
1 Launch the game
2 Navigate to the mods tab
3 Click Mod Tools Click Upload Mod
4 Click Create Mod 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 | edit source]

Uploading and updating a mod follows 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 you when it’s done or if an error occurred.
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!

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[edit | edit source]

Game structure[edit | edit source]

Below is a list of game files and folders, listed alongside the modding guide for each.

Stellaris/common/[edit | edit source]

Folder/File Summary Guides
agendas Agendas are given to leader-candidates in Oligarchic government-forms Agendas
agreement_presets Definitions for subject types.since v.3.4 Subjects
agreement_resources Definitions for subject types.since v.3.4 Subjects
agreement_term_values Definitions for subject types.since v.3.4 Subjects
agreement_terms Definitions for subject types.since v.3.4 Subjects
ai_budget Determine how AI should handle resources. AI
ambient_objects References used by code to spawn ambient objects Models
archaeological_site_types Definitions for Archaeological Sites to be discovered and delved by Science Ships. Ancestral Relics
anomalies Events that occur for research ships Anomalies
armies Definitions for army types Armies
army_attachments (Deprecated)
artifact_actions Definitions for Artifact Actions. Ancestral Relics
ascension_perks Definitions for Ascension Perks. Traditions
attitudes Definitions containing the restrictions for each attitude used by the AI AI
bombardment_stances Definitions of bombardment stances. Bombardment Stances
buildable_pops (Deprecated)
buildings Setup for buildings constructable on planets, and those given through events Buildings
button_effects Definitions for button effects. Graphics
bypass Definitions for bypasses (gateway, worm hole and l-gate) Bypasses
casus_belli Definitions for casus belli. Wars
colony_automation Definitions for colony autobuild types. Colony Automations
colony_automation_exceptions Definitions for colony autobuild types. Colony Automations
colors Color definitions used for the country color selection Countries
component_flags (Deprecated)
component_sets List of the sets of components used by ships Ships
component_slot_templates Slot templates to be used with ship sections. 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
decisions Definitions for planetary decisions. Decisions
defines Basic game behaviors and settings Defines
deposit_categories Deposit categories relevant to deposit generation. Planet Generation
deposits Setup for the deposits of resources found on planets as well as blockers spawned on habitable planets. Planet Generation
diplo_phrases Setup for the logic behind the diplomatic phrases used between countries. AI
diplomacy_economy Economy units based on diplomacy. Diplomatic upkeeps like influence upkeep of Federations are defined here. Diplomacy
diplomatic_actions Setup for the rules for diplomatic actions. Diplomacy
districts Definitions for districts. Buildings
economic_categories Definitions for economic categories. Economy
economic_plans Definitions for AI economy plans. AI
edicts Setup for the edicts used by 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
federation_law_categories Definitions for federation law categories. Diplomacy
federation_laws Definitions for federation laws. Diplomacy
federation_perks Definitions for federation perks. Diplomacy
federation_types Definitions for federation types. Diplomacy
galactic_focuses Definitions for galactic focuses relevant to the Galactic Community. Diplomacy
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 lighting used for ships, which differs between graphical cultures. Species
lawsuits Unused.
leader_classes Definitions for leader classes. Leaders
mandates Controls the mandates used by factions Mandates
map_modes Definitions for map modes to be used in the galaxy view. Map Modes
megastructures Definitions for megastructures. Megastructures
name_lists Sets up the names used for each species. Empire
notification_modifiers A variation of static modifiers. They have no modifiers and can only be added to empires. Static Modifiers
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.). Planet Generation
policies AI Policy grabbing (What order they take policies in) Policies
pop_categories Definitions for pop categories (social strata). Pop Jobs
pop_faction_types Population faction types and personalities Pop Factions
pop_jobs Definitions for pop jobs. Pop Jobs
precursor_civilizations Precursor civilization weightings Planets
random_names Lists of random names for Empires Gameplay
relics Definitions for Relics. Ancestral Relics
resolution_categories Definitions for resolution categories relevant to the Galactic Community. Diplomacy
resolutions Definitions for resolutions relevant to the Galactic Community. Diplomacy
scripted_effects Pre-defined blocks of Effects to be called elsewhere. Dynamic
scripted_loc Pre-defined methods to provide text based on the scoped object’s attributes. Dynamic
scripted_triggers Pre-defined blocks of Conditions to be called elsewhere. Dynamic
scripted_variables Pre-defined "@" variables to be called from other game files. Dynamic
section_templates Container of components that consist actual ships. Ship
sector_focuses Types of sectors and how they act. Colony Automations
sector_types Types of sectors and how they act. Colony Automations
ship_behaviours Standard ship behaviours. Ship
ship_of_size_limits Number of ships that can be built based on size_multiplier and naval_cap_div 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 (Deprecated)
special_projects Special Projects
species_archetypes Definitions for species archetypes to give some shared attributes to species classes. Species
species_classes Definitions for species classes that are sets of species portraits. Species
species_names Definitions for species random names. Species
species_rights Definitions for species rights. Species
star_classes Types of solar systems (NOT individual stars themselves!) Systems
starbase_buildings Definitions for starbase buildings that each starbase can only have one of each of them. Starbases
starbase_levels Definitions for starbase levels. Starbases
starbase_modules Definitions for starbase modules. Starbases
starbase_types Definitions for starbase types. To players, no effects, flavor only. To the AI, a starbase auto-build guide. Starbases
start_screen_messages Messages that should be shown to the player at the start of the game. Gameplay
static_modifiers Blocks of Modifiers to be added to objects. Static Modifiers
strategic_resources Definitions for resources, not just strategic resources. Economy
subjects (Deprecated) Definitions for subject types.since v.3.4 Diplomacy
system_types Definitions for system types. No effects, flavor only. Starbases
technology Definitions for technologies. Technology
terraform Definitions for terraform methods. Planets
trade_conversions Definitions for trade value conversions. Economy
tile_blockers (Deprecated)
tradition_categories Definitions for tradition groups. Traditions
traditions Definitions for traditions. Traditions
traits Definitions for species traits and leader traits. Traits
triggered_modifiers (Deprecated)
war_demand_counters (Deprecated)
war_demand_types (Deprecated)
war_goals Definitions for war goals. Wars
achievements.txt Definitions for achievements. Modding this file doesn't make sense, since achievements are disabled for any "common" changing/expanding mods anyway.
alerts.txt Messages
message_types.txt Messages

Stellaris/events/[edit | edit source]

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

Stellaris/flags/[edit | edit source]

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 | edit source]

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

Stellaris/gfx/[edit | edit source]

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 | edit source]

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 | edit source]

File Summary Guides
*l_simp_chinese.yml Contains Chinese localisation Localisation
*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 | edit source]

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

Stellaris/music/[edit | edit source]

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 | edit source]

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 | edit source]

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

Overwriting specific elements[edit | edit source]

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.[2] 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[edit | edit source]

Folder Overwrite Contents
Type Error Log Notes
achievements Achievements
agendas LIOS Object key already exists Agenda Agenda definitions and weights.
agreement_presets
since v.3.4
Functions are limited/restricted by:
diplomatic_actions and game_rules
Diplomacy isvassal.png Subject empire type definitions.
agreement_resources
since v.3.4
agreement_term_values
since v.3.4
FIOS Object with key already exists
agreement_terms
since v.3.4
ai_budget What fractions of its resources the AI wants to spend on things.
ai_espionage None (all content in subfolders)
├───operations
└───spynetworks
ambient_objects Graphics objects.
anomalies LIOS Object key already exists Message anomaly.png Anomaly description keys, images, spawn chances and conditions, and event pointers.
archaeological_site_types Archaeology map icon.png Archaeology Site definitions.
armies LIOS Object key already exists Army assault.png Army type definitions.
artifact_actions LIOS Object key already exists Minor artifacts.png Minor Artifact artifact action definitions.
ascension_perks LIOS [None]
since 3.X
Pre v.3.X: [Error log] Object key already exists Ap slot available.png Ascension Perk definitions.
asteroid_belts Planet asteroid.png Graphics for asteroid belts.
attitudes LIOS Object key already exists Diplomacy opinion.png AI Attitude definitions.
bombardment_stances LIOS Object key already exists Orbital bombardment type definitions.
buildings LIOS
since 3.3
Object key already exists Pre v.3.3: Breaks auto-generated modifiers Building Building definitions.
button_effects LIOS Object key already exists
bypass LIOS Object key already exists Bypass type definitions.
casus_belli LIOS Object key already exists Diplomacy status casus belli holder.png Casus Belli conditions.
colony_automation How player colonies controlled by automated sector management determine which districts and buildings to build. Each designation has its own script. Not used by AI empires.
colony_automation_categories LIOS Object key already exists Lists the categories of planetary automation that you can select in the planet interface
colony_automation_exceptions Job criminal.png Conditional overrides to automated sector management.
colony_types LIOS Object key already exists Colony type picker.png Colony Designation definitions.
colors RGB country and species color sets.
component_sets FIOS Object key already exists Component Ship component icon and frame assignment.
component_slot_templates Graphics assignments for weapon slot types.
component_tags Component List of referenceable tags assignable to ship components.
component_templates FIOS Object key already exists Component Ship component definitions.
country_container
country_customization Which capital building types and robot portraits empires use.
country_limits LIOS None (all content in subfolders)
├───ownership_limits LIOS Object key already exists ship_of_size_limits for each country type
└───ship_of_size_limits LIOS Object key already exists Number of ships that can be built based on size_multiplier and naval_cap_div
country_types LIOS [None]
since 3.X
Pre v.3.X: [Error log] Object key already exists Rules for empires, enclaves, and other country types.
crisis_levels LIOS Become the Crisis Become the Crisis ascension perk crisis level definitions.
crisis_objectives LIOS Menace.png Menace rewards for completing Become the Crisis Become the Crisis objectives.
decisions LIOS Object key already exists Decision default.png Decision definitions and AI weights.
defines LIOS [none] The block the define is in must be included as well.
E.g.: NGameplay = { POLICY_YEARS = 10 }
Global variables and settings.
deposit_categories List of orbital deposit and planetary feature categories.
deposits LIOS Object key already exists Orbital deposit, planetary feature, and blocker definitions and drop weights.
diplo_phrases Diplomacy alliance.png Diplomatic phrase keys and conditions for diplomatic actions.
diplomatic_economy LIOS Object key already exists Diplomacy alliance.png Diplomatic agreement costs.
diplomatic_actions LIOS Object key already exists Diplomacy alliance.png Diplomatic action conditions.
districts LIOS
since 3.3
Object key already exists Pre v.3.3: Breaks auto-generated modifiers District.png District definitions.
dynamic_text
economic_categories LIOS Object key already exists Empire economy.png Definitions and modifier generation for economic categories used by resource blocks and AI budgets.
  • Pop job.png Includes job categories and subcategories which determine which modifiers apply to which jobs
economic_plans AI empire resource income goals.
edicts LIOS Object key already exists Menu icon edicts.png Edict definitions and AI weights.
espionage_assets LIOS Entire override : PASS Spy network.png Espionage asset definitions.
espionage_operation_categories Spy network.png List of espionage operation and intel categories.
espionage_operation_types LIOS Entire override : PASS Spy network.png Espionage operation definitions.
ethics LIOS [none] Might break "selected ethic" graphic if too many Ethics; WARNING: Due to new multiple ethics files, the auto-generated file will randomly break off as some empires have no ethics when randomly generated. So entire overwrite is suggested. Default.png Empire ethic definitions and ethic attraction modifiers.
event_chains FIOS [none] Message event generic.png Event chain image assignment and referenceable counters.
fallen_empires Origins elder race.png Fallen empire definitions.
federation_law_categories Diplomacy federation.png Federation law category assignment.
federation_laws Diplomacy federation.png Federation law definitions and AI weights.
federation_perks Diplomacy federation.png Federation perk definitions.
federation_types Diplomacy federation.png Federation type definitions.
first_contact Firstcontact map icon.png First contact progression definitions.
galactic_community_actions GalacticCommunity mainButton single.png Costs to perform special galactic community actions.
galactic_focuses GalacticCommunity mainButton single.png Galactic focus definitions.
game_rules LIOS [none] Tooltip generating conditions.
global_ship_designs FIOS A ship design already exists Ship class Premade ship designs.
governments LIOS Object key already exists Government type conditions, ruler titles, and election candidate weights.
├───authorities LIOS Object key already exists Specific override is impossible. Entries override ONLY. Authority definitions.
└───civics LIOS Object key already exists Civic and origin definitions.
graphical_culture Graphics info for ship skins.
greeting_overlay_sounds
inline_scripts
since v.3.5
Inline scripts.
intel_categories Intel.png Which information is revealed by specific intel category levels.
intel_levels Intel.png Assigns intel category levels to intel level.
lawsuits Unused
leader_classes LIOS Object key already exists Menu icon leaders.png Leader type definitions.
mandates LIOS Object key already exists Mandate Mandate definitions.
map_modes LIOS Object key already exists Map mode definitions.
megastructures LIOS Object key already exists Megastructure definitions.
menace_perks Become the Crisis Become the Crisis perk definitions.
message_types Alert message icon definitions.
name_lists Sets of random names for ships, fleets, armies, planets, and leaders.
notification_modifiers
observation_station_missions DUPL/LIOS Entire override ONLY. Observation post mission definitions and AI weights.
on_actions NO/MERGE [none] Cannot modify existing entries; new entries will be merged with the existing entry with the same NAME={}.
Load order is top first.
Message event generic.png Assigns events to be triggered when certain game actions happen.
opinion_modifiers DUPL/LIOS [none] add_opinion_modifier is LIOS Diplomacy opinion.png Opinion modifiers and conditions.
personalities LIOS Object key already exists AI Personality definitions and weights.
planet_classes DUPL/LIOS [none] DUPL – breaks habitability modifiers if individually overwritten. Planet.png Celestial body graphics and definitions.
planet_modifiers LIOS Object key already exists Pm unknown.pngPm frame 2.png Random planet modifier spawn chances.
policies LIOS Object key already exists Existing Object key can be override with NAME = {} Menu icon policies.png Policy definitions and AI weights.
pop_categories LIOS Object key already exists Pop.png Pop category type definitions.
pop_faction_types LIOS Object key already exists Menu icon factions.png Faction demands, join conditions, attraction modifiers, and actions.
pop_jobs LIOS
since 3.3
Object key already exists Pre v.3.3: [Type] NO – Breaks auto-generated modifiers if overwriting a specific job and not the whole file. Pop job.png Job definitions and auto-assignment weights.
precursor_civilizations List of Precursor civilizations and conditions.
random_names Components for randomly generated Empire, Federation, Faction, First Contact, and War names.
└───base Lists of celestial object names and randomly generated species name affixes.
relics LIOS Object with key already exists Relic definitions and AI triumph weights.
resolution_categories GalacticCommunity mainButton single.png Defines which category individual resolutions are in and the category icon.
resolution_groups LIOS Object with key already exists GalacticCommunity mainButton single.png Assigns frames and text colors to resolution categories.
resolutions LIOS Object with key already exists GalacticCommunity mainButton single.png Resolution definitions and AI weights.
script_values LIOS Dynamically calculated referenceable values.
scripted_effects LIOS Object key already exists Scripted effects.
scripted_loc LIOS [none] Existing Object key can be override with name = key Dynamic localization.
scripted_triggers LIOS Object key already exists Boolean trigger conditions.
scripted_variables FIOS Variable name taken Global variables.
section_templates NO DUPL/FIOS Duplicate section template found. Multiple sections are named … Warning: existing can't be overwritten, used ships/starbases will get deleted. Ship class Ship section definitions.
sector_focuses LIOS Object key already exists Sector automation construction weights.
sector_types Sector definitions.
ship_behaviors FIOS Behavior name already exists Ship AI.
ship_sizes LIOS Object key already exists Ship class Ship chassis definitions, including Spaceport 1.png Starbases and spaceborne aliens.
situations Navbar icons situation.png Situation definitions.
solar_system_initializers LIOS Initializer already exists Predefined solar systems, some including country, colony, and/or fleet generation.
special_projects FIOS Object key already exists Point of interest galaxy.png Special project definitions.
species_archetypes LIOS
since 3.3
Object key already exists Pre v.3.3: Breaks auto-generated modifiers. Assigns Trait Point Trait Points and Trait sets to Species archetypes.
species_classes LIOS Object key already exists Assigns portraits, species archetype, and graphical culture to species classes.
species_names Lists for randomly generating species names.
species_rights LIOS Object key already exists Effect tooltips are independent of the effects. Species rights definitions and AI weights.
star_classes LIOS Spawn odds and planet generation rules and environmental hazards based on the central star or star set.
starbase_buildings LIOS Object key already exists Spaceport 1.png Starbase building definitions and AI weight modifiers.
starbase_levels LIOS Object key already exists Spaceport 1.png Starbase chassis definitions.
starbase_modules LIOS Object key already exists Spaceport 1.png Starbase module definitions.
starbase_types LIOS Object key already exists Spaceport 1.png Starbase designation conditions, AI ratios, and AI buildings & module weights.
start_screen_messages FIOS [none] The first valid part for each location will be used and the rest discarded without issue. Localization keys and conditions used to assemble the game start message.
static_modifiers FIOS [none] Modifier definitions.
strategic_resources FIOS [none] All resource definitions.
subjects LIOS [None] - REMOVED in v.3.4, s. agreement_presets Functions are limited/restricted by:
diplomatic_actions and game_rules
Diplomacy isvassal.png Subject empire type definitions.
system_tooltips Tooltips displayed when hovering over a system.
system_types LIOS Object key already exists System designation type conditions and weights.
technology LIOS* Duplicate technology: [tech] LIOS overrides mostly still work despite the DUPL-type error entry. However, if the overwriting tech lacks a "potential" block, it will inherit the "potential" block from the overwritten tech. Menu icon technology.png Technology definitions, drop weights, and AI weights.
├───category Menu icon technology.png List of research categories and icon assignments.
└───tier LIOS Menu icon technology.png List of technology tiers. Defines number of previous tier tech requirements.
terraform DUPL [none] Terraform planet 2.png Terraforming costs and conditions for every valid planet type pair.
trade_conversions LIOS Object key already exists Menu icon policies.png Trade Policy definitions.
tradition_categories LIOS Object key already exists Tradition tree definitions and AI weights.
traditions LIOS Object key already exists Effect tooltips are independent of the effects. Individual tradition definitions, including adoption and finisher effects.
traits DUPL/NO [none] Entire override ONLY. Species trait and Leader trait definitions.
war_goals LIOS Object key already exists Diplomacy status casus belli holder.png War goal definitions, conditions, and AI weights.

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[edit | edit source]

Localisation is likely LIOS

A guide for overwriting localisation can be found here.

Events folder[edit | edit source]

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)

Interface folder[edit | edit source]

Interface is likely LIOS

Fonts folder[edit | edit source]

Fonts is likely FIOS

Tools & utilities[edit | edit source]

Tools[edit | edit source]

Help links[edit | edit source]

Advanced tips[edit | edit source]

  • 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[edit | edit source]

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
  • reloadlocreload 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[edit | edit source]

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.[3]

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[edit | edit source]

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[edit | edit source]

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[edit | edit source]

See also[edit | edit source]

References[edit | edit source]

  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 siteDB Browser for SQLite
Empire EmpireEthicsGovernments • Civics • OriginsMandatesAgendasTraditions • Ascension perksEdictsPoliciesRelicsTechnologiesCustom empires
Pops JobsFactions
Leaders LeadersLeader traits
Species SpeciesSpecies traits
Planets PlanetsPlanetary feature • Orbital depositBuildings • DistrictsPlanetary decisions
Systems SystemsStarbasesMegastructuresBypassesMap
Fleets FleetsShips • Components
Land warfare ArmiesBombardment stance
Diplomacy Diplomacy • Federations • Galactic communityOpinion modifiersCasus Belli • War goals
Events EventsAnomaliesSpecial projectsArchaeological sites
Gameplay GameplayDefinesResources • EconomyGame start
Dynamic modding Dynamic moddingEffectsConditionsScopesModifiersVariablesAI
Media/localisation Maya exporterGraphicsPortraitsFlagsEvent picturesInterfaceIconsMusicLocalisation
Other Console commandsSave-game editingSteam WorkshopModding tutorial