Modding

CK3 Modding #1 -Brief introduction to modding. Mr Samuel Streamer (former Roll1D2 Games) guide on useful tools and how-to mod beginner's guide.

Modding, or creating mods, is the act of modifying the assets or behavior of the game either for personal use, or to release publicly to other players, for instance via Paradox Mods or the Steam Workshop.

As with all Paradox games, Crusader Kings III 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, cheating, etc.

This guide is intended to lower the entry barriers to the world of Crusader Kings III 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.

Important: the majority of mods will change the checksum, not allowing the player to get achievements. 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, shaders, fonts or music.

Tips & guidelines

• Create a mod for your modifications: use a personal mod even for minor changes, and never directly modify the game files in the CK3 game folder as they may be overwritten without warning.
• Use a good text editor to edit files and search through folders. The following are free:
  • Visual Studio Code. Has a fan-made CWTools extension with Paradox syntax highlighting, validation and tooltips for triggers and effects. To install it, go to Extensions on the left panel of VS and search for CWTools. (Note: validation rules are incomplete and will show many false errors in gui and localization files)
  • 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. Otherwise is very customizable. Choose Perl 6 (Raku) 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.
  • Sublime Text. There is an extension for it released by the developers of Imperator which could be used with CK3: Sublime Tools. It adds colored highlighting for effects and triggers. If you want to toggle comments in Sublime, you also need to add this file to the same "User" folder.
  • Intellij IDEA. Has a fan-made Paradox Language Support plugin with Paradox syntax highlighting and validation. To install it, go to File -> Settings -> Plugins and search for "Paradox Language Support".

• Start the game with -debug_mode launch option to instantly reload files and use the console.
  • On Steam: right-click the game on Steam -> Properties -> add -debug_mode to Launch Options at the bottom
  • Windows: Create a shortcut for the .exe file -> right-click it -> Properties -> add -debug_mode at the end of the Target field
  • Windows Xbox Game Pass: Open 'Command Prompt' and run 'start shell:AppsFolder\ParadoxInteractive.ProjectTitus_zfnrdv2de78ny!App -debug_mode’
• Always check the error.log file for execution errors. Documents/Paradox Interactive/Crusader Kings III/logs/error.log
• The log folder also contains lists of effects, triggers and scopes. Use "script_docs" and "DumpDataTypes" console commands in the game to generate them.
• The directory for the CK3 folder on Linux is ~/.local/share/Paradox Interactive/Crusader Kings III
• Communicate key facts about your mod clearly and succinctly:
  • Begin description with a short list of what your mod adds to or changes about the game. Add more detailed info at the bottom.
  • Clearly state whether your mod is compatible with achievements and ironman saves.
  • Provide links to your mod on other platforms (Workshop, Paradox Mods, forums).
• When possible, upload your mod to all platforms, especially if it is popular. Not everybody owns the game on Steam.
• Backup your work. Either manually or with a source control system like Git. Consider using GitHub and Discord for team collaboration.
• Remove your local copy of the mod when you subscribe to the Steam version, otherwise it will not work in the game. (removing the .mod file or changing its extension is enough)
• Use a proper merge tool (like WinMerge) to merge between folders and update modified files for a new patch.
• If you're replacing text across dozens or hundreds lines of code, regular expressions may save a lot of time. They are available in all of the text editors above. Learning resources: RegexOne, RegExr.
• Join CK3 Modding discord to ask any questions and help others
• 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.

Localization Files

• *.yml files in the localization folder must be saved with UTF-8 + BOM encoding to be read properly by the game.
• filenames need to be saved in the form as *l_<language>.yml for the game to read the file correctly. For example council_l_english.yml.
  • You must use the US spelling of "localization". The Commonwealth spelling of "localisation" will not work.
• To overwrite existing localization values, put your files with changes into a folder named "replace" within the localization folder.

Creating a mod

Main article: Mod structure#Creating initial files

It is recommended to use the game launcher to create initial mod files:

1. Open the game launcher.
2. Go to All Installed Mods on the left.
3. Press Upload Mod in the top right.
4. Press Create a Mod.
5. Enter a name, version of the mod (not the game), directory (the launcher will create it) and at least one tag. All of these must be completed before you can press Create at the bottom.
   • (Name must be at least 3 symbols long. DIrectory can include spaces, but cannot end with one.)

After this, copy the game files you want to edit to the created mod folder, following the same folder structure. For example, mod/my_new_mod/events/test_events.txt

Follow the links at the bottom of this page for more specific guides.

Uploading/updating a mod

Uploading and updating follows the same process:

1. Open the game launcher.
2. Go to All Installed Mods on the left.
3. Press Upload Mod in the top right.
4. Choose your mod from the dropdown menu.
5. Choose what platform to upload it to.
6. Enter any description. (If updating, make sure the launcher copied the most recent one from the site.)
7. Add a thumbnail
   • For the Steam Workshop, put thumbnail.png in the mod folder. Use 1:1 ratio, 1MB max. The biggest thumbnail the Workshop displays is around 600x600 pixels.
   • For Paradox Mods, drag the thumbnail to the field below the description. Suggested minimum size is 900x500, png or jpg, 1MB max.
8. Press "Upload".
   • On Steam, the mod will be uploaded in private mode and appear in your Steam Profile -> Workshop Items. Open it and change visibility on the side bar to Public to actually publish.
   • On Paradox Mods the mod will be published after the verification process. You may need to edit your description, as the site usually removes line breaks and BBCode formatting.

Installing mods manually

Mods are installed to your Documents/Paradox Interactive/Crusader Kings III/mod folder.

Every mod in it must have a .mod file and a folder. (For example, "Nameplates.mod" and "nameplates" folder)

From Forum

Modders will usually zip both the .mod file and the mod folder. In this case, you only need to unpack the zip file directly to your "mod" directory. If instead you see descriptor.mod and a number of other folders, continue to the next section:

From Paradox Mods

Mods downloaded from Paradox Mods only have the contents of the mod folder and require the following:

1. Create a new folder in your "mod" directory. Give it any name, like "my mod".
2. Unzip the downloaded mod directly to this new folder.
3. Copy descriptor.mod from it and paste to your "mod" folder.
4. Rename the copied descriptor file to anything.
5. Open it with a text editor and add a line path="mod/my mod" (where "my mod" is the name of the folder you created). Save the file.
6. After this, you should be able to add this mod in the launcher.

If this didn't work, you can try to create a new mod from the launcher and then copy the downloaded files to its folder (excluding descriptor.mod).

Extracting files From Microsoft Store version

If you want to read the files using the Microsoft Store version, you can use a program called UWPDumper to extract the files.

1. Download the latest x64 binary of UWPDumper
2. Enable Developer Mode (Windows Settings -> Update and Security -> For Developers -> Developer Mode).
3. Run CK3.
4. Run UWPInjector.exe from the program you just downloaded.
5. Enter the number next to ck3.exe : ParadoxInteractive.ProjectTitus_zfnrdv2de78ny as the processID.
6. Check where it is going to store the files (probably somewhere like C:\Users\%USERPROFILE%\AppData\Local\Packages\ParadoxInteractive.ProjectTitus_zfnrdv2de78ny\TempState\DUMP
7. Wait for the program to finish.

The files should then be present in the directory specified earlier. If you want to edit the files, create a mod and copy the desired files there.

Troubleshooting

Mods stopped working

For unknown reasons, mods sometime stop working. There are two ways to solve this:

• Reload from the launcher:
  1. Open the launcher
  2. Go to All Installed Mods on the left
  3. Press Reload Mods in the top right and Reload (Clearing cache doesn't seem to be necessary)
  4. Go to Playsets. The mod should have a warning saying the files aren't present on disk. Remove it from the playset.
  5. Close the launcher
  6. Resubscribe to the mod.
  7. Open the launcher and add the mod back again.
• If nothing helps, delete the following files if they are present and restart the launcher:
  1. Documents/Paradox Interactive/Crusader Kings III/mods_registry.json
  2. Documents/Paradox Interactive/Crusader Kings III/launcher-v2.sqlite

Tools & utilities

• Exporters (Maya and Photoshop)
• Community-made modding tools
• Clausewitz Maya Exporter: a tool to create and export 3D models to use in CK3 and other Clausewitz games.
• UWPDumper: a tool to extract files from Microsoft Store games.
• CK3 triggers, modifiers, effects, event scopes, event targets, on actions, code revisions and setup.log: List of valid inputs for most game versions since launch. Use GitHub file history feature to compare_versions.

Save game editing

> This doesn't seem to work anymore

Save files are located in:

• Windows: Documents\Paradox Interactive\Crusader Kings III\save games
• Linux: ~/.local/share/Paradox Interactive/Crusader Kings III/save games

First start the game in the debug mode and save. If it's an ironman game, exit to menu to autosave.

• On Steam: right-click the game on Steam -> Properties -> add -debug_mode to Launch Options at the bottom
• Windows: Create a shortcut for the .exe file -> right-click it -> Properties -> add -debug_mode at the end of the Target field

PC:

1. Find the save file in the save games folder.
2. If it was an autosave, skip to the next step. Else:
   1. Right-click the save file and extract it like an archive with 7-Zip or WinRar
   2. Rename the extracted 'gamestate' file to have a .ck3 extension.
3. Right-click it and open with a text editor (Windows Notepad is not recommended as the save files are very big).
4. Edit the file and save it.
   • To remove ironman status, search for "ironman=yes" and change it to "no"
5. Load it in the game.

Mac:

1. Open Terminal
2. Ensure that the directory is set to the correct folder
3. Type in "unzip FileName.ck3"
4. Rename the extracted 'gamestate' file to something with a .ck3 extension
5. Edit this plain-text save
6. Load it directly in the game (no need to re-compress)

OS	Save type	Location
Windows	Local	C:\Users\%USERPROFILE%\Documents\Paradox Interactive\Crusader Kings III\save games
Windows	Steam Cloud	C:\Program Files (x86)\Steam\userdata\####\1158310\remote\save games
Mac	Local	$HOME/Documents/Paradox Interactive/Crusader Kings III/save games
Linux	Local	$HOME/.local/share/Paradox Interactive/Crusader Kings III/save games

Contents of the gamestate file

The table below contains the possible first-level blocks in the gamestate file. Entries are provided in order of appearance.

Block	Description
meta_data	Contains metadata about the game, such as the game version. Used by the main menu screen.
ironman_manager	Related to ironman saving.
(various variables)	These variables do not belong in a block. Variable date bookmark_date first_start speed random_seed random_count
variables	Contains script flags.
game_rules	Contains the save's current game rules.
provinces	Contains province data, including buildings.
landed_titles	Contains the following sub-blocks: Sub-block Description dynamic_templates landed_titles (repetition) Contains an entry for each landed title in the game, in the format: # Exact formatting in file is different in terms of spaces and lines # It is usually more compact. # It has been edited here for clarity and demonstration. # Index for titles starts at 0 index={ key="(title id)" # The one used in 00_landed_titles.txt, e.g. k_england de_facto_liege=(title index) # Optional de_jure_liege=(title index) # Optional. The number at the start of a similar block, NOT the title id de_jure_vassals={ (title index...) } # Optional, list of title indices. holder="(character id)" # Optional name="..." adj="..." # Optional pre="..." # Optional article="..." # Optional date=2020.10.27 # yyyy.mm.dd heir={ (character id...) } # Optional. List of character ids. claim={ (character id...) } # Optional history = { (...) } # Optional capital=(province id) capital_barony=yes # Optional theocratic_lease=yes # Optional history_government="(government id)" # Optional laws={ "(law id)"... } # Optional. List of law ids. # Optional (succession_election). succession_election={ electors = { (character id...) } candidates={ (character id...) } nominations={ { elector=(character id) candidate=(character id) strength=(value) } } } # end of succession_election block coat_of_arms_id=(coat of arms id) localization_key="(localization key)" # Optional # All below is used for mercenary bands special={ type=mc identity=(id) } color=rgb { (r) (g) (b) } landless=yes destroy_if_invalid_heir=yes no_automatic_claims=yes definite_form=yes } In vanilla CK3, this block ends at entry ~12369. index=(value) (variable)
dynasties	Contains the following sub-blocks: dynasty_house (ends at entry ~6401) dynasties (ends at entry ~6239) static_dynasties (list of numbers) static_dynasty_houses (list of numbers)
deleted_characters
living	Contains entries of living characters. The following format is used for each character: index={ first_name="..." birth=(date) # Format: yyy.m.d female=yes # Optional was_playable=yes # Optional nickname="nick_..." # Optional culture=(culture index) # Optional if dynasty_house is specified, defaults to dynasty_house culture. Required if no dynasty_house, or culture different from that of dynasty_house. faith=(faith index) # Optional if dynasty_house is specified, defaults to dynasty_house faith. Required if no dynasty_house or faith different from that of dynasty_house. dynasty_house=(dynasty house index) # Optional, must specify culture and faith if omitted skill={ (diplomacy) (stewardship) (martial) (intrigue) (learning) (prowess) } # One value for each skill prowess_age=(value) # Optional. Negative value. dna="(dna string)" # Optional mass=(value) # Optional, exclusive with weight weight={ # Optional, exclusive with mass base=(value) current=(value) # Optional target=(value) # Optional } sexuality=(value) # Optional. Defaults to heterosexual. Valid values: ho, bi, as, none. None is for children under 10. traits={ (trait index...) } # Optional. List of trait indices. Typically omitted for young children. recessive_traits = { (trait index...) } # Optional. List of trait indices inactive_traits = { (trait index...) } # Optional. List of trait indices # Optional (family_data) family_data={ real_father=(character id) # Optional betrothed=(character id) # Optional primary_spouse=(character id) # Optional. Equal to one of the spouse ids. spouse=(character id) # Optional. First spouse spouse=(character id) # Optional. Second spouse spouse=(character id) # Optional. Third spouse spouse=(character id) # Optional. Fourth spouse concubine=(character id) # Optional. First concubine concubine=(character id) # Optional. Second concubine concubine=(character id) # Optional. Third concubine former_spouses={ (character id...) } # Optional. List of character ids former_concubines={ (character id...) } # Optional. List of character ids former_concubinists={ (character id...) } # Optional. List of character ids child = { (character id...) } # Optional. List of character ids } alive_data={ # Optional (variables), contains flags variables={ data={ # (...) } } # Optional (modifiers), various locations in alive_data modifier={ modifier="(modifier)" expiration_date=(date) } gold=(value) # Optional income=(value) # Optional location=(landed title index) # Optional stress=(value) # Optional fertility=(value) health=(value) piety={ currency=(value) accumulated=(value) # Optional. Devotion } prestige={ currency=(value) # Optional accumulated=(value) # Optional. Fame } focus={ # Optional type="(value)" # Education or lifestyle date=(date) changes=(value) progress=(value) } secrets= { (id...) } # Optional. List of ids targeting_secrets={ (id...) } # Optional. List of ids schemes={ (id...) } # Optional. List of ids targeting_schemes={ (id...) } # Optional. List of ids heir={ (ids...) } # Optional. List of ids pretender={ (ids...) } # Optional. List of ids claim={ { # Optional. List of claims title=(title id) pressed=yes # Optional } } used_punishments={ # Optional. List of reasons (value)={ imprisonment_reason=yes # Optional revoke_title_reason=yes # Optional } } lifestyle_xp={ # Optional diplomacy_lifestyle=(value) # Optional martial_lifestyle=(value) # Optional stewardship_lifestyle=(value) # Optional intrigue_lifestyle=(value) # Optional learning_lifestyle=(value) # Optional } perk={ ... } # Optional. List of perks prison_data={ # Optional imprisoner=(character id) date=(date) imprison_type_date=(date) type="(value)" # house_arrest or dungeon } weight_update=(value) # Optional kills={ (character ids... } # Optional. List of character ids pool_history=(date) # Optional wars={ (value) (value) (value) (value) } # Optional } # End of alive_data block court_data={ # All keys within this block are optional host=(value) employer=(character id) council_task=(council task index) special_council_tasks={ (value...) } army=(value) regiment=(regiment index) knight=yes wants_to_leave_court=yes leave_court_date=(date) } # Optional (landed_data) landed_data={ domain={ (landed title index...) } # List of landed title indices vassal_contracts={ (values) } # List of values units= { (values...) } # Optional last_war_finish_date=(date) # Optional last_raid=(date) # Optional became_ruler_date=(date) laws={ "(law id)"... } # List of law ids strength=(value) strength_for_liege=(value) # Optional liege_tax=(value) # Optional balance=(value) dread=(value) # Optional known_schemes={ (ids...) } # Optional. List of ids succession={ (character id...) } # List of character ids is_powerful_vassal=yes # Optional vassal_power_value=(value) # Optional domain_limit=(value) vassal_limit=(value) # Optional vassals_towards_limit=(value) # Optional government="(government id)" realm_capital=(value) ai_allowed_to_marry=yes council={ (value...) } # List of values at_peace_penalty=(value) diplo_centers={ (value...) } # List of values election_titles={ (landed title index...) } # List of landed title indices absolute_control=yes # Optional interaction_cooldowns={ # Optional (interaction)=(date) } } # End of landed_data block # Optional (playable_data) playable_data={ knights={ (character id...) } # List of character ids was_player=yes } }
dead_unprunable	Contains character entries.
characters	Contains the following sub-blocks: dead_prunable (contains character entries) prune_queue dummy_female (contains a character entry) dummy_male (contains a character entry) unborn (contains unborn data entries) natural_deaths current_natural_death sexuality_chances
character_lookup
units
activities
opinions	Contains the following sub-blocks: active_opinions (contains opinion entries)
relations	Encompasses hooks, alliances, Contains the following sub-blocks: active_relations
schemes	Contains the following sub-blocks: active (contains scheme entries)
stories	Contains the following sub-blocks: active (contains story entries) next=(date) (variable)
pending_character_interactions	Contains the following sub-blocks: data player
secrets	Contains the following sub-blocks: secrets (contains entries of secrets) (repetition) indices type target type identity=(id) owner=(id) relation_type participants = { (ids)} known_secrets = { secret=(id) owner=(id)
armies	Contains the following sub-blocks: regiments army_regiments armies
religion	Contains the following sub-blocks: religions faiths great_holy_wars holy_sites
wars	Contains the following sub-blocks: active_wars names
sieges	Contains the following sub-blocks: sieges (repetition)
raid	Contains the following sub-blocks: raid (repetition)
succession
holdings
ai	Contains the following sub-blocks: war_coordinator_db war_plan_db ai_stategies
county_manager	Contains the following sub-blocks: counties monthly_increase (list of values)
fleet_manager	Contains the following sub-blocks: fleets
council_task_manager	Contains the following sub-blocks: active
important_action_manager	Contains the following sub-blocks: active
faction_manager	Contains the following sub-blocks: factions
culture_manager	Contains the following sub-blocks: cultures template_cultures (list of numbers) era_discovery
mercenary_company_manager	Contains the following sub-blocks: mercenary_companies
holy_orders	Contains the following sub-blocks: holy_orders religion_name faith_name
coat_of_arms	Contains the following sub-blocks: coat_of_arms_manager_name_map coat_of_arms_manager_database (ends at entry ~17278) next_id=(id) (variable)
(triggered events)	Each triggered event has its own block, started using triggered_event={
next_player_event_id=(value) (variable)
played_character	Contains the following sub-blocks: name="..." (variable) character=(character id) (variable) player=(value) (variable) important_decisions legacy rally_points
currently_played_characters={ (character id...) }	List of character ids.

Mods with wiki pages

Wiki pages for modifications are the responsibility of the modification team, not the Paradox wiki team

• Way of Kings
• Kingdom of Heaven
• When the World Stopped Making Sense
• Princes of Darkness
• Elder Kings II

External links

• CK3 User Mods on the Paradox Forum.
• Crusader Kings official Discord modding channel. Go to the server-roles channel and choose CK3 Modding in the Channel Access post.
• CK3 Mod Coop A community Discord server dedicated to modding for CK3.

Modding

Map	Map • Terrain

Audio

Music • Sound

Mechanics