编辑“触发器”（章节）

== Trigger blocks ==

Triggers are used in trigger script blocks.

Those usually are either explicitly named so, like an event's <code>trigger = { }</code> block, or their name are questions which can be answered by yes or no, like a decision's <code>is_shown = { }</code> and <code>is_valid = { }</code>.

In some cases, triggers are used in hybrid script blocks that accept triggers amongst other things.

Ex: [[weight modifier]]
<pre>modifier = {
   is_ai = yes
   factor = 0
}</pre>
In this block, <code>is_ai = no</code> is a trigger, but <code>factor = 0</code> is an operator.

=== Early out ===

Unless they are being tooltipped, trigger blocks operate on the so-called "early out" principle.

For a trigger block to be true, all triggers within must be true. "early out" means that as soon as a trigger in the block is evaluated as false, the rest of the triggers in that block are not evaluated.

This is useful to avoid errors.

Ex: the following trigger block checks that the current character scope's primary spouse has the same culture as them. To avoid errors, it first checks that the character `has` a spouse to begin with.
<pre>trigger = {
   exists = primary_spouse
   culture = primary_spouse.culture
}</pre>
If <code>exists = primary_spouse</code> is false, the second trigger is not evaluated.

It is also useful for performance optimization. In a trigger block containing multiple triggers, putting the ones most likely to fail first can significantly reduce the number of triggers checked overall.

Ex: this trigger block checks that the current character scope is a player and an independent ruler.
<pre>trigger = {
   is_ai = no
   is_independent_ruler = yes
}</pre>
If this trigger block is evaluated once a year for each character in the game, since most characters in the game are not players, <code>is_ai = no</code> will almost always be false, and the 2nd trigger will almost never be evaluated at all.

=== Logic blocks ===

Trigger blocks can contain several triggers. By default, if all of them are true, the trigger block as a whole is true, but some logic blocks can manipulate that logic.

==== AND ====

<pre>AND = {
   is_ai = no
   is_independent_ruler = yes
}</pre>

The <code>AND</code> block is true if the current character both is a player and an independent ruler.

==== OR ====

<pre>OR = {
   is_ai = no
   is_independent_ruler = yes
}</pre>

The <code>OR</code> block is true if the current character scope is either a player `or` an independent ruler.

==== NOT/NOR/NAND ====

<pre>NOT = { has_title = title:k_france }</pre>

The <code>NOT</code> block is true if the current character scope does not hold the Kingdom of France.

To avoid ambiguity, <code>NOT</code> should only contain a single trigger. For multiple triggers, using <code>NOR</code> or <code>NAND</code> makes the intent clear.

<pre>NAND = {
   has_title = title:k_france
   has_title = title:k_aquitaine
}</pre>

The <code>NAND</code> block is true if the current character scope holds either the Kingdom of France or the Kingdom of Aquitaine or neither of the two. It is false if they hold both titles.

<pre>NOR = {
   has_title = title:k_france
   has_title = title:k_aquitaine
}</pre>

The <code>NOR</code> block is true if the current character scope holds neither the Kingdom of France nor the Kingdom of Aquitaine. It is false if they hold either of the titles.

=== Limit blocks ===

The <code>limit</code> block is used for conditional effects and triggers.

==== if/else_if ====

The most common use of the <code>limit</code> block is with the <code>if</code>/<code>else_if</code> effects, to execute effects only if the <code>limit</code> block is true.

Ex: this effect adds gold to the current character scope if they are a player.
<pre>if = {
   limit = { is_ai = no }
   add_gold = 100
}</pre>

==== effect list-builders ====

Limit blocks are also commonly used to restrict effect list builders.

Ex: this effect adds gold to the current character scope's children if they are male
<pre>every_child = {
   limit = { is_male = yes }
   add_gold = 100
}</pre>

Note: the <code>any_X</code> list-builder does ''not'' use a <code>limit</code> block.

==== trigger_if/trigger_else_if/trigger_else ====

<code>trigger_if</code> can be used to check a trigger only if the <code>limit</code> block is true.

Ex: if the current character scope is not an ai, this trigger checks whether they are an independent ruler
<pre>trigger_if = {
   limit = { is_ai = no }
   is_independent_ruler = yes
}</pre>

Conditional triggers are often used in tooltipped trigger blocks both for legibility and to avoid errors, because when tooltipped, early-out does not apply.

Ex: this trigger, when tooltipped, would throw an error when <code>primary_spouse</code> does not exist.
<pre>trigger = {
   exists = primary_spouse
   culture = primary_spouse.culture
}</pre>
but this would not throw an error, because if the <code>limit</code> block is false, the trigger is not evaluated.
<pre>trigger_if = {
   limit = { exists = primary_spouse }
   culture = primary_spouse.culture
}</pre>