Scopes

From Europa Universalis 4 Wiki
Jump to navigation Jump to search

A scope is the context that conditions and commands are used in.

Overview[edit]

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[edit]

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 is useful for effects and triggers when you want to point to a scope that isn't the ROOT scope without more scope switching.

Logic scopes[edit]

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 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[edit]

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[edit]

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[edit]

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[edit]

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[edit]

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[edit]

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[edit]

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

Trade node[edit]

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[edit]

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[edit]

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 valid countries that meet the triggers in the limit. 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 = { } Scopes to all valid countries that meet the triggers in the limit. Yes Country 1.1
every_neighbor_country every_neighbor_country = { } Scopes to all countries that share a border (or sea zone?) with the current scope. Yes Country 1.1
every_rival_country every_rival_country = { } Scopes to all valid countries that meet the triggers in the limit. 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 valid country that meet the triggers in the limit. No Country 1.1
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 = { } Scopes to one valid country that meet the triggers in the limit. No Country 1.1
random_neighbor_country random_neighbor_country = { } Scopes to one random country that shares a border (or sea zone?) with the current scope. No Country 1.1
random_rival_country random_rival_country = { } Scopes to one valid country that meet the triggers in the limit. 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.
You can use type = all to scope to all valid areas.
No Province 1.18
random_owned_province random_owned_province = { } Scopes to one random province the current scope owns. No Province 1.1
every_trade_node every_trade_node = { } Scopes to all trade nodes. Yes 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

Province[edit]

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 border (or sea zone?) 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 border (or sea zone?) 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 (area?). No Province 1.20
random_empty_neighbor_province random_empty_neighbor_province = { } Scopes to one random province sharing a border (or sea zone?) 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 border(or sea zone?) 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
every_empty_neighbor_province every_empty_neighbor_province = { } Scopes to all provinces sharing a border (or sea zone?) with the current scope that are colonizable and uncolonized. No Province 1.1

Tradenode[edit]

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[edit]

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[edit]

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[edit]

Country[edit]

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 valid countries that meet the triggers. 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 = { } Scopes to all valid countries that meet the triggers. Yes Country 1.1
all_neighbor_country all_neighbor_country = { } Scopes to all countries that own a province that shares a border (or sea zone?) with a province owned by the current scope. Yes Country 1.1
all_rival_country all_rival_country = { } Scopes to all valid countries that meet the triggers. 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 valid country that meet the triggers. 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 = { } Scopes to one valid country that meet the triggers. No Country 1.1
any_neighbor_country any_neighbor_country = { } Scopes to one country sharing a border (or sea zone?) with the current scope. No Country 1.1
any_rival_country any_rival_country = { } Scopes to one valid country that meet the triggers. 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_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[edit]

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 border (or sea zone?) 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 border (or sea zone?) with the current scope. Yes Province 1.1
all_empty_neighbor_province all_empty_neighbor_province = { } Scopes to all provinces sharing a border (or sea zone?) with the current scope that are colonizable and uncolonized. Yes Province 1.1
any_empty_neighbor_province any_empty_neighbor_province = { } Scopes to one province sharing a border (or sea zone?) 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 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 (or sea zone?) 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. No Country 1.1
any_core_country any_core_country = { } Scopes to all countries that have a core on the current scope, whether existing or not. No Country 1.1

Trade node[edit]

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[edit]

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

References[edit]

Documentation EffectsTriggersModifiersScopesVariablesLocalisationCustomizable localization
Scripting AdvisorsAgesBookmarksBuildingsCasus belliColonial regionsCountriesCultureDecisionsDefinesDiplomatic actionsDisastersEstatesEventsFactionsGovernmentGreat projectsHistoryIdea groupsInstitutionsMissionsModifiersNation designerPoliciesReligionRebel typesSubject typesTechnologyTrade companiesTrade goodsUnits
Map MapRandom New WorldTrade nodes
Graphics 3D ModelsInterfaceGraphical AssetsFontsParticlesShadersUnit models
Audio MusicSound
Other Console commandsChecksumJoroDox mod making toolMod structureTroubleshootingThe Validator
Guides Adding a province