Scopes

From Crusader Kings II Wiki
Jump to: navigation, search

Scopes are used in scripting to 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 (create_character, ...).

There are only 6 types of scope: characters, titles, provinces, wars, sieges, and units. Note that there is also a special portrait scope used for portrait rendering rules.

Scopes can be nested (see scope chain), and are usually relative to the scope from which there are called, except for the ones that are global and can be called from "Any" scope.

Quickcard[edit]

The most import scopes are shown in this quickcard:

Scopes modding quickcard.png

Legend:

  • (!) CPU heavy, use with care
  • (scope) deprecated variant, rarely used in vanilla
  • * coming in some next patch[1]

List of scopes[edit]

Character[edit]

Character scopes are all scopes that target characters. Most scopes in the game are character scopes. The "from scope" column shows what scope(s) it can be called from.

Note that dead characters are special: they usually need one of the scopes with suffix _even_if_dead to be scoped to (ex: father_even_if_dead, and some scopes may not work inside a dead character scope.

Scope Used in vanilla Description Trigger Effect From scope
%trait_name% In a trigger scope, this scopes to all characters with given trait. In an effect scope, this scopes to a random character with the given trait. The given trait needs to have the flag cached = yes.
on_hajj = {
  NOT = {
    has_character_flag = hajj_arrived_in_mecca
    opinion = { who = ROOT value = 0 }
  }
}
Any
any_allied_character X Scopes to all allies. Expensive calculation, use with care[2] Character
any_attacker Scopes to all attackers in a war War
any_backed_character Scopes to all characters whose plots a character is supporting Character
any_character X Scopes to all characters. WARNING CPU HEAVY Any
any_child
any_child_even_if_dead
Scopes to all of a character's children Character
any_claimant Scopes to all claimants of a title Title
any_close_relative Scopes to all close relatives of a character. X Character
any_courtier Scopes to everyone in the character's court. Note that it will match prisoners (even if foreign) and councillors (even if landed). Character
any_current_enemy Scopes to all characters actively at war with a character. Both characters have to be participating directly in the war, not as vassals Character
any_de_jure_vassal Scopes to all de jure vassals of a character or title. X[3] Character, title
any_defender Scopes to all defenders in a war War
any_dynasty_member
any_dynasty_member_even_if_dead
Scopes to all members of a character's dynasty. Character
any_enemy_plotter X Character
any_faction_backer Scopes to faction members. Faction field can be used to specify faction (ex: faction = faction_lower_tribal_organization) Character
any_favor_holder X Scopes to all characters to which a character owes a favor Character
any_favor_ower Scopes to all characters that owe a favor to the character Character
any_friend Scopes to all of a character's friends Character
any_independent_ruler Scopes to all independent rulers currently alive. Excludes revolts. Doesn't include ROOT. Any
any_known_enemy_plotter X Character
any_known_plotter Scopes to any plotter character whose plot the character is scope knows about Character
any_liege Scopes to all lieges a character has, regardless of how many tiers above. This includes liege and top_liege scopes. Character
any_lover Scopes to all lovers a character has Character
any_non_aggression_pact_character Scopes to all characters to which someone has a non-aggression pact [?] Character
any_opinion_modifier_target Scopes to all characters having an opinion modifier toward scoped character
any_opinion_modifier_target = {
  limit = {
   reverse_has_opinion_modifier = {
     who = PREV
     modifier = opinion_spying_on
   }
  }
  reverse_remove_opinion = {
    who = PREV
    modifier = opinion_spying_on
  }
}
Character
any_playable_ruler Scopes to all playable rulers currently alive. Combined with limit = { ai = no }, it allows to broadcast events to human players. Any
any_plot_backer Scopes to everyone backing the character's plot Character
any_plotter Scopes to all plotters (anywhere?). Vanilla usage uses "target = ROOT" on the first line of the scope to limit the search. (?)
any_plotter = {
	target = ROOT
	limit = {
		OR = {
			has_plot = plot_kill_character
			has_plot = plot_kill_spouse
		}
	}
	character_event = { id = CM.6001 }
}
Character
any_previous_holder Scopes to previous holders of a title Title
any_province_character Scopes to all characters in the province Province
any_province_lord Scopes to all landed characters in the province Province
any_realm_character Scopes to all characters within the current character or title's sub-realm. Includes both vassals and courtiers, but not the liege of the realm. Character, title
any_realm_lord Scopes to all landed characters within the current character's realm. It doesn't include the liege of the realm. Character
any_rival Scopes to all of a character's rivals Character
any_sibling
any_sibling_even_if_dead
Scopes to all of a character's siblings Character
any_spouse
any_spouse_even_if_dead
Scopes to all of a character's spouses Character
any_consort Scopes to all of a character's consorts (not only concubines, works for both genders) Character
any_suzerain X Character
any_trade_post Scopes to all of a character's trade posts Character, Province?
any_unique_dynasty_vassal Scopes to vassals with different dynasties (excluding dynasty of scoped character). Character
any_unknown_enemy_plotter X Character
any_vassal Scopes to all direct vassals of a character or title. Does not include courtiers. To scope to all vassals (direct or not) consider using any_realm_character. Character, title
any_voter Scopes to all voters in a character's council [?] Character
any_ward Scopes to all of a character's wards Character
attacker Scopes to the aggressor in a war War
band_creator Scopes to the creator of a dynamic mercenary band. Title
best_crusade_claimant Scopes to the best claimant for that title in context of crusade Title
biggest_realm_size_relative Scopes to relatives with biggest realm size. Character
center_flank_leader Scopes to the central flank leader of an army Character
left_flank_leader Scopes to the left flank leader of an army Character
right_flank_leader Scopes to the right flank leader of an army Character
controller Scopes to the character controlling a barony. Rarely used, more generic scope owner being favored. Title (barony or county)
current_heir Scopes to the character's heir. This is the character who inherits the primary title, regardless if he is dynastic heir or not. Character
defender Scopes to the defender in a war War
dynasty_head Scopes to the head of the dynasty Character
educator Scopes to the educator of a child (Conclave DLC education) Character
employer Scopes to the character's employer Character
enemy Scopes to the enemy in a siege Siege
father
father_even_if_dead
Scopes to the character's father Character
father_of_unborn Scopes to the unborn child's father Character
guardian Scopes to the child's guardian Character
heir_under_seniority_law Scopes to the character who'd be heir if Seniority succession was enacted Title
heir_under_primogeniture_law Scopes to the character who'd be heir if Primogeniture succession was enacted Title
highest_ranked_relative Scopes to relatives with highest feudal tier Character
holder_scope Scopes to the owner of the province or title Title, province
host Scopes to the owner of where the character resides. Note: if same as employer, then character is residing at court. Character
killer Scopes to the killer of a character Character
leader Scopes to the leader of a force in a siege Siege
liege Scopes to a character's direct liege Character
liege_before_war Scopes to whoever was the character's liege before his rebellion Character
lover Scopes to the character's lover Character
mercenary_employer Character
most_participating_attacker Scopes to the attacker that's done the most in a war War
most_participating_crusader Scopes to the non-theocracy attacker that's done the most in a war [Verification needed] War
most_participating_defender Scopes to the defender that's done the most in a war War
most_popular_vassal Scopes to a the most popular vassal who meets its limit clause. Seems to use an average of opinion among all vassals (including mayors). Used to determine the new ruler when the "Oust ruler" faction is successful. [?] Character
most_prestigious_clan_vassal Character
mother Scopes to the character's mother Character
mother_even_if_dead Scopes to the character's mother, even if she's dead Character
new_character Scopes to the character previously created in the event, via create_character or similar command. X Any
owner Scopes to the owner of the province or title Title,Province
parent_religion_head Scopes to the religion head of the parent religion Character,Province
plot_target_char Scopes to the character that's being plotted against Character
preferred_war_target Scopes to the character's attack target Character
random_allied_character X Scopes to an ally X Character
random_backed_character Scopes to a random character the character is backing. Cannot be used as a trigger X Character
random_character X Scopes to all characters. Cannot be used as a trigger. Note: This scope doesn't apply commands to ROOT. X Any
random_child
random_child_even_if_dead
Scopes to a random child of the character. Cannot be used as a trigger X Character
random_courtier Scopes to a random courtier of the character, including prisoners. Cannot be used as a trigger X Character
random_current_enemy Scopes to a random enemy of the character. Both characters must be participating directly in the war, not as vassals. X Character
random_dynasty_member
random_dynasty_member_even_if_dead
Scopes to a random member of the character's dynasty. X Character
random_enemy_plotter X X Character
random_friend Scopes to a random friend of the character. X Character
random_independent_ruler Scopes to a random independent ruler. Doesn't include ROOT. X Any
random_known_enemy_plotter X X Character
random_lover Scopes to a random lover. X Character
random_non_aggression_pact_character Scopes to a random character with a non-aggression pact toward current character. X Character
random_opinion_modifier_target X Scopes to a random character with an opinion modifier toward scoped character X Character
random_playable_ruler Scopes to a random playable ruler. X Any
random_province_character Scopes to a random character in the province. X Province
random_province_lord Scopes to a random landed character in the province. X Province
random_realm_character Scopes to a random character in the character or title's realm. X Character, title
random_realm_lord Scopes to a random landed character in the character or title's realm. X Character, title
random_rival Scopes to a random rival of the character. X Character
random_sibling
random_sibling_even_if_dead
Scopes to a random sibling of the character. X Character
random_spouse
random_spouse_even_if_dead
Scopes to a random spouse of the character. X Character
random_consort Scopes to a random consort of the character (not only concubines, works for both genders). X Character
random_trade_post Scopes to a random trade post of the character or province. X Character, Province?
random_unknown_enemy_plotter X X Character
random_vassal Scopes to a random vassal of the character or title. X Character, title
random_voter X Scopes to a random voter on the council X Character
random_ward Scopes to a random ward of the character. X Character
real_father
real_father_even_if_dead
Scopes to the character's real father Character
reincarnation_scope Scopes to the character that currently scoped character is the reincarnation of Character
regent Scopes to the character's regent Character
religion_head Scopes to the character's religious head(s). Does NOT includes antipopes Character/Province
rightful_religious_head_scope Scopes to the character's rightful religious head. Includes antipopes Character
ruler Scopes to the province's owner. Rarely used, owner being preferred. Province
spouse Scopes to the character's primary spouse Character
spouse_even_if_dead Scopes to the character's primary spouse, even if dead Character
strongest_clan_vassal Character
supported_claimant Character
suzerain Scopes to the suzerain of a tributary character Character
top_liege Scopes to a character's independent liege Character
trade_post_owner Scopes to the owner of the trade post Province,Title
job_chancellor Scopes to the character's current Chancellor, if they have one. Character
job_marshal Scopes to the character's current Marshal, if they have one. Character
job_treasurer Scopes to the character's current Steward, if they have one. Beware, it's "treasurer", not "steward"! Character
job_spymaster Scopes to the character's current Spymaster, if they have one. Character
job_spiritual Scopes to the character's current Chaplain, if they have one. Character
title_to_get_rid_of Scopes to titles over the demesne limit Title

Title[edit]

Title scopes are all scopes that target titles.

Title scopes of baron tier are also referred as holding scopes, and certain triggers/commands will only work in holdings (E.g. add_building).

The "from scope" column shows what scope(s) it can be called from.

Scope Used in vanilla Description Trigger Effect From scope
%title_ID% Scopes to a title based on its id (starting with b_, c_, d_, k_, or e_).

For instance: e_byzantium = { }

Any
any_claim Scopes to all titles a character has claims upon Character
any_de_jure_vassal_title Scopes to all titles that are dejure part of a character or title's realm X[4] Character, title
any_direct_de_jure_vassal_title Scopes to all titles that are dejure part of a title's realm Title
any_demesne_title Scopes to all titles a character holds Character
any_heir_title Scopes to all titles of a character's heir (current_heir) Character
any_landed_title X Scopes to all landed titles. Warning CPU HEAVY Any
any_mercenary_band Scopes to all mercenary bands Any
any_potential_tribal_county X Character
any_pretender_title Scopes to all titles held by pretenders Character, title
any_province_holding Scopes to all holdings of a province* Province
any_realm_title Scopes to all titles within a character or title's realm X Character
any_title Scopes to all titles [Verification needed] Any
blood_brother Character
capital_holding Scopes to the character's capital holding title. Note: this is different from capital_scope which scopes to the capital province. Character, province
clan_title Scopes to the clan of a nomad. Character
county Scopes to the county a barony is in Province,Title (barony only)
crownlaw_title Scopes to the title giving a character or title its crown laws Character, title
crusade_target Scopes to the target of the ongoing crusade of the character's religion Character
defacto_liege_title Scopes to the title a title de facto belongs to [Verification needed] Title
dejure_liege_title Scopes to the title a character or title de jure belongs to Character, title
duchy Scopes to the duchy a barony or county belongs to Province,Title (barony or county)
empire Scopes to the empire a title belongs to Province,Title (any except empires)
family_palace Scopes to the family palace title of a patrician. Character
invasion_target X
kingdom Scopes to the kingdom a title belongs to Province,Title (duchy or below)
new_title X Scopes to the title previously created in the same scope via create_title command. X Any
plot_target_title Scopes to the title of the character the character is plotting against Character
primary_title Scopes to the character's primary title Character
random_claim Scopes to a random title the character has a claim upon. X Character
random_demesne_title Scopes to a random title the character holds. X Character
random_landed_title X Scopes to a random landed title X Any
random_potential_tribal_county Scopes to a county suitable for tribal takeover X Character
random_province_holding Scopes to a random holding of a province X Province
random_realm_title Scopes to a random title in realm. X Character
supported_claimant_title Character
realm Scopes to the independent realm the character or title is part of. It is the equivalent of top_liege for titles. Character, title
succ_law_title Scopes to a title where has_law trigger can be used to check succession law. Title
thirdparty_title_scope Only valid if thirdparty title is involved in the war War

Province[edit]

Province scopes are all scopes that target provinces. The "from scope" column shows what scope(s) it can be called from.

Scope Used in vanilla Description Trigger Effect From scope
%province_ID% Scopes to a province based on its id (number from 1 to (max_provinces - 1) where max_provinces is coded into map/default.map).

For instance: 290 = { # Uppland }

Any
any_demesne_province Scopes to all provinces in a character's demesne. ✓ (v2.6.1) Character
any_neighbor_province Scopes to all border provinces Province
any_province X Scopes to all provinces. WARNING CPU HEAVY Any
any_realm_province Scopes to all provinces in a character or title's realm Character, title
any_trade_route_province Scopes to all other provinces on a trade route [Verification needed] Province
capital_scope Scopes to the character's (or title's, if a capital has been defined in landed_titles definitions) capital province Character, Title
location Scopes to the character's location (or county title's province) Character, title
plot_target_province Scopes to the province that the character's plot is targeting Character
random_demesne_province Scopes to a random province in the character's demesne. X Character
random_neighbor_province Scopes to a random bordering province. Unlike any_neighbor_province, this does NOT scope to sea provinces! X Province
random_province X Scopes to a random province province X Any
random_realm_province Scopes to a random province in the character or title's realm. X Character, title
sea_zone Scopes to a sea province near currently scoped province Province

War[edit]

War scope allows to scope to on-going wars. There are very few trigger and effects available in war scope (using_cb , war_score, war_title, end_war, days_since_last_hostile_action).

Scope Used in vanilla Description Trigger Effect From scope
any_war Scopes to any war the character is participating in as an active member; a liege participating would not count.

When used in title scope, checks all wars for that title.

Character, Title

Siege[edit]

Siege (or flank) scopes allow to scope to on-going combats. They are different from unit scopes.

Scope Used in vanilla Description Trigger Effect From scope
siege Scopes to the siege the character is participating in Character

Unit[edit]

Unit scope allows to scope to an army (outside of a battle/siege) or fleet. It is rarely used in vanilla, and there are very few triggers or effects that work in these scopes (loot, set_looting, set_can_toggle_looting).

Scope Used in vanilla Description Trigger Effect From scope
any_army Scopes to all armies belonging to the character. Character
any_fleet X Scopes to all fleet belonging to the character. Character
any_unit X Scopes to all units belonging to the character. Character
random_army X Scopes to an armies belonging to the character. X Character
random_fleet X Scopes to a fleet belonging to the character. X Character
random_unit X Scopes to a unit belonging to the character. X Character

Misc[edit]

These are the scopes that don't fit in any other category. The "from scope" column shows what scope(s) it can be called from.

Scope Used in vanilla Description Trigger Effect From scope
tooltip Displays commands in the option/decision tooltip, but doesn't actually perform the commands. Useful for manipulating the tooltip Any
hidden_tooltip Hides commands from display. Good for bulk commands and situations where the player shouldn't know what's happening Any

References[edit]

  1. forum:774248/page-32#post-22178309
  2. Forum:774248
  3. https://forum.paradoxplaza.com/forum/index.php?posts/19782549
  4. https://forum.paradoxplaza.com/forum/index.php?posts/19782549
Modding
CommandsConditionsScopesModifiersEventsDecisions
Gfx/Sfx/localisation