数据结构

Within Hearts of Iron IV, there are several types of data structures, used to store data to be used for later. This can be used in-game as a way to check if some effect block was executed or not, as a counter of sorts, or something else.

Constants

Constants serve as a way to use the same value with a reference. The constants are marked with the @ symbol when defining or using them. An example definition is the following:

@CONSTANT_1 = 10
@CONSTANT_2 = "TAG_my_idea"

This can later be used in the file as, for example, cost = @CONSTANT_1. These definitions can be in any point of the file.

Constants are available in the vast majority of game files, including most, if not all, *.txt and *.gui files. Constants can be used as a way to link several values to be the same if they can easily be changed at any point in the development. However, constants that store a string for its value can only be used in triggers and the attributes of elements and windows, trying to use them in an effect will result in an "invalid database object for effect/trigger" error.
For example, if there is a large decision system where every decision is intended to have the same cost, then these constants may be used if the political power cost gets changed mid-development for better balance.
Another example would be a scripted GUI container: if a large multitude of elements are to be at the same X or Y position, it might be worth it to link them to be a constant in case their position could be changed for better appearance or to fit in another GUI element.

示例decision file that utilises constants:

@CONSTANT_1 = 10
@CONSTANT_2 = "TAG_my_idea"
TAG_decision_category = {
    TAG_decision = {
        icon = test_icon
        cost = @CONSTANT_1
        complete_effect = {
            if = {
                limit = {
                    has_ideas = @CONSTANT_2
                }
                add_stability = 0.1
            }
        }
    }
}

定义文件

主条目：定义文件

Defines are a particular type of constant that are used within internal calculations only, defined within /Hearts of Iron IV/common/defines/*.lua files. These cannot be referenced in any other files and are only used within the internal, unchangeable code.

Some of the things included in the defines are that events by default stay for 13 days before auto-selecting the first option^[1] or that the ai_will_do value is 50% higher for focuses which were unlocked by the just-completed focus^[2]. 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^[3] or the list of experience need for a division to progress to the next level^[4].
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.

由于 Defines 是 Lua 代码，而不是由 PDXscript 解析的文件，因此其中可以放入任何 Lua 代码，但无法使用能够跳出此目录的模块。因此，无需复制整个文件即可进行编辑。Defines（包括图形 Defines）只是一个由 Lua 包含的数组，可以用 Lua 修改数组中的单个成员，例如 NDefines.NGame.START_DATE = "1936.1.2.12"。这些行各自独占一行，且 它们之间没有用逗号分隔，如下所示：

NDefines.NGame.START_DATE = "1936.1.2.12"
NDefines.NGraphics.COUNTRY_FLAG_TEX_MAX_SIZE = 2048

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.
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.
A mod should 绝不 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.

标记

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 国家创建 for the starting flags and 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. 变量 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 5 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.
• Military industrial organisation. The mio shortnening is used in code for them, such as set_mio_flag.

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 任意 effect block. There is no file where flags need to be defined, they will exist if set and stop existing when cleared.
The simplest formatting for setting a flag is set_country_flag = my_flag_name. 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. custom_effect_tooltip may be used to tell the player that something will be done, if wanting to keep them in the know.
Afterwards, that flag can be checked with has_country_flag = my_flag_name 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 key. As such, my_flag_name: "Has my flag" will make that appear when the country flag is checked.
If a flag is no longer useful, it can be cleared by using clr_country_flag = my_flag_name, 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 国家 is swapped with the type's name like set_global_flag, has_state_flag, or clr_character_flag) 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 @TAG to the name of the flag, though it can be placed anywhere within the tag name except for the first character. For example, set_country_flag = my_targeted_flag_@PREV 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, has_country_flag = my_targeted_flag_TAG will come up as true for the same country it was set in. This can be used to create dynamic flags without relying on 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.

示例

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 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:

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
    }
}

Flags provide a way to mark that this event has been received, in this case set within the immediate effect block of the event.

In order to utilise this, the has_country_flag trigger will have to be used similarly to this example decision:

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
        }
    }
}

This will work fine, however, as is, the player will see either a check mark or a 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 /Hearts of Iron IV/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):

 ALG_1936_elect_campaign: "The 1936 election campaign is currently ongoing"

In order to clear the flag when needed, the clr_country_flag effect would be used as such:

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
}

Note that neither of the effects that modify country flags have tooltips, so a custom effect tooltip can be used to notify the player in some cases.
Everything is the exact same for flags of other scope types.

Non-boolean usage

This will cover the non-boolean usage of flags. 变量 usually do this job better, but this still has some usages.

The set_<type>_flag effect can also be expanded with the optional days和value arguments. This will appear like the following:

set_state_flag = {
    flag = my_state_flag
    days = 50
    value = 3
}

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. If the value is left out, the flag will not be changed.

And the trigger if a flag is set can also be expanded as such:

has_global_flag = {
    flag = my_global_flag
    value > 2
    days > 30
    date < "1938.1.1"
}

While the flag and the value arguments are self-explanatory, days checks how many days it was since the flag was set (Not how many are remaining), while the date checks the date at which the flag is set. Every argument aside from the flag 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.

Additionally, it is possible to modify a flag as such:

modify_character_flag = {
    flag = my_character_flag
    value = 4
}

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.

Debugging

The following console commands exist for debugging variables. In console commands, the 'current scope' is what is currently selected: the country opened in diplomacy, the state selected, the unit leader that's selected. If left out, assumes to be the player country.

set_country_flag my_flag 

set_global_flag my_flag 

list_vars

事件目标

Event targets serve as a primitive way to set a pointer to a scope (country, state, character) to be referred to later. Any single event target can only point towards a single scope at a time, however a scope may have several event targets at the same time. Similarly to flags, there is no set folder for event targets, they can be assigned in any event block.
There are two types of event targets: regular and global. The difference between them is purely when they get cleared.

A scope can be checked if it has an event target assigned using has_event_target = name_of_event_target.

Global event targets

Global event targets can be declared using save_global_event_target_as = my_event_target as an effect. This will create the global event target with the name of my_event_target and it will last forever. Afterwards, it can be referred to as event_target:my_event_target, both as a scope and as a target.

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

For example, by using start_civil_war as an effect block, the following will assign the TAG_democratic_side event target to the revolter:

start_civil_war = {
    size = 0.5
    ideology = democratic
    save_global_event_target_as = TAG_democratic_side
}

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:

event_target:TAG_democratic_side = {
    transfer_state = 123
}
transfer_units_fraction = {
    target = event_target:TAG_democratic_side
    size = 0.2
}

It would make sense to clear the event target after it no longer exist, such as by using the on_civil_war_end on action.

When using the event target as a scope for a namespace in localisation, the event_target: prefix is not needed, instead it'll look like [TAG_democratic_side.GetName].

Regular event targets

Regular event targets can be declared using save_event_target_as = my_event_target 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 target_state and then fire the event mod_event.0 in 10 days:

random_owned_controlled_state = {
    save_event_target_as = target_state
}
country_event = { id = mod_event.0 days = 10 }

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.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:

123 = {
    save_event_target_as = demanded_prov_target
}
TAG = {
    country_event = generic.23
}

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 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.

Country tag aliases are stored within /Hearts of Iron IV/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:

• variable = global.var_name - This will make sure that the country tag alias is equivalent to the country that the specified variable points to, in this case var_name assigned to the global scope.
• event_target = my_event_target - This will make sure that the country tag alias is equivalent to the country that the specified 正规 event target points to, in this case my_event_target.
• global_event_target = my_event_target - 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 my_event_target.
• original_tag = TAG - This puts every country that originates from TAG (created with start_civil_war or create_dynamic_country) as a possible target for the alias. In this case, further specification is needed with triggers. This is equivalent to the original_tag trigger, but this is treated as an argument here as it does make certain errors go away.
• targets = { ABC DEF GHI } - 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.
• target_array = global.my_array - This puts every country that's within the specified array (my_array 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.
• country_score = { ... } - This is a 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.
• fallback = TAG - 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:

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
}

This is most commonly used with start_civil_war or create_dynamic_country. For example:

SDA = {
    original_tag = SDI
    has_country_flag = SDI_side_A
}

In order for this country tag alias to get used for side A of the civil war, it must have the country flag set. This is usually done directly in the effect that spawns it:

start_civil_war = {
    ideology = neutrality
    size = 0.5
    set_country_flag = SDI_side_A
}

After doing this, it's possible to use SDA as if it's a regular country tag, e.g. SDA = { add_political_power = 100 } or transfer_state_to = SDA.

separate from the method above another easier method to give custom tag to a dynamic d## country eg d04 (this method does not require a flag to be set)

in common\country_tag_aliases\tag_aliases.txt add

INA = {                                  #new tag
	original_tag = INS
	has_government = monarchism     #change monarchism to democratic etc to define which faction you want
}

The INA tag above will be functional without any other changes e.g. INA = { add_political_power = 100 }

using a limit

        if = {                                          ## Put this inside completion reward in a focus to create a custom cosmetic tag for a dynamic country, 
	limit = { 					##checks both conditions below match
		any_country = { original_tag = INS } 	##INS is original country Tag
		NOT = { has_government = democratic } 	## democratic/neutrality etc is government type change it to usually the government type of the original country or  , custom ideologies can be used here too.
		}					##  if the civil war has  MORE than 2 factions of differing government types  copy the NOT line and enter the third factions government type. 
	set_cosmetic_tag = INA				## set any country matching the above conditions to cosmetic tag INA that can be used.
	}

To Change a Dynamic country Name the name file you need is \localisation\countries_cosmetic_l_english.yml

add the below lines (rename inside " " to suit your needs)

 INA:0 "Indonesia Royalist uprising"                         #INA is new cosmetic tag created above
 INA_AST_autonomy_puppet_DEF:0 "Royal $OVERLORDADJ$ Indies"  # will change name to overlords adjective 

变量

A variable within Hearts of Iron IV is defined by appending a signed 32-bit integer ranging from -2 147 483 648 to 2 147 483 648 to another integer ranging from 0 to 99 999, representing the whole number and fractional parts of the variable respectively as <whole numbers>.<decimals>. As such, it effectively ranges from -2 147 483 648.99 999 to 2 147 483 647.99 999. Adding further amounts above or below the variable will result in an overflow, causing the value go from the maximum to the minimum or vice-versa. Additionally, this means that the highest level of accuracy achievable using the variable system is to the closest 0.00001, and any levels of precision beyond this will be truncated.

Variables are not stored within any particular file and can be created dynamically with any effect or (temporary variables-only) trigger. 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 tokenizable database types, a token: prefix is necessary when assigning a literal, for example: var_name = token:some_idea_name.

When using a variable as a scope, the var: 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 transfer_state = var:my_state_variable, the var: can be omitted with no difference (For some cases, there will be logged errors, yet it will work in-game), but in var:my_country_variable = { transfer_state = 123 } the var: is 必填. Despite functioning similarly to a scope, the var: prefix is optional when a variable is used as a weight inside of random_list. Same as with event targets, using variables in localisation for namespaces does not require the var: prefix, such as [?var_name.GetName]. 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 var: so that the parser can distinguish whether the token being passed is meant to reference a database object or a variable. If var: 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, var: is always optional in variable and array manipulation operators (including check_variable), 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 123_my_variable is invalid. This requirement common in many programming languages, and is implemented here for the same reason that the var: 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 capital can prevent any subsequent usage of the 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 (POL_capital) or the name of the mechanic (Usually shortened like PC_capital).

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 variable to temp_variable.
• 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 trigger 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 and must be assigned to countries, states, characters, and to the global scope.
If nothing else is specified, the current scope, or THIS, is used as the scope of the variable. For example, ABC = { set_variable = { my_var = 1 } } will set the variable with the name of my_var within the scope of ABC. CBA = { check_variable = { my_var = 1 } } would then come up as false, since it checks for the variable only within CBA, while the variable is set in ABC.

The scope where the variable is read can be changed by prepending any dual scope that can be used as a target and can be used in any scope (For example, character scopes can not be prepended before variable because character scopes are not any-scoping scopes, which means they can not be used in other character scopes.) before the variable's name, separated with a dot, such as PREV.PREV.var_name being the value of var_name as checked for PREV.PREV or event_target:my_event_target.var_name. This also includes global in order to assign it globally, which is necessary to scope into global. Other variables, if pointing to a scope, can also be used, but the var: is unneeded. Variables must be chained using the : separator (rather than the usual dot), such as ABC.capital:var_name being the variable var_name as it's assigned to the capital state of the country ABC, where capital is a built-in variable pointing to the capital state of the country. Note that the scope specifier preceding capital is separated from it by a . since it is a static (that is, non-variable) scope. The way to intuit this syntax is that the whole ABC.capital clause forms a variable scope specifier, in which var_name is accessed.

Here are some examples of scoped variable references:

var_name                                    # Scopes to THIS
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.

In practice, scoping to distinguish variables may look like this:

every_country = {
    set_variable = { weighted_manpower = 0 } # Reset the counter to default in case it already exists
    every_owned_state = {
        set_variable = { weighted_manpower = state_population_k } # Completely unrelated to the above variable due to being in a different scope
        if = {
            limit = {
                NOT = { is_core_of = PREV } # Is core of the owner
            }
            divide_variable = { weighted_manpower  = 10 } # Divides the state's equivalent
        }
        add_to_variable = { PREV.weighted_manpower = weighted_manpower } # Adds to the owner's counter
    }
}

In this case, each state has a weighted_manpower variable which is equal to the population in thousands if it's a core of the owner at the time of being set and it's divided by 10 otherwise. Each country will also have a weighted_manpower variable, which sums up the weighted manpower of each state. Despite having the same name, these variables are completely unrelated to each other due to one being country-level and the other being state-level.

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: 何时 each scope stops evaluating. If a scope stops evaluating, then the variable will not be modified anymore. In general, trigger scopes that can select multiple targets are divided into two groups: all_<scope type>和any_<scope type>. 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.
Empty trigger blocks are considered true by default, so one would instantly stop the validation of the second group (any_ triggers). For this reason, since scope limits are not supported in trigger scopes, then the proper usage for modifying temp variables would be an 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.

本地化文件

In order to display the value of a variable in localisation, [?var_name] 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: var_value_tt: "There are [?num_of_dogs] dog(s) in the country"
By default, the scope where this is used gets assumed. Scoping works the same way as it does with variables regularly: GER_var_value_tt: "There are [?GER.num_of_dogs] dog(s) in [GER.GetNameWithFlag]"
When the variable is a scope by itself, the question mark is still mandatory to use to distinguish from event targets: target_tt: "The target country is [?target_country.GetName]". Variables can only be displayed in UI that supports dynamic localisation, otherwise it will appear exactly as in the localisation file. List of such UI elements and necessary conditions for them to support dynamic localisation can be found in Localisation § Namespaces.

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: most_dogs_tt: "[?most_dogs.GetNameDefCap] has the most dogs out of any country." Question marks are still mandatory to include in this case.

Variables have a unique way for applying colouring, also allowing extra formatting characters. These are applied after a pipe placed at the end of the variable's name, such as [?my_variable|R] that will turn the colour of the variable my_variable red. If no colouring is applied, it will use the same colour as regular text: the §-colour block, textbox's text_color_mode, or the font's default colour in that order.

The list of formatting characters that are restricted to variables only are the following:

Any unrecognised symbols will neither change how the variable is localised nor get recognised as an error in-game. For example, it's common practice in the base game to prepend a dot before the digit used to control the amount of displayed digits as [?var|.1]. In case of overlap between mutually-exclusive rules, the last-used one will be prioritised. However, static colouring has a lower priority than dynamic colouring (e.g. [?var|+Y] will be treated as [?var|+]), and using %% will also override %.

Some examples of formatting characters in usage:

l_english:
 loc_key: "Democratic 党派 popularity: [?party_popularity@democracy|%G0]" 
 loc_key_2: "Modifier token's value: [?modifier@my_modifier|.1%%+]"
 pol_power_trigger_tt: "Has 更多 than [?var_name|Y] 政治 power"

Within these examples, the first string depicts the current scope's democratic popularity as a percentage multiplied by 100 (%), in green (G), rounded to a whole number with 0 decimals (0). The second string displays the my_modifier modifier token's value as a 'good' number (+ making it green if positive, red if negative), with a percentage sign appended in the end (%%) and rounded to a number with one decimal (.1). The third string displays the variable in yellow colouring (as is common in the base game's tooltips), leaving it unchanged otherwise.

By default, variable-related arguments such as set_variable or check_variable do not have a tooltip. For some of these arguments, such as add_to_temp_variable, it is possible to set a tooltip with an optional tooltip = localisation_key argument within. Others, such as check_variable, do not support this and a custom tooltip must be used instead, whether it's for 效果 or for 触发器.

This tooltip argument is notable since the value of that localisation key allows using two strictly-internal variables marked with dollar signs: $LEFT$和$RIGHT$.
$LEFT$ represents the variable's value before the operation, while $RIGHT$ 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 custom_effect_tooltip.

Here's an example of it being done:

add_to_variable = {
    var = num_dogs
    value = ENG.num_cats
    tooltip = add_cats_to_dogs_tt
}

This is the effect itself. Within localisation, this would be done:

 add_cat_to_dogs_tt: "Adds [ENG.GetAdjective] cats to our $LEFT$ dog(s) to get $RIGHT$ in total."

Additional usage

By default, an unset variable is equal to zero when checked. However, the game also provides a null coalescing operator for variables, used with a question mark. For example, cost = var_name?100 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 政治点数 instead of 0.

Similarly to flags, a variable can be set as targeted by appending the target with @TAG. 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 var_name_@GER would resolve to a variable named var_name_GER. If called in a scope where PREV= { tag = ENG }, a variable reference var_name_@PREV would resolve to a variable named var_name_ENG. This can even be applied to temporary variables. You can also target variables using the syntax var_name_@var:target_var_name, 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. 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 var_name_@THIS_@PREV. However, this is extremely inconsistent, and the exact rules that govern how it behaves are currently an open question.

Operators

以下是与变量相关的效果和触发器列表。修改变量的效果都有对应的临时变量版本，只是用temp_variable代替variable，且这些临时变量运算符同样可作为触发器使用，如上所述。每个运算符都可以用于不存在的变量，此时假定其值为 0，除非使用了空值合并运算符。

set_variable = {
    var = my_variable
    value = 100
    tooltip = set_var_to_100_tt
}

set_temp_variable = { temp_var = ROOT.overlord }

set_variable_to_random = {
    var = random_num
    max = 11
    integer = yes
}

set_temp_variable_to_random = my_var

clear_variable = my_variable

check_variable = {
    var = my_var
    value = 10
    compare = greater_than_or_equals
}

check_variable = { var_name > 10 }

has_variable = my_variable

add_to_variable = {
    var = my_variable
    value = 100
    tooltip = add_100_to_var_tt
}

add_to_temp_variable = { temp_var = num_owned_states }

subtract_from_variable = {
    var = my_variable
    value = 100
    tooltip = sub_100_from_var_tt
}

subtract_from_temp_variable = { temp_var = num_owned_states }

multiply_variable = {
    var = my_variable
    value = 100
    tooltip = multiply_var_by_100_tt
}

multiply_temp_variable = { temp_var = num_owned_states }

divide_variable = {
    var = my_variable
    value = 100
    tooltip = divide_var_by_100_tt
}

divide_temp_variable = { temp_var = num_owned_states }

modulo_variable = {
    var = my_variable
    value = 50
    tooltip = get_modulo_of_var_by_50_tt
}

modulo_temp_variable = { temp_var = num_controlled_states }

round_variable = my_variable

round_temp_variable = temp

clamp_variable = {
    var = my_var
    min = 0
}

clamp_temp_variable = {
    var = my_var
    min = 0
}

career_profile_set_temp_playthrough_variable = {
  sum = rocket_sites_built_1936
}

career_profile_set_temp_variable = {
  var = num_dogs
  value = num_dogs_in_career_profile
}

Math expressions

Calculations with extensive number of steps and complex usage of temporary variables may be simplified with the usage of math expressions.

Math expressions is a block of consecutive math functions that gets executed on the given value. Template for building a math expression looks like this:

{ value = 0 add = 1 }

value parameter is used as the default value, on which all the following functions are used.

add is a function name that is being executed on the value parameter. There could be multiple functions in one math expression, but there's no priorities for functions, thus they get executed by an order they are given in a block.

{ value = 0 add = 2 multiply = 3 } this block results in 6, not 2.

This whole block could be used in any of the short-hand variable operations given above. For example:

set_variable = {
     x = { value = y sin = yes }
}

For the boolean functions, 1.0 is considered true, with 0.0 considered false.

{ value = 10 less_than = 3 } results in 0.0.

Math functions

Below is the list of all existing math functions in the game.

{ value = 2 less_than = 10 }

{ value = 2 greater_than = 10 }

{ value = 2 add = 10 }

{ value = 1  and = 1 }

{ value = 1  atan = yes }

{ value = 1  atan2 = 1 }

{ value = num_units  clamp = { min = 0 max = 100 } }

{ value = 0  cos = yes }

{ value = 100  divide = 5 }

{ value = 7  equals = 7 }

{ value = 0
 every_collection = {
    named_collection = my_collection
    add = element_value } }

{ value = 5  greater_than_or_equals = 5 }

{ value = x
  if = { limit = { value = x  greater_than = 10 }  add = 100 }
  else = { subtract = 1 } }

{ value = 10  lerp = { to = 20  alpha = 0.5 } }

{ value = 5  less_than_or_equals = 5 }

{ value = 1000  log = 10 }
{ value = 1000  log = 10  round = yes }

{ value = 9  max = 15 }

{ value = 9  min = 4 }

{ value = 17  mod = 5 }

{ value = 2.3  multiply = num_units }

{ value = 0  not = yes }

{ value = 7  not_equals = 5 }

{ value = 0  or = 1 }

{ value = 2  pow = 10 }
{ value = 2  pow = 10  round = yes }

{ value = 16  root = 2 }
{ value = 27  root = 3 }
{ value = 16  root = 2  round = yes }

{ value = 3.7  round = yes }

{ value = 0  sin = yes }

{ value = 20  subtract = 5 }

{ value = 0  tan = yes }

{ value = 1  xor = 0 }

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.
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:

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. 
        }                                                                 # Temp variables are unscoped so it doesn't matter where they're edited.
    }                                                                     # For regular varibles, "add_to_variable" would need to scope into the correct country such as with "PREV.temp_manpower".
    add_manpower = var:temp_manpower # 'add_manpower = temp_manpower' also works
}

Since temporary variables can be set in triggers, they can be used as an alternative version of count_triggers, to count the amount of scopes where the trigger is fulfilled instead of counting the amount of fulfilled triggers:

if = {
    limit = {
        all_country = { # all_-typed scopes iterate over each entity until encountering a false, making them preferred over any_-typed ones that will exit out at a true.
            if = {                              # Direct limiting is only supported in effect scopes.
                limit = {
                    has_country_flag = example_flag
                }
                add_to_temp_variable = { flag_counter = 1 } # Assumed to be zero if unset
            }
        }
        check_variable = { flag_counter > 9 }
    }
    country_event = example.0 # The event fires if at least 10 countries have the example_flag flag.
}

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.
When using variables in this sense, it is better to use 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:

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.
}

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:

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, as long as the scripted effect is called upon each change of CAN_beavers.
    
    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
}

After creating these scripted effects, these can be used within any effect block to modify the variable at will. Showing its value in localisation to the player would also be helpful, such as within a decision category or in scripted GUI. Variables cannot be used within idea modifiers directly, 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 set_politics = { ruling_party = highest_party_ideology@exclude_ruling_party }. Similarly, some event target-type variables can be used to cut down on code, such as transfer_state = GER.capital immediately transferring the capital of GER to the current scope.

MTTH variables

MTTH variables allow to dynamically create a MTTH block to be used as a variable. These are stored within /Hearts of Iron IV/common/mtth/*.txt files, where each MTTH variable is a separate block, the name of which gets taken as the MTTH variable.
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 factor or 基础 and then each modifier = { ... } begin a trigger block needed to be fulfilled for the add (for adding) or/and factor (for multiplying) within to be applied. For example, the following is an example of a /Hearts of Iron IV/common/mtth/*.txt file:

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
}

This can be called the same way as a game variable, but somewhat differently: set_variable = { my_var = mtth:my_mtth_variable_1 }. This will check the MTTH block for the scope where it's checked and return the total result as a variable.

Debugging variables

There are the following arguments that can be used in trigger or effect blocks:

log = "Current value of myVar in [THIS.GetName]: [?myVar]"

print_variables = {
    file = my_file
    text = "These variables are printed at [GetDateText]"
    append = yes
    print_global = yes
}

print_variables = {
    file = my_file_2
    var_list = { temp1 temp2 temp3 }
}

Additionally, the following console commands exist for variables. In console commands, the 'current scope' is what is currently selected: the country opened in diplomacy, the state selected, the unit leader that's selected. If left out, assumes to be the player country.

set_var my_variable 10

get_var my_variable

list_vars

Token-valued variables

When one uses a literal of the form token:some_tokenizable_value, 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 list_vars console command by dint of being automatically translated into their underlying raw-token strings. For example, some_var_name = token:some_tokenizable_value (27012).

When the variable contains a token value, it is possible to use the GetTokenKey localisation function (such as [?some_var_with_token_value.GetTokenKey]) to get the token string value of the variable, token: prefix not included. This is useful for pasting in meta-effects和meta-triggers, however note that the token: prefix is still required if using it within the set_(temp_)variable operator. With some token-valued variables (specifically, those backed by named database objects of a tokenizable datatype), it is possible to use GetTokenLocalizedKey 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 on_add 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.
• Everything listed in /Hearts of Iron IV/common/script_enums.txt
• Ideologies/Ideology groups
• 科技
• Equipment types - Sometimes this is a bit inconsistent with regards to the archetype/non-archetype distinction, so be wary.
• 行动
• 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 GetTokenKey和GetTokenLocalizedKey, 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.
• 决议
• 建筑

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 /Hearts of Iron IV/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 TAG, TAG_DEF, and TAG_ADJ keys. An example of that would be creating an idea foo_bar 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 foo_bar_description (NOT foo_bar_desc, this collides with the localisation key generated for foo_bar) to carry the localisation value for the description that would be associated with the data value identified by foo_bar. This description localisation can be accessed with a meta-effect or meta-trigger (including in scripted localisation), such as set_temp_variable = { description_var = token:[IDEA_TOKEN]_description } (where IDEA_TOKEN = "[?idea_var_name.GetTokenKey]"). This allows accessing [?description_var.GetTokenLocalizedKey] in localisation where description_var is visible, such as the localization_key following the scripted localisation trigger 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 position_attorney_general, a corresponding description idea (suffixed with _description), a singular name idea (suffixed with _singular, carrying the name of the data value in singular form, like "Attorney General"), and a plural name idea (suffixed with _plural, carrying the name in plural form, like "Attorneys General"), it is possible to select which name to use by having a dummy idea called enum_position_name_singular with the localisation value "_singular", and another called enum_position_name_plural with the localisation value "_plural". After that, the mod may pass one of the enum_position ideas in a variable and then paste its GetTokenLocalizedKey after the GetTokenKey of the base idea in a meta-effect/trigger to produce either token:position_attorney_general_singular or token:position_attorney_general_plural. 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 /Hearts of Iron IV/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 script_enums 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, token:set_stability (that is, a token literal of the name of the set_stability effect) is perfectly valid, and yields a token for which GetTokenKey和GetTokenLocalizedKey both return set_stability. 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

修正定义允许创建一个自定义修正，在你想使用它时可以作为变量访问。定义之后，它完全像一个新变量那样运作，可以用相同的modifier@modifier_name流程作为变量读取。默认情况下它不会有任何效果，只是作为一种通过修正块以加算方式改变该变量数值的手段。每个修正记号都在/Hearts of Iron IV/common/modifier_definitions/*.txt文件中定义为一个独立的代码块，代码块的名称即该修正定义的 ID。它内部可以包含以下参数：

• color_type = good决定修正数值本身的颜色。共有三个取值：good、bad和neutral。neutral永远是黄色，而good会把正值显示为绿色、负值显示为红色。bad则与good相反。
• value_type = percentage 决定该数字在提示框中显示的方式。此参数可以设置为以下值：
  • number会显示修正的确切数值。0.02 会显示为“Modifier definition: 0.02”。
  • percentage会让修正以 0 到 1 为刻度的百分比显示。0.2 会显示为“Modifier token: 20%”。
  • percentage_in_hundred会让修正以 0 到 100 为刻度的百分比显示。10 会显示为“Modifier token: 10%”。
  • yes_no以布尔值显示：任何大于 1 的数值都显示为yes，而 0 显示为no。
• precision = 1决定提示框中在小数点后显示几位数字。例如，如果设为 1，提示框会把 0.341 显示得如同 0.3。请注意游戏本身不支持超过 3 位小数，因此该值不能大于 3。
• postfix决定在提示框中修正数值之后附加什么内容。允许的取值为 'none'（默认）、'days'、'hours' 和 'daily'。
• 类别决定该修正的类别。默认类别为 'all'，即属于每一个类别。某些提示框只会显示属于特定类别的修正。可以为同一个修正定义设置多个类别，只需把它们依次定义即可。

允许的取值为 'none'、'all'、'country'、'state'、'unit_leader'、'army'、'naval'、'air'、'peace'、'politics'、'ai'、'defensive'、'aggressive'、'war_production'、'military_advancements'、'military_equipment'、'autonomy'、'government_in_exile' 和 'intelligence_agency'。

修正定义的 ID 也被用作本地化键，以便根据当前开启的语言更改该修正的名称。

示例

modifier_definition_example = {
	color_type = good
	value_type = number
	precision = 1
	postfix = daily
	
	category = country
	category = state
}
modifier_definition_example_2 = {
    color_type = bad
    value_type = percentage
}

在变量中使用

修正定义的作用是改变某个游戏变量的数值，而该变量可以被其他变量读取。你可以通过执行set_variable = { var_name = modifier@modifier_token_name }，把某个变量设为等于当前作用域中同一修正记号所有数值之和。这个示例会把 var_name 设为等于 modifier_token_name 的总数值。

请注意，与国家、州不同，单位指挥官在其作用域中使用的是 leader_modifier@modifier_definition_name 或 unit_modifier@modifier_definition_name。

让某个修正记号每月在随机的核心州中创建民用工厂的用法示例，可放在任意 on action 文件中：

on_actions = {
    on_monthly = {
        effect = {
            if = {
                limit = {
                    check_variable = { modifier@modifier_definition_example > 0 }
                }
                for_loop_effect = {
                    start = 0
                    end = modifier@modifier_definition_example
                    random_owned_controlled_state = {
                        limit = {
                            is_core_of = ROOT
                            free_building_slots = {
                                building = industrial_complex
                                size > 0
                                include_locked = no
                            }
                        }
                        add_building_construction = {
                            type = industrial_complex
                            level = 1
                            instant_build = yes
                        }
                    }
                }
            }
        }
    }
}

数组

Arrays are similar to variables, but they instead store a collection of variables.
An array in the game is structured with indexes starting from 0. arrayname^0 as a variable refers to the first item of arrayname, arrayname^1 refers to the second item in the array, and so on. In order to obtain the total amount of items within the given array, arrayname^num is used. An array is assumed to have no elements by default, if not already created, with 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: set_variable = { arrayname^0 = 10 } will set the first element to be equal to 10 (with set_temp_variable used for temporary arrays), check_variable = { arrayname^0 > 10 } is also valid syntax, and [?arrayname^0] 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.

参数

The following arguments exist for arrays. Similarly to variables, temporary versions exist by replacing array with temp_array.

add_to_array = {
    array = global.my_countries
    value = THIS.id
}

add_to_temp_array = { temp_states = THIS }

remove_from_array = {
    array = global.my_countries
    index = 0
}

remove_from_temp_array = { temp_states = THIS }

clear_array = global.my_countries

clear_temp_array = temp_states

resize_array = {
    array = global.countries_by_states
    value = 10
    size = global.countries^num
}

resize_temp_array = { temp_states = 20 }

find_highest_in_array = {
    array = global.countries_by_states
    value = temp_largest_country
    index = temp_country_index
}

find_lowest_in_array = {
    array = global.countries_by_states
    value = temp_largest_country
    index = temp_country_index
}

Meanwhile, the following triggers exist that are array-related. As with variables, these are the exact same for temporary and regular variables.

is_in_array = {
    array = global.my_countries
    value = THIS.id
}

is_in_array = { temp_states = THIS }

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.
}

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 }
}

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.
}

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 }
    }
}

The following effects also exist in addition used, with arrays. While some are nominally unrelated to arrays, they are often used in conjunction.

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
        }
    }
}

for_each_scope_loop = {
    array = global.majors
    if = {
        limit = {
            NOT = { tag = PREV } # Not the country where the for_each_scope_loop is executed
        }
        random_owned_controlled_state = {
            transfer_state_to = PREV.PREV
        }
    }
}

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.
    }
}

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
                }
            }
        }
    }
}

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 }
    }
}

Scorers

Scorers are defined within /Hearts of Iron IV/common/scorers/country/*.txt files, serving as a sorted list of targeted countries, based on how well they did in the specified MTTH block. The scorer has the primary country which the scorer is used for and targeted countries.

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 targets = { ... } block that encompasses everything else about the scorer.

Scorers target countries similarly to 有目标决议 but with differences, with the following arguments being used within of targets = { ... }:

As with targetted decisions, FROM is the scope of the country being targeted by the scorer, while ROOT is the scope of the country invoking the scorer.

Scorers do not seem to hotreload very reliably. But, assuming you're changing an existing file rather than making a brand new one, edits to a scorer are reflected if you quit to main menu and then re-enter the game.

• targets = { TAG, TAG } - A list of country tags, including other dual scopes such as 宗主国, that can be targeted by this scorer. Unlike targeted decisions, this seems to be comma-separated.
• target_array = global.majors - The array to target. The default scope is the primary country.
• target_root_trigger = { ... } - 主要国家为使目标生效而必须满足的触发器块。在这里，ROOT（默认作用域）是运行评分器的国家。
  • It's not clear if there's any difference between target_root_trigger和target_trigger except that target_root_trigger is presumably only run once when invoking a scorer, and FROM cannot be used within it.
• target_trigger = { ... } - The trigger block that target country must fulfill for the target to work. In here, ROOT (default scope) is the country running the scorer and FROM is the potential target of the scorer.
• targets_dynamic = yes - If set, makes the dynamic countries possible targets. Defaults to no.
• target_non_existing = yes - If set, makes non-existing countries possible targets. Defaults to no.
• score = { ... } - 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:

asian_countries_owned_states_scorer = {
	majors_owned_states = {
		targets = {
			target_array = global.countries
			target_trigger = {
				FROM = {
					capital_scope = {
						is_on_continent = asia
					}
				}
			}
			score = {
				modifier = {
					add = num_owned_states
				}
			}
		}
	}
}

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.

get_highest_scored_country = {
    scorer = asian_countries_owned_states_scorer
    var = largest_asian_country
}

get_highest_scored_country_temp = {
    scorer = asian_countries_owned_states_scorer
    var = largest_asian_country
}

get_sorted_scored_countries = {
    scorer = asian_countries_owned_states_scorer
    array = asian_countries_by_size
    scores = asian_country_size_scores
}

get_sorted_scored_countries_temp = {
    scorer = asian_countries_owned_states_scorer
    array = asian_countries_by_size
    scores = asian_country_size_scores
}

示例

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.

Within the scorer file:

infantry_equipment_scorer = {
	targets = {
		target_array = global.countries
		targets_dynamic = yes
		score = {
		    modifier = {
		    	add = num_equipment@infantry_equipment
		    }
		}
	}
}

Within an effect block:

ROOT = {
	get_sorted_scored_countries_temp = {
		scorer = infantry_equipment_scorer
		array = scored_array
		scores = scored_values
	}

	for_loop_effect = {
		end = scored_array^num
		value = s
		log = "[?scored_array^s.GetName] had inf equipment [?scored_values^s]"
	}
}

Game variables

Game variables are read-only variables that are used to read certain aspects of the game, such as the current political power that the player has. These cannot be modified using any variable-modifying argument, but they can serve as the value within them (such as add_to_temp_variable = { temp = GER.army_experience } adding the amount of army experience that GER has to the temp temporary variable). Some are targeted, requiring one more argument in the target's place. For example, modifier has a modifier token as the target, so it would be used as set_temp_variable = { temp = modifier@consumer_goods_factor }, where consumer_goods_factor 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 global.year rather than leaving out the scope. A list of game variables can be found within /Hearts of Iron IV/documentation/dynamic_variables_documentation. A large portion of purely numeric 触发器 also have corresponding game variables that are not mentioned in the documentation. The following game variables exist in the game (Some duplicates are omitted):

Country-scoped intelligence-related game variables:

变量	Target	Description/Notes
army_intel	Country.	Army intel against the target country.
navy_intel	Country.	Navy intel against the target country.
airforce_intel	Country.	Air intel against the target country.(If you need to use this variable as a trigger for checking, please write a localization yourself.)
civilian_intel	Country.	Civilian intel against the target country.
encryption_strength	无。	Total encryption strength of the country. Only without the 抵抗运动 DLC.
decryption_speed	无。	Total decryption speed of the country. Only without the 抵抗运动 DLC.
cryptology_defense_level	无。	cryptology defense level of the country.
agency_upgrade_number	无。	The number of upgrade done in the intelligence agency.
decryption_progress	Country.	Decryption progress against the target country.
network_national_coverage	Country.	Network national coverage the current country has over the target country.
num_fake_intel_divisions	无。	The amount of fake intel division that the country has.
num_operative_slots	无。	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.
num_free_operative_slots	无。	The amount of operative slots that are currently empty and an operative can be recruited in.
num_of_operatives	无。	The number of operatives the country controls.

A large portion of the AI-related game variables can have values seen in-game by using the aiview console command.

Game arrays

参考资料