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

Most of them, besides the last form (random_<name>) and other small exceptions, have the option to override tooltip title. You can use tooltip = key to change it. Example:

any_neighbor_country = {
	tooltip = my_loc_string #custom title text
	… #other triggers to check
}

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
TAG Country tag scope. <SOV> = { … } Anywhere Country 1.0
OVERLORD Master of this subject. every_enemy_country = {
    OVERLORD = { … }
}
Country/ies Country 1.3
all_country Check if all countries meets the trigger. all_country = { … } X Anywhere Country/ies 1.0
any_country Check if any country meets the trigger. any_country = { … } X Anywhere Country 1.0
any_other_country Check if any other country (not including the current scope) meets the trigger. any_other_country = { … } X Country Country 1.0
all_country_with_original_tag Check if all countries with current scope's original tag meets the trigger. all_country_with_original_tag = {
    original_tag_to_check = <TAG> #check all countries that has this original tag
    … # other triggers to check
}
X Anywhere Country/ies 1.9
any_country_with_original_tag Check if any country with current scope's original tag meets the trigger. any_country_with_original_tag = {
    original_tag_to_check = <TAG> #check all countries that has this original tag
    … #other triggers to check
}
X Anywhere Country 1.9
all_neighbor_country Check if all neighbor countries meet the trigger. all_neighbor_country = { … } X Country Country/ies 1.0
any_neighbor_country Check if any neighbor country meets the trigger. any_neighbor_country = { … } X Country Country 1.0
any_home_area_neighbor_country Check if any neighbor country in the home area (cored states) meets the trigger. any_home_area_neighbor_country = { … } X Country Country 1.0
all_guaranteed_country Check if every country with current scoped country guarantees meets the trigger. all_guaranteed_country = { … } X Country Country/ies 1.9
any_guaranteed_country Check if any country with current scoped country guarantees meets the trigger. any_guaranteed_country = { … } X Country Country 1.9
all_allied_country Check if all allied countries meet the trigger. Does not include the country itself. all_allied_country = { … } X Country Country/ies 1.9
any_allied_country Check if any allied country meets the trigger. Does not include the country itself. any_allied_country = { … } X Country Country 1.9
all_occupied_country Check if all occupied countries meets the trigger. all_occupied_country = { … } X Country Country/ies 1.9
any_occupied_country Check if any occupied country meets the trigger. any_occupied_country = { … } X Country Country 1.9
all_enemy_country Check if all enemy countries meet the trigger. all_enemy_country = { … } X Country Country/ies 1.0
any_enemy_country Check if any enemy country meets the trigger. any_enemy_country = { … } X Country Country 1.0
every_country Executes children effects on every country that fulfills the "limit" trigger. every_country = { … } X Anywhere Country/ies 1.0
every_country_with_original_tag Executes children effects on all countries with original tag. every_country_with_original_tag = {
    original_tag_to_check = <TAG> #the effect will only run on countries that has this original tag
    limit = { … } #a limit can be defined to limit scopes
    … #effects to execute
}
X Anywhere Country/ies 1.9
random_country Executes children effects on random country that fulfills the "limit" trigger. random_country = { … } X Anywhere Country 1.0
random_country_with_original_tag Executes children effects on a random country with original tag. random_country_with_original_tag = {
    original_tag_to_check = <TAG> #the effect will only run on countries that has this original tag
    limit = { … } #a limit can be defined to limit scopes
    … #effects to execute
}
X Anywhere Country 1.9
every_other_country Executes children effects on every other country that fulfills the "limit" trigger. Excludes current country. every_other_country = { … } X Country Country/ies 1.0
every_neighbor_country Executes children effects on every neighbor country that fulfills the "limit" trigger. every_neighbor_country = { … } X Country Country/ies 1.0
random_neighbor_country Executes children effects on random neighbor country that fulfills the "limit" trigger. random_neighbor_country = { … } X Country Country 1.0
every_occupied_country Executes children effects on every occupied country that fulfills the "limit" trigger. every_occupied_country = { … } X Country Country/ies 1.9
random_occupied_country Executes children effects on random occupied country that fulfills the "limit" trigger. random_occupied_country = { … } X Country Country 1.9
every_enemy_country Executes children effects on every enemy country that fulfills the "limit" trigger. every_enemy_country = { … } X Country Country/ies 1.0
random_enemy_country Executes children effects on random enemy country that fulfills the "limit" trigger. random_enemy_country = { … } X Country Country 1.0
faction_leader Faction leader of the faction the country is a part of. faction_leader = { … } Country Country 1.10.1
state_id State ID scope. 145 = { … } Anywhere State 1.0
owner Owner of the state. owner = { … } State Country 1.0
controller Controller of the state. controller = { … } State Country 1.0
capital_scope Capital state of the current country. capital_scope = { … } Country State 1.0
any_state Check if any state meets the trigger. any_state = { … } X Anywhere State 1.0
all_state Check if all states meets the trigger. all_state = { … } X Anywhere State/s 1.0
any_neighbor_state Check if any neighbor state meets the trigger. any_neighbor_state = { … } X State State 1.0
all_neighbor_state Check if all neighbor states meets the trigger. all_neighbor_state = { … } X State State/s 1.0
any_owned_state Check if any owned state meets the trigger. any_owned_state = { … } X Country State 1.0
all_owned_state Check if all owned states meets the trigger. all_owned_state = { … } X Country State/s 1.0
any_controlled_state Check if any of the states controlled by the scope country meets the trigger. any_controlled_state = { … } X Country State 1.9
all_controlled_state Check if all of the states controlled by the scope country meets the trigger. all_controlled_state = { … } X Country State/s 1.9
every_state Executes children effects on every state, that fulfills the "limit" trigger. every_state = { … } X State State/s 1.0
random_state Executes children effects on a random state that fulfills the "limit" trigger. random_state = {
    prioritize = { <stateID> <stateID> } #to pick those states first if they fulfill the limit
    … #effects to execute
}
X Anywhere State 1.0
every_neighbor_state Executes children effects on every neighbor state that fulfills the "limit" trigger. every_neighbor_state = { … } X State State/s 1.0
random_neighbor_state Executes children effects on random neighbor state that fulfills the "limit" trigger. random_neighbor_state = { … } X State State 1.0
every_owned_state Executes children effects on every owned state that fulfills the "limit" trigger. every_owned_state = { … } X Country State/s 1.0
random_owned_state Executes children effects on random owned state that fulfills the "limit" trigger. random_owned_state = {
    prioritize = { <stateID> <stateID> } #to pick those states first if they fulfill the limit
    … #effects to execute
}
X Country State 1.0
every_controlled_state Executes children effects on every controlled state that fulfills the "limit" trigger. every_controlled_state = { … } X Country State/s 1.9
random_controlled_state Executes children effects on random controlled state that fulfills the "limit" trigger. random_controlled_state = {
    prioritize = { <stateID> <stateID> } #to pick those states first if they fulfill the limit
    … #effects to execute
}
X Country State 1.9
random_owned_controlled_state Executes children effects on random owned and controlled state that fulfills the "limit" trigger. random_owned_controlled_state = {
    prioritize = { <stateID> <stateID> } #to pick those states first if they fulfill the limit
    … #effects to execute
}
X Country State 1.3
all_unit_leader Check if all unit leaders meets the trigger. all_unit_leader = { … } X Country Unit Leader/s 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 unit leaders meets the trigger. all_army_leader = { … } X Country Unit Leader/s 1.5
any_army_leader Check if any unit leader meets the trigger. any_army_leader = { … } X Country Unit Leader 1.5
all_navy_leader Check if all unit leaders meets the trigger. all_navy_leader = { … } X Country Unit Leader/s 1.5
any_navy_leader Check if any unit leader meets the trigger. any_navy_leader = { … } X Country Unit Leader 1.5
every_unit_leader Executes children effects on unit leaders that fulfills the "limit" trigger. every_unit_leader = { … } X Country Unit Leader/s 1.5
random_unit_leader Executes children effects on random unit leader that fulfills the "limit" trigger. random_unit_leader = { … } X Country Unit Leader 1.5
global_every_army_leader Executes children effects on army leaders for every country in the world that fulfills the "limit" trigger. Better to use every_army_leader if you know the country. global_every_army_leader = { … } X Country Unit Leader/s 1.5
every_army_leader Executes children effects on army leaders that fulfills the "limit" trigger. every_unit_leader = { … } X Country Unit Leader/s 1.5
random_army_leader Executes children effects on random army leader that fulfills the "limit" trigger. random_army_leader = { … } X Country Unit Leader 1.5
every_navy_leader Executes children effects on navy leaders that fulfills the "limit" trigger. every_navy_leader = { … } X Country Unit Leader/s 1.5
random_navy_leader Executes children effects on random navy leader that fulfills the "limit" trigger. random_navy_leader = { … } X Country Unit Leader 1.5
all_operative_leader Check if all operatives meets the trigger. all_operative_leader = { … } X Country/Operation Operatives 1.9
any_operative_leader Check if any operatives meets the trigger. any_operative_leader = { … } X Country/Operation Operative 1.9
every_operative Executes children effects on operatives that fulfills the "limit" trigger. every_operative = { … } X Country/Operation Operative/s 1.9
random_operative Executes children effects on a random operatives that fulfills the "limit" trigger. 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
}

Note that in trigger scopes, such as all_country or any_state, limit = {} is not directly supported. Instead, if = {} can be used.

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]