Enter your birth date

State your age before entering the gates to this website

Invalid date

We were unable to grant you access to the website.

Unfortunately, we were unable to grant you access to the website.


Dev Diary #37: Modding

News / 2020-08-11
Dev Diary #37: Modding

Hello everyone and welcome to the 37th CK3 Dev Diary!

I’m Matthew, one of the Programmers on the CK3 team, and today I am going to talk to you about the modding in Crusader Kings III!

Mods are something very important to the team and something especially close to my heart. I got started at Paradox as a Content Designer due to my modding work on Crusader Kings II, so being able to make sure the sequel has lots of modding opportunities and trying to give back to the community that aided me in getting into this industry is something I am very passionate about, and I know others on the team had similar starts in modding as well.

We’ve aimed to make the game a lot more open in terms of what can be achieved in modding: we’ve got over 80 database object folders (some even with sub-folders), a very versatile event system structure, a GUI system that can be fully changed, history files, localization, sound, music, and more! So huge parts of the game can be changed to suit your needs!



In the rest of this diary I’ll talk less about what you can do overall and more spotlight some things I think modders of CK2 will be excited about, as otherwise this diary would be huge and I need to get back to coding at some point.

At its core our scripting language in Imperator and Crusader Kings III is based on an in-house grand strategy library called Jomini, which acts as a more GSG focused layer used on top of our Clausewitz engine.

When Imperator released I posted a lot of information about the things that come directly from Jomini and which are shared between both games, so I would recommend checking out my Grand Jomini Modding Information Manuscript thread if you are an interested modder.

If you’d like to know more about event scripting then Dev Diary 30 had a very good coverage of that which you should check out!

Feel free to ask questions about both the linked threads in this one as well!

Character Interactions

To focus more on game level things, one of the biggest things changed from CK2 is the character interactions.

For a brief history lesson in CK2 modding, most of these core interactions were hardcoded, things like arranging marriages, declaring war, alliances etc. It was only after quite a few patches that the ability to add custom “targeted decisions” was introduced, and it’s worth noting that it was only the ability to add or modify those targeted decisions – the older hardcoded core interactions were still not particularly moddable.

For CK3 we wanted to open all of that up to go through one unified character interaction system, so every action goes through our script system now. This gives many benefits: with script being able to change it we can now change weights for the AI’s use of these actions with just a few text file changes instead of needing code time, we can change who can do them, and what people are considered good matches etc. And of course that opens it all up for modders as well.

The AI can also be scripted to use all of these custom interactions, tell them who’s a good target, as well as how often they should evaluate it (which is important for performance).

There are still some hard coded links with the interactions, specifically when it’s an interaction that’s needed to be used by the AI in a non-trivial manner. These interactions are all marked clearly, though, and if you attempt to remove them then the game will give you a warning when loading that it really needs this interaction so put it back please. This behaviour in fact applies to almost all hard coded database objects, not just those which are interactions.

For reference here is a full list of all the options interactions can use that impact how they are taken, received, responded to, shown graphically and used by the AI:

(To see the full list of options, please visit our Forums)


Combining Mods

Combining multiple mods together has always been a bit tricky but I wanted to try and make some gains with compatibility so that it doesn’t require as many manual patches. 

To aid in this a bit I’ve made it so database entries can be overridden by key even if that new entry is in a different file. This means if you want to override what the lunatic trait does then instead of needing to copy the entire traits file just to change one entry you can just make your own file just containing your new definition of what the lunatic trait does, such as giving it a boost in learning, prowess, and attraction opinion like I have done below!

This also applies to files from other mods, as long as yours is loaded first, so you can overwrite traits and other database elements from other mods

Currently we do not support appending to a definition instead of fully overwriting, as we’d need to rework a good chunk of things and test it extensively though it is something I am keeping in mind for the future.

Alerts, Issues and Notifications

As I mentioned in Dev Diary 16, all of the new interface utilities we have for explaining the game are moddable. Which means you can add, remove, and modify any of these things through script instead of them being hard coded like in CK2.

I’ll start with the notifications and toasts as they are the simplest. You simply make a database entry in the common folder for your notification and then wherever you want to run it from you use the send_interface_message or send_interface_toast effect.

Those effects take the type of message as well as optional overrides for the title and text instead of using what was scripted in the database. They can also take any number of effects to run which will then be included as text when displayed, though it is often recommended to use a custom tooltip instead of bloating the message with a lot of mechanical text.

For alerts, advice and current issues they all go through the same “important actions” system, the core difference between them is which type they are specified to use which controls their visual appearance and location.

These important actions have a check_create_action and effect block, both run interface effects (specially marked effects that do not modify the game state across MP but just local UI things) to see if they can be created and what to do when clicked.

The main interface effect to run in check_create_action will be the try_create_important_action which attempts to create a UI element for this action type and this will usually be behind an if check.

In the effect block for when the UI element is clicked there are a couple of things which are a good idea to run, if its a piece of reactive advice then using the start_tutorial_lesson is a great idea, and for alerts or issues then the open_view_data effect is the way to go to open the window that can help address whatever is causing the alert or issue!

Note: Whilst making this dev diary I actually found out that in 1.0 adding a custom icon like you see via a mod is actually not functional, it’s already been fixed for 1.1 but I thought I should note that here quickly for people coming back to this dev diary to tell me off when it doesn’t work right away.

The suggestions are similar to the important actions, but also have fields for the weight which checks how important the suggestion is to the player and a score which checks which potential target of a suggestion is best. 

For example, in the fabricate claim suggestion the weight is based on if there is anything nearby you could fabricate on, how many claims you already have, and if you are already fabricating a claim. The score for which title to suggest you fabricate is based on a much larger list of values such as the development level of the county, how easy it’ll probably be to conquer, if you share a faith or culture, etc.

Scripted GUIs

Like with Imperator the interface is incredibly moddable, the GUI scripting language whilst different from the normal database and event script is still very versatile and lets you change both the appearance and positioning and full functionality of almost all the GUI elements in the game. We also have a GUI debug mode in game which allows viewing through the hierarchy and opening to the file and line of where elements are defined which makes working with the interface a lot easier.

Currently we do not support creating your own new windows GUIs (though it is on my never ending to do list), but the easy work around there is just to make them as children of the main HUD window, which is always shown, and then you can have anything.

As is listed briefly in the Jomini Modding info I linked it is possible to make scripted GUIs, which allow a link to exist between the GUI system to the normal script system so you can test for if different triggers evaluate true or false and to run effects in the game state safely across multiplayer.

I am very excited to see what people end up doing with this especially, there should hopefully be a massive reduction in the number of hacks needed to display information now that real interfaces can be made for mods to show things about their unique mechanics.

Thanks for tuning in folks! I know this diary might have some more niche appeal, for those of you looking for a look at more gameplay then make sure to tune in for our next gameplay stream!

Click right here to join the Discussion on our Forum or on our Official Discord!

More news