Hearts of Iron 4 Wiki (2024)

This is a community maintained wiki. If you spot a mistake, please help with fixing it.

Scopes change the currently-selected entity where the effects should apply or which is checked by the triggers. Each one must follow the same formatting of scope = { <contents> }.

When a scope is used as for effects, each effect inside of the scope's block is executed. Conversely, when a scope is used as for triggers, it serves as a logical conjunction, requiring every trigger in the scope's block to be met for that scope to evaluate as true.

In addition to serving as blocks for effects or triggers, some scopes can also serve as targets of effects or triggers: e.g. transfer_state_to = ROOT or owns_state = 123.
However, only some dual scopes can be used as a target. For scopes that cannot be used as targets, PREV, Variables, or Event targets can be used to get around this limitation.

Types[edit | edit source]

Scopes can be thought of as divided into 3 types by purpose:

• Trigger scopes - those that can only be used in trigger blocks, failing when put within an effect block.
• Effect scopes - those that can only be used in effect blocks, failing when put within an trigger block.
• Dual scopes - those that can be put in both trigger and effect blocks without issues.

It is to be noted that trigger or effect scopes cannot ever be used as targets. That is strictly limited to some dual scopes.

Most of the non-dual scopes follow one of these following patterns:

Only some scopes that follow this pattern have equivalents with a different pattern. For example, random_owned_controlled_state exists, but every_owned_controlled_state does not. Each of these non-dual scopes cannot select a country that does not exist, with the exception of every_possible_country.

Additionally, scopes can be divided into 6 types by the targets of the scope for which effects are executed or triggers are checked:

• Country scopes - Executed for countries.
• State scopes - Executed for states.
• Character scopes - Executed for characters. Some subsets exist, such as unit leaders and country leaders.
• Division scopes - Executed for divisions.
• MIO scopes - Executed for military industrial organisations.
• Contract scopes - Executed for purchase contracts.

Only effects or triggers of the same target type can be used. For example, add_building_construction can only be used in a state scope such as random_owned_controlled_state = { ... }, as you can only construct buildings in states. For countries, offsite buildings are used instead.

Examples[edit | edit source]

Example scope with effects: all contained effects are executed for the scope. This adds 10% Stability and 20% War support to the Soviet Union:

SOV = { add_stability = 0.1 add_war_support = 0.2}

Example scope with triggers: all contained triggers must return true for the scope; otherwise, the scope returns false. This requires the state 123 (South-West England) to be owned by the United Kingdom and controlled by Ireland:

123 = { is_owned_by = ENG is_controlled_by = IRE}

Example use of PREV as target for non-targetable scope. Since random_country cannot be used as a target, add_to_faction = random_country is not valid syntax; instead, PREV can be used to get around this limitation. The following example adds random country to ROOT's faction:

random_country = { ROOT = { add_to_faction = PREV }}

Settings[edit | edit source]

This is a community maintained wiki. If you spot a mistake, please help with fixing it.

Scopes can have additional settings to narrow down the usage. This may change how many and which targets it's able to select or what the tooltip shows.

Limiting[edit | edit source]

Non-dual scopes that select unit leaders or MIOs, such as every_navy_leader, by default only include those that are visible to the player, i.e. those unit leaders whose roles do not have an unfulfilled visible = { ... } and those MIOs that do not have an unfulfilled visible = { ... }. By including include_invisible = yes, this can be changed. This will look as such:

random_army_leader = { include_invisible = yes set_nationality = SWE}

Within only effect scopes, limit = { ... } can be used as a trigger block, evaluated for each possible target contained by the scope. In case of the every_<name> pattern, this will ensure that the tooltip will function properly, which may not be the case when using if directly. In case of the random_<name> pattern, this will remove the possibility of scopes not meeting the triggers being chosen, limiting the selection. For party_leader in specific, the limit must contain has_ideology, while there are no requirements on other scopes. An example of limiting the selection is the following:

every_neighbor_country = { #Targets every neighbor country limit = { num_of_military_factories > 5 #Limit the scope to neighbor countries with more than 5 (at least 6) military factories } give_military_access = ROOT #Neighbor countries with more than 5 military factories give military access to the ROOT country}

In case of multiple triggers, limit acts like an AND block, requiring each one to be true. To reiterate, this cannot be used within trigger or dual scopes, only in effect scopes.

For scopes of the every_ type, an additional setting for limiting the selection is random_select_amount. In particular, it takes an integer and limits the maximum amount of chosen scopes to that number, picking a random sub-set if exceeded. It is used as such:

every_country = { random_select_amount = 3 # Selects 3 random countries country_event = lottery_win.0}

Tooltip[edit | edit source]

By default, using a scope of either of the any_, all_, and every_ types will show a title specific to that scope in the tooltip, such as Every country: or All neighbor states:. If scope limits are used, then this changes to the list of scopes that fulfill the limit, such as Corsica, Rome, Sardinia:. For countries, the order in which country tags are created is used in ordering; for states, the state ID is used. If the tooltip differs depending on the scope where it's executed, such as with if statements, then only the first-selected scope is used in the evaluation.

By using tooltip = loc_key within any non-dual scope, including of the random_ type, the tooltip shown to the player can be changed towards the value of the targeted localisation key in the currently enabled language. This will look like the following:

any_country = { hidden_trigger = { has_opinion = { target = PREV value > 50 } # Serves as a "limit" hidden from the player. } tooltip = any_friendly_country_tt # Replaces "Any country" with the localisation key has_war_with = ITA}

The localisation key will be defined as such in any localisation file:

l_english: any_friendly_country_tt: "Any friendly country"

This will appear in the tooltip as such:

In tooltips of the every_ type where scope limits are used, by default the tooltip unites it into a single scope, such as Germany, United Kingdom, Soviet Union:. By using display_individual_scopes = yes, this will make each selected scope appear in the tooltip separately. For example:

every_neighbor_country = { limit = { OR = { has_government = communism has_government = fascism } } display_individual_scopes = yes if = { limit = { has_government = fascism } add_war_support = -0.1 } else = { add_stability = -0.1 }}

Without displaying individual scopes, this will be shown as one effect block, such as the following:

By the nature of tooltips, the if statements for the first country are evaluated and the same tooltip is shown for both countries. This falsely implies that the Soviet Union will have 10% War support removed. However, adding display_individual_scopes = yes changes it to the following:

Priority[edit | edit source]

Within effect scopes of the random_ type, if it is aimed at states, it is possible to prioritize a certain state if possible, by using prioritize as such:

random_owned_controlled_state = { prioritize = { 123 321 } limit = { is_core_of = PREV } <...>}

In this case, the limit will first be evaluated for states 123 and 321. Only if neither of the states 123 or 321 meets the conditions of being owned, controlled, and cored by the country will the random_owned_controlled_state scope be able to select a state that isn't 123 or 321. States 123 and 321, in this case, have the same priority: if both have conditions fulfilled, which one will be picked is random. This only applies at scopes of the random_ type which target states, this cannot be done with countries or characters.

Dual scopes[edit | edit source]

The following scopes can be used either as effect or trigger scopes; some can also be used as the right side of some effects and triggers as a target. If usage as a target is possible, it's marked within the table.

Several dual scopes may have a scope that varies depending on where it's used, such as variables, which can be set to anything.

ENG = { FRA = { GER = { declare_war_on = { target = ROOT type = annex_everything } } }} #GER declares war on ENG (if there is no scope before ENG)

set_temp_variable = { target_country = THIS }

FRA = { random_country = { GER = { declare_war_on = { target = PREV type = annex_everything } } }} #Germany declares war on random_country

declare_war_on = { target = FROM type = annex_everything}FROM = { load_oob = defend_ourselves}

controller = { ROOT = { create_wargoal = { target = PREV type = take_state_focus generator = { 123 } } }}

Invalid event target[edit | edit source]

See also: Event targets

In regards to some dual scopes, a possible logged error to get while using them is "Invalid event target", as in common/national_focus/generic.txt:690: controller: invalid event target: controller, while the scope being used is not necessarily an event target.
This refers to the scope not having any defined target in the context that it is used, i.e. it is impossible to select any single target when it is used. In case of controller = { ... } as in the example, this means that the scope is checked or executed in a state that isn't controlled by any country. Such states are rather unstable and can cause crashes easily (such as if evaluated for an air mission by AI or if doing almost any effect on them), so if this happens for controller or owner, then this must be fixed only by making sure that every state has an owner or controller.

In practice, this gets skipped over entirely when evaluating the effects or triggers: none of the effects would be executed; as a trigger it'll not come up as either true or false. However, since this can be checked every tick, leaving it as is can result in cluttering the error log. To avoid this, it's possible to use the if statement in effects or triggers in such a manner that the dual scope would only be checked if the conditions for it existing are fulfilled, such as by checking that the country is indeed a subject before checking the overlord. An example of that being done is as such:

if = { limit = { is_subject = yes } overlord = { country_event = example.0 }}

While this has identical effects regardless of whether the country is independent or is a subject, this doesn't access the overlord scope for an independent country.

Trigger scopes[edit | edit source]

These can only be used as triggers; trying to use them as effects will result in nothing happening.

This is a community maintained wiki. If you spot a mistake, please help with fixing it.

all_country_with_original_tag = { original_tag_to_check = TAG #required … #triggers to check}

any_country_with_original_tag = { original_tag_to_check = TAG #required … #triggers to check}

Effect scopes[edit | edit source]

These can only be used as effects; trying to use them as triggers will result in nothing happening.

This is a community maintained wiki. If you spot a mistake, please help with fixing it.

every_country_with_original_tag = { original_tag_to_check = TAG #required … #effects to run}

random_country_with_original_tag = { original_tag_to_check = TAG #required … #effects to run}

random_state = { prioritize = { 123 321 } #optional … #effects to run}

random_owned_state = { prioritize = { 123 321 } #optional … #effects to run}

random_core_state = { prioritize = { 123 321 } #optional … #effects to run}

random_controlled_state = { prioritize = { 123 321 } #optional … #effects to run}

random_owned_controlled_state = { prioritize = { 123 321 } #optional … #effects to run}

party_leader = { limit = { has_ideology = liberalism } set_nationality = BHR}

NOTE: Some of these scopes may have no countries/states that match the criteria

Effects with scopes[edit | edit source]

There are the following effects that also change the currently-selected scope:

start_civil_war = { ruling_party = communism # Original country's ideology changes to communism ideology = ROOT # Breakaway gets old ideology of ROOT size = 0.8 capital = 282 states = { 282 533 536 555 529 530 528 } keep_unit_leaders = { 750 751 752 } keep_political_leader = yes keep_political_party_members = yes}

start_civil_war = { ideology = democratic size = 0.1 states = all states_filter = { is_on_continent = europe is_capital = no } set_country_flag = TAG_my_country_tag_alias_trigger # Sets a country flag that gets used in a country tag alias.}

start_civil_war = { ideology = neutrality size = 0.1 army_ratio = 0.5 navy_ratio = 0 air_ratio = 1 keep_unit_leaders_trigger = { has_trait = my_trait_name } keep_all_characters = yes PREV = { # Original country TAG_airforce_leader = { # Character set_nationality = PREV.PREV # Transfers to breakaway } } promote_character = TAG_airforce_leader}

create_dynamic_country = { original_tag = POL copy_tag = SOV add_political_power = 100 transfer_state = 123}

Array scopes[edit | edit source]

See also: Arrays

Arrays can be used to create a generic selection of scopes meeting the criteria. These scopes exist for checking conditions on elements of an array or executing effects on them:

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

for_each_scope_loop = { array = global.majors if = { limit = { NOT = { tag = ROOT } } random_owned_controlled_state = { transfer_state_to = ROOT } }}

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

PREV usage[edit | edit source]

In order to understand PREV, it can be helpful to think back to the trigger/effect scopes such as every_controlled_state. In this case, if put inside directly, PREV can be used as the controller of the state. In fact, every_controlled_state is equivalent to every_state with a limit of is_controlled_by = PREV in most ways, although it is recommended to use every_controlled_state instead as it is better for optimisation. For example, the following will transfer every state to its controller, changing the owner:

every_country = { every_controlled_state = { transfer_state_to = PREV }}

If thinking of it as a tree, the scopes are in the order of [every_country,every_controlled_state]. Using it within every_controlled_state will refer back to the parent node, or every_country, specifically the country in the every_country list this is currently being executed for. This can be used in other ways, such as obtaining a wargoal against the owner of a state:

123 = { owner = { ROOT = { create_wargoal = { target = PREV type = take_state_focus generator = { 123 } } } }}

In this case, the tree is constructed with [123,owner,ROOT]. Using PREV within ROOT will refer to the previously-defined owner.

Chaining PREV can be done by separating them with a dot as PREV.PREV.PREV. This can be useful if the needed scope is more than 1 scope back.
This is an another example of PREV usage with an attached diagram showing how they connect to other scopes:

every_country = { limit = { any_country = { any_country = { has_war_with = PREV is_neighbor_of = PREV.PREV } has_attache_from = PREV } } country_event = my_event.0}

In this case, an event will be sent to every country that has sent an attaché to a country that's at war with a neighbour of the original country (i.e. the country that would receive the event). Using PREV.PREV is necessary in this case as all 3 countries don't have single defined tags or pointers and all interact with each other.

In many cases, using PREV can result in seemingly broken tooltips which'll work fine regardless when executing the effects in-game. This typically happens when using it pointing to scopes of the every_<...>/all_<...> types. A single effect or trigger's tooltip can only show one scope as a target at once, and the game would only pick the first possible scope in the tooltip. This can look like the following:

• (Sardinia, Corsica, Sicily):
  • Switzerland:
    • Becomes owner and controller of Sardinia

This can not be avoided with traditional means while still using PREV. Instead, it's possible to use hidden_effect and custom_effect_tooltip or custom_trigger_tooltip in order to completely replace the tooltip in this case.

Flow control tools[edit | edit source]

While these aren't scopes, not changing where the effects are run or triggers are checked, they still function as blocks of code that can be used within any trigger and/or effect.

AND = { original_tag = GER has_stability > 0.5}

OR = { original_tag = ENG original_tag = USA}

NOT = { has_stability > 0.5 has_war_support > 0.5}

count_triggers = { amount = 2 10 = { state_population_k > 100 } 11 = { state_population_k > 100 } 12 = { state_population_k > 100 }}

hidden_trigger = { country_exists = GER}

custom_trigger_tooltip = { tooltip = sunrise_invasion_tt any_state = { is_owned_by = JAP is_on_continent = europe is_coastal = yes }}

hidden_effect = { declare_war_on = { target = PREV type = annex_everything }}

effect_tooltip = { declare_war_on = { target = FROM type = annex_everything }}

if = { limit = { original_tag = GER } has_political_power > 100}else_if = { limit = { original_tag = ENG } has_stability > 0.5}else = { has_war_support > 0.5}

for_loop_effect = { start = -3 end = 9 compare = less_than_or_equals add = 3 value = value_name break = break_name add_political_power = value_name # Adds -3, then 0, then 3, then 6, then 9, after which the loop breaks for 15 total political power.}

while_loop_effect = { break = temp_break limit = { country_exists = GER } random_state = { limit = { is_owned_by = GER } random_country = { limit = { NOT = { tag = GER } } transfer_state = PREV } }}

random = { chance = 80 add_stability = 0.8}

random_list = { 10 = { modifier = { factor = 0 has_stability > 0.9 } add_stability = 0.1 } 20 = { add_stability = -0.1 }}