View source for Data structures

{{Version|1.12}}
在《Hearts of Iron IV》中有几种不同类型的数据结构，用于存储之后使用的数据。这可以在游戏中用于检查某些效果块是否被执行、作为各种计数器或其他东西。

__TOC__

== 常量 ==
常量是将相同的数值用一个符号替换的一种方式。在定义或使用常量时，用@符号标记它们。下面是一个示例定义:<pre>@CONSTANT = 10</pre> 这可以在之后的文件中被使用到，例如, <code>cost = @CONSTANT</code>. 对常量的定义可以出现在文件的任何位置

常量在绝大多数文件中都可以使用，包括 *.txt 和 *.gui 文件。常量可以用于将一些相同的数值链接在一起，以便在开发的任何时刻简单地改变它们。

例如，如果你有一个大型的决议系统，其中每一个决议都共用相同的政治点数花费，那么使用常量来代替这些值可以让你在接下来的开发中更好地修改这些政治点数花费。

另一个例子是在GUI制作中：如果有大量的元素（elements）使用了相同的X或Y坐标，那么把它们（这些坐标）用一个常量来链接是值得的，这样可以确保在更改这些坐标时具有更好的表现效果以及更加符合其他的GUI元素。

=== Defines ===
{{Main|Defines}}
Defines 是仅在内部计算中使用的特定类型的常量，在文件 {{path|common/defines/*.lua}} 中被定义。 它们不能在任何其他文件中被引用，只能在不可更改的内部代码中使用。

Some of the things included in the defines are that events by default stay for 13 days before auto-selecting the first option<ref><code>NDefines.NGame.EVENT_TIMEOUT_DEFAULT = 13</code> in [[Defines]]</ref> or that the ai_will_do value is 50% higher for focuses which were unlocked by the just-completed focus<ref><code>NDefines.NAI.FOCUS_TREE_CONTINUE_FACTOR = 1.5</code> in [[Defines]]</ref>. Most defines are numerical in nature, but some can be strings or blocks, such as the end date at which the game over screen appears<ref><code>NDefines.NGame.END_DATE = "1949.1.1.1"</code> in [[Defines]]</ref> or the list of experience need for a division to progress to the next level<ref><code>NDefines.NMilitary.UNIT_EXP_LEVELS = { 0.1, 0.3, 0.75, 0.9 }</code> in [[Defines]]</ref>.<br/>
The list of defines is vast and touches on every mechanic in the game, so if something can't be changed within the mechanic's respective files, it may be worth to check defines. Defines don't include the [[Modifiers#Static modifiers]], which can serve a similar purpose but with modifier blocks.

As defines are Lua code rather than a PDXscript-interpreted file, any Lua code can go in there, however modules allowing to go out of this directory are not available. As a consequence of this, '''there is no need to copy the entire file to edit it'''. Defines, including graphical defines, are merely a Lua-contained array, and it is possible to modify a single member of the array in Lua using, for example, <code>NDefines.NGame.START_DATE = "1936.1.2.12"</code>. Each of these lines is contained on a separate line and {{hover|They are present in the base game defines file due to the fact that NDefines is one single large array, and when defining an array with members, the members are separated with commas. However, separate commands are not separated with commas.|there are no commas separating them}}, such as the following:
<pre>NDefines.NGame.START_DATE = "1936.1.2.12"
NDefines.NGraphics.COUNTRY_FLAG_TEX_MAX_SIZE = 2048</pre>
This goes into a separate file set to be evaluated after the base game defines, which is done by making the filename be later in the alphabetical order (decided by Unicode character IDs). As most Unicode characters (including every uppercase or lowercase letter) have larger IDs than the code used for the number 0, the filename is almost irrelevant.<br/>
In the base game files, the graphical defines are set to be merged into NDefines in the last line of the base game file. However, since Lua does not create copies of tables by default, the base game's NDefines contains pointers to the actual elements, which are contained within NDefines_Graphics regardless. For this reason, modifying either NDefines or NDefines_Graphics works for changing graphical defines.<br/>
A mod should '''never''' contain the 00_defines.lua and 00_graphics.lua files within of itself: these files are commonly changed even in minor game updates, and having a define missing from a file results in the mod being unstable, potentially having a crash on startup.

== Flags ==
In this case, flags are used in the sense of a computer variable that is used to set data to and later read it from, commonly but not necessarily of a boolean value (i.e. either 0 or 1). For editing the flags used for representing countries in-game, see [[Country creation]] for the starting flags and [[Cosmetic tag modding|cosmetic tags]] for changing them in the middle of the game.

Flags within PDXScript are a 32-bit signed integer, ranging from -2147483648 to 2147483647. A flag can only be set to a specific value (Potentially for a certain amount of days), modified in an additive way by a certain value and read, no other operations can be done. [[#Variables|Variables]] serve as a more operational alternative, with far more capacity for changing (Such as multiplication or non-integer values, reading game values, being able to set to other database entries rather than numbers, etc). Flags are still recommended to use as a boolean value, as these are more optimised than the variables, and so using variables will lead to an unnecessary increase in memory usage and will lead to the game running slower compared to flags.

Flags are divided into 4 scopes:
* Global. These can be read from anywhere in the game, without the need for scoping.
* Country. These are assigned to individual countries, being impossible to assign or read elsewhere. A country flag can have different values depending on which country it's checked in.
* State. These are assigned to individual states, being impossible to assign or read elsewhere. A state flag can have different values depending on which state it's checked in.
* Character. These are assigned to individual characters, being impossible to assign or read elsewhere. A character flag can have different values depending on which character it's checked in.
In general, the same principles apply to them with little changes. While unit leader flags exist, these are marked as deprecated and are likely to be removed within the next updates.

A flag can be set in ''any'' [[effect]] block. There is no file where flags need to be defined, they will exist if set and stop existing when cleared.<br/>
The simplest formatting for setting a flag is <code>set_country_flag = my_flag_name</code>. This will create the country flag (If it did not exist otherwise) and set it to be a value of 1. ''This has no tooltip'' and so it will be invisible to the player. [[Effect#custom_effect_tooltip|custom_effect_tooltip]] may be used to tell the player that something will be done, if wanting to keep them in the know.<br/>
Afterwards, that flag can be checked with <code>has_country_flag = my_flag_name</code> as a trigger. This is set to be true if the flag was set, regardless of which value it has. This will create a tooltip using the flag's name as the [[localisation|localisation key]]. As such, <code>my_flag_name: "Has my flag"</code> will make that appear when the country flag is checked.<br/>
If a flag is no longer useful, it can be cleared by using <code>clr_country_flag = my_flag_name</code>, which'll mark it as no longer being set. This also has no tooltip and the player will not be aware unless specifically told with the custom effect tooltip that the flag was cleared.

The exact same principles apply with global, state, and character flags. The only differences are in the used effects/triggers (In which case the word <code>country</code> is swapped with the type's name like <code>set_global_flag</code>, <code>has_state_flag</code>, or <code>clr_character_flag</code>) scopes in which they can be set and where they can be checked. For global flags, it can be done in any scope rather than the 'global' scope: it can be set in either country, state, character, or rare other scopes.

Flags can also be targeted towards a certain country. This is usually done by appending the <code>@TAG</code> to the name of the flag, though it can be placed anywhere within the tag name except for the first character. For example, <code>set_country_flag = my_targeted_flag_@PREV</code> will set it to be targeted towards the country represented by PREV, which we'll take as TAG. ''This just appends the PREV's tag to the flag's name''. After this, <code>has_country_flag = my_targeted_flag_TAG</code> will come up as true for the same country it was set in. This can be used to create dynamic flags without relying on [[Effect#Meta effects|meta effects]]. You cannot have more than one target specifier in a single tag, You can only use @ROOT, @PREV, @FROM, and @THIS, even @PREV.PREV does not work. Both of these restrictions do not apply to targeted variables, so those may be a more flexible alternative if you need.

=== Example ===
The most common use of flags is to simply to mark a certain event (in the generic sense of a word, not necessarily the in-game [[events|event mechanic]]) as having occurred, such as an election, an invasion, a diplomatic deal, et cetera. For example, here's an event that starts off an election campaign in the country:
<pre>country_event = {
    id = algeria_election.0         # Namespace is assumed to exist.
    title = algeria_election.0.t
    desc = algeria_election.0.desc
    
    is_triggered_only = yes
    
    immediate = {
        set_country_flag = ALG_1936_elect_campaign  # Since set_country_flag has no tooltip, no need to hide it.
    }
    
    option = {
        < ... >                     # Irrelevant what's in the option
    }
}</pre>Flags provide a way to mark that this event has been received, in this case set within the immediate effect block of the event.<br/>
In order to utilise this, the <code>has_country_flag</code> trigger will have to be used similarly to this example decision:
<pre>ALG_1936_campaign_category = {         # Decision category is assumed to exist and contain 'allowed = { tag = ALG }'
    ALG_1936_select_candidate_A = {
        available = {
            has_country_flag = ALG_1936_elect_campaign
        }
        
        icon = ALG_elect
        cost = 50
        fire_only_once = yes
        
        complete_effect = {
            country_event = algeria_election.1
        }
    }
}</pre>
This will work fine, however, as is, the player will see either a {{icon|yes}} check mark or a {{icon|no}} cross next to 'ALG_1936_elect_campaign', with no indication what that truly means. In order to correct that, a localisation entry can be added to any working localisation file (i.e. is an *.yml file within the {{path|localisation/}} folder or any of its subfolders, has the internal name of the language in the end of filename before the extension, and is encoded in UTF-8 with the byte order mark present):
<pre> ALG_1936_elect_campaign: "The 1936 election campaign is currently ongoing"</pre>
In order to clear the flag when needed, the <code>clr_country_flag</code> effect would be used as such:
<pre>country_event = {
    id = algeria_election.100         # Namespace is assumed to exist.
    title = algeria_election.100.t
    desc = algeria_election.100.desc
    
    is_triggered_only = yes
    option = {
        name = algeria_election.100.a
        trigger = {
            has_country_flag = ALG_candidate_A_won
        }
        clr_country_flag = ALG_1936_elect_campaign
        < ... >                     # Irrelevant what else is in the option
    }
    option = {
        name = algeria_election.100.b
        trigger = {
            has_country_flag = ALG_candidate_B_won
        }
        clr_country_flag = ALG_1936_elect_campaign
        < ... >                     # Irrelevant what else is in the option
    }
    < ... >                         # Other potential options
}</pre>
Note that neither of the effects that modify country flags have tooltips, so [[Effect#Effect tooltips|a custom effect tooltip can be used to notify the player]] in some cases.<br/>
Everything is the exact same for flags of other scope types.
=== Complexities ===
This will cover the non-boolean usage of flags. [[#Variables|Variables]] usually do this job better, but this still has some usages.

The <code>set_<type>_flag</code> effect can also be expanded with the optional <code>days</code> and <code>value</code> arguments. This will appear like the following:
<pre>set_state_flag = {
    flag = my_state_flag
    days = 50
    value = 3
}</pre>This in particular will set the flag my_state_flag to the state to be equal to 3 for 50 days. After these 50 days end, the flag will be cleared completely, reset to 0. If days are left out, the flag will be set to that value forever, while if the value is left out it'll be set to 1.
And the trigger if a flag is set can also be expanded as such:
<pre>has_global_flag = {
    flag = my_global_flag
    value > 2
    days > 30
    date < "1938.1.1"
}</pre>While the flag and the value arguments are self-explanatory, <code>days</code> checks how many days it was ''since the flag was set'' (Not how many are remaining), while the <code>date</code> checks the date at which the flag is set. Every argument aside from the <code>flag</code> one is optional, just assumed to be always true if not set. This trigger will still always fail if the flag was never set or if it was cleared.<br/>
Additionally, it is possible to ''modify'' a flag as such:
<pre>modify_character_flag = {
    flag = my_character_flag
    value = 4
}</pre>This ''adds'' the amount to the flag, with negatives being possible. However, there's one catch: '''this does nothing if the flag is not set''', having a value of 0.

Each of the preceding examples can be used for any flag type.

== 事件目标（Event targets） ==
事件目标作为一种基本的方式来设置一个指针，指向一个以后要引用的作用域(国家、省份、人物)。任何单个事件目标一次只能指向一个作用域，但是一个作用域可以同时有几个事件目标。与标签（flags）类似，事件目标没有设置文件夹，它们可以在任何地方分配。<br/>
有两种类型的事件目标:常规和全球。他们之间的区别纯粹是当他们被清除。

如果范围具有使用分配的事件目标，则可以检查范围<code>has_event_target = name_of_event_target</code>.
=== 全球事件目标（Global event targets） ===
Global event targets can be declared using <code>save_global_event_target_as = my_event_target</code> as an effect. This will create the global event target with the name of <code>my_event_target</code> and it will last forever. Afterwards, it can be referred to as <code>event_target:my_event_target</code>, both as a scope and as a target.

If <code>save_global_event_target_as = my_event_target</code> is used when the event target is already set, the event target will change scopes to the one where the effect is used.<br/>
Additionally, <code>clear_global_event_target = my_event_target</code> (to be used in any scope, not necessarily the event target) will clear the specified global event target entirely, while <code>clear_global_event_targets = ROOT</code> will clear every global event target from the specified scope.

For example, by using [[Effect#start_civil_war|start_civil_war]] as an effect block, the following will assign the TAG_democratic_side event target to the revolter:
<pre>start_civil_war = {
    size = 0.5
    ideology = democratic
    save_global_event_target_as = TAG_democratic_side
}</pre>
After this, TAG_democratic_side event target will refer to the democratic side. For example, this code later in another effect block can be used to transfer a state and a part of the armies to the event target:
<pre>event_target:TAG_democratic_side = {
    transfer_state = 123
}
transfer_units_fraction = {
    target = event_target:TAG_democratic_side
    size = 0.2
}</pre>
It would make sense to clear the event target after it no longer exist, such as by using the [[On_actions#on_civil_war_end|on_civil_war_end on action]].

When using the event target as a scope for a namespace in localisation, the <code>event_target:</code> prefix is not needed, instead it'll look like <code>[TAG_democratic_side.GetName]</code>.
=== 常规事件目标（Regular event targets） ===
Regular event targets can be declared using <code>save_event_target_as = my_event_target</code> as an effect. The difference between regular and global event targets is in when they get cleared. While global event targets are used forever and can only be cleared manually, regular event targets only last as long as the effect block does (carrying over into events fired within as well), clearing automatically afterwards, and there is no way to clear them manually.

For example, this in an effect block will save a random owned and controlled state as the event target <code>target_state</code> and then fire the event mod_event.0 in 10 days:
<pre>random_owned_controlled_state = {
    save_event_target_as = target_state
}
country_event = { id = mod_event.0 days = 10 }</pre>
Assuming no other events, this event target will only exist within this effect block and the event mod_event.0 (Where it can be used in its corresponding trigger or effect blocks). If the event mod_event.0 fires another event within a corresponding effect block, this event target will exist in that event as well, meaning that this carries over to the entire mod_event.0-starting event chain. For example, the generic event [[Generic events#generic.23|generic.23 ([From.GetNameDefCap] Demands Control of [demanded_prov_target.GetName])]] uses this with demanded_prov_target as the event target. In order to make ROOT demand the state 123 from TAG using this, this effect block will be used:
<pre>123 = {
    save_event_target_as = demanded_prov_target
}
TAG = {
    country_event = generic.23
}</pre>

Event targets can be used in ''most'' effect blocks, they are called event targets only because they carry over to events. However, there are a few effect blocks, such as scripted diplomatic actions, where event targets are impossible to set.
== Country tag aliases ==
Country tag aliases are somewhat similar to event targets: they are used as pointers towards a specific scope, a single alias can point towards a single scope, and a single scope can have several aliases. However, there are differences. Primarily, country tag aliases can only point towards countries (as per the name) and they are set and cleared entirely automatically without any manual involvement. A country tag alias can point towards a non-existing country.<br/>
Usually, these are used to ease referencing to a specific side of a civil war by using country flags set when creating the revolter within either the [[Effect#start_civil_war|start_civil_war]] or the [[Effect#create_dynamic_country|create_dynamic_country]] effects. Both serve as effect blocks running the effects on the newly-executed country.

Country tag aliases are stored within {{path|common/country_tag_aliases/*.txt}} files. Each country tag alias is stored as a separate block within the file, with the name of the block being the name of the alias. Additionally, the country tag aliases serve as a trigger block, so any trigger can be used within. These are the arguments that can be used within:
* <code>variable = global.var_name</code> - This will make sure that the country tag alias is equivalent to the country that the specified [[#Variables|variable]] points to, in this case <code>var_name</code> assigned to the global scope.
* <code>event_target = my_event_target</code> - This will make sure that the country tag alias is equivalent to the country that the specified '''regular''' event target points to, in this case <code>my_event_target</code>.
* <code>global_event_target = my_event_target</code> - This will make sure that the country tag alias is equivalent to the country that the specified '''global''' event target points to, in this case <code>my_event_target</code>.
* <code>original_tag = TAG</code> - This puts every country that originates from TAG (created with [[Effect#start_civil_war|start_civil_war]] or [[Effect#create_dynamic_country|create_dynamic_country]]) as a possible target for the alias. In this case, further specification is needed with triggers. This is equivalent to the [[Conditions#original_tag|original_tag trigger]], but this is treated as an argument here as it does make certain errors go away.
* <code>targets = { ABC DEF GHI }</code> - This is a whitespace-separated list of country tags that the country tag alias can select. In this case, further specification is needed with triggers.
* <code>target_array = global.my_array</code> - This puts every country that's within the specified array (<code>my_array</code> in the global scope in this case) as a possible target for the country tag alias. In this case, further specification is needed with triggers.
* <code>country_score = { ... }</code> - This is a [[AI modding#MTTH blocks|MTTH block]] evaluated for each country. The country which has the highest total score will be picked for the country tag alias, provided the conditions imposed by every other argument are met.
* <code>fallback = TAG</code> - This is what the country tag alias will point to if no country fulfills the conditions specified within triggers or other arguments.

Here are some examples of country tag aliases:
<pre>MOD = {
    targets = { ABC DEF GHI }
    has_country_flag = my_flag
    country_score = {
        base = 1
        modifier = {
            add = 2
            tag = ABC
        }
        modifier = {
            add = 1
            tag = DEF
        }
    }
    fallback = ABC  # This will point to ABC, DEF, or GHI if they have the specified country flags. ABC is prioritised over DEF, which is prioritised over GHI. If neither have the country flag, defaults to ABC.
}
ARB = {
    target_array = global.arab_countries
    has_cosmetic_tag = ARABIA_UNITED    # This will point to any country in the global.arab_countries array if they have the ARABIA_UNITED cosmetic tag, provided they exist.
    exists = yes
}</pre>

== 变量（Variables） ==
A variable within Hearts of Iron IV is a signed 32-bit fixed point number with scaling of <math>\frac{1}{1000}</math>. As such, it ranges from -2 147 483.648 to 2 147 483.647. Adding further amounts above or below the variable will result in an [[wp:Integer overflow|overflow]], causing the value go from the maximum to the minimum or vice-versa. 

Variables are not stored within any particular file and can be created dynamically. Each database object (such as countries, states, ideas, or even equipment types) has a unique internal numeric ID, which can be assigned to a variable. For example, setting a variable's value to a country tag will make it take on the ID of the tag, and then the variable will be taken as a country when used as a target or as a scope. For [[#Token-valued variables|tokenizable database types]], a <code>token:</code> prefix is necessary when assigning a literal, for example: <code>var_name = token:some_idea_name</code>.

When using a variable as a scope, the <code>var:</code> prefix is needed, however in some cases the prefix is optional: most notably when using it as the target of an effect or trigger. For example, in <code>transfer_state = var:my_state_variable</code>, the <code>var:</code> can be omitted with no difference (For some cases, there will be logged errors, yet it will work in-game), but in <code>var:my_country_variable = { transfer_state = 123 }</code> the <code>var:</code> is ''mandatory''. Despite functioning similarly to a scope, the <code>var:</code> prefix is optional when a variable is used as a weight inside of [[Effect#Random effects|random_list]]. Same as with event targets, using variables in localisation for namespaces does not require the <code>var:</code> prefix, such as <code>[var_name.GetName]</code>. A good rule of thumb is that when passing a variable in a place where a raw token (rather than, say, a quoted string, a number, or a numeric state ID) is acceptable, it must usually be prefixed with <code>var:</code> so that the parser can distinguish whether the token being passed is meant to reference a database object or a variable. If <code>var:</code> is absent in a location where it should be present, the code may work, but the game will often complain in the error log. In general, it is best to err on the side of caution in this regard, as what may result in a merely-complaining error in one context, might result in an effect-nullifying, or worse, trigger-falsifying, error in another context. However, <code>var:</code> is always optional in variable and array manipulation operators (including <code>check_variable</code>), and so it can be elided in those operators for readability's sake.

Within their names, variables can have any word character, i.e. the 26 English letters (Either lowercase or uppercase), underscores, and the decimal digits from 0 to 9. However, a variable name cannot ''begin'' with a decimal digit, so a name like <code>123_my_variable</code> is invalid. This requirement common in many programming languages, and is implemented here for the same reason that the <code>var:</code> prefix exists: so that the parser can determine what syntactic type a token will be from the first (few) characters, and therefore doesn't have to worry about backtracking as much. In addition, it is recommended to avoid any names by variables that are already used for something else. For example, naming a variable <code>capital</code> can prevent any subsequent usage of the [[#Game variables|game variable with the same name]] within the internal code. A common naming convention to avoid overlap is to add a prefix signifying where it's used, such as the country's tag (<code>POL_capital</code>) or the name of the mechanic (Usually shortened like <code>PC_capital</code>).

=== 变量类型（Variable types） ===
There are two types of variables: regular and temporary. There are the following differences between the two:
* Different effects are used to set and modify regular and temporary variables. Typically, the difference is just in changing <code>variable</code> to <code>temp_variable</code>.
* Temporary variables only exist within the effect or trigger block where they're defined, similarly to regular event targets (although without carrying over to events). This does not mean they don't survive outside of the scope where they're defined, but the '''entire'' effect block, such as a focus reward or an event option. Meanwhile, regular variables exist forever. Note that this, however, does not always function properly in regards to scripted effects or triggers: temporary variables defined within of them may not still exist outside of them within the same effect/trigger block. However, a temporary variable defined before the scripted effect or trigger's usage will always carry on into it and get modified properly within.
* Due to the previous point, '''temporary variables can be defined and modified in trigger blocks''' as well as in effect blocks. This enables them to be computed as-needed in scripted triggers called from the <code>trigger</code> block of scripted localizations. Meanwhile, regular variables are restricted to only being defined in effect blocks.
* Temporary variables are unscoped: they will remain the same regardless of in which scope they're defined and where they're checked. Meanwhile, regular variables are restricted to scopes, so that the variable has different values depending on which scope it's checked in, such as how different countries may have different stability values.

=== 区域（Scoping） ===
'''Scoping only exists for regular variables.''' They can be assigned to countries, states, characters, and to the global scope.<br/>
The scopes are assigned by prepending any [[Scopes#Dual scopes|dual scope]] that can be used as a target before the variable's name, separated with a dot, such as <code>PREV.PREV.var_name</code> being the value of <code>var_name</code> as checked for <code>PREV.PREV</code> or <code>event_target:my_event_target.var_name</code>. This also includes <code>global</code> in order to assign it globally. Other variables, if pointing to a scope, can also be used, but the <code>var:</code> is unneeded. Variables can also be chained using the <code>:</code> separator (rather than the usual dot), such as <code>ABC.capital:var_name</code> being the variable <code>var_name</code> as it's assigned to the capital state of the country ABC, where <code>capital</code> is a built-in variable pointing to the capital state of the country. Note that the scope specifier preceding <code>capital</code> is separated from it by a <code>.</code> since it is a static (that is, non-variable) scope. The way to intuit this syntax is that the whole <code>ABC.capital</code> clause forms a variable scope specifier, in which <code>var_name</code> is accessed.

If there is no scope specified, then the current scope (or <code>THIS</code>) is implied. For example <code>set_variable = { var_name = 10 }</code> will create a variable with the name of <code>var_name</code> within the scope it's executed in (country, state, character, etc). However, in some cases where the implicit scope differs from <code>THIS</code>, such as state events and certain types of scripted GUI, using the implicit scope can cause in-game confusion on whether it refers to the default scope or ROOT. In these cases, it's better to specify <code>THIS.var_name</code> for the current scope or <code>ROOT.var_name</code> for ROOT. '''It is necessary to put in 'global' to scope into global''', it is never assumed by default.

Here are some examples of scoped variable references:
<pre>GER.var_name                               # Scopes to GER
123.var_name                                # Scopes to state 123
global.var_name                             # Scopes to global
province_controllers^1234:capital:var_name  # Scopes to the capital state of the country that controls the province 1234.
</pre>

=== Trigger usage ===
'''Only temporary variables can be modified within a trigger block.''' Regular variables can only be used in effects, while temporary can be used in both triggers and effects.

However, there's one aspect of triggers that's important to know: ''when'' each scope stops evaluating. If a scope stops evaluating, then the variable will not be modified anymore. In general, [[Scopes#Trigger scopes|trigger scopes]] that can select multiple targets are divided into two groups: <code>all_<scope type></code> and <code>any_<scope type></code>. The first group, requiring all targets to meet triggers, evaluates each target in order and stops when it encounters one where the triggers aren't met. The second group, requiring any target to meet triggers, evaluates each target and stops when it encounters a true one.<br/>
Empty trigger blocks are considered true by default, so one would instantly stop the validation of the second group (<code>any_</code> triggers). For this reason, [[Scopes#Scope limits|since scope limits are not supported in trigger scopes]], then the proper usage for modifying temp variables would be an [[Conditions#if|if statement]] that modifies the variable if the limit is met with no other triggers that can come up as true or false coming up.

=== Localisation ===
{{Hatnote|Parts of this section are transcluded from [[Localisation#Formatting variables]]}}
In order to display the value of a variable in localisation, <code>[?var_name]</code> is used, with the question mark signifying that it's a variable. '''The question mark is mandatory''' in order to distinguish the variable from the event targets. For example, such a localisation value will work: <code> var_value_tt: "There are [?num_of_dogs] dog(s) in the country"</code><br/>
By default, the scope where this is used gets assumed. Scoping works the same way as it does with variables regularly: <code> GER_var_value_tt: "There are [?GER.num_of_dogs] dog(s) in [GER.GetNameWithFlag]"</code>

If the variable points to a certain address with more localised text, such as a country, namespaces can be used in the same manner as with a regular tag or event target: <code> most_dogs_tt: "[?most_dogs.GetNameDefCap] has the most dogs out of any country."</code> Question marks are still mandatory to include in this case. {{#section-h:Localisation|Formatting variables}}
There's also a more precise way to display ''arguments'' that modify variables. Some such arguments have an optional <code>tooltip = localisation_key</code> argument within. This tooltip is notable since the value of that localisation key allows using two [[Localisation#Nested strings|strictly-internal variables]] marked with dollar signs: <code>$LEFT$</code> and <code>$RIGHT$</code>.<br/>
<code>$LEFT$</code> represents the variable's value before the operation, while <code>$RIGHT$</code> represents the variable's value after the operation. This can be used to let the player know the current and/or the potential value of the variable in the same localisation key without taking up more space with <code>custom_effect_tooltip</code>.

Here's an example of it being done:
<pre>add_to_variable = {
    var = num_dogs
    value = ENG.num_cats
    tooltip = add_cats_to_dogs_tt
}</pre>This is the effect itself. Within localisation, this would be done:
<pre> add_cat_to_dogs_tt: "Adds [ENG.GetAdjective] cats to our $LEFT$ dog(s) to get $RIGHT$ in total."</pre>

=== Additional usage ===
By default, an unset variable is equal to zero when checked. However, the game also provides a [[wp:null coalescing operator|null coalescing operator]] for variables, used with a question mark. For example, <code>cost = var_name?100</code> within a decision will result in the cost of the decision being the same as var_name for the country. However, if that variable was never set or was cleared beforehand, then the decision will cost 100 {{icon|political power|1}} instead of 0.

Similarly to flags, a variable can be set as targeted by appending the target with <code>@TAG</code>. However, there are differences: in variables this does not append the target's ID to the name but stores it as a separate variable, as well as it being possible to target far more than countries, but also, for example, states or ideology groups. A variable reference <code>var_name_@GER</code> would resolve to a variable named <code>var_name_GER</code>. If called in a scope where PREV<code>= { tag = ENG }</code>, a variable reference <code>var_name_@PREV</code> would resolve to a variable named <code>var_name_ENG</code>. This can even be applied to temporary variables. You can also target variables using the syntax <code>var_name_@var:target_var_name</code>, regardless of the type of their value: be it country, state, token, even a raw integer. Variables targeting tokenizable types such as ideology groups and ideas provides a powerful alternative to scoped variables for associating a set of variable fields together, enabling one to get around the fact that ideas, ideologies, etc. do not have their own scopes. Generally, when you target a token, it is pasted in as its underlying integer ID (a number in the ten-thousands, usually), but this generally works fine, because it's consistent; the only problem is it's not human-readable. '''Note that it is not possible to use targeting in the name of an array, this will crash the game to desktop without a helpful error or crash message.''' If you must have a dynamically-named array, an alternative is to use a meta-effect or meta-trigger to paste the appropriate token into the array name. In general, variable targeting is substantially more optimized than meta-effect/trigger token pasting, not to mention more readable and understandable, so should be preferred wherever feasible.

It is technically possible, under some circumstances, to use multiple target specifiers in one variable name, usually strung together back-to-back at the end of the name, like <code>var_name_@THIS_@PREV</code>. However, this is extremely inconsistent, and the exact rules that govern how it behaves are currently an open question.

=== Operators ===
The following is a list of variable-related effects and triggers. Variable-modifying effects have an equivalent for temporary variables, with <code>temp_variable</code> being used instead of <code>variable</code>, and these temporary variable operators are also valid triggers, as described above. Every operator can be used with variables that do not exist, assuming a value of 0 unless a null-coalescing operator is used.
{| class="wikitable sortable mw-collapsible" style="display: inline-block; padding: 5px" width="100%"
|+ {{nowrap|Variable-related arguments:}}
! width="10%" |Name
! width="25%" |Parameters
! width="25%" |Examples
! width="20%" |Description
! width="20%" |Notes
|-id="set_variable"
|set_variable
|<code>var = <variable></code><br/>要修改或创建的变量。<br/>
<code>value = <decimal>/<variable></code><br/>要将变量设置为的值。<br/>
<code>tooltip = localisation_key</code>Localisation used  

by the operation. Optional. 
|<pre>set_variable = {
    var = my_variable
    value = 100
    tooltip = set_var_to_100_tt
}</pre>
<pre>set_temp_variable = { temp_var = ROOT.overlord }</pre>
|将变量值设置为指定值，如果未定义，则创建它。
|缩短版本存在于<code>set_variable = { <variable> = <value> }</code>.
|-id="set_variable_to_random"
|set_variable_to_random
|<code>var = <variable></code><br/>要修改或创建的变量。<br/>
<code>min = <decimal></code><br/>最小可能值，默认为0。<br/>
<code>max = <decimal></code><br/>最大可能值，默认为1。<br/>
<code>integer = <bool></code><br/>设置变量必须是整数还是可以是小数。默认为false。<br/>
|<pre>set_variable_to_random = {
    var = random_num
    max = 11
    integer = yes
}</pre>
<pre>set_temp_variable_to_random = my_var</pre>
|将变量值设置为指定值，如果未定义，则创建它。结果将大于或等于最小值，并且严格小于最大值。
|缩短版本存在于<code>set_variable_to_random = <variable></code>,将其设置为0到1之间的十进制数。可以在触发器中使用。
|-id="clear_variable"
|clear_variable
|<code><variable></code><br/>要清除的变量。
|<pre>clear_variable = my_variable</pre>
|Clears the value from the memory entirely.
|Can only be used on regular variables. 
|-id="check_variable"
|check_variable
|<code>var = <variable></code><br/>要比较的变量。<br/>
<code>value = <decimal>/<variable></code><br/>要与变量进行比较的值。<br/>
<code>compare = <compare type>/<variable></code><br/>比较类型，有<code>equals</code>, <code>not_equals</code>, <code>less_than</code>, <code>less_than_or_equals</code>, <code>greater_than</code>,<code>greater_than_or_equals</code>. 

默认为<code>greater_than_or_equals</code>.
|<pre>check_variable = {
    var = my_var
    value = 10
    compare = greater_than_or_equals
}</pre>
<pre>check_variable = { var_name > 10 }</pre>
|比较变量的值。用作触发器。
|Temporary and regular formatting use the exact same formatting. Shortened variant exists as <code>check_variable = { <variable> < <value> }</code>, where the operator in the middle is an equality sign (=), greater than sign (>), or a lesser than sign (<). The comparison type is always strict in this case: <code>check_variable = { var_name > 10 }</code> will come up as false if <code>var_name</code> is exactly 10.
|-id="has_variable"
|has_variable
|<code><variable></code><br/>要检查的变量。
|<pre>has_variable = my_variable</pre>
|Checks if the value was set, regardless of its amount. Used as a trigger.
|A variable is considered set even if its value is 0, as long as it wasn't cleared.
|-id="add_to_variable"
|add_to_variable
|<code>var = <variable></code><br/>要添加的变量。<br/>
<code>value = <decimal>/<variable></code><br/>要添加到变量中的值。<br/>
<code>tooltip = localisation_key</code>操作使用的本地化。可选。 
|<pre>add_to_variable = {
    var = my_variable
    value = 100
    tooltip = add_100_to_var_tt
}</pre>
<pre>add_to_temp_variable = { temp_var = num_owned_states }</pre>
|将变量值增加指定的量，如果未定义，则创建它。
|Shortened version exists with <code>add_to_variable = { <variable> = <value> }</code>.
|-id="subtract_from_variable"
|subtract_from_variable
|<code>var = <variable></code><br/>要减去的变量。<br/>
<code>value = <decimal>/<variable></code><br/>要减去到变量中的值。<br/>
<code>tooltip = localisation_key</code>Localisation used by the operation. Optional.
|<pre>subtract_from_variable = {
    var = my_variable
    value = -100
    tooltip = add_100_to_var_tt
}</pre>
<pre>subtract_from_temp_variable = { temp_var = num_owned_states }</pre>
|将变量值减去指定的量。
|Shortened version exists with <code>subtract_from_variable = { <variable> = <value> }</code>. Equivalent to adding a negative amount.
|-id="multiply_variable"
|multiply_variable
|<code>var = <variable></code><br/>要相乘的变量。<br/>
<code>value = <decimal>/<variable></code><br/>要相乘到变量中的值。<br/>
<code>tooltip = localisation_key</code>Localisation used by the operation. Optional. 
|<pre>multiply_variable = {
    var = my_variable
    value = 100
    tooltip = multiply_var_by_100_tt
}</pre>
<pre>multiply_temp_variable = { temp_var = num_owned_states }</pre>
|将变量值相乘指定的量。
|Shortened version exists with <code>multiply_variable = { <variable> = <value> }</code>.
|-id="divide_variable"
|divide_variable
|<code>var = <variable></code><br/>要除以的变量。<br/>
<code>value = <decimal>/<variable></code><br/>要除以到变量中的值。<br/>
<code>tooltip = localisation_key</code>Localisation used by the operation. Optional. 
|<pre>divide_variable = {
    var = my_variable
    value = 100
    tooltip = divide_var_by_100_tt
}</pre>
<pre>divide_temp_variable = { temp_var = num_owned_states }</pre>
|将变量值除以指定的量。
|Shortened version exists with <code>divide_variable = { <variable> = <value> }</code>.
|-id="modulo_variable"
|modulo_variable
|<code>var = <variable></code><br/>The variable to modulo.<br/>
<code>value = <decimal>/<variable></code><br/>The value to modulo the variable by.<br/>
<code>tooltip = localisation_key</code>Localisation used by the operation. Optional. 
|<pre>modulo_variable = {
    var = my_variable
    value = 50
    tooltip = get_modulo_of_var_by_50_tt
}</pre>
<pre>modulo_temp_variable = { temp_var = num_controlled_states }</pre>
|Makes the variable become the remainder of [[wp:Euclidean division|Euclidean division]] of the variable by the specified value.
|Shortened version exists with <code>modulo_variable = { <variable> = <value> }</code>.
|-id="round_variable"
|round_variable
|<code><variable></code><br/>The variable to round.
|<pre>round_variable = my_variable</pre>
<pre>round_temp_variable = temp</pre>
|Rounds the variable towards the closest integer value.
|If exactly between two integers (Such as 1.5), the larger option gets chosen.
|-id="clamp_variable"
|clamp_variable
|<code>var = <variable></code><br/>The variable to clamp.<br/>
<code>min = <decimal>/<variable></code><br/>The minimum value of the variable after the clamp.<br/>
<code>max = <decimal>/<variable></code><br/>The maximum value of the variable after the clamp.
|<pre>clamp_temp_variable = {
    var = my_var
    min = 0
}</pre>
|Clamps the variable to ensure its value is between the two specified numbers, raising to the minimum if smaller or lowering to the maximum if larger.
|Either min or max can be omitted, in which case it'll not be checked. Does nothing if the variable is already in the range between min and max. '''This only changes the current value of the variable''', it can still go beyond the minimum or the maximum after the clamp.
|}

=== Usage examples ===
A common usage for variables is to grant a more 'complex' effect or a trigger. This is best done with temporary variables, as they can be set in either triggers or effects and they're not bound to scopes making operations on them more simple.<br/>
For example, the following can take 0.1% of every controlled state's population and add it directly to the manpower pool if the country has more democratic party support than fascist and communist party support combined:
<pre>if = {
    limit = {
        set_temp_variable = { fascom_pop = party_popularity@fascism }
        add_to_temp_variable = { fascom_pop = party_popularity@communism }
        check_variable = { party_popularity@democratic > fascom_pop }   # Completely hidden from the player.
    }                                                                   # 'limit = {}' is always hidden so it doesn't matter here, but use custom_trigger_tooltip when wanting the player to be aware.
    hidden_effect = {   # Every controlled state can look weird to the player otherwise.
        set_temp_variable = { temp_manpower = 0 }   # Optional, can be omitted as variables are assumed to be 0 if unset.
        every_controlled_state = {
            add_to_temp_variable = { temp_manpower = state_population_k } # Executed in the state's scope, so state_population_k is of the state. 
        }                                                                 # However, temp variables are unscoped so it doesn't matter where they're edited.
    }
    add_manpower = var:temp_manpower # 'add_manpower = temp_manpower' also works
}</pre>

Additionally, it is common for a variable to be a counter of something within a mechanic. For example, let CAN_beavers be a counter of beavers within the country.<br/>
When using variables in this sense, '''it is better to use [[Effect#Scripted effects|scripted effects]] to modify them''', in order to make changes to the variable easier. For example, a small gain in beavers could be the following:
<pre>CAN_beavers_small_add = {
    custom_effect_tooltip = CAN_beavers_small_add_tt    # Tooltip for the player to be aware.
    add_to_variable = { CAN_beavers = 100 } # Adds 100 beavers.
}</pre>
However, if 100 seems like too little, the scripted effect can be changed and it'll immediately apply the changes every single time that scripted effect was used without needing to find them manually. These effects may also share a single 'recalculating' scripted effect in common. This can be used to clamp the variable between a minimum and a maximum, to have an instant effect as soon as some variable value is reached, or to have another variable 'tied' to the value to be kept at an exact or a dynamic ratio. For example, these scripted effects can be used with the same CAN_beavers example:
<pre>CAN_beavers_calibrate = {
    clamp_variable = {  # The variable will be kept between these levels by calling this each time the variable is changed.
        var = CAN_beavers
        min = 0
        max = 2000
    }
    
    set_variable = { CAN_beavers_modifier = CAN_beavers }
    divide_variable = { CAN_beavers_modifier = 1000 }   # Another variable tied to the base value.
    
    if = {
        limit = {
            check_variable = { CAN_beavers = 0 }
        }
        country_event = CAN_beavers_extinction.0    # The event gets fired as soon as CAN_beavers hits 0.
    }
}

CAN_beavers_small_add = {   # Same as before, but with calling the previous effect
    custom_effect_tooltip = CAN_beavers_small_add_tt
    add_to_variable = { CAN_beavers = 100 }
    CAN_beavers_calibrate = yes
}

CAN_beavers_small_remove = { # Another example of a variable-modifying effect
    custom_effect_tooltip = CAN_beavers_small_remove_tt
    add_to_variable = { CAN_beavers = -100 }    # 'subtract_from_variable = { CAN_beavers = 100 }' also works.
    CAN_beavers_calibrate = yes
}</pre>
After creating these scripted effects, these can be used within any effect block to modify the variable at will. [[#Additional usage|Showing its value in localisation to the player]] would also be helpful, such as within a [[Decision modding|decision category]] or in [[Scripted GUI modding|scripted GUI]]. '''Variables cannot be used within idea modifiers directly, [[Modifiers#Dynamic_modifiers|dynamic modifiers can be used instead.]]'''

Remember that variables are not necessarily used as numbers only. For example, the simplest way to make the current ideology group to change to the one that's the most popular (aside from the ruling party) would be a <code>set_politics = { ruling_party = highest_party_ideology@exclude_ruling_party }</code>. Similarly, some event target-type variables can be used to cut down on code, such as <code>transfer_state = GER.capital</code> immediately transferring the capital of GER to the current scope. 
=== MTTH variables ===
MTTH variables allow to dynamically create a [[AI modding#MTTH blocks|MTTH block]] to be used as a variable. These are stored within {{path|common/mtth/*.txt}} files, where each MTTH variable is a separate block, the name of which gets taken as the MTTH variable.<br/>
As per the name, the MTTH variables serve as a MTTH block, so everything that applies to MTTH blocks applies here: The starting base is defined with <code>factor</code> or <code>base</code> and then each <code>modifier = { ... }</code> begin a trigger block needed to be fulfilled for the <code>add</code> (for adding) or/and <code>factor</code> (for multiplying) within to be applied.
For example, the following is an example of a {{path|common/mtth/*.txt}} file:
<pre>my_mtth_variable_1 = {
    base = 10
    modifier = {
        factor = 10
        is_major = yes
    }
    modifier = {
        add = -10
        tag = FRA
    }
}
my_mtth_variable_2 = {
    base = other_variable
    factor = 0.5
    add = 10
}</pre>
This can be called the same way as a game variable, but somewhat differently: <code>set_variable = { my_var = mtth:my_mtth_variable_1 }</code>. This will check the MTTH block for the scope where it's checked and return the total result as a variable.
=== 调试变量（Debugging variables） ===
在触发器或效果块中可以使用以下参数:
{| class="wikitable sortable mw-collapsible" style="display: inline-block; padding: 5px" width="100%"
|+ {{nowrap|Debugging-related arguments:}}
! width="10%" |Name
! width="25%" |Parameters
! width="25%" |Examples
! width="20%" |Description
! width="20%" |Notes
|-id="log"
|log
|<code><string></code><br/>日志中要写什么。
|<pre>log = "Current value of myVar: [?myVar]"</pre>
|Creates an entry in the {{path|logs/game.log}} file in the [[Modding|user directory]] and, if console is open and debug mode is turned on, in console as well.
|While it nominally has nothing to do with variables, its most common use is for variables.
|-id="print_variables"
|print_variables
|<code>file = <string></code><br/>The name of the file, not counting the file extension. Defaults to "variable_dump".<br/>
<code>text = <string></code><br/>What will be printed in the beginning of the file. Defaults to "No Header".<br/>
<code>append = yes</code><br/>If set, will append the current variables (and the text) to the end of the file instead of overwriting.<br/>
<code>print_global = yes</code><br/>If true, will print the variables from the global scope as well.<br/>
<code>var_list = { ... }</code><br/>A whitespace-separated list of variables the values of which should be printed. Optional: every variable in the scope (and global if set) if left out.
|<pre>print_variables = {
    file = my_file
    text = "These variables are printed at [GetDateText]"
    append = yes
    print_global = yes
}</pre>
<pre>print_variables = {
    file = my_file_2
    var_list = { temp1 temp2 temp3 }
}</pre>
|Dumps the specified variables from the current scope and optionally the global scope into a log file with the specified name. 
|The log will be within {{path|logs/variable_dumps/}} in the [[Modding|user directory]]. 
|}

此外，以下控制台命令适用于变量。在控制台命令中,“当前范围”是当前被选中的:在外交中打开的国家，被选中的省份，被选中的单位领袖。如果被排除在外，假定为玩家国家
{| class="wikitable sortable mw-collapsible" style="display: inline-block; padding: 5px" width="100%"
|+ {{nowrap|Debugging-related console commands:}}
! width="10%" |Name
! width="25%" |Parameters
! width="25%" |Examples
! width="40%" |Description
|-id="set_var"
|set_var
|<code><variable></code><br/>要获取其值的变量<br/>
<code><value></code><br/>将变量设置为什么。
|<pre>set_var my_variable 10</pre>
|在指定范围内更改变量的值。
|-id="get_var"
|get_var
|<code><variable></code><br/>要获取其值的变量
|<pre>get_var my_variable</pre>
|打印控制台中变量的值。
|-id="list_vars"
|list_vars
|<code><scope></code>可选。将范围从当前选定的范围更改为指定的范围。
|<pre>list_vars</pre>
|列出当前选定范围内的变量及其值。
|}

=== Token-valued variables ===
When one uses a literal of the form <code>token:some_tokenizable_value</code>, what is actually returned is an integer variable (commonly with a large value), with an internal flag set so that it is interpreted as an index into a central table of token strings that exists within the game's memory. This can be placed into a variable and passed around freely, it can be compared for equality to other token variables, and it can even be treated as a numeric in arithmetic even if usages for such cases are rare if nonexistent. Variables that have the token flag set can be distinguished in the output of the <code>list_vars</code> console command by dint of being automatically translated into their underlying raw-token strings. For example, <code>some_var_name = token:some_tokenizable_value (27012)</code>.

When the variable contains a token value, it is possible to use the <code>GetTokenKey</code> [[Localisation#Functions|localisation function]] (such as <code>[?some_var_with_token_value.GetTokenKey]</code>) to get the token string value of the variable, <code>token:</code> prefix not included. This is useful for pasting in [[Effect#Meta_effects|meta-effects]] and [[Conditions#Meta_triggers|meta-triggers]], however note that the <code>token:</code> prefix is still required if using it within the <code>set_(temp_)variable</code> operator. With some token-valued variables (specifically, those backed by named database objects of a tokenizable datatype), it is possible to use <code>GetTokenLocalizedKey</code> to retrieve the value of the localisation key with the same name as the token itself. This can be used to produce and/or define human-readable names, but it can also be taken advantage of to pass around arbitrary localisation values.

At present (1.12), known tokenizable datatypes include (but are probably not limited to):
* Ideas: These are generally the most flexible tokenizable datatype to use for a token that represents some arbitrary value by using a dummy idea. They can also carry an effectual payload in their <code>on_add</code> clauses, which can be used to pass around effects, or better yet, to return a set of variables encoding information relevant to the token value.
* Ideologies/Ideology groups
* Technologies
* Equipment types - Sometimes this is a bit inconsistent with regards to the archetype/non-archetype distinction, so be wary.
* Operations
* Characters/Unit leaders: These are finicky in the game's core. When a character is promoted to a unit leader position, all tokenizations of that character's token will begin to return a different value, representing the token for the unit leader with the same identifier, which is linked to, but not the same as, the original character. The unit leader version of the token returns the same <code>GetTokenKey</code> and <code>GetTokenLocalizedKey</code>, but it is ''not numerically equal to the character version of the token.'' This can come into play if code compares the equality of two character-pointing variables.
* Decisions
* Buildings

=== Advanced use of tokens ===
Using tokenizable values in variables is the key to a number of advanced techniques that enable relatively seamless abstraction and metaprogramming, with a minimum of scripted-localisation boilerplate code. These techniques are, however, difficult to learn how to apply and can be unintuitive for those not already experienced. Therefore, caution is advised.

It is often useful to define related dummy tokenizable database entries, especially ideas, to represent arbitrary (possibly enumerable) custom datatypes. In most cases, ideas are preferable, however there can be uses for other token types, such as technologies if the code is to implement something that can't be done with a regular idea. The reason for idea preference is little to no downstream effects simply from existing, ease to define in bulk with minimal syntactic overhead, and ease to separate different custom datatypes by using custom idea categories and by placing the definitions for different custom datatypes in different files within {{path|common/ideas/}}. Decisions or technologies are common alternatives for custom datatypes with different usages, but generally datatypes other than these have too much downstream baggage (i.e. their very existence has consequences elsewhere, such as custom building types appearing automatically in certain UIs) to be worth using for dummy values. 

Using a systematic naming scheme, custom tokenizable datatypes can also convey multiple related localisation keys, similarly to the approach that the base game does for country naming with separate <code>TAG</code>, <code>TAG_DEF</code>, and <code>TAG_ADJ</code> keys. An example of that would be creating an idea <code>foo_bar</code> to act as the key identifier of the custom data value, whose localisation value carries the human-readable name of the data value, and another idea <code>foo_bar_description</code> ('''NOT <code>foo_bar_desc</code>, this collides with the localisation key generated for <code>foo_bar</code>''') to carry the localisation value for the description that would be associated with the data value identified by <code>foo_bar</code>. This description localisation can be accessed with a meta-effect or meta-trigger (including in scripted localisation), such as <code>set_temp_variable = { description_var = token:[IDEA_TOKEN]_description }</code> (where <code>IDEA_TOKEN = "[?idea_var_name.GetTokenKey]"</code>). This allows accessing <code>[?description_var.GetTokenLocalizedKey]</code> in localisation where <code>description_var</code> is visible, such as the <code>localization_key</code> following the scripted localisation <code>trigger</code> block where the pasting meta-trigger is called.

As far more advanced usage, it is possible to rig up the dummy tokenizable values with arbitrary localisation payloads that carry fragments of Clausewitz code which can then be pasted together in meta-effects (or triggers) to approximate true token string manipulation or at least concatenation, as there's presently no way to split strings, token or otherwise. This is probably most useful for encoding a set of suffixes that can be applied to an idea token to dynamically navigate within the custom datatype's naming scheme. For example, if the mod has a custom datatype representing positions within a government such as the Secretary of State and the Attorney General, such that it might have a base idea <code>position_attorney_general</code>, a corresponding description idea (suffixed with <code>_description</code>), a singular name idea (suffixed with <code>_singular</code>, carrying the name of the data value in singular form, like "Attorney General"), and a plural name idea (suffixed with <code>_plural</code>, carrying the name in plural form, like "Attorneys General"), it is possible to select which name to use by having a dummy idea called <code>enum_position_name_singular</code> with the localisation value <code>"_singular"</code>, and another called <code>enum_position_name_plural</code> with the localisation value <code>"_plural"</code>. After that, the mod may pass one of the <code>enum_position</code> ideas in a variable and then paste its <code>GetTokenLocalizedKey</code> after the <code>GetTokenKey</code> of the base idea in a meta-effect/trigger to produce either <code>token:position_attorney_general_singular</code> or <code>token:position_attorney_general_plural</code>. This is a contrived example, and is also possible to be done using a scripted localisation system with hard-coded entries to access the singular vs. plural ideas, but this approach has far more use in more complex systems where creating a scripted localisation file can prove to be far too bulky.

From 1.12 onwards, anything defined in {{path|common/script_enums.txt}} can be freely tokenized, even if defined in a totally custom enumeration block, seperate from the ones hard-coded into the game. It is therefore theoretically possible to define arbitrary tokens of a custom enum type in this file. However, for compatibility reasons, using <code>script_enums</code> for custom enumeration types should be avoided, as this will ensure that the mod will not be compatible with any other mod that overwrites that file, no matter which mod gets priority on the file. As before, it's preferable to have a custom idea category with a set of dummy ideas in their own file that will not be overridden by other mods representing the values the custom enum can take on. This pattern is a useful replacement for passing around arbitrary integers that have some enumerable meaning when interpreted by code, especially if those integers are interpreted to yield names in scripted localisation, in which case this pattern can substantially remove the need for scripted localisation boilerplate by allowing defining the localised name for each enum member directly in a localisation file, as similarly to defining the localised name for an idea.

Technically, any raw token used in the language can actually be tokenized: for instance, <code>token:set_stability</code> (that is, a token literal of the name of the [[Effect#Mana|set_stability effect]]) is perfectly valid, and yields a token for which <code>GetTokenKey</code> and <code>GetTokenLocalizedKey</code> both return <code>set_stability</code>. However, this is rarely useful (especially since it does not apply to scripted effect and trigger names), and arguably counts as a bug; it mostly just provides an interesting peek into the internals of the tokenization system, indicating that it most likely delegates to a pre-existing string de-duplication system built into the Clausewitz engine.

== Modifier tokens ==
{{Hatnote|This section is transposed from [[Modifiers#Modifier tokens|Modifiers § Modifier definitions]]}}
{{#lsth:Modifiers|Modifier definitions}}

== Arrays ==
Arrays are similar to variables, but they instead store a collection of variables.<br/>
An array in the game is structured with indexes starting from 0. <code>arrayname^0</code> as a variable refers to the first item of <code>arrayname</code>, <code>arrayname^1</code> refers to the second item in the array, and so on. In order to obtain the total amount of items within the given array, <code>arrayname^num</code> is used. An array is assumed to have no elements by default, if not already created, with [[#add_to_array|add_to_array or add_to_temp_array]] usually being used to create an array.

Temporary and regular arrays exist, with the same distinction between them as in variables: temp arrays can be set and modified in triggers and effects, are unscoped, and cleared after the effect/trigger block ends; regular arrays can only be set or modified in effects, are linked to a specific scope, and persist forever until cleared manually.

A single element of an array is considered a variable in every regard: <code>set_variable = { arrayname^0 = 10 }</code> will set the first element to be equal to 10 (with <code>set_temp_variable</code> used for temporary arrays), <code>check_variable = { arrayname^0 > 10 }</code> is also valid syntax, and <code>[?arrayname^0]</code> will print the value of the element in localisation. However, the element must already exist for it to be edited. '''There is no simple way to print an entire array in localisation''', however a recursive scripted localisation can be used, which modifies the value of a temporary variable by one until hitting the array's size each time that it's used.
=== Arguments ===
以下是数组的参数。 Similarly to variables, temporary versions exist by replacing <code>array</code> with <code>temp_array</code>.
{| class="wikitable sortable mw-collapsible" style="display: inline-block; padding: 5px" width="100%"
|+ {{nowrap|Arguments for modifying arrays:}}
! width="10%" |Name
! width="25%" |Parameters
! width="25%" |Examples
! width="20%" |Description
! width="20%" |Notes
|-id="add_to_array"
|add_to_array
|<code>array = <array></code><br/>The array to modify.<br/>
<code>value = <decimal>/<variable></code><br/>The variable to add.<br/>
<code>index = <integer></code><br/>The index to place the variable on in the array. Optional, defaults to the end of the array.
|<pre>add_to_array = {
    array = global.my_countries
    value = THIS.id
}</pre>
<pre>add_to_temp_array = { temp_states = THIS }</pre>
|Adds an element to the variable either at the end or the specified index.
|Shortened version exists with <code>add_to_array = { <array> = <value> }</code>.
|-id="remove_from_array"
|remove_from_array
|<code>array = <array></code><br/>The array to modify.<br/>
<code>value = <decimal>/<variable></code><br/>The variable to remove. Optional.<br/>
<code>index = <integer></code><br/>The index to remove the variable from in the array. Optional.
|<pre>remove_from_array = {
    array = global.my_countries
    index = 0
}</pre>
<pre>remove_from_temp_array = { temp_states = THIS }</pre>
|Removes an element from the variable either with the specified value or the index.
|Shortened version exists with <code>remove_from_array = { <array> = <value> }</code>. If neither value nor index are specified, then the last element is deleted.
|-id="clear_array"
|clear_array
|<code><array></code><br/>The array to clear.
|<pre>clear_array = global.my_countries</pre>
<pre>clear_temp_array = temp_states</pre>
|Clears the array, removing every element inside.
|
|-id="resize_array"
|resize_array
|<code>array = <array></code><br/>The array to modify.<br/>
<code>value = <decimal>/<variable></code><br/>The variable to add to the array if the size is larger than the array's current size. Optional, defaults to 0.<br/>
<code>size = <integer></code><br/>The amount of elements inside of the array after the resizing.
|<pre>resize_array = {
    array = global.countries_by_states
    value = 10
    size = global.countries^num
}</pre>
<pre>resize_temp_array = { temp_states = 20 }</pre>
|Resizes the array, removing or adding elements in the end if necessary.
|Shortened version exists with <code>resize_array = { <array> = <size> }</code>.
|-id="find_highest_in_array"
|find_highest_in_array
|<code>array = <array></code><br/>The array to modify.<br/>
<code>value = <variable></code><br/>The temporary variable where the largest value will get stored.<br/>
<code>index = <variable></code><br/>The temporary variable where the index of the largest value will get stored.
|<pre>find_highest_in_array = {
    array = global.countries_by_states
    value = temp_largest_country
    index = temp_country_index
}</pre>
|Finds the largest value in the array and assigns its value and index to a temporary variable.
|Either value or index are optional to specify.
|-id="find_lowest_in_array"
|find_lowest_in_array
|<code>array = <array></code><br/>The array to modify.<br/>
<code>value = <variable></code><br/>The temporary variable where the smallest value will get stored.<br/>
<code>index = <variable></code><br/>The temporary variable where the index of the smallest value will get stored.
|<pre>find_lowest_in_array = {
    array = global.countries_by_states
    value = temp_largest_country
    index = temp_country_index
}</pre>
|Finds the smallest value in the array and assigns its value and index to a temporary variable.
|Either value or index are optional to specify.
|}
Meanwhile, the following triggers exist that are array-related. As with variables, these are the exact same for temporary and regular variables. 
{| class="wikitable sortable mw-collapsible" style="display: inline-block; padding: 5px" width="100%"
|+ {{nowrap|Array-related triggers:}}
! width="10%" |Name
! width="25%" |Parameters
! width="25%" |Examples
! width="20%" |Description
! width="20%" |Notes
|-id="is_in_array"
|is_in_array
|<code>array = <array></code><br/>要检查的数组。<br/>
<code>value = <decimal>/<variable></code><br/>要检查的值。
|<pre>is_in_array = {
    array = global.my_countries
    value = THIS.id
}</pre>
<pre>is_in_array = { temp_states = THIS }</pre>
|Checks if any value within the array is the same as the specified value.
|Shortened version exists with <code>is_in_array = { <array> = <value> }</code>.
|-id="any_of"
|any_of
|<code>array = <array></code><br/>The array to check.<br/>
<code>value = <variable></code><br/>The name of the temporary variable where the value of the currently-selected element is stored.<br/>
<code>index = <variable></code><br/>The name of the temporary variable where the index of the currently-selected element is stored.<br/>
<code><triggers></code><br/> An AND trigger block.
|<pre>any_of = {
    array = temp_numbers
    value = v
    index = i
    multiply_temp_variable = { v = i }
    check_variable = { v > political_power }     # Checks if the value multiplied by the index is larger than the political power of the country this is checked in.
}</pre>
|Checks if any value within the array fulfills the triggers, halting and returning true if that's the case.
|The scope does not change from the one this is checked in by default, requiring one of [[scopes]].
|-id="any_of_scopes"
|any_of_scopes
|<code>array = <array></code><br/>The array to check.<br/>
<code>tooltip = <localisation key></code><br/>The localisation key used for the trigger.<br/>
<code><triggers></code><br/> An AND trigger block.
|<pre>any_of_scopes = {
    array = global.majors
    tooltip = has_more_states_than_any_other_major_tt
    NOT = { tag = PREV }
    check_variable = { num_owned_controlled_states > PREV.num_owned_controlled_states }
}</pre>
|Checks if any value within the array fulfills the triggers, halting and returning true if that's the case, scoping into each element in the array.
|Appending <code>_NOT</code> to the tooltip's key (such as has_more_states_than_any_other_major_tt_NOT in the example) results in the localisation key used if this any_of_scopes is put inside of <code>NOT = { ... }</code>. Since this changes scopes, [[Scopes#PREV]] would, unless there's deeper scoping, refer to the scope this trigger is checked in.
|-id="all_of"
|all_of
|<code>array = <array></code><br/>The array to check.<br/>
<code>value = <variable></code><br/>The name of the temporary variable where the value of the currently-selected element is stored.<br/>
<code>index = <variable></code><br/>The name of the temporary variable where the index of the currently-selected element is stored.<br/>
<code><triggers></code><br/> An AND trigger block.
|<pre>all_of = {
    array = temp_numbers
    value = v
    index = i
    multiply_temp_variable = { v = i }
    check_variable = { v > political_power }     # Checks if the value multiplied by the index is larger than the political power of the country this is checked in.
}</pre>
|Checks if every value within the array fulfills the triggers, halting and returning false if any one doesn't.
|The scope does not change from the one this is checked in by default, requiring one of [[scopes]].
|-id="all_of_scopes"
|all_of_scopes
|<code>array = <array></code><br/>The array to check.<br/>
<code>tooltip = <localisation key></code><br/>The localisation key used for the trigger.<br/>
<code><triggers></code><br/> An AND trigger block.
|<pre>all_of_scopes = {
    array = global.majors
    tooltip = has_more_states_than_every_other_major_tt
    OR = { 
        tag = PREV
        check_variable = { num_owned_controlled_states < PREV.num_owned_controlled_states }
    }
}</pre>
|Checks if every value within the array fulfills the triggers, halting and returning false if any one doesn't, scoping into each element in the array.
|Appending <code>_NOT</code> to the tooltip's key (such as has_more_states_than_every_other_major_tt_NOT in the example) results in the localisation key used if this any_of_scopes is put inside of <code>NOT = { ... }</code>. Since this changes scopes, [[Scopes#PREV]] would, unless there's deeper scoping, refer to the scope this trigger is checked in.
|}
The following effects also exist in addition used, with arrays. While some are nominally unrelated to arrays, they are often used in conjunction.
{| class="wikitable sortable mw-collapsible" style="display: inline-block; padding: 5px" width="100%"
|+ {{nowrap|Array-related effects:}}
! width="10%" |Name
! width="25%" |Parameters
! width="25%" |Examples
! width="20%" |Description
! width="20%" |Notes
|-id="for_each_loop"
|for_each_loop
|<code>array = <array></code><br/>The array to check.<br/>
<code>value = <variable></code><br/>The name of the temporary variable where the value of the currently-selected element is stored.<br/>
<code>index = <variable></code><br/>The name of the temporary variable where the index of the currently-selected element is stored.<br/>
<code>break = <variable></code><br/>The temporary variable that can be set to be not 0 to instantly break the loop.<br/>
<code><effects></code><br/> An effect block.
|<pre>for_each_loop = {
    array = temp_numbers
    value = v
    break = break
    random_list = {
        10 = { add_political_power = v }
        10 = {
            divide_temp_variable = { v = 100 }
            add_stability = v
        }
        10 = {
            divide_temp_variable = { v = 100 }
            add_war_support = v
        }
    }
}</pre>
|Runs an effect once for every element in the array.
|The scope does not change from the one this is checked in by default, requiring one of [[scopes]].
|-id="for_each_scope_loop"
|for_each_scope_loop
|<code>array = <array></code><br/>The array to check.<br/>
<code>break = <variable></code><br/>The temporary variable that can be set to be not 0 to instantly break the loop.<br/>
<code><effects></code><br/> An effect block.
|<pre>for_each_scope_loop = {
    array = global.majors
    if = {
        limit = {
            NOT = { tag = ROOT }
        }
        random_owned_controlled_state = {
            transfer_state_to = ROOT
        }
    }
}</pre>
|Runs the effects for every scope within the array.
|Equivalent to a <code>every_<...></code> effect scope type, with additional <code>break</code>. Since this changes scopes, [[Scopes#PREV]] would, unless there's deeper scoping, refer to the scope this trigger is checked in.
|-id="random_scope_in_array"
|random_scope_in_array
|<code>array = <array></code><br/>The array to check.<br/>
<code>break = <variable></code><br/>The temporary variable that can be set to be not 0 to instantly break the loop.<br/>
<code>limit = { <triggers> }</code><br/>An AND trigger block deciding which scopes can be picked.<br/>
<code><effects></code><br/> An effect block.
|<pre>random_scope_in_array = {
    array = global.countries
    break = break
    limit = {
        is_dynamic_country = no
        exists = no
        any_state = {
            is_core_of = PREV   # Is core of the currently-checked country
        }
    }
    random_core_state = {
        transfer_state_to = PREV    # Transfers to the currently-selected country.
    }
}</pre>
|Runs the effects for a random scope within the array.
|Equivalent to a <code>random_<...></code> effect scope type, with additional <code>break</code>. Since this changes scopes, [[Scopes#PREV]] would, unless there's deeper scoping, refer to the scope this trigger is checked in.
|-id="while_loop_effect"
|while_loop_effect
|<code>limit = { <triggers> }</code><br/>An AND trigger block deciding when the effect would repeat.<br/>
<code>break = <variable></code><br/>The temporary variable that can be set to be not 0 to instantly break the loop.<br/>
<code><effects></code><br/> An effect block.
|<pre>while_loop_effect = {
    limit = {
        any_country = {
            num_owned_controlled_states > 10
        }
    }
    random_country = {
        limit = {
            num_owned_controlled_states > 10
        }
        random_other_country = {
            limit = {
                num_owned_controlled_states < 10
            }
            PREV = {
                random_owned_controlled_state = {
                    transfer_state_to = PREV.PREV
                }
            }
        }
    }
}</pre>
|Runs the effects as long as the limit is fulfilled.
|The limit is only checked at the beginning and once the effect block is executed. Can't run for more than 1000 times by default<ref name="loop"><code>NDefines.NGame.MAX_EFFECT_ITERATION = 1000</code> in [[Defines]]</ref>.
|-id="for_loop_effect"
|for_loop_effect
|<code>start = <decimal>/<variable></code><br/>The value at which the evaluation starts. Default to 0.<br/>
<code>end = <decimal>/<variable></code><br/>The value at which the evaluation ends. Default to 0.<br/>
<code>compare_type = <compare type></code><br/>How the currently-evaluated value must compare with the <code>end</code> for the for loop to continue. Defaults to <code>less_than</code>, leading to the end value never being picked.<br/>
<code>add = <variable></code><br/>How much is being added to the <code>start</code> value for every iteration. Defaults to 1.<br/>
<code>break = <variable></code><br/>The temporary variable that can be set to be not 0 to instantly break the loop.<br/>
<code>value = <variable></code><br/>The name of the temporary variable where the current value of evaluation is stored.<br/>
<code><effects></code><br/> An effect block.
|<pre>for_loop_effect = {
    end = 4
    value = temp
    if = {
        limit = {
            NOT = {
                count_triggers = {
                    amount = 2
                    check_variable = { temparr^temp < temparr^0 }
                    check_variable = { temparr^temp < temparr^1 }
                    check_variable = { temparr^temp < temparr^2 }
                    check_variable = { temparr^temp < temparr^3 }
                }
            }
        }
        add_to_array = { potential_max = temp }
    }
}</pre>
|Runs the effects as long as the limit is fulfilled.
|The limit is only checked at the beginning and once the effect block is executed. Can't run for more than 1000 times by default<ref name="loop"/>. Comparison types are the same as used in [[#check_variable|check_variable]].
|}

=== Scorers ===
Scorers are defined within {{path|common/scorers/country/*.txt}} files, serving as a sorted list of targeted countries, based on how well they did in the specified [[AI modding#MTTH block|MTTH block]]. The scorer has the primary country which the scorer is used for and targeted countries.<br/>
Each scorer is a separate block within the file, with the name of the block being the name of the scorer. The scorer then has the <code>targets = { ... }</code> block that encompasses everything else about the scorer.<br/>
Scorers target countries similarly to [[Decision modding#Targeted decisions|targeted decisions]] but with differences, with the following arguments being used within of <code>targets = { ... }</code>:
* <code>targets = { TAG, TAG }</code> - A list of country tags, including other [[Scopes#Dual scopes|dual scopes]] such as [[Scopes#overlord|overlord]], that can be targeted by this scorer. Unlike targeted decisions, this seems to be comma-separated.
* <code>target_array = global.majors</code> - The array to target. The default scope is the primary country.
* <code>target_root_trigger = { ... }</code> - The trigger block which the primary country must fulfill for the target to work.
* <code>target_trigger = { ... }</code> - The trigger block that target country must fulfill for the target to work.
* <code>targets_dynamic = yes</code> - If set, makes the dynamic countries possible targets. Defaults to no.
* <code>target_non_existing = yes</code> - If set, makes non-existing countries possible targets. Defaults to no.
* <code>score = { ... }</code> - This is the MTTH block itself that ranks the countries in the list. By default, THIS (the default scope) is the target, FROM is the primary country initialising the check.
For example, the following is a scorer that sorts every major country depending on the amount of states they own:
<pre>majors_owned_states = {
    targets = {
        target_array = global.majors    # Global is not the default scope, scope into it.
        targets_dynamic = yes
        target_non_existing = yes       # As implausible as this is, this is likely technically possible by using the set_major effect.
        score = {
            factor = num_owned_states
        }
    }
}</pre>
After defining a scorer, there is the way to use it: an argument, similar to arrays and variables. Similarly to them, regular and temporary versions exist, which decides whether the variable/array it's writing to is regular or temporary. Both can only be used inside of country scope. Regular versions can only be used in effects, and temporary versions can be used in effects and triggers.
{| class="wikitable sortable mw-collapsible" style="display: inline-block; padding: 5px" width="100%"
|+ {{nowrap|Scorer-related arguments:}}
! width="10%" |Name
! width="25%" |Parameters
! width="25%" |Examples
! width="20%" |Description
! width="20%" |Notes
|-id="get_highest_scored_country"
|get_highest_scored_country
|<code>scorer = <scorer></code><br/>The scorer to use.<br/>
<code>var = <variable></code><br/>The variable where the result will be stored.
|<pre>get_highest_scored_country = {
    var = majors_owned_states
    value = largest_major
}</pre>
<pre>get_highest_scored_country_temp = {
    var = majors_owned_states
    value = largest_major
}</pre>
|Sets the specified variable to be the highest-scoring country within the scorer, as checked for the country where this is used.
|
|-id="get_sorted_scored_countries"
|get_sorted_scored_countries
|<code>scorer = <scorer></code><br/>The scorer to use.<br/>
<code>array = <variable></code><br/>The array where the countries will be stored.<br/>
<code>scores = <variable></code><br/>The array where the scores will be stored.
|<pre>get_sorted_scored_countries = {
    scorer = majors_owned_states
    array = major_owners
    values = major_states
}</pre>
<pre>get_sorted_scored_countries_temp = {
    scorer = majors_owned_states
    array = major_owners
    values = major_states
}</pre>
|Creates two arrays of countries and their corresponding values, sorted in the ascending order.
|Values with the same index are connected: in the example, major_owners^0 is the country that got major_states^0 points in the majors_owned_states scorer.
|}
==== Example ====
Scorers can be helpful to create a sorted list of scopes by a certain element, such as political power. For example, the following can be used to find the countries with the most infantry equipment and send an event to the top three that are at peace with ROOT:

Within the scorer file:
<pre>infantry_equipment_sort = {
    target_array = global.countries
    targets_dynamic = yes
    score = {
        factor = num_equipment@infantry_equipment
    }
}</pre>
Within an effect block:
<pre>ROOT = {
    get_sorted_scored_countries_temp = {
        scorer = infantry_equipment_sort
        array = temp_inf_eq_countries
    }
    for_each_scope_loop = {
        array = temp_inf_eq_countries
        break = break
        if = {
            limit = {
                NOT = { 
                    tag = ROOT
                    has_war_with = ROOT
                }
            }
            add_to_temp_variable = { v = 1 }
            country_event = equipment_please.0
        }
        if = {
            limit = {
                check_variable = { v = 3 }
            }
            set_temp_variable = { break = 1 }
        }
    }
}</pre>

== 游戏变量（Game variables） ==
{{SVersion|1.12}}
游戏变量是只读变量，用于读取游戏的某些方面，例如玩家当前拥有的政治权力。These cannot be modified using any variable-modifying argument, but they can serve as the value within them (such as <code>add_to_temp_variable = { temp = GER.army_experience }</code> adding the amount of army experience that GER has to the <code>temp</code> temporary variable. Some are targeted, requiring one more argument in the target's place. For example, <code>modifier</code> has a modifier token as the target, so it would be used as <code>set_temp_variable = { temp = modifier@consumer_goods_factor }</code>, where <code>consumer_goods_factor</code> is the name of the modifier used as the argument.

Remember that to get global-scoped game variables, it is necessary to scope into global as <code>global.year</code> rather than leaving out the scope. A list of game variables can be found within {{path|documentation/dynamic_variables_documentation}}, alongside that a large portion of purely numeric [[Triggers]] have corresponding game variables. The following game variables exist in the game (Some duplicates are omitted):
{| class="wikitable sortable mw-collapsible" style="display: inline-block; padding: 5px" width="100%"
|+ {{nowrap|Global-scoped game variables:}}
|-
! width="5%" | Variable
! width="5%" | Target
! width="90%" | Description/Notes
|-id="year"
|year
|None.
|当前年份, 例如 1936.
|-id="date"
|date
|None.
|当前日期的ID。这可以通过多种不同的方式进行本地化, 使用以<code>GetDateString</code>开始的本地化函数. This variable functions by having one game hour be 0.001, with 0 of the variable corresponding to the date 1st January -5000, 1:00.
|-id="num_days"
|num_days
|None.
|自开始日期以来经过的天数. 开始日期被认为是 NDefines.NGame.START_DATE 设置.
|-id="difficulty"
|difficulty
|None.
|当前难度值从0(平民)到4(精英)。
|-id="threat"
|threat
|None.
|从0到1范围内的当前世界紧张度。
|}
{| class="wikitable sortable mw-collapsible" style="display: inline-block; padding: 5px" width="100%"
|+ {{nowrap|Country-scoped general game variables:}}
! width="10%" | Variable
! width="20%" | Target
! width="70%" | Description/Notes
|-id="modifier"
|modifier
|Modifier's name, such as <code>@political_power_gain</code>.
|The total value of the current [[modifier]] as the country has in total. Targeted modifiers have separate definitions.
|-id="id"
|id
|None.
|国家的内部ID。相当于不指定任何内容，类似<code>set_temp_variable = { temp = TAG }</code>.
|-id="max_manpower"
|max_manpower
|None.
|全国总人口。已弃用, 建议改用 [[#max_manpower_k|max_manpower_k]] 以免溢出。
|-id="max_manpower_k"
|max_manpower_k
|None.
|全国总人口，以千计。
|-id="party_popularity"
|party_popularity
|Ideology group or <code>ruling_party</code>, such as <code>@ruling_party</code>.
|指定政党的支持度，范围从0到1
|-id="party_popularity_100"
|party_popularity_100
|Ideology group or <code>ruling_party</code>, such as <code>@neutrality</code>.
|指定政党的支持度，范围从0到100
|-id="highest_party_ideology"
|highest_party_ideology
|<code>exclude_ruling_party</code> or nothing.
|在国内拥有最高政党支持度的意识形态团体，可以选择排除执政党
|-id="highest_party_popularity"
|highest_party_popularity
|<code>exclude_ruling_party</code> or nothing.
|在国内拥有最高政党支持度的意识形态团体，可以选择排除执政党. 范围从0到1
|-id="current_party_ideology_group"
|current_party_ideology_group
|None.
|这个国家目前的意识形态。
|-id="original_tag"
|original_tag
|None.
|当前国家原本的标签。与非动态国家的常规标签相同。
|-id="opinion"
|opinion
|Country.
|The opinion of the current country towards the specified one.
|-id="days_decision_timeout"
|days_decision_timeout
|Decision, such as <code>@my_decision</code>.
|The remaining amount of days for a completed decision before it gets removed.
|-id="days_mission_timeout"
|days_mission_timeout
|Mission.
|The remaining amount of days for an ongoing mission before it times out.
|-id="political_power"
|political_power
|None.
|Total current political power of the country. <code>has_political_power</code> can be used in the same way.
|-id="political_power_daily"
|political_power_daily
|None.
|Current amount of daily gain of political power, equivalent to <code>political_power_growth</code>.
|-id="stability"
|stability
|None.
|Current stability of the country on the scale from 0 to 1.
|-id="has_war_support"
|has_war_support
|None.
|Current war support of the country on the scale from 0 to 1.
|-id="power_balance_value"
|power_balance_value
|None.
|The current power balance value.
|-id="power_balance_daily"
|power_balance_daily
|None.
|The current daily change in power balance.
|-id="power_balance_weekly"
|power_balance_weekly
|None.
|The current weekly change in power balance.
|-id="capital"
|capital
|None.
|The capital state of the country.
|-id="autonomy_ratio"
|autonomy_ratio
|None.
|How close the country is to taking the next autonomy level. 0 if can be downgraded, 1 if can be upgraded, -1 if independent.
|-id="overlord"
|overlord
|None.
|The country that the current country is a subject of.
|-id="num_subjects"
|num_subjects
|None.
|The number of subjects that the country has as an overlord.
|-id="core_compliance"
|core_compliance
|Country.
|Average compliance within cores of the target country occupied by the current country.
|-id="core_resistance"
|core_resistance
|Country.
|Average resistance within cores of the target country occupied by the current country.
|-id="has_collaboration"
|has_collaboration
|Country.
|The collaboration of the target country with the current country within target's cores currently occupied by the current country.
|-id="faction_leader"
|faction_leader
|None.
|The leader of the faction the current country is in. Returns nothing if not in a faction.
|-id="num_faction_members"
|num_faction_members
|None.
|The number of members in the faction with the current country.
|-id="fuel_k"
|fuel_k
|None.
|Current fuel of country in thousands.
|-id="max_fuel_k"
|max_fuel_k
|None.
|Maximum fuel of country in thousands.
|-id="fuel_ratio"
|fuel_ratio
|None.
|Ratio of the current fuel compared to the maximum amount, from 0 to 1.
|-id="host"
|host
|None.
|The host of the current country. Returns nothing if not exiled.
|-id="legitimacy"
|legitimacy
|None.
|The legitimacy of the currently-exiled country. Returns -1 if not exiled.
|-id="num_controlled_states"
|num_controlled_states
|None.
|The amount of states that are controlled but not necessarily owned by the current country.
|-id="num_core_states"
|num_core_states
|None.
|The amount of states that are national territory of the current country.
|-id="num_owned_controlled_states"
|num_owned_controlled_states
|None.
|The amount of states that are owned and controlled by the current country.
|-id="num_owned_states"
|num_owned_states
|None.
|The amount of states that are owned but not necessarily controlled by the current country.
|-id="num_occupied_states"
|num_occupied_states
|None.
|The number of states occupied by the country.
|-id="resource"
|resource
|Resource, such as <code>@steel</code>.
|The amount of surplus resource of the specified type, which isn't exported or used in production.
|-id="resource_consumed"
|resource_consumed
|Resource, such as <code>@aluminium</code>.
|The amount of resource of the specified type currently used for equipment production.
|-id="resource_exported"
|resource_exported
|Resource, such as <code>@oil</code>.
|The amount of resource of the specified type currently set to be exported with the [[Modifiers#min_export|min_export modifier]].
|-id="resource_imported"
|resource_imported
|Resource, such as <code>@tungsten</code>.
|The amount of resource of the specified type currently set to be imported from trade with other countries.
|-id="resource_produced"
|resource_produced
|Resource, such as <code>@rubber</code>.
|The amount of resource of the specified type produced from the country's controlled states, buildings on them, and resource rights.
|-id="alliance_strength_ratio"
|alliance_strength_ratio
|Country.
|The ratio of land strength between the current country's faction and the target's faction.
|-id="alliance_naval_strength_ratio"
|alliance_naval_strength_ratio
|Country.
|The ratio of naval strength between the current country's faction and the target's faction.
|-id="enemies_naval_strength_ratio"
|enemies_naval_strength_ratio
|None.
|The estimated navy strength between the current country and all its enemies.
|-id="enemies_strength_ratio"
|enemies_strength_ratio
|None.
|The estimated army strength between the current country and all its enemies.
|-id="amount_research_slots"
|amount_research_slots
|None.
|The current amount of research slots the country has.
|-id="original_research_slots"
|original_research_slots
|None.
|The amount of research slots that the country had in the beginning of the game, as set in the [[Country creation#Effects|history file]].
|-id="any_war_score"
|any_war_score
|None.
|The highest war score that the country has among wars it's in, on the scale from 0 to 100.
|-id="casualties"
|casualties
|None.
|The amount of casualties a country has suffered in all of its wars.
|-id="casualties_k"
|casualties_k
|None.
|The amount of casualties a country has suffered in all of its wars in thousands.
|-id="days_since_capitulated"
|days_since_capitulated
|None.
|The amount of days since the country has capitulated. Not intended to be used if the country has never capitulated, returning an 'extremely large' value<ref>{{path|documentation/triggers_documentation}}</ref>.
|-id="convoy_threat"
|convoy_threat
|None.
|Returns, in the range from 0 to 1, the current danger that enemy convoys pose to the current country. Uses NDefines.NNavy.NAVAL_CONVOY_DANGER_RATIOS as the baseline.
|-id="mine_threat"
|mine_threat
|None.
|Returns, in the range from 0 to 1, the current danger that enemy mines pose to the current country. Uses NDefines.NNavy.NAVAL_MINE_DANGER_RATIOS as the baseline.
|-id="foreign_manpower"
|foreign_manpower
|None.
|The amount of foreign garrison manpower that the country has.
|-id="garrison_manpower_need"
|garrison_manpower_need
|None.
|The amount of manpower needed by garrisons.
|-id="has_added_tension_amount"
|has_added_tension_amount
|None.
|The amount of world tension currently added by the country.
|-id="manpower_per_military_factory"
|manpower_per_military_factory
|None.
|The amount of manpower that the country has for each military factory.
|-id="num_of_available_civilian_factories"
|num_of_available_civilian_factories
|None.
|Amount of available civilian factories.
|-id="num_of_available_military_factories"
|num_of_available_military_factories
|None.
|Amount of available military factories.
|-id="num_of_available_naval_factories"
|num_of_available_naval_factories
|None.
|Amount of available naval factories.
|-id="num_of_civilian_factories"
|num_of_civilian_factories
|None.
|Amount of civilian factories.
|-id="num_of_civilian_factories_available_for_projects"
|num_of_civilian_factories_available_for_projects
|None.
|Amount of civilian factories available for a new project to use.
|-id="total_constructed_civilian_factory"
|total_constructed_civilian_factory
|None.
|Amount of civilian factories that have been constructed after the game's start by the country.
|-id="num_of_factories"
|num_of_factories
|None.
|Amount of total factories.
|-id="num_of_military_factories"
|num_of_military_factories
|None.
|Amount of military factories.
|-id="num_of_naval_factories"
|num_of_naval_factories
|None.
|Amount of naval factories.
|-id="num_of_controlled_factories"
|num_of_controlled_factories
|None.
|Amount of factories within controlled states.
|-id="num_of_owned_factories"
|num_of_owned_factories
|None.
|Amount of factories within owned states.
|-id="num_of_nukes"
|num_of_nukes
|None.
|Amount of nukes.
|-id="num_researched_technologies"
|num_researched_technologies
|Number of technologies a tag has researched.
|-id="num_tech_sharing_groups"
|num_tech_sharing_groups
|None.
|How many tech sharing groups a nation is a member of.
|-id="surrender_progress"
|surrender_progress
|None.
|How close the country is to surrendering on the scale from 0 to 1.
|}
{| class="wikitable sortable mw-collapsible" style="display: inline-block; padding: 5px" width="100%"
|+ {{nowrap|Country-scoped intelligence-related game variables:}}
! width="10%" | Variable
! width="20%" | Target
! width="70%" | Description/Notes
|-id="army_intel"
|army_intel
|Country.
|Army intel against the target country.
|-id="navy_intel"
|navy_intel
|Country.
|Navy intel against the target country.
|-id="air_intel"
|air_intel
|Country.
|Air intel against the target country.
|-id="civilian_intel"
|civilian_intel
|Country.
|Civilian intel against the target country.
|-id="encryption_strength"
|encryption_strength
|None.
|Total encryption strength of the country. Only without the {{icon|lar|1}} DLC.
|-id="decryption_speed"
|decryption_speed
|None.
|Total decryption speed of the country. Only without the {{icon|lar|1}} DLC.
|-id="cryptology_defense_level"
|cryptology_defense_level
|None.
|cryptology defense level of the country.
|-id="agency_upgrade_number"
|agency_upgrade_number
|None.
|The number of upgrade done in the intelligence agency.
|-id="decryption_progress"
|decryption_progress
|Country.
|Decryption progress against the target country.
|-id="network_national_coverage"
|network_national_coverage
|Country.
|Network national coverage the current country has over the target country.
|-id="num_fake_intel_divisions"
|num_fake_intel_divisions
|None.
|The amount of fake intel division that the country has.
|-id="num_free_operative_slots"
|num_free_operative_slots
|None.
|The amount of operative slots that are currently empty and an operative can be recruited in.
|-id="num_of_operatives"
|num_of_operatives
|None.
|The number of operatives the country controls.
|-id="num_operative_slots"
|num_operative_slots
|None.
|The number of available operative slots a country has. If this differs from the number of operative, this does not mean the country can recruit an operative, but that it will eventually be able to.
|}
{| class="wikitable sortable mw-collapsible" style="display: inline-block; padding: 5px" width="100%"
|+ {{nowrap|Country-scoped military-related game variables:}}
! width="10%" | Variable
! width="20%" | Target
! width="70%" | Description/Notes
|-id="manpower"
|manpower
|None.
|Manpower that the country has, both in the army and reserved. Deprecated, recommended to use [[#manpower_k|manpower_k]] instead as to avoid overflows.
|-id="manpower_k"
|manpower_k
|None.
|Manpower that the country has, both in the army and reserved, in thousands.
|-id="max_available_manpower"
|max_available_manpower
|None.
|Manpower that the country has, both in the army and reserved, taking into account those that are in the process of being drafted as the result of a recent conscription amount change. Deprecated, recommended to use [[#max_available_manpower_k|max_available_manpower_k]] instead as to avoid overflows.
|-id="max_available_manpower_k"
|max_available_manpower_k
|None.
|Manpower that the country has, both in the army and reserved, taking into account those that are in the process of being drafted as the result of a recent conscription amount change, in thousands.
|-id="target_conscription_amount"
|target_conscription_amount
|None.
|The target conscription amount of the country.
|-id="amount_manpower_in_deployment_queue"
|amount_manpower_in_deployment_queue
|None.
|Amount of manpower currently in the deployment view.
|-id="conscription_ratio"
|conscription_ratio
|None.
|Conscription ratio of the country compared to target conscription ratio.
|-id="current_conscription_amount"
|current_conscription_amount
|None.
|The current conscription amount of the country.
|-id="command_power"
|command_power
|None.
|The current command power of country.
|-id="command_power_daily"
|command_power_daily
|None.
|The current daily gain of command power by country.
|-id="army_experience"
|army_experience
|None.
|Army experience that the country has.
|-id="navy_experience"
|navy_experience
|None.
|Naval experience that the country has.
|-id="air_experience"
|air_experience
|None.
|Air experience that the country has.
|-id="num_armies"
|num_armies
|None.
|Amount of land divisions.
|-id="num_armies_in_state"
|num_armies_in_state
|State such as <code>@123</code>.
|Amount of land divisions within the target state.
|-id="num_armies_with_type"
|num_armies_with_type
|Subunit type such as <code>@light_armor</code>.
|Amount of land divisions that are majority of the same subunit type.
|-id="num_battalions"
|num_battalions
|None.
|Amount of battalions within land divisions the country has.
|-id="num_battalions_with_type"
|num_battalions_with_type
|Subunit type such as <code>@cavalry</code>.
|Amount of battalions within land divisions the country has that have the specified subunit type.
|-id="num_deployed_planes"
|num_deployed_planes
|None.
|Amount of deployed planes.
|-id="num_deployed_planes_with_type"
|num_deployed_planes_with_type
|Subunit type such as <code>@fighter</code>.
|Amount of deployed planes with equipment type.
|-id="num_divisions"
|num_divisions
|None.
|Amount of land and naval divisions.
|-id="num_equipment"
|num_equipment
|Equipment type or archetype such as <code>@infantry_equipment</code>.
|Amount of equipment within the country's stockpile.
|-id="num_equipment_in_armies"
|num_equipment_in_armies
|Equipment type or archetype such as <code>@artillery_equipment</code>.
|Amount of equipment in country that are used in armies. If there's a large amount of equipment possible, use [[#num_equipment_in_armies_k|num_equipment_in_armies_k]].
|-id="num_equipment_in_armies_k"
|num_equipment_in_armies_k
|Equipment type or archetype such as <code>@support_equipment</code>.
|Amount of equipment in country that are used in armies, in thousands.
|-id="num_target_equipment_in_armies"
|num_target_equipment_in_armies
|Equipment type or archetype such as <code>@motorized_equipment_1</code>.
|Amount of equipment in country that are wanted in armies. If there's a large amount of equipment possible, use [[#num_target_equipment_in_armies_k|num_target_equipment_in_armies_k]].
|-id="num_target_equipment_in_armies_k"
|num_target_equipment_in_armies_k
|Equipment type or archetype such as <code>@anti_air_equipment_1</code>.
|Amount of equipment in country that are wanted in armies, in thousands.
|-id="num_ships"
|num_ships
|None.
|Amount of ships.
|-id="num_ships_with_type"
|num_ships_with_type
|Subunit type such as <code>@carrier</code>.
|Amount of ships with the specified subunit type.
|-id="land_doctrine_level"
|land_doctrine_level
|None.
|The currently-researched land doctrine level.
|}
A large portion of the AI-related game variables can have values seen in-game by using the <code>aiview</code> console command.
{| class="wikitable sortable mw-collapsible" style="display: inline-block; padding: 5px" width="100%"
|+ {{nowrap|Country-scoped AI-related game variables:}}
! width="10%" | Variable
! width="10%" | Target
! width="80%" | Description/Notes
|-id="ai_attitude_allied_weight"
|ai_attitude_allied_weight
|Country.
|The total amount of the <code>attitude_allied</code> AI attribute.
|-id="ai_attitude_friendly_weight"
|ai_attitude_friendly_weight
|Country.
|The total amount of the <code>attitude_friendly</code> AI attribute.
|-id="ai_attitude_hostile_weight"
|ai_attitude_hostile_weight
|Country.
|The total amount of the <code>attitude_hostile</code> AI attribute.
|-id="ai_attitude_is_threatened"
|ai_attitude_is_threatened
|None.
|Returns 1 if the AI is threatened, 0 otherwise.
|-id="ai_attitude_neutral_weight"
|ai_attitude_neutral_weight
|Country.
|The total amount of the <code>attitude_neutral</code> AI attribute.
|-id="ai_attitude_outraged_weight"
|ai_attitude_outraged_weight
|Country.
|The total amount of the <code>attitude_outraged</code> AI attribute.
|-id="ai_attitude_protective_weight"
|ai_attitude_protective_weight
|Country.
|The total amount of the <code>attitude_protective</code> AI attribute.
|-id="ai_attitude_threatened_weight"
|ai_attitude_threatened_weight
|Country.
|The total amount of the <code>attitude_threatened</code> AI attribute.
|-id="ai_attitude_wants_ally"
|ai_attitude_wants_ally
|None.
|Returns 1 if the AI wants to ally any country, 0 otherwise.
|-id="ai_attitude_wants_antagonize"
|ai_attitude_wants_antagonize
|None.
|Returns 1 if the AI wants to antagonize any country, 0 otherwise.
|-id="ai_attitude_wants_ignore"
|ai_attitude_wants_ignore
|None.
|Returns 1 if the AI wants to ignore any country, 0 otherwise.
|-id="ai_attitude_wants_protect"
|ai_attitude_wants_protect
|None.
|Returns 1 if the AI wants to protect any country, 0 otherwise.
|-id="ai_attitude_wants_weaken"
|ai_attitude_wants_weaken
|None.
|Returns 1 if the AI wants to weaken any country, 0 otherwise.
|-id="ai_strategy_activate_crypto"
|ai_strategy_activate_crypto
|Country.
|Total sum of the [[AI modding#AI strategies|AI strategy]] values of the type <code>activate_crypto</code> towards the target country.
|-id="ai_strategy_alliance"
|ai_strategy_alliance
|Country.
|Total sum of the [[AI modding#AI strategies|AI strategy]] values of the type <code>alliance</code> towards the target country.
|-id="ai_strategy_antagonize"
|ai_strategy_antagonize
|Country.
|Total sum of the [[AI modding#AI strategies|AI strategy]] values of the type <code>antagonize</code> towards the target country.
|-id="ai_strategy_befriend"
|ai_strategy_befriend
|Country.
|Total sum of the [[AI modding#AI strategies|AI strategy]] values of the type <code>befriend</code> towards the target country.
|-id="ai_strategy_conquer"
|ai_strategy_conquer
|Country.
|Total sum of the [[AI modding#AI strategies|AI strategy]] values of the type <code>conquer</code> towards the target country.
|-id="ai_strategy_consider_weak"
|ai_strategy_consider_weak
|Country.
|Total sum of the [[AI modding#AI strategies|AI strategy]] values of the type <code>consider_weak</code> towards the target country.
|-id="ai_strategy_contain"
|ai_strategy_contain
|Country.
|Total sum of the [[AI modding#AI strategies|AI strategy]] values of the type <code>contain</code> towards the target country.
|-id="ai_strategy_declare_war"
|ai_strategy_declare_war
|Country.
|Total sum of the [[AI modding#AI strategies|AI strategy]] values of the type <code>declare_war</code> towards the target country.
|-id="ai_strategy_decrypt_target"
|ai_strategy_decrypt_target
|Country.
|Total sum of the [[AI modding#AI strategies|AI strategy]] values of the type <code>decrypt_target</code> towards the target country.
|-id="ai_strategy_dont_defend_ally_borders"
|ai_strategy_dont_defend_ally_borders
|Country.
|Total sum of the [[AI modding#AI strategies|AI strategy]] values of the type <code>dont_defend_ally_borders</code> towards the target country.
|-id="ai_strategy_force_defend_ally_borders"
|ai_strategy_force_defend_ally_borders
|Country.
|Total sum of the [[AI modding#AI strategies|AI strategy]] values of the type <code>force_defend_ally_borders</code> towards the target country.
|-id="ai_strategy_ignore"
|ai_strategy_ignore
|Country.
|Total sum of the [[AI modding#AI strategies|AI strategy]] values of the type <code>ignore</code> towards the target country.
|-id="ai_strategy_ignore_claim"
|ai_strategy_ignore_claim
|Country.
|Total sum of the [[AI modding#AI strategies|AI strategy]] values of the type <code>ignore_claim</code> towards the target country.
|-id="ai_strategy_influence"
|ai_strategy_influence
|Country.
|Total sum of the [[AI modding#AI strategies|AI strategy]] values of the type <code>influence</code> towards the target country.
|-id="ai_strategy_invade"
|ai_strategy_invade
|Country.
|Total sum of the [[AI modding#AI strategies|AI strategy]] values of the type <code>invade</code> towards the target country.
|-id="ai_strategy_occupation_policy"
|ai_strategy_occupation_policy
|Country.
|Total sum of the [[AI modding#AI strategies|AI strategy]] values of the type <code>occupation_policy</code> towards the target country.
|-id="ai_strategy_prepare_for_war"
|ai_strategy_prepare_for_war
|Country.
|Total sum of the [[AI modding#AI strategies|AI strategy]] values of the type <code>prepare_for_war</code> towards the target country.
|-id="ai_strategy_protect"
|ai_strategy_protect
|Country.
|Total sum of the [[AI modding#AI strategies|AI strategy]] values of the type <code>protect</code> towards the target country.
|-id="ai_strategy_send_volunteers_desire"
|ai_strategy_send_volunteers_desire
|Country.
|Total sum of the [[AI modding#AI strategies|AI strategy]] values of the type <code>send_volunteers_desire</code> towards the target country.
|-id="ai_strategy_support"
|ai_strategy_support
|Country.
|Total sum of the [[AI modding#AI strategies|AI strategy]] values of the type <code>support</code> towards the target country.
|-id="ai_irrationality"
|ai_irrationality
|None.
|The AI's irrationality value.
|-id="ai_wants_divisions"
|ai_wants_divisions
|None.
|The total amount of divisions that the AI aims for.
|}
{| class="wikitable sortable mw-collapsible" style="display: inline-block; padding: 5px" width="100%"
|+ {{nowrap|State-scoped game variables:}}
! width="10%" | Variable
! width="10%" | Target
! width="80%" | Description/Notes
|-id="state_id"
|id
|None.
|The internal ID of the state. While regular <code>set_variable = { my_state_pointer = 123 }</code> would still work as a pointer to the state, this can remove ambiguity within the code whether the number is used as a state ID or the number that matches up with the state ID.
|-id="building_level"
|building_level
|Building such as <code>@nuclear_reactor</code>.
|The level of a building with the target type.
|-id="arms_factory_level"
|arms_factory_level
|None.
|Military factory level in the state
|-id="industrial_complex_level"
|industrial_complex_level
|None.
|civilian factory level in the state
|-id="infrastructure_level"
|infrastructure_level
|None.
|infrastructure level in the state
|-id="damaged_building_level"
|damaged_building_level
|Building such as <code>@industrial_complex</code>.
|Damaged building level of a building with target type.
|-id="non_damaged_building_level"
|non_damaged_building_level
|Building such as <code>@arms_factory</code>.
|Non-damaged building level of a building with target type.
|-id="modifier"
|modifier
|Modifier's name, such as <code>@political_power_gain</code>.
|The total value of the current [[modifier]] as the country has in total. Targeted modifiers have separate definitions.
|-id="controller"
|controller
|None.
|Controller of the state.
|-id="owner"
|owner
|None.
|Owner of the state.
|-id="distance_to"
|distance_to
|State.
|Distance between the current state and the target state.
|-id="resource"
|resource
|Resource type such as <code>@chromium</code>
|Amount of the resource produced within state.
|-id="compliance"
|compliance
|None.
|Current compliance level of the state.
|-id="compliance_speed"
|compliance_speed
|None.
|Current compliance speed of the state.
|-id="days_since_last_strategic_bombing"
|days_since_last_strategic_bombing
|None.
|Amount of days since the state was last strategic bombed.
|-id="resistance"
|resistance
|None.
|Current resistance level of the state.
|-id="resistance_speed"
|resistance_speed
|None.
|Current resistance speed of the state.
|-id="resistance_target"
|resistance_target
|None.
|Current resistance target of the state.
|-id="state_population"
|state_population
|None.
|Current population of the state. Recommended to use [[#state_population_k|state_population_k]] when possible to avoid overflows.
|-id="state_population_k"
|state_population_k
|None.
|Current population of the state in thousands.
|-id="state_and_terrain_strategic_value"
|state_and_terrain_strategic_value
|None.
|Current state and terrain strategic value, decided by buildings and terrain of provinces.
|-id="state_strategic_value"
|state_strategic_value
|None.
|Current state strategic value, decided by buildings.
|}
{| class="wikitable sortable mw-collapsible" style="display: inline-block; padding: 5px" width="100%"
|+ {{nowrap|Unit leader-scoped game variables:}}
! width="10%" | Variable
! width="10%" | Target
! width="80%" | Description/Notes
|-id="leader_modifier"
|leader_modifier
|Modifier's name, such as <code>@navy_max_range</code>.
|The total value of the specified [[modifier]] as the unit leader has in total, applied towards the leader. This is represented with <code>non_shared_modifier = { ... }</code> in [[Character modding#Unit leader traits|unit leader traits]].
|-id="unit_modifier"
|unit_modifier
|Modifier type, such as <code>@army_attack_factor</code>
|The total value of the specified [[modifier]] as the unit leader has in total, applied towards the units. This is represented with <code>modifier = { ... }</code> in [[Character modding#Unit leader traits|unit leader traits]].
|-id="sum_unit_terrain_modifier"
|sum_unit_terrain_modifier
|Modifier type, such as <code>@sickness_chance</code>
|The total sum of the modifier value applied by each province that this unit leader has divisions on.
|-id="army_attack_level"
|army_attack_level
|None.
|The attack level of the leader.
|-id="army_defense_level"
|army_defense_level
|None.
|The defense level of the leader.
|-id="attack_level"
|attack_level
|None.
|The attack level of the leader.
|-id="coordination_level"
|coordination_level
|None.
|The coordination level of the leader.
|-id="defense_level"
|defense_level
|None.
|The defense level of the leader.
|-id="logistics_level"
|logistics_level
|None.
|The logistics level of the leader.
|-id="maneuvering_level"
|maneuvering_level
|None.
|The maneuvering level of the leader.
|-id="planning_level"
|planning_level
|None.
|The maneuvering level of the leader.
|-id="skill_level"
|skill_level
|None.
|The general skill level of the leader.
|-id="average_stats"
|average_stats
|None.
|The average stats of the unit leader.
|-id="avg_combat_status"
|avg_combat_status
|None.
|The average status of each engagement that units led by the leader are participating in.
|-id="avg_defensive_combat_status"
|avg_defensive_combat_status
|None.
|The average status of each defensive engagement that units led by the leader are participating in.
|-id="avg_offensive_combat_status"
|avg_offensive_combat_status
|None.
|The average status of each offensive engagement that units led by the leader are participating in.
|-id="avg_unit_planning_ratio"
|avg_unit_planning_ratio
|None.
|The average ratio of planning bonus that each unit has.
|-id="avg_units_acclimation"
|avg_units_acclimation
|Acclimatization type, such as <code>@hot_climate</code>
|Average unit acclimatization for the specified climate, which is defined in {{path|common/acclimatation.txt}}
|-id="has_orders_group"
|has_orders_group
|None.
|Returns 1 if the general has any order groups assigned to them, 0 otherwise.
|-id="num_traits"
|num_traits
|None.
|Amount of traits that the unit leader has.
|-id="num_assigned_traits"
|num_assigned_traits
|None.
|Amount of assigned traits the leader has.
|-id="num_basic_traits"
|num_basic_traits
|None.
|Amount of basic traits that the unit leader has.
|-id="num_personality_traits"
|num_personality_traits
|None.
|Amount of personality traits that the unit leader has.
|-id="num_status_traits"
|num_status_traits
|None.
|Amount of status traits that the unit leader has.
|-id="num_max_traits"
|num_max_traits
|None.
|Amount of maximum assignable traits the leader can have.
|-id="num_terrain_traits"
|num_terrain_traits
|None.
|Amount of terrain traits that the unit leader has.
|-id="num_battalions"
|num_battalions
|None.
|Amount of battalions that the army leader has within units under their control.
|-id="num_battalions_with_type"
|num_battalions_with_type
|Subunit type such as <code>@artillery_brigade</code>
|Amount of battalions with sub unit type, sub unit type is defined in target, example: num_battalions_with_type@light_armor
|-id="num_battle_plans"
|num_battle_plans
|None.
|Amount of battle plans that the unit leader is assigned to.
|-id="num_orders_groups"
|num_orders_groups
|None.
|Number of order groups assigned to the unit leader.
|-id="num_equipment"
|num_equipment
|Equipment type or archetype such as <code>@light_tank_chassis</code>.
|Amount of equipment fulfilled within units led by the unit leader.
|-id="num_target_equipment"
|num_target_equipment
|Equipment type or archetype such as <code>@anti_tank_equipment</code>
|Amount of equipment required within units led by the unit leader.
|-id="num_units_with_type"
|num_units_with_type
|Subunit type such as <code>@modern_armor</code>
|The amount of units controlled by the unit leader that are predominantly filled with subunits that are assigned the specified type.
|-id="num_armored"
|num_armored
|None.
|The amount of units controlled by the unit leader that are predominantly filled with subunits that are assigned the <code>armored</code> type.
|-id="num_artillery"
|num_artillery
|None.
|The amount of units controlled by the unit leader that are predominantly filled with subunits that are assigned the <code>artillery</code> type.
|-id="num_cavalry"
|num_cavalry
|None.
|The amount of units controlled by the unit leader that are predominantly filled with subunits that are assigned the <code>cavalry</code> type.
|-id="num_infantry"
|num_infantry
|None.
|The amount of units controlled by the unit leader that are predominantly filled with subunits that are assigned the <code>infantry</code> type.
|-id="num_mechanized"
|num_mechanized
|None.
|The amount of units controlled by the unit leader that are predominantly filled with subunits that are assigned the <code>mechanized</code> type.
|-id="num_motorized"
|num_motorized
|None.
|The amount of units controlled by the unit leader that are predominantly filled with subunits that are assigned the <code>motorized</code> type.
|-id="num_rocket"
|num_rocket
|None.
|The amount of units controlled by the unit leader that are predominantly filled with subunits that are assigned the <code>rocket</code> type.
|-id="num_special"
|num_special
|None.
|The amount of units controlled by the unit leader that are predominantly filled with subunits that are assigned the <code>special</code> type.
|-id="num_ships"
|num_ships
|None.
|Amount of ships controlled by the unit leader
|-id="num_ships_with_type"
|num_ships_with_type
|Subunit type such as <code>@destroyer</code>.
|Amount of ships controlled by the unit leader, ship type is defined in target, example: num_ships_with_type@carrier
|-id="num_units"
|num_units
|None.
|Amount of units controlled by the unit leader.
|-id="num_units_crossing_river"
|num_units_crossing_river
|None.
|Amount of units currently passing through a river.
|-id="num_units_in_combat"
|num_units_in_combat
|None.
|Amount of units currently fighting under control of this unit leader.
|-id="num_units_defensive_combats"
|num_units_defensive_combats
|None.
|Amount of units in defensive combat under control of this unit leader.
|-id="num_units_defensive_combats_on"
|num_units_defensive_combats_on
|Provincial terrain, such as <code>@marsh</code>
|Amount of units that are currently defensively fighting on the specified terrain under control of this unit leader.
|-id="num_units_offensive_combats"
|num_units_offensive_combats
|None.
|Amount of units in offensive combat under control of this unit leader.
|-id="num_units_offensive_combats_against"
|num_units_offensive_combats_against
|Provincial terrain type such as <code>@urban</code>
|Amount of units that are currently offensively fighting on the specified terrain under control of this unit leader.
|-id="num_units_in_state"
|num_units_in_state
|State.
|Amount of units controlled by the unit leader within the target state.
|-id="num_units_on_climate"
|num_units_on_climate
|Acclimatization type, such as <code>@cold_climate</code>
|Amount of units under control of the unit leader that are on provinces with a climate that requires the specified acclimatization type.
|-id="unit_ratio_ready_for_plan"
|unit_ratio_ready_for_plan
|None.
|The percentage of units, on the scale from 0 to 1, under control of this unit leader that have the full planning bonus.
|}
{| class="wikitable sortable mw-collapsible" style="display: inline-block; padding: 5px" width="100%"
|+ {{nowrap|Operative-scoped game variables:}}
! width="10%" | Variable
! width="10%" | Target
! width="80%" | Description/Notes
|-id="intel_yield_factor_on_capture"
|intel_yield_factor_on_capture
|None.
|The rate at which intel is extracted from this operative by an enemy country.
|-id="operation_country"
|operation_country
|None.
|The country that the operative is assigned to work in. 0 if not assigned to a country.
|-id="operation_state"
|operation_state
|None.
|The state that the operative is assigned to work in. 0 if not assigned to a country.
|-id="operation_type"
|operation_type
|None.
|The operation that the operative to work on.
|-id="operative_captor"
|operative_captor
|None.
|The country that the operative is captured by.
|-id="own_capture_chance_factor"
|own_capture_chance_factor
|None.
|The chance that the operative has to be captured.
|-id="own_forced_into_hiding_time_factor"
|own_forced_into_hiding_time_factor
|None.
|The chance that the operative has to be forced into hiding.
|-id="own_harmed_time_factor"
|own_harmed_time_factor
|None.
|The chance that the operative has to be harmed.
|}
=== Game arrays ===
{| class="wikitable sortable mw-collapsible" style="display: inline-block; padding: 5px" width="100%"
|+ {{nowrap|Global-scoped game arrays:}}
! width="10%" | Array
! width="90%" | Description/Notes
|-id="countries"
|countries
|Every single country, regardless if they exist or not, including the {{hover|By default as defined in common/country_tags/zz_dynamic_countries.txt|50 dynamic countries}} even if they do not have an original tag defined.
|-id="majors"
|majors
|Every country that is currently major.
|-id="states"
|states
|Every state that exists in the game.
|-id="ideology_groups"
|ideology_groups
|Every ideology group that exists in the game.
|-id="operations"
|operations
|Every operation that exists in the game.
|-id="province_controllers"
|province_controllers
|An array of controller countries for each province. In this case, the province ID serves as the index: the controller of province 1234 is province_controllers^1234.
|}
{| class="wikitable sortable mw-collapsible" style="display: inline-block; padding: 5px" width="100%"
|+ {{nowrap|Country-scoped game arrays:}}
! width="10%" | Array
! width="90%" | Description/Notes
|-id="allies"
|allies
|Countries that are considered an ally, including fellow faction members, subjects, and the overlord.
|-id="army_leaders"
|army_leaders
|Army leaders recruited by the country.
|-id="enemies"
|enemies
|Countries that the current country is at war with.
|-id="enemies_of_allies"
|enemies_of_allies
|Countries that are considered an ally of any country that is at war with the current country.
|-id="faction_members"
|faction_members
|Countries that are in the same faction as this one.
|-id="occupied_countries"
|occupied_countries
|Countries that are currently occupied by this one.
|-id="subjects"
|subjects
|Countries that are subject to this one.
|-id="owned_controlled_states"
|owned_controlled_states
|States that are owned and controlled by the current country.
|-id="owned_states"
|owned_states
|States that are owned, but not necessarily controlled, by the current country.
|-id="potential_and_current_enemies"
|potential_and_current_enemies
|Countries that are considered enemies and that 'may' become enemies (due to being an ally of an enemy or by having a wargoal)
|-id="controlled_states"
|controlled_states
|States that are controlled, but not necessarily owned, by the current country.
|-id="core_states"
|core_states
|States that are considered national territory of the current country.
|-id="neighbors"
|neighbors
|Countries that are considered neighbours to the current country, having at least one border within controlled provinces.
|-id="neighbors_owned"
|neighbors_owned
|Countries that are considered neighbours to the current country, having at least one owned state that borders any state that the current country owns.
|-id="researched_techs"
|researched_techs
|Technologies that were researched by the current country.
|-id="navy_leaders"
|navy_leaders
|Navy leaders recruited by the country.
|-id="operatives"
|operatives
|Operatives recruited by the country.
|-id="exiles"
|exiles
|The exiled governments that the current country is hosting.
|}
{| class="wikitable sortable mw-collapsible" style="display: inline-block; padding: 5px" width="100%"
|+ {{nowrap|State-scoped game arrays:}}
! width="10%" | Array
! width="90%" | Description/Notes
|-id="core_countries"
|core_countries
|Countries that consider this state to be national territory.
|}

== References ==
<references/>
[[Category:Modding]]
{{Modding navbox}}