Modding allows to change elements of the game or add new features.
Certain things are hardcoded, i.e. not available for modding, such as changing mapmodes and diplomatic actions or adding new hotkeys.
Improtant: the majority of mods will change the checksum, not allowing the player to get achievements. Loading an ironman game with such a mod will irreversably corrupt the save file, so be careful.
See "checksum_manifest.txt" in the game folder for the list of checksummed folders and files. The only safe mods are the ones that replace textures, fonts or music.
Tips & Guidelines
- Create a mod instead of directly modifying the game files, as they will be overwritten with any game update.
- Use a good text editor for syntax highlighting, autocompletion and search across multiple files. The following programs are free:
- Visual Studio Code. There is a fan-made CWTools extension for VS, which recognizes Paradox code language, will warn you of missing brackets and show information about scopes and effects in a tooltip. To install it, go to Extensions on the left panel of VS and search for CWTools. (Note: if the extension isn't up to date with the patch, it may show many false errors)
- Sublime Text. Imperator developers have released Sublime Tools with syntax highlighting and function search. In addition, to be able to toggle comments, you need to add this file to the same "User" folder.
- Notepad++. Choose Perl as your language, as it will provide good highlighting and allow to fold blocks of code and comments. To set it as default, go to Settings, Styler Configurator, find Perl in the list on the left and add "gui txt" (without quotes) to the "User ext." field at the bottom.
- Atom. Doesn't include UTF-8-BOM encoding needed for localization files. Choose Perl 6 as your language for better results. To set it as default, go to File, Config, find "core:" and add below it: "customFileTypes: "source.perl6": [ "txt" "gui"]", like in this example.
- Indent properly, so that opening and closing brackets are on the same level. Proper formatting will allow you to fold blocks of code, help spot any mistakes and make it easier to read.
- Add comments, starting with #, to remember later how things works, to navigate easier or to disable parts of code without deleting them.
- Use UTF-8 encoding for text files.
- Use UTF-8-BOM for localization files.
- Start the game with the "-debug_mode" and "-develop" options to use the console, dev tools and "reload" commands. See here how to add launch options.
- Use the error.log to catch any bugs. It's located next to the mod folder, in Documents/Paradox Interactive/Imperator/logs.
- Use "script_docs" and "DumpDataTypes" console commands in the game to generate other logs with event effects, triggers and scopes.
- Remove your local mod when you subscribe to the Steam version, otherwise it won't work.
- Clearly communicate to users whether your mod is ironman-friendly.
- Backup your work. Either manually or with a source control system like Git. Also consider using GitHub for team collaboration.
- Use a proper merge tool (like WinMerge) to merge between folders and update modified files for a new patch.
Creating your first mod
1. Start the game launcher, go to Mods, Mod Tools and fill in all the fields, including tags. Clicking Create will create a new folder and a .mod file in Documents/Paradox Interactive/Imperator/mod.
- "Version" refers to the game version this mod is made for.
- Folder name may include spaces, although it is common to use lower_spaces instead.
2. Copy the game files you wish to mod to your newly created mod folder or create your own files, while using the same folder structure.
- For example, if you want to mod the topbar, your should have the following: my_topbar_mod/gui/ingame_topbar.gui.
- If you want to add events to this mod, you would have my_topbar_mod/events/topbar_events.txt.
3. After modifying the files, enable the mod in the launcher and test it in the game.
- If modding UI, you can use "reload gui" command to see new changes without restarting the game. (This requires both -develop and -debug_mode launch options. See above how to enable them.)
- Remember to check the error.log for any errors.
4. To add a thumbnail for a mod, name your image "thumbnail.png" and put it inside your mod folder. Make it at least 200x200 pixels, so Steam doesn't add black borders around it.
5. To upload a mod, open the game launcher, go to Mods, Mod Tools, Upload a mod to Steam. Select your mod from the dropdown menu and click Upload. The description isn't necessary.
- You will find your mod in your Steam profile, Workshop Items. New mods are uploaded in private mode, so change their visibility to Public to actually publish them.
- Remember, remove your local mod folder if you want to test the Steam version of it, otherwise they will conflict with each other. You may simply move it, along with the .mod file, to another folder and move it back whenever you want to update your mod.
- To upload a mod to the Paradox mod platform, you will need to zip it first. Include both the mod folder and .mod file with its name in your zip archive. Then go to the site, click Upload and follow the instructions.
6. To update a Steam mod, simply open the launcher and upload it again.
(When you upload a mod for the first time, the launcher creates a descriptor.mod file in your mod folder which links to your Steam mod. This is what's used for updating, so don't remove this file.)
- Effects - Used in order to dynamically affect the game.
- Triggers - Used in order to execute commands/events/decisions/etc. only when certain things are true.
- Scopes - Used to specify the target of the effects and triggers.
- Modifier list - Script modifiers that affect aspects of the game.
- Defines - Global values used by the game in almost every aspect.
- Country list - Basic info on all countries in the vanilla game, including country tags.
- Console commands - Guide on how to use the games console commands.
The mod doesn't work after uploading to Steam
Check whether other mods work for you. If not and your Documents folder is not in the default place, the launcher can't find it.
You need to edit "launcher-settings.json":
- open the game directory (Right-click on Steam, Properties, Local Files, Browse Local Files)
- in the 'launcher' folder open launcher-settings.json with a notepad
- change gameDataPath to "%USER_DOCUMENTS%/Paradox Interactive/Imperator"
If this still doesn't help, try using the whole path, like "F:/Documents/Paradox Interactive/Imperator". Make sure you use forward slashes / and double quotes ".
The path in the .mod file changed to absolute
The new launcher overwrites the "mod/modname" path to the absolute one, like "C:/Users/User/Documents.../mod/modname".
While this is normal, for some modders it can prevent the game from loading the mod. To solve it:
- Change the path to relative again.
- Right-click the file -> Properties -> check Read-only.
This will prevent the launcher from editing it. Remember to disable read-only when uploading, since the launcher needs access to the file.
Tools & utilities
- Clausewitz Maya Exporter - A tool allowing for easier creation of 3D models (units) to use in mods for newer Clausewitz games.
- VS Code - Powerful, hackable, free open source editor from Microsoft.
- CWTools - An extension for VS Code that provides validation, completion, syntax highlighting and more for Paradox script files.
- Notepad++ Syntax Highlighter
- province setup converter 1.3.x -> 1.4 - A tool to convert old province data information from Imperator 1.3.x or using a province_setup.csv file into the text format for Imperator 1.4
- Forum modding guide: Imperator Modding Guide Index
- Imperator: Rome - User Mods - A subforum on the Paradox Plaza forums dedicated to user modding for I:R.
- Imperator Modding Coop - A Discord server dedicated to user modding for I:R.