作用域

作用域 change the currently-selected entity where the 效果 should apply or which is checked by the 触发器. 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, 变量, or 事件目标 can be used to get around this limitation.

类型

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 a 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.
• Special Project scopes - Executed for special projects.

Only 效果 or 触发器 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.

示例

Example scope with effects: all contained effects are executed for the scope. This adds 10% 稳定度 and 20% 战争支持度 to the  苏联:

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  英国 and controlled by  爱尔兰:

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

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

Non-dual scopes that select unit leaders or 军工组织（MIO）, 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

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 本地化 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 国家"

This will appear in the tooltip as such:

任何友好国家： Is at war with  意大利.

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:

德国，苏联： Gain Base War Support: -10%.

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% 战争支持度 removed. However, adding display_individual_scopes = yes changes it to the following:

德国： Gain Base War Support: -10%.  苏联: Gain Base Stability: -10%.

Empty Effect Scopes

An effect scope argument that is frequently used in conjunction with tooltip is visible_when_empty = yes which will show the scope's effects even when no valid targets can be found (that meet the limit).

Because this allows an empty line of targets to exist in the tooltip, tooltip can be used to describe the targets even if there aren't currently any:

every_other_country = {
	limit = {
		is_in_faction_with = ROOT
	}
	tooltip = ALL_OTHER_FACTION_MEMBERS
	visible_when_empty = yes
	add_political_power = 100
}

Alternatively custom_effect_tooltip could be used directly in front of the scope to show a replacement tooltip for the empty line, with a separate if-statement to verify it is currently empty, this maintains the dynamic target list when any country does meet the requirements.

if = {
	limit = {
		NOT = {
			any_other_country = {
				is_in_faction_with = ROOT
			}
		}
	}
	custom_effect_tooltip = ALL_OTHER_FACTION_MEMBERS
}
every_other_country = {
	limit = {
		is_in_faction_with = ROOT
	}
	visible_when_empty = yes
	add_political_power = 100
}

优先级

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.

双重作用域

以下作用域既可用作效果作用域，也可用作触发器作用域；有些还可作为某些效果和触发器的右侧目标使用。若可作为目标使用，会在表中标注。

部分双重作用域的作用域会随使用位置而变化，例如变量可被设为任何内容。

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

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 效果 or 触发器 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 宗主国 scope for an independent country.

Trigger scopes

These can only be used as 触发器; trying to use them as 效果 will result in nothing happening.

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
}

all_country_of = {
	tooltip = my_loc # Optional bindable localization
	target = { SWE NOR FIN DEN ICE }
	has_defensive_war = yes
}

all_country_of = {
    tooltip = my_loc # Optional bindable localization
	target = constant:country_groups:nordics
	has_defensive_war = yes
}

any_country_of = {
	tooltip = my_loc # Optional bindable localization
	target = { SWE NOR FIN DEN ICE }
	has_defensive_war = yes
}

any_country_of = {
    tooltip = my_loc # Optional bindable localization
	target = constant:country_groups:nordics
	has_defensive_war = yes
}

any_state_in = {
  array = array_of_states  #required 
    …                  #triggers to check
}

array = <array_of_states>
continent = <continent_name>
ai_area = <ai_area_name>
strategic_region = <strategic_region_number>

any_state_of = {
	tooltip = my_loc # Optional bindable localization
	target = { 1 42 1992 }
	controller = {
		has_defensive_war = yes
	}
}

any_state_of = {
    tooltip = my_loc # Optional bindable localization
	target = constant:country_groups:nordics
	controller = {
		has_defensive_war = yes
	}
}

效果作用域

这些只能作为效果使用；把它们当作 触发器 使用将不会产生任何效果。

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
}

every_collection_element = {
    input = {
        input = collection_id # This can be a collection name or an inline definition of a collection
        limit = {
            # Trigger - limit effect execution to a subset of elements
        }
    }
    # Effects to be executed
}

注意： 其中一些作用域可能没有符合条件的国家/州。

会改变作用域的效果

There are the following 效果 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

数组 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 用法

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

示意图，展示 PREV 和 PREV.PREV 如何与代码示例中的其他条目相连接。

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

• （撒丁岛、科西嘉、西西里）：
  •  瑞士:
    • Becomes owner and controller of 撒丁岛

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

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

custom_override_tooltip = {
    tooltip = MY_TOOLTIP
    not_tooltip = MY_TOOLTIP_NOT
    <triggers/effects>
}

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