• We have updated our Community Code of Conduct. Please read through the new rules for the forum that are an integral part of Paradox Interactive’s User Agreement.

Crusader Kings 3 Dev Diary #30 - Event Scripting

Welcome, comrades, to another dev diary! Today, we’ll be taking a look at the structure of an event in CK3, how they’re assembled in script, and how they differ from CK2.

Anatomy of an Event
The core of a standard character event is almost certainly quite familiar to you already: we have a title, a description, typically a portrait, and one or more options along the bottom.

In script, however, we’ve changed a few things around, looking to improve functionality, readability, and general script hygiene over time. Here’s a comparison of the start of an event in CK2 vs. CK3:
001.png


The first change you’ll notice is that we’ve swapped the event type and the event ID: an event is now created by a namespace (still defined at the top of each file) and unique ID, and the type defined inside the event, rather than the inverse. This means that you can now still read event IDs after folding the events themselves!

002.png


Next, is that we’ve changed how triggered text works. In CK2, this was a really useful tool for ensuring that flavour was localised appropriately to the player’s situation, and let us make events very broadly applicable whilst still feeling unique. It could, however, get a bit cumbersome, since we had no method for triggered text to be easily mutually exclusive, occasionally leading to situations like this:
003.png


Not the worst in the world, but pretty chonky for what we actually want it to do.

In CK3, we can cut this down by using a first_valid block inside triggered text blocks (as in the first image shown), picking the first entry from a list which meets a set of criteria. This means that, instead of having to make sure triggered text blocks are always mutually exclusive according to a trigger (and one which tends to increase in complexity along with the number of triggered texts), we can just order our preferred text logically according to fairly simple triggers.

For instance, if I have a triggered text block where the copy is different for a French character, an Ashari character, and a character who’s over eighty years old, with a fallback for anyone who doesn’t fit into those categories, I’d script something like the following:
004.png


This will then automatically proceed down the list. A French character would see one thing, a non-French Ashari would see another thing, a non-French non-Ashari who’s over eighty would see a third thing, and everyone else would see a fourth. This makes it incredibly easy to add new context-sensitive copy to both event descriptions and titles.

A further minor point, but as triggered text is now also kept within the body of a superior block, it’s far easier to sort on the fly: no matter how much triggered text you have, it’s just one click to collapse the body in your file editor of choice, not a dozen or more. When minimising clicks, every little bit helps!

Event Themes & Backgrounds
A couple of notable absences in the CK3 format are the picture & border blocks.

Well, that’s with good reason! These have mostly been subsumed into the new event theming system, which you can see in the very first CK3 script example above.

Themes are what decide on the event icon displayed in the top-left, helping to group together broadly-thematic sets of events, and to let the player know what they can expect an event to relate to. They also give us a default appropriate image background (which, itself, sets the lighting used on the character portraits), which will change according to your situation, and different sets of ambient SFX.

Backgrounds and theme icons can be overridden as necessary via a manual line of script if we feel like we’ve got a more appropriate one to show, too, so although the system is set-up to reduce the amount of work that goes in to adding extra flavour to each event, we still have total control over what flavour we actually include should we want it.

Needless to say, event themes are fully scriptable: you can mod in whatever icon, default background, character model lighting, & ambient SFX you like, as well as create and adjust themes with ease.

Portraits & Animations
The good stuff! Portraits in the new system are, very surprisingly, somewhat more dynamic than in CK2, and any given event can have between 0 and 5 total portraits present. Of these, two are fully animated (positioned to the left and the right, respectively), and three are headshots lined up evenly along the bottom of the event. These can be used in any combination you like to get just the right look for an event.

005.png


The left and right portraits can use any of a fairly wide array of animations created for release. Headshots are not animated, instead allowing you to visualise ancillary characters mentioned in the event’s description.

On Actions for All!
All events come from somewhere, and, in CK2 (especially earlier in the title’s life cycle), this was often done through the Mean Time To Happen system, which let us define roughly how long an event would take to fire in (typically) months. Unfortunately, when balancing extremely large numbers of events against each other, the flexibility of this system becomes more of a disadvantage than anything else, making it difficult to govern how frequently an event should spawn without particularly stringent triggers. It also caused a lot of weird statistical anomalies due to working off of pure probabilities, and absolutely tanked performance.

Over CK2’s long life, we started to move more towards triggering events via on_actions, small hooks in code attached to features or regular pulses that activate events (and, if necessary, effects) whenever that hook is called. These take a bit more work to balance, but give us much more control over how and when events are called, as well as making tweaking such significantly easier, and are super fast performance-wise.

For CK3, we use entirely on_actions to fire events. There’s quite an array hooked up from code, allowing us to trigger events either when a specific action occurs in the world (e.g., when a character is born) or on a regular pulse (e.g., every five years). These can be set to go off every time that on_action fires, or placed in a weighted list of potential events that might fire (in which case, weight multipliers still apply and support the usual factors and such).

One major improvement over CK2’s on_actions (other than a more thorough, rationalised system of use, which I think is very exciting but I also appreciate that other people lead much more interesting lives than me and may have stricter standards) is the addition of scripted on_actions! These allow us (and, of course, you!) to create and hook up on_actions entirely in script that behave as regular on_actions, instead of always having to rely on the hard-coded on_actions. Scripted on_actions then behave exactly as coded on_actions, acting as a complex of weighted & unweighted events/effects, just called from somewhere in the accessible-script rather than the inaccessible-code.

For instance, say I’ve made a new set of events about reconciliation after a civil war, neighbours learning to live side by side with each other after fighting for opposite lieges, that type of thing, and I want to hook it up to happen whenever a civil war ends. All I have to do to set up that flow is add something like this to the relevant war end effects:
006.png


And then create a file including this in the appropriate directory:
007.png


Anywhere that you can script an effect, you can script a reference to a new (or existing scripted) on_action.

The Immediate Block & You
A major new addition to CK scripting, which we use with extreme regularity in the immediate block, is the scripted list!

These allow us to sort through various groups, pick out relevant characters matching a set of criteria, and then sort within the list of relevant characters only with ease.

For instance, let’s say I want to grab every ornery old man from amongst my vassals and courtiers, I’d write something vaguely thus:
008.png


And then, I want to pick out the two angriest and orneriest from amongst them so that I can have them get into an argument in an event or what have you:
009.png


Sorted! I can then refer to these two characters in my localisation, apply effects to them, make them portrait characters, etc., as needed. You may note our cool new alternative_limit functionality: these are limits which are checked if the limit immediately above them fails.

That said, we’re all about minimising unnecessary maintenance and nipping potential bugs before they exist, and this script should still be setting off alarm bells, what with calling two separate lists that use the same conditions, which are, themselves, part of a separate scripted trigger.

There are a few ways we could solve this, but let’s go for showing off some new functionality, with the ordered_in_list effect:
010.png


Ordered_in_list takes a list, and, using a system called script_maths (which we’ll hopefully have time to talk about another time), assigns numerical values to items in that list. It then applies any effects in its block as normal to, by default, the highest valued item in the list (though, as here, we can tell it to apply its effects to any number of items in the list). Here, we were sorting a relatively small amount of list items by a fairly limited set of factors, but this sorting functionality can be as complex and as extensive as you require.

In other immediate block-related news, we’ve also made it easier to save scopes (formerly event targets, which you can see a bit of in the above example), and variables, and customarily use this block to define musical stings for maximum drama. Standard immediate block functionality (being executed before the event is displayed) is unchanged, and visible effects executed in the Immediate will be shown under a “Has Happened” header in all event option tooltips.

Options: Giving the AI Personality & Stressing Out Players
Finally, options. Options behave similarly to CK2, with a minimum of one per visible event and each option requiring a text label, but otherwise allowing you to enter any and various effects you fancy.

011.png


The two main additions to this area that you’ll notice are a drastically expanded use of ai_chance, and, fairly commonly, stress_impact.

AI chance, as in CK2, governs the approximate chance that an NPC character will pick that option. In CK3, we’re making much more extensive use of this block, and of our exposed ai_value_modifiers (building a personality for each character based off how much/little of each value they have, in turn derived mostly from their traits) to ensure that characters act in accordance with their personality as much as possible by weighing almost all event options up or down based on appropriate ai_value_modifiers. The block still takes other triggers as well, so we can have the AI prefer an option more or less based on traits, if they’re at war, if the option relates to a rival, etc.

Stress_impact, meanwhilst, is how we organise the new stress mechanic, which you may remember from some diaries ago! Don’t stress (*ahem*) if you don’t: stress is, in a nutshell, a measure of negative effects that your character gains when performing actions that run contrary to their personality (e.g., a compassionate character does not enjoy torturing people).

We check for that here, by filling out the stress_impact block with any personality traits relevant to picking a particular option, and using the scripted stress_impact values. Due to sorcerous automagic, we can combine any number of stresses gained and lost in the stress_impact block, and it’ll be calculated on an event option into one number.

You can also add stress as an ordinary effect, outside of the stress_impact block, in which case it will not combine. If desired, you can even add multiple stress impact blocks, which will only combine the individual stress modifiers, or you can omit the block entirely. Whatever floats your scripting-boat.

And, with that, we come to the end of another dev diary. I’ll be around for a couple of hours to answer any questions you might have, and we look forward to seeing you ne-

A-aren’t you going to cover Triggers?
Ha, you fell for my cunning plot-twist. Hands up anyone who noticed the stealthy trigger spoiler in an earlier screenshot, you win exactly one internet point!

For everyone else, let’s have that screenshot again:
012.png


Now, a quick recap: scripted triggers in CK2 were a way of grouping a long list of requirements together under a single reference, and then referring to that reference when needing to check things.

For instance, say I have two places in an event where I need to check 20+ conditions: the event will be perfectly functional if I script all those conditions out twice, but what if someone in the future updates one set of triggers but not the other? Instant source of bugs. Now, what if I have to check those triggers more than twice, or across multiple events, or, for maximum-sadism, across multiple events in different files?

As you can imagine, that rapidly devolves into chaos. However, we don’t want to use less complex triggers, partially because that makes the title worse and less fun for everyone (is it really CK without ludicrous amounts of specificity?), and partially because that’s only reducing the scale of the problem, not fixing it.

Instead, we’d create a scripted trigger, which is the list of triggers written out once in a file that can be referenced by other files. Then, in any spot needing to check those triggers, we call the scripted trigger, which checks its contents. Any time the triggers need updating or fixing, simply fix the scripted trigger once, and, typically, all subsequent places that check the scripted trigger have been fixed by proxy also. Instant maintenance savings, immediate huge reductions in bug potential!

However, in CK2, these scripted triggers had to be stored inside a specific folder in /common, separate from the events (and other script) that they referenced. This may not sound like a huge deal, but it adds a bit of extra leg-work to creating and maintaining scripted triggers, and only really gives you a huge list of scripted triggers, some of which may be used only a few times in a couple of places.

In CK3, we’re improving on this by adding inline scripted triggers, meaning scripted triggers that can be written directly into the file that uses them, provided they are only used in that file. For more utilitarian scripted triggers that need to be used across multiple files, the old folder system still works. This lets us split up major and minor scripted triggers, and use scripted triggers (and, for that matter, scripted effects) significantly more thoroughly throughout the title, making it markedly easier for us (and you!) to create script that doesn’t compromise on complexity or detail whilst still being easy to maintain.

And with that, we come to the actual end of the dev diary. We look forward to seeing you next week!
 
  • 87
  • 60Like
  • 33Love
  • 5
  • 1Haha
  • 1
Reactions:
- Is event_target still around and has there been any important changes to how it works?
They are called saved scopes these days, mainly cause event target got conflated with what that means in code and script documentation, they function pretty much the same you do save_scope_as = name to save them and then scope:name to find them.

- Is there still a basic yearly, bi-yearly, every five years, etc. on_actions in vanilla, as well as a a startup on_actions in vanilla that will allow us to trigger events at the start of the game?
We've got those sorts of pulses and startup on actions still yes

- Are pre-triggers still in?
No, they proved to be fairly unnecessary when you don't use mean time to happen for everything so aren't checking lots of things regularly all the time to the point that going into the script system to evaluate triggers becomes a noticeable overhead.

- On a related vein, in CK2 a common scripting sleight of hand was to have the Pope trigger certain maintenance or narrative events since he's always around - will CK3 use a similar system or is there something in-built to take care of those kinds of situations?
There is a yearly_global_pulse which is fired one on Jan 1st every year and has no scope set as root or any saved scopes, that can be used as a master caller to run maintenance effects and trigger events reliably instead of needing to use a character as a dummy stand in like the Pope.

- Does the code for creating characters differ in CK3 from CK2 significantly, and/or has any new functionalities been added to it?
There are a fair few more bells and whistles on it, mainly to make it generate better random characters in an entire culture group or inheriting a dynasty into a new house and being able to be given random traits from a list of valid ones.
To make it a bit easier to generate nicer random characters more easily there is also a new database of scripted character templates so you can make something like new_warrior_character as a template and give them a list of things you want them to be able to get for example always giving them a martial education and a lifestyle trait that is military or fighting based as well as being able to specify some min-max bounds for martial skill and prowess.
The rest of the character's info will be determined via defaulting to whoever employs them for things like faith or specified/overridden in the create_character invocation in script.
 
  • 6
  • 3Like
Reactions:
I understood very little of all this but what I understood looks good, the life and history of our characters can be more entertaining and the mods will be much better done.
I do not understand people who complain or who say it is useless, this affects gameplay a lot.
 
  • 2Like
Reactions:
I, uh, am having an increasingly hard time keeping my expectations to a reasonable level.

Given the way event IDs are now defined, I wonder if something was done about the override of individual events. In CK2, this would require overriding the entire event file, with produces a lot of pointless incompatibilities and maintenance. Being able to redefine an event from scratch, by simply reusing its ID in another file, would already be a huge improvement.

I have a similar question about scripted triggers/effects/scores. In CK2, all scripted blocks with the same name would be appended together by file load order, which allowed for some hacks but was just clunky and counterintuitive more often than not. Is there any change in that regard?

Finally, it appears that the new inline scripted blocks are tied to files. Wouldn't it make more sense for them to be assigned to the namespace instead?
 
  • 2Like
  • 1
Reactions:
We'll all spend countless hours playing mods and total conversions.

So this Dev Diary just tells me that these mods will be even better due to the enhanced scripting. And what not.

Now this excites me more than CK3 itself.
 
  • 2
  • 1Like
Reactions:
There is a yearly_global_pulse which is fired one on Jan 1st every year and has no scope set as root or any saved scopes, that can be used as a master caller to run maintenance effects and trigger events reliably instead of needing to use a character as a dummy stand in like the Pope.
Thanks a lot for that!
 
  • 1
Reactions:
They are called saved scopes these days, mainly cause event target got conflated with what that means in code and script documentation, they function pretty much the same you do save_scope_as = name to save them and then scope:name to find them.


We've got those sorts of pulses and startup on actions still yes


No, they proved to be fairly unnecessary when you don't use mean time to happen for everything so aren't checking lots of things regularly all the time to the point that going into the script system to evaluate triggers becomes a noticeable overhead.


There is a yearly_global_pulse which is fired one on Jan 1st every year and has no scope set as root or any saved scopes, that can be used as a master caller to run maintenance effects and trigger events reliably instead of needing to use a character as a dummy stand in like the Pope.

THanks for the quick responses, looks all good to me! The yearly_global_pulse seems like a simple but good solution for the Pope sleight of hand.

There are a fair few more bells and whistles on it, mainly to make it generate better random characters in an entire culture group or inheriting a dynasty into a new house and being able to be given random traits from a list of valid ones.
To make it a bit easier to generate nicer random characters more easily there is also a new database of scripted character templates so you can make something like new_warrior_character as a template and give them a list of things you want them to be able to get for example always giving them a martial education and a lifestyle trait that is military or fighting based as well as being able to specify some min-max bounds for martial skill and prowess.
The rest of the character's info will be determined via defaulting to whoever employs them for things like faith or specified/overridden in the create_character invocation in script.

Couple follow up questions to this:

- So if I understand it there won't be the CK2 system where it's create_character and then five different types of create_character for every attribute/education type (i.e. create priest, create soldier, etc.), and instead I can make a custom create_character like, for example, "new_hot_character" which will make a character that always as a minimum has traits to make them attractive?
- When you say there's a database of scripted character templates, do you mean there's a unique file or folder that is focused purely on scripting new character creation templates, or this is more just a standard scripted effect?

Thanks again for the response!
 
Will the Pope be given more to do?: As of CK2, he only seems to Call for Crusades-something he can only do once every ten years, I think-and Excommunicate Rulers.

If the Pope is given more things to do every year, he might Excommunicate less...
 
This, while certainly useful, is NOT the thing you should feed to the fans you are already blueballing harshly by lack of any new materials not even 3 months before release.

Edit: Wow, just wow. Your hype denial is over 9000 at least.
 
Last edited:
  • 29
  • 1
Reactions:
NOT the thing you should feed to the fans you are already blueballing harshly by lack of any new materials
Dunno this is pretty great because it reinforces the fact that modding will be expanded upon in CK3. I guess if you don't use mods its not exciting.

Not sure about the lack of new materials thing though, all the dev diaries so far have been quite good. And thats coming from someone who read all the previews and watched all the videos of CK3.
 
  • 8
  • 1Like
Reactions:
This, while certainly useful, is NOT the thing you should feed to the fans you are already blueballing harshly by lack of any new materials not even 3 months before release.
Dunno this is pretty great because it reinforces the fact that modding will be expanded upon in CK3. I guess if you don't use mods its not exciting.
This dev diary isn't just an indication of new modding features (though they are extremely exciting for the many modders and their many more players) but also a general indication of CK3's new scripting capabilities, hygiene, and performance over CK2. Exciting news for anyone interested in (script-related) performance improvements, new capabilities, ease of future bug fixing, integration of future features with existing content (I'm looking at you personal combat skill rebalancing), and the ability of both Paradox and modders to make as much quality content as possible in a given time period that will require as little revisiting in the future to be integrated with later additions. Some parts of the line-by-line might not be relevant to everyone, sure, but the gist of the information presented here is something for everyone to be excited about
 
  • 7
  • 2Like
  • 2
Reactions:
This, while certainly useful, is NOT the thing you should feed to the fans you are already blueballing harshly by lack of any new materials not even 3 months before release.
Wrong.
 
  • 6
  • 1Like
Reactions:
Well, this is an interesting dev diary. So it is cleaner version compared to CK2. This is always nice. Good job and I am looking forward how this will pan out.

It should also make modding a bit easier I guess. Maybe I should reactivate my rusty script skills to mod my wish for the three-way-split for the Soumensko faith in that I wanted.

Edit: I just realized that there is no post about this on twitter? Also looked at facebook. Is the Social Media team asleep with this DD?
 
Last edited:
- So if I understand it there won't be the CK2 system where it's create_character and then five different types of create_character for every attribute/education type (i.e. create priest, create soldier, etc.), and instead I can make a custom create_character like, for example, "new_hot_character" which will make a character that always as a minimum has traits to make them attractive?
Exactly! There is a line in the effect where you would do template = new_hot_character and that will then be the base for them

- When you say there's a database of scripted character templates, do you mean there's a unique file or folder that is focused purely on scripting new character creation templates, or this is more just a standard scripted effect?
Its a unique database folder, common/scripted_character_templates, where the entries made in files there have a key and then all the various values you want and can use it in the effect like I mentioned above by doing template = key_of_entry.
 
  • 10
  • 4Love
Reactions:
However, in CK2, these scripted triggers had to be stored inside a specific folder in /common, separate from the events (and other script) that they referenced.
Good to see

This was very annoying when I wanted to edit some portrait triggers for personal use, since editing common changed checksum (whereas portrait triggers did not), thus needing a big copy operation.
 
  • 1
Reactions:
Exactly! There is a line in the effect where you would do template = new_hot_character and that will then be the base for them


Its a unique database folder, common/scripted_character_templates, where the entries made in files there have a key and then all the various values you want and can use it in the effect like I mentioned above by doing template = key_of_entry.

Oh wow this is really, really handy, as I make quite a bit of use of create_character in CK2 currently, and while the current system works it can be clunky if you're doing more complex things with it as you probably well know. Thanks for the clarification!
 
  • 2Like
Reactions:
boring
 
  • 28
Reactions: