Scopes

From Hearts of Iron 4 Wiki
Jump to navigation Jump to search

Scopes select entities in order to check for conditions or apply commands.

Scopes always have a bracketed block on the right side:

<scope_name> = {
	#Stuff to execute in the scope.
}

But not all bracketed blocks are scopes: some are function blocks (option, trigger, mean_time_to_happen,...), operators (AND), flow control statements (if, limit), or clause for complex conditions or commands.

Scope-change types[edit]

There are different types of scope change operators.

  • Condition: Conditional scopes do return a Boolean value like other conditions
  • Command: Command scopes do execute commands on the new scope
  • Both: These operators can be used as both of the above.

Most of the general scope change operators have four different forms.

Name Description
all_<name> Conditional, all must meet the subconditions
any_<name> Conditional, at least one must meet the subconditions
every_<name> Command, executed on every subscope
random_<name> Command, executed on one random subscope

List of Scopes[edit]

Please be aware of the following:

If a scope has trigger set to , then you may test it against a condition.
If a scope has effect set to , then you may run a command on it.
Scope Description Example Trigger Effect From Scope To Scope Game Version
all_unit_leader Check if all unit leaders owned by the current country scope meet the trigger. all_unit_leader = { ... } X Country Unit Leader 1.5
any_unit_leader Check if any unit leader meets the trigger. any_unit_leader = { ... } X Country Unit Leader 1.5
all_army_leader Check if all army unit leaders owned by the current country scope meet the trigger all_unit_leader = { ... } X Country Unit Leader 1.5
any_army_leader Check if any army unit leader owned by the current country scope meets the trigger all_unit_leader = { ... } X Country Unit Leader 1.5
all_navy_leader Check if all navy unit leaders owned by the current country scope meet the trigger all_navy_leader = { ... } X Country Unit Leader 1.5
any_navy_leader Check if any navy unit leader owned by the current country scope meets the trigger. all_navy_leader = { ... } X Country Unit Leader 1.5
random_unit_leader Targets a random unit leader owned by the current country scope random_unit_leader = { ... } X Country Unit Leader 1.5
every_unit_leader Targets every unit leader owned by the current country scope every_unit_leader = { ... } X Country Unit Leader 1.5
random_army_leader Targets a random army unit leader owned by the current country scope random_army_leader = { ... } X Country Unit Leader 1.5
every_army_leader Targets every army unit leader owned by the current country scope every_army_leader = { ... } X Country Unit Leader 1.5
random_navy_leader Targets a random naval unit leader owned by the current country scope random_navy_leader = { ... } X Country Unit Leader 1.5
every_navy_leader Targets every naval unit leader owned by the current country scope every_navy_leader = { ... } X Country Unit Leader 1.5
global_every_army_leader Targets every army leader for every country in the world (Better to use every_army_leader if you know the country) global_every_army_leader = { ... } X Country Unit Leader 1.5
OVERLORD Targets the overlord of the current scope, if current scope is a subject RAJ = { OVERLORD = { ... } } Country Country 1.3
TAG Targets a specific country by tag FRA = { ... } Anywhere Country 1.0
any_country Targets any country in the world (including the current scope, see any_other_country) any_country = { ... } X Anywhere Country 1.0
any_country_with_original_tag Targets any country with current scope's original tag any_country_with_original_tag = { ... } X Anywhere Country 1.9
any_neighbor_country Targets any neighboring country of the current scope any_neighbor_country = { ... } X Country Country 1.0
any_home_area_neighbor_country Targets any country that shares a border with the current scope's home area (cored states) any_home_area_neighbor_country = { ... } X Anywhere Country 1.0
any_guaranteed_country Targets any country with current scoped country guarantees any_guaranteed_country = { ... } X Country Country 1.9
any_allied_country Targets any allied country of the current scope any_allied_country = { ... } X Country Country 1.0
any_other_country Targets any other country in the world (not including the current scope) any_other_country = { ... } X Country Country 1.0
any_enemy_country Targets any enemy country of the current scope any_enemy_country = { ... } X Country Country 1.0
any_occupied_country Targets any occupied country by the current scope any_occupied_country = { ... } X Country Country 1.9
all_neighbor_country Targets all neighboring countries of the current scope all_neighbor_country = { ... } X Country Country/ies 1.0
all_country Targets all countries in the world all_country = { ... } X Anywhere Country/ies 1.0
all_country_with_original_tag Targets all country with current scope's original tag all_country_with_original_tag = { ... } X Anywhere Country/ies 1.9
all_allied_country Targets all allied countries of the current scope all_allied_country = { ... } X Country Country/ies 1.9
all_guaranteed_country Targets every country with current scoped country guarantees all_guaranteed_country = { ... } X Country Country/ies 1.9
all_enemy_country Targets all enemy countries of the current scope all_enemy_country = { ... } X Country Country/ies 1.0
all_occupied_country Targets all occupied countries all_occupied_country = { ... } X Country Country/ies 1.9
state_id Targets a specific state by id number 145 = { ... } Anywhere State 1.0
any_state Targets any state in the world any_state = { ... } X Anywhere State 1.0
any_controlled_state Targets any of the states controlled by the scope country any_controlled_state = { ... } X Country State 1.9
any_owned_state Targets any owned state of the current scope any_owned_state = { ... } X Country State 1.0
any_neighbor_state Targets any neighboring state of the current scope any_neighbor_state = { ... } X State State 1.0
all_state Targets all states in the world all_state = { ... } X Anywhere State/s 1.0
all_owned_state Targets all owned states of the current scope all_owned_state = { ... } X Country State/s 1.0
all_neighbor_state Targets all neighboring states of the current scope all_neighbor_state = { ... } X State State/s 1.0
all_owned_state Targets all owned states of the current scope all_owned_state = { ... } X Country State/s 1.0
all_controlled_state Targets all of the states controlled by the scope country all_controlled_state = { ... } X Country State/s 1.9
every_country Targets every country in the world (including the current scope, see every_other_country) every_country = { ... } X Anywhere Country/ies 1.0
every_country_with_original_tag Targets every country with original tag every_country_with_original_tag = { original_tag_to_check = TAG limit = { ... } ... } X Anywhere Country/ies 1.9
every_other_country Targets every other country in the world (not including the current scope) every_other_country = { ... } X Country Country/ies 1.0
every_neighbor_country Targets every neighboring country of the current scope every_neighbor_country = { ... } X Country Country/ies 1.0
every_enemy_country Targets every enemy country of the current scope every_enemy_country = { ... } X Country Country/ies 1.0
every_occupied_country Targets every occupied country of the current scope every_occupied_country = { ... } X Country Country/ies 1.9
random_country Targets a random country in the world (including the current scope) random_country = { ... } X Anywhere Country 1.0
random_country_with_original_tag Targets a random country with original tag random_country_with_original_tag = { original_tag_to_check = TAG limit = {...} ... } X Anywhere Country 1.9
random_neighbor_country Targets a random neighboring country of the current scope random_neighbor_country = { ... } X Country Country/ies 1.0
random_enemy_country Targets a random enemy country of the current scope random_enemy_country = { ... } X Country Country 1.0
random_occupied_country Targets a random occupied country of the current scope random_occupied_country = { ... } X Country Country 1.9
random_state Targets a random state in the world random_state = { ... } X Anywhere State 1.0
random_owned_state Targets a random owned state of the current scope random_owned_state = { ... } X Country State 1.0
random_controlled_state Targets a random controlled state of the current scope random_controlled_state = { prioritize = { <stateID> <stateID> } to pick those states first if they fulfill the limit ... } X Country State 1.9
random_owned_controlled_state Targets a random owned and controlled state for the current scope random_owned_controlled_state = { ... } X Country State 1.3
random_neighbor_state Targets a random neighboring state of the current scope random_neighbor_state = { ... } X State State 1.0
every_state Targets every state in the world every_state = { ... } X State State/s 1.0
every_controlled_state Targets every controlled state of the current scope every_controlled_state = { ... } X Country State/s 1.9
every_owned_state Targets every owned state of the current scope every_owned_state = { ... } X Country State/s 1.0
every_neighbor_state Targets every neighboring state of the current scope every_neighbor_state = { ... } X State State/s 1.0
capital_scope Targets the capital state of the current scope capital_scope = { ... } Country State 1.0
owner scope Targets the owner of a state owner = { ... } X State Country 1.0
controller scope Targets the controller of a state controller = { ... } X State Country 1.0
all_operative_leader Targets all operatives of the current scope all_operative_leader = { ... } X Country/Operation Operatives 1.9
any_operative_leader Targets any operative of the current scope any_operative_leader = { ... } X Country/Operation Operative 1.9
every_operative Targets every operatives of the current scope every_operative = { ... } X Country/Operation Operative 1.9
random_operative Targets a random operative of the current scope random_operative = { ... } X Country/Operation Operative 1.9

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

Scope limits[edit]

It is possible to use the limit block to narrow down scopes using specific conditions. Simply insert the limit block inside a scope (ex. every neighbor country), put in the desired conditions (ex. has more than 5 military factories) and after closing the limit block, put in the commands (ex. give military access) to affect the specified scopes. A short example is available here:

every_neighbor_country = { # Targets every neighbor country
	limit = {
		num_of_military_factories > 5 # Limit the scope to neighbor countries with more than 5 military factories
	}
	give_military_access = ROOT # Give military access to neighbor countries with more than 5 military factories
}

Moving Between Scopes[edit]

There are a series of links to help you call effects or check triggers in other scopes. All these links can be used in effects or triggers, although not all commands and conditions seem to accept them, or as scopes themselves

Link Description Example
ROOT Targets the root (this first scope the script enters) country that this effect or trigger is in, regardless of what other scope this is
ENG = {
	FRA = {
		GER = {
			declare_war_on = {
				target = ROOT
				type = annex_everything
			}
		}
	}
} # Germany declares war on Britain (assuming there is no scope before ENG = { )
THIS Targets the current scope
random_state = {
    add_resource = {
        type = oil
        amount = 50
        state = THIS
    }
}#The resource is added to random_state
PREV Targets the previous scope
FRA = {
	random_country = {
		GER = {
			declare_war_on = {
				target = PREV
				type = annex_everything
			}
		}
	}
} #Germany declares war on random_country

FROM In decisions, this scopes to the target of a target trigger decision

In events, this scopes to the tag that sent you this event, if applicable (i.e. if Germany sends an event to Italy)

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

FROM and PREV can be chained together to go back multiple scopes by adding more of them after each other after a . - e.g. FROM.FROM or PREV.PREV.PREV. In this example of chaining these links, two arms factories are built in two random states of a random country, and PREV.PREV is used to ensure the second state is not the same as the first state.

random_country = { #1st scope [1]
    random_owned_state = { # 2nd scope [1,2]
        add_extra_state_shared_building_slots = 2
        add_building_construction = {
            type = arms_factory
            level = 2
            instant_build = yes
        }
        PREV = { #from random_owned_state(#2nd) to random_country(#1st). [1,2,1]
            random_owned_state = { #new second scope [1,2_old,1,2_new]
                limit = { NOT = { state = PREV.PREV } } # The first PREV scopes back to the country, the second scopes back to the first random state <Value:1,2_old,̶1̶,̶̶̶2̶̶̶_̶̶̶n̶̶̶e̶̶̶w>
                add_extra_state_shared_building_slots = 2 #Note: We used PREV.PREV to get a value, but didn't actually enter that scope. [1,2_old,1,2_new]
                add_building_construction = {
                    type = arms_factory
                    level = 2
                    instant_build = yes
                }
            }
        }
    }
}

References[edit]