编辑“触发器”（章节）

== Trigger syntax ==

=== Scope comparison ===

A scope comparison is a statement with two scopes on either side of an <code>=</code> sign. It is true if both objects are the same, and false otherwise.

Scopes in a scope comparison can be database scopes, event targets, saved scopes or variables.

Note: even if both scopes are not the same objects, they do need to be of the same scope type.

Ex: this trigger checks whether whoever holds the kingdom of France is the same character as the father of the current character scope.
<pre>title:k_france.holder = father</pre>

In a scope comparison, both sides need to be valid. In this example, the current character must have a father, and the Kingdom of France must be created, otherwise the scope comparison throws an error in the error log, so the existence of both scopes needs to be checked at some point before the comparison is made.

The existence of the scope on the left-hand side of the comparison itself by using <code>?=</code>:
<pre>title:k_france.holder ?= father</pre>

=== Value comparison ===

A value comparison is a statement with two numerical values on either side of either
* an equal sign <code>=</code>
* a comparison symbol
** strictly greater than <code>></code>
** greater than or equal to <code>>=</code>
** lower than <code><</code>
** lower than or equal to <code><=</code>
It is true if the comparison is mathematically correct.

Numerical values in a value comparison can be:
* a number
* a named value
* a [[script_value]]
* a saved scope value
* a [[variable]] storing a number

Ex: this trigger checks whether the current character scope's gold is strictly greater than 1000.
<pre>gold > 1000</pre>

=== Code triggers ===

Code triggers have a predetermined syntax. They usually require a specific scope type context to work.

Code triggers can take several forms:

==== Basic triggers ====

Basic triggers check whether the statement has the expected positive or negative result.

Ex: this trigger is true if the current character scope is ''not'' an AI.
<code>is_ai = no</code>

==== Simple triggers ====

Simple triggers check whether they are true depending on the argument provided on the right hand side of the <code>=</code> sign.

The argument is either:

* a scope
Ex: this trigger checks whether the current character scope is a vassal of the saved scope <code>scope:actor</code>.
<pre>is_vassal_of = scope:actor</pre>

* a database key
Ex: this trigger checks whether the current character scope has the trait defined with the <code>infirm</code> key.
<pre>has_trait = infirm</pre>

==== Complex triggers ====

Complex triggers use several parameters in a script block. Those parameters can be a scope, a database key, a numerical value or a flag value.

Ex: this trigger checks whether the current character scope has an active scheme of the murder type targeting their liege.
<pre>is_scheming_against = {
  target = liege
  type = murder
}</pre>

Some code triggers have both a simple form and a complex form.

==== In-line complex triggers ====

Some complex triggers can be written in one line to return a value.

It is written in quotation marks, with the additional argument in brackets.

For example, a script value would look like this:<syntaxhighlight lang="c">
distance_to_liege_sval = {
  value = "realm_to_title_distance_squared(liege.capital_county)"
}
</syntaxhighlight>This feature is not documented and doesn't work with all triggers. From testing, it seems to only support triggers with this line in their description: <code>Traits: <, <=, =, !=, >, >=</code>

If a trigger has multiple arguments, like <code>has_trait_xp</code> which requires trait and track, they are added with a |

<code>value = "has_trait_xp(lifestyle_traveler|danger)"</code>

So far, this is the only known trigger with this multi-argument syntax.

=== scripted_triggers ===

Scripted_triggers are macros that enable replacing a set of triggers with a single statement, to make script more legible and avoid repetition.

They are usually defined in <code>common/scripted_triggers</code>, and can then be used anywhere triggers are allowed.

They are sometimes defined locally in event files (see [[events]]), in which case they can only be used in events from the same file.

==== Basic scripted_triggers ====

Simple scripted_triggers check whether a predetermined set of triggers is evaluated as a whole as true (<code>= yes</code>) or false (<code>= no</code>).

Ex: if the following set of triggers is repeatedly used to check whether a character is a rich adult independent ruler:
<pre>is_independent_ruler = yes
is_adult = yes
gold > 1000</pre>
instead of repeating the same set of triggers in different places, they can be defined as a scripted_trigger:
<pre>is_rich_adult_independent_ruler = {
   is_adult = yes
   is_independent_ruler = yes
   gold > 1000
}</pre>

and anywhere that set of triggers needs to be checked, it can be replaced by the following statement:
<code>is_rich_adult_independent_ruler = yes</code>

Using the negative version
<pre>is_rich_adult_independent_ruler = no</pre>
is the same as using a <code>NOT</code> logic block
<pre>NOT = { is_rich_adult_independent_ruler = yes }</pre>

Because scripted_triggers can be used in a variety of different contexts, it is advised not to use in their definition ambiguous event targets such as <code>root</code> or <code>prev</code>.

==== Complex scripted_triggers ====

Scripted_triggers can also have a complex form that handles literal text replacement, allowing to pass arguments.

For example, if the following set of triggers are used to check that the current character scope is a vassal of the King of France and related to them:

<pre>is_vassal_of = title:k_france.holder
is_close_family_of = title:k_france.holder</pre>
that set of triggers can be defined as a scripted_trigger, but instead of referencing <code>title:k_france.holder</code> specifically, the scripted_trigger uses an argument defined in uppercase letters wrapped in two <code>$</code> signs:
<pre>is_related_vassal_of = {
   is_vassal_of = $TARGET$
   is_close_family_of = $TARGET$
}</pre>
When used, the complex form of the scripted_trigger specifies what the expected argument is, by using the same name but without the <code>$</code> signs:
<pre>is_related_vassal_of = {
   TARGET = title:k_france.holder
}</pre>

With that form, every occurrence of <code>$TARGET$</code> in the scripted_trigger  will be ''literally'' replaced with the argument provided: the text replacement happens ''before'' the scripted_trigger is evaluated.