Event scripting: tricks and traps explained

About the conditions and effects for the events, just take a look at

/db/events/event effects.txt

But be aware that now they are divided in two classes, one for character events and other for province events

O

The Duchies and Kingdoms are in the Provinces.csv, there you can find to wich one belongs each province, I suppose that you can move some provinces from one to another. About creating a new Kingdom, I'm not sure if you can add a tag, but you could use one of the defined in the world_names.csv (in the config folder), just changing the name to the one that you want for your kingdom: If you then use that tag in the kingdom column for the provinces you want (in Provinces.csv) you will be able to create a kingdom of your liking

About the events, they are a bit more complex than in the former Paradox games, but I think that much more flexible than even before, and the province system really rocks!

O

Note that changing the tags will almost certainly result in the export-to-EU2 function crashing.

CK events are quite different that any previous game's events and it takes some time to become handy at scripting them. You will want to devote some time to reading through existing events to get the general flavour of them, and then use the ...\ck\db\events\event effects.txt file as a reference for most of the available triggers, conditions and effects. There are a few others that the beta team requested that were implemented but aren't documented in the event effects file, and there are some aspects of some of the triggers/conditions that are rather tricky to understand at first and may vary depending on what type of event you're scripting.

Important thing to grasp: there are three different event types:

• character events - these are events that happen to characters and the game engine tests each character in the game for each of these events on a dynamic basis.
• province events - these are events that effect provinces and the game engine tests each province for each of these events on a dynamic basis.
• province_x_province events - these are the spread events that the game engine tests for pairs of provinces. These are tested for each province, taking each neighbour in turn until either an event successfully triggers or the province runs out of neighbours (at which point it moves on to the next province). Again, these are tested dynamically.

The character events have their own unique triggers/conditions/effects that are (in most cases) different from the ones that are province-related (which apply to both the province and province_x_province events). DO NOT mix up the triggers or effects since the odds are that they won't work!

Also, some triggers behave differently for province events than they do for province_x_province events. Example: "same_religion" in a province event checks to see whether the province religion is the same as its ruler's religion; whereas "same_religion" in a province_x_province event checks to see whether the two neighbouring provinces have are the same religion.

"Dynamic" testing means that each character and province is not tested for all events every day (or even every month) since that would result in a massive performance hit - particularly since expanding the number and range of events is high on the to do list for both the developers and some of the betas. The best rule of thumb (athough not strictly an accurate one) is to assume that during any given year of game play each character and each province will be tested about 3 or 4 times for every event.

Available ID ranges:

• Event IDs below 5000 are reserved for Paradox use only. Do not use an ID in this range if you're scripting events.
• Event IDs in the 5000-9999 range are reserved for beta testers and are being "booked out" in blocks of 100 event IDs. Do not use these IDs since it's likely that most will get used during the upcoming months. (That's a handy way to see who wrote events )
• Event IDs from 10000 up are "reserved" for public use (that means you!) so you can use any of those that you wish without fear that it will later conflict with either a developer or beta event that will be in future DEMs. As a community, you may wish to "parcel" these for specific large scale projects so you don't conflict with one another, and I think you'll understand that Paradox will not support any bugs or CTDs caused by events in this range.

Very important concept: MTTH (=mean_time_to_happen)

Events are tested based on their probability to happen, not on a specific set-in-stone date (although date may be a component of the event trigger). Loosely, this is based on a statistical concept used in materials testing and analysis called "mean time to failure". A web search will show you some of the complexities of this system for those who are mathematically inclined but may need to bone up on their statistics.

Each event is assigned a MTTH value in either days, months or years. It is recommended that you avoid using very large or very small numbers since in testing we have observed some "clipping" due to processor rounding. This assigned value is plugged into a hard-coded formula that determines the odds of an event firing and then compared to the result of a RNG to see if it fires in any particular instance. This means that events are not tracked to see how many times it has been tested for someone (or some province) and frees up vast amounts of CPU and memory for other game functions.

The net effect is that assigning a MTTH of 1 year does not mean that the event will fire in 1 year. It means that the mean time to happen is one year, but the formula being used has a rather long head and tail so it could fire in a matter of days, or it could fire years from now (or never) depending on what number the RNG produces. Think of it as predicting the results of a die roll. You can calculate the odds of a certain result, but you can't guarantee that any given test will produce it. You could, theoretically, have a test that *never* produces the result - although the odds of this happening are staggeringly small.

Further, there are currently (as of 1.00 and 1.01) some hard-coded "cheats" being used as part of the processor optimization process that are helping to keep the game performance as high as possible but are resulting in some slightly negative effects on "real" MTTH as opposed to statistically determined MTTH. This is being worked on, but for now I would recommend using a lower MTTH value than would be empirically calculated in order to have your events trigger when you want them to, and then test your event repeatedly in a controlled environment to determine if its frequency is roughly what you desire. My personal rule of thumb - and this is a personal reccomendation, not an official one - is to use an MTTH value that is about 25% lower than the one you would normally expect to use.

Example: if I want something to have a *real* MTTH of 10 years I would usually set the event MTTH to about 7.5 years. To repeat an earlier caveat, though, this doesn't guarantee that the event will fire in 10 years - it merely results in the effective event MTTH being about 10 years and repeated testing will probably produce a mean firing frequency of 10 years. It could fire in a day, or it could fire 100 years from now. I conducted several thousand controlled statistical tests on both the advances_discovery and advances_spread events when I scripted them to ensure that they were WAD with the MTTH values I'd assigned them, and I would recommend that anyone doing "critical" event scripting conduct similar testing.

Some more tips:

Don't forget to use MTTH modifiers since they tend to make events more interesting and more "fun" for the players - and decrease the average person's ability to guess roughly when an event will fire. In particular, use monarch or kingdom stats in tiers (i.e. apply different modifiers depending on how good or bad the martial skill is), or power settings in tiers. In character events, don't forget to throw in some traits modifiers to increase the importance/effect of having a certain trait. There is plenty of fun to be had with these!

Caveat: don't forget, when scripting, that all modifiers that are valid (i.e. the condition test results in "true") are multiplied together to produce a modified MTTH. This is a common error that can be made when scripting tiers.

In province_x_province events, don't forget that you *must* specify either "to" or "from" in almost every trigger, condition and effect. For the few that you don't have to specify, either the "to" province is used or the condition is a comparison between the two provinces.

There are probably more tips, but those are the ones that spring to mind right now.

Have fun!

Woops...just remembered one...

Note that in province_x_province spread events, the test is conducted on neighbouring provinces - i.e. ones that share a land border. There is also a file called spreadneighbours.csv that creates a special set of neighbours for spread events to make it possible for islands and more remote coastal provinces to experience spread events. This file shows pairs of provinces that are treated as neighbours for the purposes of spread events. While there might be an inclination to go and edit this file to have it more closely approximate historical trade routes, the current file is intentionally designed *not* to do this since it proved to be too much of an imbalance during betatesting. Also, I will be looking at a revision to that file for 1.02 based on further testing, so expect it to change.

Nice infos MrT!
But the MTTH -> :wacko:
I will try to understand so please tell me if i'm right:
1.Let's say the RNG creates the number 125(is it calculated in days or seconds???)
2.In the event i have a MTTH Years=10, which is modified to 2 years for example.

Does this mean that the event will fire soonest 125 days from the actual(or which is the base?) date and latest 2 years and 125 days from now?

KonigMaximilian said:

Wa to confusing for my little brain, I think ill wait for Paradox to add what I want in the next patch thats if their event going to consider it

Belive me im not Mathematicly inclined, im probably the worst person at it lol

Plus they way you said things about certain area's like the Character Evcents, well this event was to be fired reagardles of character, so it can fire for any Christian Faith, so you could have a Kingdom of Brittany, or a Kingdom of Brandenburg, and also the King titel to go with it for the leader, but from what I see its to diffiult for my brain to event do let allone try to make an event like this.

Click to expand...

Event scripting is not for the faint of heart - particularly CK event scripting which is quite a bit more complex than pervious Paradox event syntax has been.

There are ways to "screen" out certain characters. Example: you can use the "is_independant" condition in the trigger section of the event to limit it firing for only rulers in their own right (i.e. kings, or independent dukes and counts). You can use the "religion" condition in the trigger section to prevent is from firing for anyone other than a Christian character. Etc. Yeah...they're complex and you have to be careful when scripting that you don't allow an event to happen to someone it shouldn't.

Wilhelm II. said:

Nice infos MrT!
But the MTTH -> :wacko:
I will try to understand so please tell me if i'm right:
1.Let's say the RNG creates the number 125(is it calculated in days or seconds???)
2.In the event i have a MTTH Years=10, which is modified to 2 years for example.

Does this mean that the event will fire soonest 125 days from the actual(or which is the base?) date and latest 2 years and 125 days from now?

Click to expand...

No. The RNG produces a number that is tested against another number to determine if the event fires, not when the event fires.

To take a simple example from another game, let's say that you're playing D&D or some other dice-driven RPG and you enter into combat. As a result of your "to hit" stats (strength, weapon, skills, etc.) and the monster's armour class (base AC, dexterity, skills, combat conditions, etc.) you determine that you need to roll a "15" on a 20 sided die to hit the beast and inflict some damage. Once you start combat what guarantees do you have? None. You can't definitively say that when you'll hit the monster. You can't say whether it will be on the first attempt, the second attempt, the third attempt...or the nth attempt. You can, however, use statistical analysis based on your knowledge of the die (it has 20 sides and isn't a trick die) and a set of mathematical forumlas to predict how likely it is that you will hit the monster, and roughly how often you should expect to hit it. When you actually fight the combat you could get lucky and hit it the first time, the second time, and the third time and kill it quickly without suffering a scratch yourself. You could be very unlucky and roll a string of misses and end up as the unscathed monster's lunch. The odds of either happening are very much lower, but it could happen. Most likely, though, you'll hit it about once in every 4 tries, inflicting some damage.

MTTH in CK works much the same way, except of setting the "to hit" or "AC" values, you're setting the value of the probability of you hitting and the game reverse-calculates this into a "to hit" value that is meaningful to its event engine and compares it to the random number generated each time it performs the test. The "to hit" number doesn't change, just as in the D&D combat above it doesn't change. You still have no guarantees at all that you will hit (or miss) on any one test. Your MTTH setting is simply providing a value that, over a period of time where a number of die rolls are made, is likely to result in a "hit".

The modified MTTH of 2 years that you gave in your example simply means that if you conducted the same test many thousands of times, you expect the mean time it takes to get a "hit" to be two years. When you're playing, you might have a lucky "die roll" resulting in the event triggering on the very first die roll (thus taking 1 game day) or you might get very unlucky and roll a long string of failures resulting in the event finally firing fity years from now - or, possibly (although highly improbably), you could have truly abysmal luck and it might never fire in the 400 years you play the game because you keep rolling crap results.

The amazing advantage of such a system is many-fold:

1. It is impossible for a player to know exactly when an event will fire so there will always be some unpredictability. This makes it harder for a player to take an advantage over the AI since it levels the playing field somewhat.
2. It virtually eliminated predeterminism, thus making it possible for exactly the same starting conditions to produce significantly different results. This should enhance the game's replayability by making it improbable that any two otherwise identical games will go the same way. Example: if you started a Hastings scenario with France, within a few short years there would likely be fairly significant differences in what has transpired since the game engine uses MTTH-based events (and other hard-coded stuff that is MTTH-based).
3. Since you're performing a new test every time and the results of previous tests aren't required, the amount of data that needs to be stored is vastly reduced. Imagine, for a moment, that you had to keep track of every single event's test results for every single character and provice it had been tested against until it fired, and then had to clear out the unncessary data afterwards. This would cause the CPU and memory requirements to expand to Big Blue levels and would introduce massive potential for bugs/processor erros to creep in. This innovative system results in something that is vastly more complex and amazingly flexible, while still making it run on a PC.

...and more!

That's a fabulous explanation, MrT. Thanks.

Steve.

Some tips about coding events

1) Adjust the factors and conditions so that, performance wise, the least test and calculation would be made:

I learn this one from MrT.

Example: If you want to have factor changes depending on an attribute (like stewardship), and you want a malus for very low attribute, and a bonus for very high attribute, decide of your MTTH value for intermediary values (let's say 3-8), which are the most likely to be the ones of the majority of characters, and give a bonus factor (exemple: 1.2) for high attribute (condition: stewardship >= 9) and a malus factor (example: 0.8) for low attribute (condition: not stewardship >= 2).

This way, for most of the characters, the factor adjustment won't happen if the event triggered, thus saving some CPU time...

2) There are several ways to code the same effect:

In fact, MrT and I are using opposing styles when we are writing our events

MrT likes the cumulative way like:

So, as you can see, here, there isn't any modifiers for a stewardship between 7 and 13. If you have 20 in stewardship, you will have a 1.25*1.25*1.25 = 1.953125 modifier (above 13, above 17 and above 20). If you have 1 in stewardship, you will have a 0.75*0.75 = 0.5625 modifier (below 5 and below 7).

I like a more straightforward way, using comments to outline what I am not calculating:

My conditions are more complicated, but I prefer to read my events this way. If you have 13, your factor is *1.5 , if you have 17, it's *2.

3) Always remember to create a pair of events if you can be affected indirectly !

Try to give the second event a choice if possible.

Example: You design an event so that you insult a vassal, and he loses loyalty.

Don't design it so that "type = loyalty for = random_vassal value = -0.5" !

Because if YOU are the vassal of an AI, and if this event is triggered by the AI, your loyalty will plummet without notice, warning, explanation or pop-up !

So rather, make the first event trigger a second, where you give the vassal (which may be you) the choice of becoming disloyal or not.

Example:


4) Always think as if you were coding a EU2 random event.

There is no idea of event history in CK. An event will fire multiple times, as long as the conditions exist (so my previous example is a bit silly as all arbitrary characters will insult their vassals regularly ). One-shot event are not really possible.


That should give you enough to start playing with events in CK.

Cat

Thanks MrT and Cat Lord!
This will help a lot!!!

You will also discover, that there are subtilities in chain of events and that they are very difficult to script.

For example, a liege has a one to many relationship to vassals, but a vassal has a one to one relationship to his liege.

So you can script an event for a liege, which will affect one of his vassal randomly, which gives this vassal choices that will affect his liege back. Because there is a target_char for "liege".

But you cannot script an event for a vassal, which will affect his liege, which gives his liege choices that will affect this vassal back. Because the target_char for vassals are "best_vassal", "worst_vassal" and "random_vassal". So you have lost the history of which vassal started the chain of events in the first place.

Believe me, it can become quite confusing

Cat

A comment to something Cat Lord said...

Cat Lord said:

If you want to have factor changes depending on an attribute (like stewardship), and you want a malus for very low attribute, and a bonus for very high attribute, decide of your MTTH value for intermediary values (let's say 3-8), which are the most likely to be the ones of the majority of characters...

Click to expand...

Note that character events look only at character stats. Province events and province spread events (province_x_province) look at combined kingdom stats.

Example: The king of France has a martial of 8 and his marshall has a martial of 9.

A character event using modifiers for martial, when tested for the king, will use the king's stat of 8. A province event, when tested in one of the king's demesne provinces, will use the kingdom stat of 17 - as would a spread event.

MrT said:

Note that character events look only at character stats. Province events and province spread events (province_x_province) look at combined kingdom stats.

Example: The king of France has a martial of 8 and his marshall has a martial of 9.

A character event using modifiers for martial, when tested for the king, will use the king's stat of 8. A province event, when tested in one of the king's demesne provinces, will use the kingdom stat of 17 - as would a spread event.

Click to expand...

Which remind me I should correct a couple of events in the beta forum o

Cat

Are there 'start dates' and 'death dates' for events?

It seems as though it's not impossible to get an event to fire once and only once, it's just not easy, and it's more likely you'd end up with a 'once and maybe never.'

Couldn't you have an event fire once, set a flag, and have !flag as a condition? Or is this no longer there as well?

Thanks a lot for the info!

Let me see if I understand the MTTH concept. Very roughly it states that if you give a value of 100 days you will get around X% chance of happening each day, so the gauss bell will center in 100 with more or less large tails in every direction?

Great explanation, I think this should be stickied or placed in the FAQ

O

Aquitaine said:

Are there 'start dates' and 'death dates' for events?

Click to expand...

You can set conditions on year only.

Aquitaine said:

It seems as though it's not impossible to get an event to fire once and only once, it's just not easy, and it's more likely you'd end up with a 'once and maybe never.'

Click to expand...

Exactly, for a single event in a particular year, you can set a condition for "after this year" but "before this year", and try to set a MTTH value so that the evnt should roughly happen in the middle, but you may be unlucky that it never fires or fire twice...

Aquitaine said:

Couldn't you have an event fire once, set a flag, and have !flag as a condition? Or is this no longer there as well?

Click to expand...

There is no flag as yet in the scripting language...

Cat

Orlando said:

Let me see if I understand the MTTH concept. Very roughly it states that if you give a value of 100 days you will get around X% chance of happening each day, so the gauss bell will center in 100 with more or less large tails in every direction?

Click to expand...

Yes, very roughly this is the case, but because the number of events poll in a year is not that much, it is quite wrong for very low MTTH value (less that a year), and also, for very big MTTH value, you probability of happening is lowered by the few number of poll in a year.

Adjusting frequency of events still requires a bit of trial of success and failures.

Cat

Cat Lord said:

Yes, very roughly this is the case, but because the number of events poll in a year is not that much, it is quite wrong for very low MTTH value (less that a year), and also, for very big MTTH value, you probability of happening is lowered by the few number of poll in a year.

Click to expand...

So are there a fixed number of polls per year or is the polling random?

O