Crusader Kings 3 Dev Diary #30 - Event Scripting

Crusader Kings 3 Dev Diary #30 - Event Scripting

  • Pre order now!

    Paradox Development Studio brings you the sequel to one of the most popular strategy games ever made! Crusader Kings III is soon upon us and you can pre order it today!


    Releasing September 1st 2020

Wokeg

Juniorest Content Designer
May 14, 2018
49
778
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!
 

Wokeg

Juniorest Content Designer
May 14, 2018
49
778
well you found me...
The best development diary thus far :D
Very glad of these improvements on the scripts.This will make CK3 more moddable than CK2 and easier.Keep up the good work.
<3

Helpful for modders I guess, but not much for the rest of us who hunger for CK3 info.
:p You're not wrong, though I hope it's still interesting for people who like to see how the sausage is made, but modders deserve love too!

The thing I'm most excited about is that French culture is referred to as french, and not frankish
^^ Well, I'm happy that ye're happy.
 

Naggym

Recruit
151 Badges
Feb 3, 2013
4
7
  • A Game of Dwarves
  • Age of Wonders: Planetfall Season pass
  • Imperator: Rome - Magna Graecia
  • Arsenal of Democracy
  • Cities in Motion
  • Cities in Motion 2
  • Crusader Kings II
  • Crusader Kings II: Conclave
  • Darkest Hour
  • Dungeonland
  • Europa Universalis III Complete
  • Divine Wind
  • Europa Universalis III Complete
  • Europa Universalis III Complete
  • Victoria 2
  • 500k Club
  • Mount & Blade: Warband
  • Crusader Kings II: Way of Life
  • Europa Universalis IV: Common Sense
  • Stellaris Sign-up
  • Hearts of Iron IV: Colonel
  • Tyranny: Gold Edition
  • Steel Division: Normandy 44
  • Crusader Kings Complete
  • BATTLETECH
  • BATTLETECH - Digital Deluxe Edition
  • Shadowrun Returns
  • Surviving Mars: First Colony Edition
  • Imperator: Rome Deluxe Edition
  • Prison Architect
  • VtM - Bloodlines 2 Blood Moon Edition
  • Imperator: Rome Sign Up
  • Age of Wonders: Planetfall Deluxe edition
  • Crusader Kings III Referal
  • Hearts of Iron III Collection
  • Heir to the Throne
  • Impire
  • Knights of Pen and Paper +1 Edition
  • Magicka
  • Majesty 2 Collection
  • Rome Gold
  • Semper Fi
  • Sengoku
  • Warlock: Master of the Arcane
  • Pillars of Eternity
  • Magicka 2
  • Crusader Kings II: Limited Collectors Edition
  • Tyranny: Archon Edition
  • Cities: Skylines
So if, in the future, you(or modders) would like to utilize one "minor inline trigger" for another seperate script. Would it be best to referense to that file, create an identical inline trigger or edit it out from the original and move the trigger to an shared file?
 

LordMune

Content Design Lead
26 Badges
Mar 15, 2015
136
849
  • IPO Investor
  • Stellaris Sign-up
  • Shadowrun: Hong Kong
  • Shadowrun: Dragonfall
  • Shadowrun Returns
  • Stellaris: Humanoids Species Pack
  • Age of Wonders
  • Stellaris: Synthetic Dawn
  • Stellaris - Path to Destruction bundle
  • Stellaris: Leviathans Story Pack
  • Stellaris: Galaxy Edition
  • Stellaris: Galaxy Edition
  • Stellaris: Galaxy Edition
  • Pillars of Eternity
  • Magicka: Wizard Wars Founder Wizard
  • War of the Roses
  • Warlock: Master of the Arcane
  • The Showdown Effect
So if, in the future, you(or modders) would like to utilize one "minor inline trigger" for another seperate script. Would it be best to referense to that file, create an identical inline trigger or edit it out from the original and move the trigger to an shared file?
Assuming the new use case is in a separate file, you'd move the trigger to a shared scripted trigger database (for maximum Script Hygiene).
 
Jun 3, 2020
21
422
Is long-term gameplay now viable for players with low spec laptops? Ck2 runs well the first hundred years but after that it runs as well as a hundred year old horse. Probably has something to do with the amount of courtiers. Will the game have the same performance at the beginning of the game until the very end?
 

vyshan

Retired Kaiserreich Developer
82 Badges
Mar 30, 2011
3.044
3.049
  • Cities: Skylines
  • Victoria 2: Heart of Darkness
  • Victoria 2: A House Divided
  • Crusader Kings II
  • Europa Universalis IV: Third Rome
  • Stellaris: Humanoids Species Pack
  • Europa Universalis IV: El Dorado
  • Mount & Blade: With Fire and Sword
  • Crusader Kings II: Way of Life
  • Europa Universalis IV: Common Sense
  • Crusader Kings II: Horse Lords
  • Hearts of Iron IV: Death or Dishonor
  • Cities: Skylines - Green Cities
  • Crusader Kings II: Conclave
  • Hearts of Iron IV: Expansion Pass
  • 500k Club
  • Stellaris Sign-up
  • Hearts of Iron IV: Cadet
  • Hearts of Iron IV: Colonel
  • Crusader Kings II: Reapers Due
  • Europa Universalis IV: Rights of Man
  • Stellaris: Digital Anniversary Edition
  • Stellaris: Leviathans Story Pack
  • Hearts of Iron IV: Together for Victory
  • Crusader Kings II: Monks and Mystics
  • Stellaris: Apocalypse
  • Cities: Skylines - Mass Transit
  • Europa Universalis IV: Mandate of Heaven
  • Stellaris: Distant Stars
  • Europa Universalis IV: Dharma
  • Shadowrun Returns
  • Shadowrun: Dragonfall
  • Surviving Mars: First Colony Edition
  • Crusader Kings II: Holy Fury
  • Imperator: Rome Deluxe Edition
  • Imperator: Rome Sign Up
  • Imperator: Rome - Magna Graecia
  • Surviving Mars: Digital Deluxe Edition
  • Europa Universalis III Complete
  • Europa Universalis IV: Rule Britannia
  • Europa Universalis III Complete
  • Surviving Mars
  • Victoria 2
  • Cities: Skylines - Parklife Pre-Order
  • Cities: Skylines - Parklife
  • Crusader Kings II: Jade Dragon
  • Hearts of Iron III: Their Finest Hour
  • Hearts of Iron III
  • For the Motherland
Assuming the new use case is in a separate file, you'd move the trigger to a shared scripted trigger database (for maximum Script Hygiene).
Databases? Does this mean that CK3 has actual legit database connections? or am I just misunderstanding things and you meant to refer to the Commons Folder where scripted triggers are stored now?
 

DrDarkspeed

Recruit
49 Badges
May 17, 2020
2
3
  • Shadowrun: Dragonfall
  • Crusader Kings II: Monks and Mystics
  • Stellaris - Path to Destruction bundle
  • Cities: Skylines - Mass Transit
  • Crusader Kings Complete
  • BATTLETECH
  • Surviving Mars
  • Stellaris: Synthetic Dawn
  • Stellaris: Humanoids Species Pack
  • Stellaris: Apocalypse
  • Surviving Mars: Digital Deluxe Edition
  • Stellaris: Distant Stars
  • Shadowrun Returns
  • Stellaris: Leviathans Story Pack
  • Shadowrun: Hong Kong
  • Surviving Mars: First Colony Edition
  • BATTLETECH: Flashpoint
  • Stellaris: Megacorp
  • Crusader Kings II: Holy Fury
  • Prison Architect
  • Surviving Mars: First Colony Edition
  • Stellaris: Ancient Relics
  • BATTLETECH: Season pass
  • Stellaris: Lithoids
  • BATTLETECH: Heavy Metal
  • Europa Universalis IV: El Dorado
  • Crusader Kings II
  • Crusader Kings II: Charlemagne
  • Crusader Kings II: Legacy of Rome
  • Crusader Kings II: The Old Gods
  • Crusader Kings II: Rajas of India
  • Crusader Kings II: The Republic
  • Crusader Kings II: Sons of Abraham
  • Crusader Kings II: Sunset Invasion
  • Crusader Kings II: Sword of Islam
  • Europa Universalis IV: Art of War
  • Cities: Skylines
  • Crusader Kings II: Way of Life
  • Pillars of Eternity
  • Europa Universalis IV: Common Sense
  • Crusader Kings II: Horse Lords
  • Cities: Skylines - After Dark
  • Crusader Kings II: Conclave
  • Stellaris
  • Crusader Kings II: Reapers Due
  • Europa Universalis IV: Rights of Man
  • Tyranny: Archon Edition
  • Stellaris: Digital Anniversary Edition
This is all very cool and I look forward to seeing what cool things you have used it for in the game! Also can't wait to see what modders come up with, and I imagine this will make it easier to add more and more interesting events in ongoing development/dlc.
 

Nyrael

Field Marshal
76 Badges
Jul 20, 2008
5.595
3.463
29
  • Europa Universalis IV: Mare Nostrum
  • Europa Universalis IV: Pre-order
  • Europa Universalis IV: Cossacks
  • Europa Universalis IV: Dharma
  • Victoria 2
  • Warlock 2: The Exiled
  • 500k Club
  • Europa Universalis IV: El Dorado
  • Crusader Kings II: Way of Life
  • Pillars of Eternity
  • Europa Universalis IV: Common Sense
  • Crusader Kings II: Horse Lords
  • Stellaris: Distant Stars
  • Crusader Kings II: Conclave
  • Stellaris
  • Stellaris Sign-up
  • Crusader Kings II: Reapers Due
  • Europa Universalis IV: Rights of Man
  • Tyranny: Archon Edition
  • Tyranny: Archon Edition
  • Stellaris: Digital Anniversary Edition
  • Stellaris: Leviathans Story Pack
  • Crusader Kings II: Monks and Mystics
  • Shadowrun Returns
  • Stellaris - Path to Destruction bundle
  • Shadowrun: Hong Kong
  • Stellaris: Megacorp
  • Crusader Kings II: Holy Fury
  • Europa Universalis IV: Golden Century
  • Imperator: Rome Deluxe Edition
  • Imperator: Rome Sign Up
  • Stellaris: Ancient Relics
  • Stellaris: Lithoids
  • Imperator: Rome - Magna Graecia
  • Shadowrun: Dragonfall
  • Europa Universalis IV: Rule Britannia
  • Europa Universalis IV: Mandate of Heaven
  • Tyranny - Bastards Wound
  • Europa Universalis IV: Cradle of Civilization
  • Europa Universalis III Complete
  • Stellaris: Humanoids Species Pack
  • Europa Universalis III Complete
  • Stellaris: Apocalypse
  • Stellaris: Synthetic Dawn
  • Europa Universalis IV: Third Rome
  • Rome: Vae Victis
  • Victoria 2: Heart of Darkness
  • Victoria 2: A House Divided
  • Europa Universalis III: Chronicles
The thing I'm most excited about is that French culture is referred to as french, and not frankish
Wasn't this change made in CK2 already? Frankish (in Germanic group) eventually turns into French (Latin group).
 

Gandalf_The_Black

Corporal
18 Badges
Jun 2, 2018
29
37
  • Crusader Kings II: Horse Lords
  • Imperator: Rome Sign Up
  • Prison Architect
  • Crusader Kings II: Holy Fury
  • Crusader Kings II: Jade Dragon
  • Age of Wonders III
  • Crusader Kings II: Monks and Mystics
  • Crusader Kings II: Reapers Due
  • Crusader Kings II: Conclave
  • Crusader Kings II: Way of Life
  • Victoria 2
  • Crusader Kings II
  • Crusader Kings II: Sword of Islam
  • Crusader Kings II: Sons of Abraham
  • Crusader Kings II: The Republic
  • Crusader Kings II: The Old Gods
  • Crusader Kings II: Legacy of Rome
  • Crusader Kings II: Charlemagne
Wasn't this change made in CK2 already? Frankish (in Germanic group) eventually turns into French (Latin group).
But the id for French culture is frankish in CK2 instead of French