Scopes

A scope is the context that triggers and effects are used in.

Overview

All script scopes operate on one of two internal scopes: country and province. Scopes that are for a country scope will not function correctly when used in a province scope.

Additionally, all script scopes operate in one of two type scopes: effect and trigger. Using an effect scope within a trigger scope will not work, and vice versa. There are scopes that operate in both type scopes.

Which base scopes are effect and which are trigger depends on the feature you are modding. For example, in a decision: potential = { } and allow = { } are trigger scopes, whereas effect = { } is an effect scope. This is normally self-evident in most cases.

Dynamic scopes

Four script scopes are unique in that they change their contents depending on where they are used. They can be used in both effect and trigger scopes.

Scope	Description	Example	Notes
ROOT	The base scope.	The ROOT scope in a country event is the country that the event fires for.
FROM	The calling scope.	The FROM scope in a country event would be the ROOT scope of another event that called it (via the country_event = {} effect).
PREV	The previous scope.	If you change the scope to FRA = { } and then to change scope to capital_scope = { } within it, the PREV scope is FRA = { }.
THIS	The current scope.	If you change scope to FRA = { } and then the THIS scope is FRA = { } whilst used within the FRA = { } scope.	This only works as a target for an effect. Effects placed within a THIS scope will not work correctly.

Logic scopes

There are three trigger scopes used to alter the boolean value of a trigger, or set of triggers. They are AND, OR and NOT.

The AND scope groups a set of triggers together, and returns true only if all triggers nested within return true as well. This scope is the default scope for all trigger scopes, so you don't need to explicitly use a AND scope most of the time.

AND = {
    tag = FRA
    stability = 1
}

The OR scope splits multiple sets of triggers, returning true if one or more of the sets of triggers nested within return true. This scope is used to make triggers return valid on state 1 or state 2 or state 3, and so on. Often the AND scope is used within the group multiple triggers together.

stability = 1
OR = {
    tag = FRA
    tag = CAS
}

The NOT scope inverts the truth value of a returned trigger. This allows you to check for the opposite instance of all triggers without needing an different trigger to do so. It also reverses the x or greater behaviour with numbers in triggers, making it less than x.

NOT = { stability = 1 }    # Returns true when stability is less than 1

There is no "implication" scope. If you need to express one (e.g. P → Q, "if P then Q"), use the logical equivalent with OR and negation instead (¬P ∨ Q, "(not P) or Q"). For example, the game encodes one of the conditions for using various religious CBs - "If Art of War is active and attacker and defender are both members of the Holy Roman Empire: the Peace of Westphalia has not occurred" - as something like the following:

OR = {
    NOT = { has_dlc = "Art of War" }
    is_part_of_hre = no
    FROM = { is_part_of_hre = no }
    hre_religion_treaty = no
}

Subscopes

Many scopes return multiple subscopes. For example, every_owned_province = { } returns every owned province scope. This means any effect within this scope is executed in every province subscope. Likewise for trigger scopes, just with comparison instead.

A quick reference on which scopes operate in this way:

Scope Prefix	Type	Description
all_<scope>	Trigger	Requires valid trigger matches for all subscopes.
any_<scope>	Trigger	Requires valid trigger matches for one subscope in the set.
every_<scope>	Effect	Applies effects to all subscopes.
random_<scope>	Effect	Applies effects to one random subscope.

Limit scope

For all effect scopes, you can nest a limit = { } to filter the returned subscopes.

For example, the following returns subscopes of countries that have 3 Stability:

every_country = {
    limit = {
        stability = 3
    }
}

Trigger scopes are inherently used for filtering, so do not require a limit scope.

Tradenode scopes

Theoretically tradenode scopes are province scopes. However, in practice you need to be within a tradenode scope to use tradenode effect and trigger scopes.

This means you cannot do this:

ROOT = {
    every_privateering_country = {
    
    }
}

Rather, you need to do this:

ROOT = {
    random_active_trade_node = {
        every_privateering_country = {
            
        }
    }
}

Dual scopes

Dual scopes can be used in both effect and trigger contexts. However they operate differently in either context.

In an effect scope, a dual scope will act like every_<scope> and apply effects to all subscopes.

In an trigger scope, a dual scope will act like any_<scope> and match for one subscope in the set.

You can alter this for dual scopes that return more than one subscope by including the type = all line within the dual scope. This will make the dual scope match for all subscopes.

<region> = {
    
    type = all
}

Country and Province

Name	Example	Description	Multiple Subscopes	Changes Scope To	Version Added
<province id>	110 = { }	Refers to the province ids listed /Europa Universalis IV/map/definition.csv	No	Province	1.1
<tag>	FRA = { }	Refers to the country tags listed /Europa Universalis IV/common/country_tags	No	Country	1.1
<area>	western_mediterrenean_area = { }	Refers to any area found in /Europa Universalis IV/map/area.txt	Yes	Province	1.14
<region>	france_region = { }	Refers to any region found in /Europa Universalis IV/map/region.txt	Yes	Province	1.1
<superregion>	india_superregion = { }	Refers to any superregion found in /Europa Universalis IV/map/superregion.txt	Yes	Province	1.14 (1.15 for trigger)
<provincegroup>	my_prov_group = { }	Refers to any province group found in /Europa Universalis IV/map/provincegroup.txt	Yes	Province	1.14 (1.15 for trigger)
<continent>	europe = { }	Refers to any continent found in /Europa Universalis IV/map/continent.txt	Yes	Province	1.1
<trade_company>	trade_company_west_africa = { }	Refers to any trade company found in /Europa Universalis IV/common/trade_companies/	Yes	Province	1.6
<colonial_region>	colonial_alaska = { }	Refers to any colonial region found in /Europa Universalis IV/common/colonial_regions/	Yes	Province	1.4
<event_target>	event_target:my_event_target_name = { }	Refers to the saved event target scope. Potentially can be any scope internally.	Yes	Any	1.8
emperor	emperor = { }	Refers to the country (if it exists) that is currently the Holy Roman Emperor.	No	Country	1.1
revolution_target	revolution_target = { }	Refers to the country (if it exists) that is the current revolution target.	No	Country	1.1
crusade_target	crusade_target = { }	Refers to the country (if it exists) that is the current crusade target.	No	Country	1.1

Country

Name	Example	Description	Multiple Subscopes	Changes Scope To	Version Added
colonial_parent	colonial_parent = { }	Refers to the country (if it exists) that is the colonial parent of the current country scope.	No	Country	1.4
overlord	overlord = { }	Refers to the country (if it exists) that is the overlord of the current country scope.	No	Country	1.1
capital_scope	capital_scope = { }	Refers to the capital province of the current country scope.	No	Province	1.1

Province

Name	Example	Description	Multiple Subscopes	Changes Scope To	Version Added
owner	owner = { }	Refers to the country that owns the current province scope.	No	Country	1.1
controller	controller = { }	Refers to the country that controls the current province scope.	No	Country	1.1
sea_zone	sea_zone = { }	Refers to the sea province on which the current land province scope has a port.	No	Province	1.1

Trade node

Name	Example	Description	Multiple Subscopes	Changes Scope To	Version Added
most_province_trade_power	most_province_trade_power = { }	The country in the trade node that generates the most trade power from provinces.	No	Country	1.1
strongest_trade_power	strongest_trade_power = { }	The country with the most trade power in the node.	No	Country	1.1

Effect scopes

All effect scopes that potentially match multiple subscopes, plus if, can be limited with the limit = { } scope within. For example:

every_country = { 
    limit = {
        <triggers>
    }
    <effects>
}

Scopes that choose one random subscope (e.g. random_owned_province) make their choice after applying the limit.

Country

Used within the country scopes--e.g., FRA = { }

Name	Example	Description	Multiple Subscopes	Changes Scope To	Version Added
every_ally	every_ally = { }	Scopes to all valid countries that meet the triggers in the limit.	Yes	Country	1.1
every_coalition_member	every_coalition_member = { }	Scopes to all members of the coalition against the current scope (if any).	Yes	Country	1.1
every_country	every_country = { }	Scopes to all countries in the world. Avoid this if you can use something more specific.	Yes	Country	1.1
every_elector	every_elector = { }	Scopes to all electors of the HRE.	Yes	Country	1.1
every_enemy_country	every_enemy_country = { }	Scopes to all countries that have rivalled the current scope.	Yes	Country	1.1
every_known_country	every_known_country = { }	Scopes to all countries that have been discovered by the current scope.	Yes	Country	1.1
every_local_enemy	every_local_enemy = { }	???	Yes	Country	1.1
every_neighbor_country	every_neighbor_country = { }	Scopes to all countries that share a land/strait border with the current scope.	Yes	Country	1.1
every_rival_country	every_rival_country = { }	Scopes to all countries that the current scope has rivalled.	Yes	Country	1.1
every_subject_country	every_subject_country = { }	Scopes to all subject nations under the current scope.	Yes	Country	1.4
random_ally	random_ally = { }	Scopes to one valid country that meet the triggers in the limit.	No	Country	1.1
random_coalition_member	random_coalition_member = { }	Scopes to one random member of the coalition against the current scope.	No	Country	1.1
random_country	random_country = { }	Scopes to one random country among all countries in the world. Avoid this if you can use something more specific.	No	Country	1.1
random_elector	random_elector = { }	Scopes to one random elector of the HRE.	No	Country	1.1
random_enemy_country	random_enemy_country = { }	Scopes to one country that has rivalled the current scope.	No	Country	1.1
random_hired_mercenary_company	random_hired_mercenary_company = { } Possible parameters: template = <string> Optional: Checks whether the mercenary company uses the specified template. is_foreign_company = yes Optional: Checks whether the mercenary company is of foreign origin. hired_for_months = <int> Optional: Checks how long the mercenary company has been hired. has_company_manpower = <int> Optional: Checks whether the company has X% of its manpower (can be negated by NOT = { }). home_province = { } Optional: Scopes to the company's home province if existing. location = { } Optional: Scopes to the current province location of the company.	Scopes to one random mercenary companies currently hired by the current scope.	No	Unit	1.30
random_known_country	random_known_country = { }	Scopes to one random country that has been discovered by the current scope.	No	Country	1.1
random_local_enemy	random_local_enemy = { }	???	No	Country	1.1
random_neighbor_country	random_neighbor_country = { }	Scopes to one random country that shares a land/strait border with the current scope.	No	Country	1.1
random_rival_country	random_rival_country = { }	Scopes to one country that the current scope has rivalled.	No	Country	1.1
random_subject_country	random_subject_country = { }	Scopes to one random subject country under the current scope.	No	Country	1.4
every_core_province	every_core_province = { }	Scopes to all provinces that this country has a core on, whether owned or not.	Yes	Province	1.1
every_heretic_province	every_heretic_province = { }	Scopes to all provinces whose religion is heretic to the current scope.	Yes	Province	1.1
every_owned_province	every_owned_province = { }	Scopes to all provinces the current scope owns.	Yes	Province	1.1
every_province	every_province = { }	Scopes to all provinces in the world. Note: executing effects on every province without a limit will cause slowdown in game. Use something more specific if you can.	Yes	Province	1.1
random_core_province	random_core_province = { }	Scopes to one random province that the current scope has a core on, whether owned or not.	No	Province	1.1
random_heretic_province	random_heretic_province = { }	Scopes to one random province whose religion is heretic to the current scope.	No	Province	1.1
random_owned_area	random_owned_area = { }	Scopes to one valid area that meet the triggers in the limit.	No	Province	1.18
random_owned_province	random_owned_province = { }	Scopes to one random province the current scope owns.	No	Province	1.1
random_active_trade_node	random_active_trade_node = { }	Scopes to one valid tradenode (province) that meet the triggers in the limit. Active means the current scope is interacting with the trade node in some way.	No	Province	1.18
random_trade_node	random_trade_node = { }	Scopes to one random trade node.	No	Province	1.1
home_trade_node_effect_scope	home_trade_node_effect_scope = { }	Scopes to the trade node where the country has its main trading port.	No	Province

Province

Used within the province scopes--e.g., capital_scope = { }. These generally only select land provinces.

Name	Example	Description	Multiple Subscopes	Changes Scope To	Version Added
every_empty_neighbor_province	every_empty_neighbor_province = { }	Scopes to all provinces sharing a land/strait border with the current scope that are colonizable and uncolonized.	No	Province	1.1
every_neighbor_province	every_neighbor_province = { }	Scopes to all provinces sharing a land/strait border with the current scope. Does not include empty provinces.	No	Province	1.1
every_province_in_state	every_province_in_state = { }	Scopes to all provinces in the same state (Does not apply to provinces in territories, if you want to apply in territories, then use area = { limit = { owned_by = ROOT } ... }).	No	Province	1.20
random_empty_neighbor_province	random_empty_neighbor_province = { }	Scopes to one random province sharing a land/strait border with the current scope that is colonizable and uncolonized.	No	Province	1.1
random_neighbor_province	random_neighbor_province = { }	Scopes to one random province sharing a land/strait border with the current scope. Does not include empty provinces.	No	Province	1.1
random_province_in_state	random_province_in_state = { }	Scopes to one random province in the same state as the current scope.	No	Province	1.20
random_province	random_province = { }	Scopes to one random province among all provinces in the world.	No	Province	1.1
every_core_country	every_core_country = { }	Scopes to all countries that have a core on the current scope, whether existing or not.	Yes	Country	1.1
random_core_country	random_core_country = { }	Scopes to one random country that has a core on the current scope, whether existing or not.	No	Country	1.1
area	area = { }	Refers to all provinces in the area that the current province scope is in.	Yes	Province	1.14
region	region = { }	Refers to all provinces in the region that the current province scope is in.	Yes	Province	1.14

Tradenode

Used within the tradenode scopes--e.g., random_active_trade_node = { }

Name	Example	Description	Multiple Subscopes	Changes Scope To	Version Added
every_privateering_country	every_privateering_country = { }	Scopes to all countries that are sending privateers to the current scope.	Yes	Country	1.6
random_privateering_country	random_privateering_country = { }	Scopes to one random country that is sending privateers to the current scope.	No	Country	1.6
every_trade_node_member_country	every_trade_node_member_country = { }	Scopes to all countries that own a province in the current scope.	Yes	Country	1.1
random_trade_node_member_country	random_trade_node_member_country = { }	Scopes to one random country that owns a province in the current scope.	No	Country	1.1
every_trade_node_member_province	every_trade_node_member_province = { }	Scopes to all provinces in the current trade node.	Yes	Province	1.1
random_trade_node_member_province	random_trade_node_member_province = { }	Scopes to one random province in the current trade node.	No	Province	1.1

Unit

Used within the unit scopes.

Name	Example	Description	Multiple Subscopes	Changes Scope To	Version Added
unit_owner	unit_owner = { }	Returns the unit's owner country scope. Usable from on_battle_won_unit and on_battle_lost_unit on actions.	No	Country	1.1

Missions

Only available in missions found in /Europa Universalis IV/missions.

Name	Example	Description	Multiple Subscopes	Changes Scope To	Version Added
every_target_province	every_target_province = { }	Scopes to all provinces among those specified as targets in the mission.	Yes	Province	1.1
random_target_province	random_target_province = { }	Scopes to one random province among those specified as targets in the mission.	No	Province	1.1

Trigger scopes

Country

Used within the country scopes--e.g., FRA = { }

Name	Example	Description	Multiple Subscopes	Changes Scope To	Version Added
any_army	any_army = { }	Scopes to all armies currently fielded by the current scope.	No	Unit	1.1
all_ally	all_ally = { }	Scopes to all valid countries that meet the triggers.	Yes	Country	1.1
all_coalition_member	all_coalition_member = { }	Scopes to all members of the coalition against the current scope (if any).	Yes	Country	1.1
all_country	all_country = { }	Scopes to all countries in the world excluding your own country. Avoid this if you can use something more specific.	Yes	Country	1.1
all_countries_including_self	all_countries_including_self = { }	Scopes to all countries in the world including your own country. Avoid this if you can use something more specific.	Yes	Country	1.26
all_elector	all_elector = { }	Scopes to all electors of the HRE	Yes	Country	1.1
all_enemy_country	all_enemy_country = { }	Scopes to all countries that have rivalled the current scope.	Yes	Country	1.1
all_known_country	all_known_country = { }	Scopes to all countries that have been discovered by the current scope.	Yes	Country	1.1
all_local_enemy	all_local_enemy = { }	???	Yes	Country	1.1
all_neighbor_country	all_neighbor_country = { }	Scopes to all countries that own a province that shares a land/strait border with a province owned by the current scope.	Yes	Country	1.1
all_rival_country	all_rival_country = { }	Scopes to all countries that the current scope has rivalled.	Yes	Country	1.1
all_subject_country	all_subject_country = { }	Scopes to all subject countries under the current scope.	Yes	Country	1.4
all_core_province	all_core_province = { }	Scopes to all provinces that the current scope has a core on, whether owned or not.	Yes	Province	1.1
all_heretic_province	all_heretic_province = { }	Scopes to all provinces whose religion is heretic to the current scope.	Yes	Province	1.1
all_owned_province	all_owned_province = { }	Scopes to all provinces owned by the current scope.	Yes	Province	1.1
all_province	all_province = { }	Scopes to all provinces in the world. Avoid this if you can use something more specific.	Yes	Province	1.1
all_state_province	all_state_province = { }	Scopes to all provinces in states of the current scope.	Yes	Province	1.20
all_states	all_states = { }	Scopes to all states of the current scope.	Yes	Province	1.20
all_active_trade_node	all_active_trade_node = { }	Scopes to all active trade nodes.	Yes	Province	1.18
all_trade_node	all_trade_node = { }	Scopes to all trade nodes.	Yes	Province	1.1
any_ally	any_ally = { }	Scopes to one valid country that meet the triggers.	No	Country	1.1
any_coalition_member	any_coalition_member = { }	Scopes to one member of the coalition against the current scope.	No	Country	1.1
any_country	any_country = { }	Scopes to one country among all countries in the world. Avoid this if you can use something more specific.	No	Country	1.1
any_elector	any_elector = { }	Scopes to one elector of the HRE.	No	Country	1.1
any_enemy_country	any_enemy_country = { }	Scopes to one country that has rivalled the current scope.	No	Country	1.1
any_known_country	any_known_country = { }	Scopes to one country that has been discovered by the current scope.	No	Country	1.1
any_local_enemy	any_local_enemy = { }	???	No	Country	1.1
any_neighbor_country	any_neighbor_country = { }	Scopes to one country sharing a land/strait border with the current scope.	No	Country	1.1
any_rival_country	any_rival_country = { }	Scopes to one country that the current scope has rivalled.	No	Country	1.1
any_subject_country	any_subject_country = { }	Scopes to one subject country under the current scope.	No	Country	1.4
any_core_province	any_core_province = { }	Scopes to one province that the current scope has a core on, whether owned or not.	No	Province	1.1
any_heretic_province	any_heretic_province = { }	Scopes to one province whose religion is heretic to the current scope.	No	Province	1.1
any_hired_mercenary_company	any_hired_mercenary_company = { } Possible parameters: template = <string> Optional: Checks whether the mercenary company uses the specified template. is_foreign_company = yes Optional: Checks whether the mercenary company is of foreign origin. hired_for_months = <int> Optional: Checks how long the mercenary company has been hired. has_company_manpower = <int> Optional: Checks whether the company has X% of its manpower (can be negated by NOT = { }). home_province = { } Optional: Scopes to the company's home province if existing. location = { } Optional: Scopes to the current province location of the company.	Scopes to one mercenary companies currently hired by the current scope.	No	Unit	1.30
any_owned_province	any_owned_province = { }	Scopes to one province owned by the current scope.	No	Province	1.1
any_province	any_province = { }	Scopes to one province from among all provinces in the world. Avoid this if you can use something more specific.	No	Province	1.1
any_state	any_state = { }	Scopes to one state of the current country.	No	Province	1.20
any_active_trade_node	any_active_trade_node = { }	Scopes to one valid tradenode (province) that meet the triggers. Note: will return true if a merchant is placed, even without explicit triggers.	No	Province	1.18
any_trade_node	any_trade_node = { }	Scopes to one trade node among all trade nodes in the world.	No	Province	1.1
home_trade_node	home_trade_node = { }	Scopes to the trade node containing the current scope's main trade port.	No	Province	1.1

Province

Used within the province scopes—e.g., capital_scope = { }

Name	Example	Description	Multiple Subscopes	Changes Scope To	Version Added
all_empty_neighbor_province	all_empty_neighbor_province = { }	Scopes to all provinces sharing a land/strait border with the current scope that are colonizable and uncolonized.	Yes	Province	1.1
all_province_in_state	all_province_in_state = { }	Scopes to all provinces in the same state as the current scope.	Yes	Province	1.20
all_neighbor_province	all_neighbor_province = { }	Scopes to all provinces sharing a land/strait border with the current scope.	Yes	Province	1.1
any_empty_neighbor_province	any_empty_neighbor_province = { }	Scopes to one province sharing a land/strait border with the current scope that is colonizable and uncolonized.	No	Province	1.1
any_province	any_province = { }	Scopes to one province among all provinces in the world. Avoid this if you can use something more specific.	No	Province	1.1
any_province_in_state	any_province_in_state = { }	Scopes to one province in the same state as the current scope.	No	Province	1.20
any_friendly_coast_border_province	any_friendly_coast_border_province = { }	Scopes to one province that shares a border or sea zone with the current scope that is friendly to the current scope (meaning its owner is the same or has positive relations).	No	Province	1.18
any_neighbor_province	any_neighbor_province = { }	Scopes to one province that shares a border with the current scope.	No	Province	1.1
all_core_country	all_core_country = { }	Scopes to all countries that have a core on the current scope, whether existing or not.	Yes	Country	1.1
any_core_country	any_core_country = { }	Scopes to one country that has a core on the current scope, whether existing or not.	No	Country	1.1
area_for_scope_province	area_for_scope_province = { }	Scopes to the area that the current province scope is in.	No	Province	1.14
region_for_scope_province	region_for_scope_province = { }	Scopes to the region that the current province scope is in.	No	Province	1.14

Trade node

Used within the trade node scopes—e.g., any_active_trade_node = { }

Name	Example	Description	Multiple Subscopes	Changes Scope To	Version Added
all_privateering_country	all_privateering_country = { }	Scopes to all countries that are sending privateers to the current scope.	Yes	Country	1.6
all_trade_node_member_country	all_trade_node_member_country = { }	Scopes to all countries that own a province in the current trade node.	Yes	Country	1.1
any_privateering_country	any_privateering_country = { }	Scopes to one country that is sending privateers to the current scope.	Yes	Country	1.6
any_trade_node_member_country	any_trade_node_member_country = { }	Scopes to one country that owns a province in the current trade node.	Yes	Country	1.1
all_trade_node_member_province	all_trade_node_member_province = { }	Scopes to all provinces in the current trade node.	No	Province	1.1
any_trade_node_member_province	any_trade_node_member_province = { }	Scopes to one province in the current trade node.	No	Province	1.1

Missions

Only available in missions found in /Europa Universalis IV/missions.

Name	Example	Description	Multiple Subscopes	Changes Scope To	Version Added
all_target_province	all_target_province = { }	Scopes to all provinces specified as a target in the mission.	Yes	Province	1.1
any_target_province	any_target_province = { }	Scopes to one province specified as a target in the mission.	Yes	Province	1.1

Removed scopes

Name	Example	Description	Version Removed	Alternatives
every_trade_node	every_trade_node = { }	Scopes to all trade nodes.	1.30	Province group of one trade node member each, or loop with random_trade_node

References

Modding

Audio

Music • Sound

Guides

Adding a province • Save-game editing