You can link to or quote this tutorial at wish, but please don't mirror it. This is required in order to keep discussion about it in one place.
Prerequisites
In order to be able to follow this tutorial, you should be confident with the following:
- The traits tutorial and all that is required there
- The docudemon files
Triggers
First of all, I want to make sure you understand the enormous spread of the concept of triggers in the MTW2 data files. They are directly used in all of the following files (among which are some of the most-edited files for every mod):
- descr_faction_standing.txt
- export_descr_advice.txt
- export_descr_ancillaries.txt
- export_descr_character_traits.txt
- export_descr_guilds.txt
On top of that, the monitor_event scripting structure works pretty much in the same way.
1. Overview
Well, since you are reading this tutorial, I guess you have already had a good look at one of the files containing triggers and formed your own opinion about what they do (if not, have a look at my traits tutorial and read the first part carefully). Now, to see if your assumptions are correct - look at this example:
You can clearly see that each trigger consists of four basic parts:Code:;------------------------------------------
Trigger diplomatinit6
WhenToTest AgentCreated
Condition Trait Multilingual >= 1
Affects Multilingual 1 Chance 33
- A trigger head (aka the name)
- A WhenToTest event
- Zero or more conditions
- Zero or more affects
2. The trigger head
The trigger head starts with the keyword Trigger followed by the trigger name.
The only thing you should observe here is that each trigger is assigned an individual name. I think the game will use the last version of a trigger name it can find (no idea how having the same trigger name in multiple files affects this).
3. The WhenToTest event
This part consists of the keyword WhenToTest followed by an event name. This entry determines when the trigger will actually execute. In the above example, the trigger will be run every time an agent is created, but only if the conditions are met (see below).
You can find a list of all allowed events in docudemon_events.txt which you downloaded with the docudemon package.
For more info on this file, press on "Show":
4. Conditions
This section is quite a bit more complex than the first two. Looking at our example from the beginning, you will notice that it has only one condition:
This is actually an interesting example for a trigger, because it has a certain level of the trait it is changing as a condition. This means, it will never award the trait in the first place but can amplify it.Code:;------------------------------------------
Trigger diplomatinit6
WhenToTest AgentCreated
Condition Trait Multilingual >= 1
Affects Multilingual 1 Chance 33
Let's have a look at a more complex example now:
This is one of the hate&fear triggers that will give your general boni/mali in combat against certain factions or cultures. This trigger contains 6 conditions, that are linked with the and keyword (you should put each condition on a new line), and the Effects section will only be executed if all of the conditions are true.Code:;------------------------------------------
Trigger hate_n_fear_29
WhenToTest PostBattle
Condition IsGeneral
and not WonBattle
and BattleSuccess = crushing
and I_ConflictType Normal
and BattleOdds >= 0.9
and GeneralFoughtFaction england
Affects Fearsengland 1 Chance 100
The first condition always has to be preceded by the Condition keyword, the others by and. Both of these can in turn be followed by not to negate the condition (like it's done with "and not WonBattle" in the example).
You can find a complete list of allowed condtions in docudemon_conditions.txt - shipped with the docudemon package.
5. The affects section
First of all, don't confuse this with effects for traits. This is something quite different.
This part of a trigger definition consists of zero or more variations on the theme:
This means that, when the trigger is run and all conditions are true, the character in question will have a <Percentage> chance to get <Points> trait points in <Trait>. An example:Code:Affects <Trait> <Points> Chance <Percentage>
When this is executed, the character has a 50% chance of getting one point in the GoodCommander trait chain, thus making him a more able general.Code:Affects GoodCommander 1 Chance 50
As I said, you can use multiple Affects lines in one trigger, or even omit them altogether (although this will make the trigger completely useless), like this:
5.1 Other files
To view this section, click on Show:
Monitors
Well, monitors are the scripting equivalent of triggers. Before you read this, you should have some basic grasp about scripting, which you might be able to get from old RTW tutorials.
Anyways, the thing that is closest to triggers is the monitor_event struct.
The exact command goes like this:
What this does is practically the same as a trigger: When <Event> fires (this is the same as a WhenToTest event in a trigger), and all <Conditions> are satisfied, the code inside the monitor will be executed. It is important to know that here, too, you can only use conditions which trigger requirements fit the exports of the event you are testing for.Code:monitor_event <Event> <Condition>
[and [not] <Condition>]
...code...
end_monitor
The first <Condition> is compulsory, and if you don't want to use one, supply TrueCondition here (which is, as the name says, always true).
The [and [not] <Condition>] can be repeated as many times as you like.
The second monitor struct is monitor_conditions.
The definition for it is:
This is actually a bit similar to monitor_event - but not quite. It is important to notice that, since you don't have any event to export objects, you can only use independent conditions here, whereas in monitor_event, you can also use (fitting) dependent conditions.Code:monitor_conditions <Condition
[and [not] <Condition>]
...code...
end_monitor
It's also quite apparent that a monitor_conditions will execute multiple times (in fact as long as all its conditions are true), which often has unwanted results as opposed to a monitor_event that will only execute once every time its event fires.
To prevent this, you can switch monitor_conditions on and off like this:
This monitor will add 10000 florins to your treasury every time you set the counter switch to 1 somewhere in the script and then switch itself off again.Code:declare_counter switch
set_counter switch 1
monitor_conditions I_CompareCounter switch 1
console_command add_money 10000
set_counter switch 0
end_monitor
Another important concept of monitors is that you can switch them off completely, using the terminate_monitor command. If you use that somewhere inside the monitor, it will be closed to be never executed again until you start a new game.
