查看“作用域”的源代码

{{Version|2.8}}

'''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:
<pre>
<scope_name> = {
	#Stuff to execute in the scope.
}
</pre>

But not all bracketed blocks are scopes: some are function blocks (option, trigger, mean_time_to_happen,...), [[operator]]s (<code>AND</code>), flow control statements (if, limit), or clause for complex [[conditions]] or [[commands]] (<code>create_character</code>, ...).

Ten types of scopes can be created from script: character, title/holding, province, war, siege/flank, unit, religion, culture, society, and artifact. There is also a special [[portrait scope]] used for portrait rendering rules.

Scopes can be nested (see [[Scripting#Scope_chain|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.

Triggers and effects in scopes are only evaluated and executed if the scope exists. This can be used with <code>always = yes</code> to check for the existence of a scope in a trigger or for effects that you only want to execute if, for example, a character's religion has a religious head.

Note that the condition tooltips within "any_" scopes are misleading and only show whether the conditions are satisfied for one specific, seemingly randomly-chosen thing contained within the scope, and thus may show that some conditions are false even when the scope itself evaluates to true.  These are best overridden with a custom_tooltip.

==Condition vs command scopes==

When used within a condition block, a scope allows to check whether any entity is matched by that scope:

<pre>
trigger = {
	<scope_name> = {
		#Conditions to be met by at least one entity in the scope for the trigger to evaluate to true
	}
}
</pre>

When used within a command block, a scope allows to apply commands on each entity matched by that scope:

<pre>
effect = {
	<scope_name> = {
		limit = { #Optional limit block (valid only for any_* and random_* scopes)
			#Further conditions to filter entities matched by the scope
		}
		#Commands to apply each entity in the scope
	}
}
</pre>

Some scopes only work in a condition block (this is rare), and some only work in effect command blocks (all random_* scopes).

==Count==
<code>any_</code> scopes can use <code>count = N</code>. For condition scopes, the scope will evaluate to true only if at least N items match. For effect scopes, the scope will execute for at most N items (''not'' randomized).

==Limit==

==Preferred limit==
<code>random_</code> scopes (except for <code>random_quest_target</code>) allow for one or multiple <code>preferred_limit</code> blocks in addition to the regular <code>limit</code>. When preferred limits are used, the first one that at least one target fulfills will be used in addition to the limit. If no preferred limit is fulfilled, only the base limit gets used. Very useful for when you want to pick a better target when one is available.

The following example would give 1000 gold to a random independent Norwegian with less than 1000 gold, if one exists. If none exists, it'll give it to a random independent North Germanic with less than 1000 gold. If none exists, it'll give it to a random independent ruler of any culture with less than 1000 gold.
<pre>
random_independent_ruler = {
	limit = { wealth < 1000 }
	preferred_limit = { culture = norwegian }
	preferred_limit = { culture_group = north_germanic }
	wealth = 1000 
}
</pre>

==Score value==

<code>any_</code> scopes can be narrowed to the top scorer(s) by specifying a <code>score_value</code> system:

<pre>	
any_society_member = {
    score_value = {
        value = 1
        additive_modifier = {
            society_rank == 4
            value = 1000
        }
        additive_modifier = {
            society_rank == 3
            value = 100
        }
    }
    count = 3
    add_trait = maimed
}
</pre>

If there is a tie in score, only 1 (or <code>count</code>) of the highest-scoring items will be selected, but the pick is ''not'' randomized. Set of modifiers can be defined in <code>common/scripted_score_values/</code> for reuse.

==Quickcard==

The most important scopes are shown in this quickcard:

[[File:Scopes modding quickcard.png|400px]]

Legend:
* (!) CPU heavy, use with care
* (scope) deprecated variant, rarely used in vanilla
* * coming in some next patch<ref>[[forum:774248/page-32#post-22178309]]</ref>

== List of scopes ==

=== Character ===

[[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: <code>father_even_if_dead</code>, and some scopes may not work inside a dead character scope.

{| class="wikitable sortable"
!Scope
!Used in vanilla
!Description
!Trigger
!Effect
!From scope
|-
|''c_%character_ID%''
|X
| Direct scoping to character by ID. For instance if character has ID 12345: <code>c_12345 = { }</code>
This is generally pointless as new character IDs are generated randomly, but it can be used for scripting historical events for characters defined in history with a pre-defined ID.
|✓
|✓
|Any
|-
|''%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 [[Trait modding|flag]] cached = yes.
<pre>
on_hajj = {
  NOT = {
    has_character_flag = hajj_arrived_in_mecca
    opinion = { who = ROOT value = 0 }
  }
}
</pre>
'''Warning''': <code>count = N</code> doesn't work in this scope, as it's not an any_ scope.
|✓
|✓
|Any
|-
|any_allied_character
|X
|Scopes to all allies. Expensive calculation, use with care<ref>[[Forum:774248]]</ref>
|✓
|✓
|Character
|-
|any_artifact_owner
|X
|Scopes to anyone who has ever owned the [[artifact]], including the current owner. Does not work on artifacts that have the <code>history = no</code> parameter.
|?
|?
|Artifact
|-
|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_bloodline_member
|X
|Scopes to all members of the current bloodline
|?
|?
|Bloodline
|-
|any_character
|X
|Scopes to all characters, except for offmap rulers. '''WARNING CPU HEAVY'''
|✓
|✓
|Any
|-
|any_child <br/> 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 living close relatives of a character. Includes anyone with a "red blood" icon in their dynasty (siblings, children, grandchildren, parents, grandparents, etc.), as well as bastards of their closest relatives. Does not include spouse.
|✓
|✓
|Character
|-
|any_courtier
|✓
|Scopes to everyone in the same court as the character. Note that it will match prisoners (even if foreign) and councillors (even if landed). If used for a ruler who is a councilor, it will check their liege's court instead of their own!
|✓
|✓
|Character
|-
|any_courtier_or_vassal
|✓
|
Primarily used to find [[minor title]] holders:

    any_courtier_or_vassal = {
        has_minor_title = title_court_physician
        liege = { character = PREVPREV }
    }

For direct subjects including courtiers abroad, you must use the inefficient any_character scope instead:

    any_character = {
        independent = no
        liege = { character = PREVPREV }
    }
|✓
|✓
|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<ref>https://forum.paradoxplaza.com/forum/index.php?posts/19782549</ref>
|✓
|Character, title
|-
|any_defender
|✓
|Scopes to all defenders in a war
|✓
|✓
|War
|-
|any_dynasty_member <br/> any_dynasty_member_even_if_dead
|✓
|Scopes to all members of a character's [[dynasty]].
|✓
|✓
|Character
|-
|any_enemy_plotter
|X
|Scopes to any character (known/unknown) plotting against the character in scope
|✓
|✓
|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_host_courtier
|✓
|Scopes to all characters in the same court. Shorter version of host = { any_courtier = { ... } }
|✓
|✓
|Any
|-
|any_independent_ruler
|✓
|Scopes to all independent rulers. Doesn't include <code>ROOT</code>. Excludes revolts; to include them, use a broader scope with <code>limit = { liege = { character = PREV } }</code>.
|✓
|✓
|Any
|-
|any_known_enemy_plotter
|X
|Scopes to any known character plotting against the character in scope
|✓
|✓
|Character
|-
|any_known_plotter
|✓
|Scopes to any plotter character whose plot the character in scope knows about
|✓
|✓
|Character
|-
|any_kill_list_character
|✓
|Scopes to anyone in the character's kill list.
|✓
|[?]
|Character
|-
|any_liege
|✓
|Scopes to all lieges a character has, regardless of how many tiers above. This includes <code>liege</code> and <code>top_liege</code> scopes. If <code>THIS</code> is independent, scopes to nothing.
|✓
|✓
|Character
|-
|any_lover
|✓
|Scopes to all lovers a character has
|✓
|✓
|Character
|-
|any_neighbor_independent_ruler
|✓
|Scopes to all independent rulers whose realm neighbors the realm you are in.
|✓
|✓
|Character
|-
|any_non_aggression_pact_character
|✓
|Scopes to all characters to which someone has a non-aggression pact
|✓
|{{sup|?}}
|Character
|-
|any_opinion_modifier_target
|✓
|Scopes to all characters having an opinion modifier toward scoped character
<pre>
any_opinion_modifier_target = {
  limit = {
   reverse_has_opinion_modifier = {
     who = PREV
     modifier = opinion_spying_on
   }
  }
  reverse_remove_opinion = {
    who = PREV
    modifier = opinion_spying_on
  }
}
</pre>
|✓
|✓
|Character
|-
|any_playable_ruler
|✓
|Scopes to all playable rulers currently alive. Combined with <code>limit = { ai = no }</code>, it allows to broadcast events to human players.
|✓
|✓
|Any
|-
|any_player
|✓
|Scopes to all 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. (?)
<pre>any_plotter = {
	target = ROOT
	limit = {
		OR = {
			has_plot = plot_kill_character
			has_plot = plot_kill_spouse
		}
	}
	character_event = { id = CM.6001 }
}</pre>
|✓
|✓
|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_pupil
|✓
|Scopes to all characters that the scope is educating.
|✓
|✓
|Character
|-
|any_quester
|X
|Scopes to all characters with a quest.
|✓
|✓
|Any
|-
|any_quester_targeting_this <br/> any_quester_targetting_this
|✓
|Scopes to all characters with a quest targeting the current scope.
|✓
|✓
|Character, Title, Province
|-
|any_quest_target
|X
|Scopes to all characters, provinces, and titles that are a target of a quest. Note that the script should either be able to handle all three types or filter the target type in the limit.
|✓
|✓
|Any
|-
|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. Like any_courtier, it does not include prisoners abroad.
|✓
|✓
|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 <br/> any_sibling_even_if_dead
|✓
|Scopes to all of a character's siblings
|✓
|✓
|Character
|-
|any_society_member
|✓
|Scopes to all members of the society. Note: if current scope is not a society, will scope to all characters in any society (?).
|✓
|✓
|Society/Any
|-
|any_spouse <br/> 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_tributary
|✓
|Scopes to all tributaries of the scope
|✓
|✓
|Character
|-
|any_unit_leader
|✓
|Scopes to all leaders (flank or subunit) in a unit scope. In character uses the unit that character is in. If the unit is in combat, every unit on the same side in the battle is included.
|?
|?
|Character, Unit
|-
|any_unique_dynasty_vassal
|✓
|Scopes to vassals with different dynasties (excluding dynasty of scoped character). 
|✓
|✓
|Character
|-
|any_unknown_enemy_plotter
|X
|Only scopes to the plotters of the Character in scope that are unknown
|✓
|✓
|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 <code>any_realm_character</code>.
|✓
|✓
|Character, title
|-
|any_voter
|✓
|Scopes to all voters in a character's council
|✓
|{{sup|?}}
|Character
|-
|any_ward
|✓
|Scopes to all of a character's [[wards]]
|✓
|✓
|Character
|-
|artifact_owner
|X
|Scopes to all the artifact's owner
|✓
|✓
|Artifact
|-
|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
|-
|best_fit_character_for_title
|✓
|Scopes to a character who should get a chosen title, from a chosen character's perspective. Parameters: title, perspective (from whose perspective we are viewing the title), index (The index of the character in the list)
<pre>
best_fit_character_for_title = {
  title = PREV 
  perspective = ROOT
  index = 1 
  grant_title = PREV
}
</pre>
|?
|✓
|?
|-
|betrothed
|✓
|Scopes to the character who the current scoped character is betrothed to.
|✓
|✓
|Character
|-
|biggest_realm_size_relative
|✓
|Scopes to relatives with biggest realm size.
|✓
|✓
|Character
|-
|center_flank_leader
|✓
|Scopes to the central flank leader of an army
|✓
|✓
|Army
|-
|left_flank_leader
|✓
|Scopes to the left flank leader of an army
|✓
|✓
|Army
|-
|right_flank_leader
|✓
|Scopes to the right flank leader of an army
|✓
|✓
|Army
|-
|controller
|✓
|Scopes to the character controlling a [[barony]]. Rarely used, more generic scope <code>owner</code> 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. Only works for landless characters, as landed rulers are considered their own employer, even if they work on their liege council.
|✓
|✓
|Character
|-
|enemy
|✓
|Scopes to the enemy in a siege or opposing flank in combat
|✓
|✓
|Siege
|-
|father <br/> father_even_if_dead
|✓
|Scopes to the character's father
|✓
|✓
|Character
|-
|father_of_unborn
|✓
|Scopes to the unborn child's father
|✓
|✓
|Character
|-
|founder
|✓
|Scopes to the founder of the current bloodline
|✓
|✓
|Bloodline
|-
|guardian
|✓
|Scopes to the child's guardian
|✓
|✓
|Character
|-
|governor
|✓
|Scopes to the governor of the scope's offmap power. Scope can be the offmap power itself, the offmap power ruler, or the governor title.
|✓
|✓
|Offmap Power/Character/Title.
|-
|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
|-
|hospital_owner
|X
|
|✓(?)
|✓(?)
|Province(?)
|-
|host
|✓
|Scopes to the owner of where the character resides. Works both for landed and unlanded characters. If character is residing at court, the host would be the liege. For an imprisoned character, this yields their jailer.
|✓
|✓
|Character
|-
|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
|-
|killer
|✓
|Scopes to the killer of a character
|✓
|✓
|Character
|-
|leader
|✓
|Scopes to the leader of a force in a siege, or of a flank (but not subunit) in combat
|✓
|✓
|Siege/Flank
|-
|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
|{{sup}}
|✓
|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 <code>limit</code> 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.
|{{sup|?}}
|✓
|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 <code>create_character</code> or similar command.
|X
|✓
|Any
|-
|offmap_prev_ruler
|✓
|Scopes to the previous ruler of the scope's offmap power. Scope can be the offmap power itself, the current offmap power ruler, the governor, or the governor title.
|✓
|✓
|Offmap Power/Character/Title
|-
|offmap_ruler
|✓
|Scopes to the ruler of the scope's offmap power. Scope can be the offmap power itself, the governor, or the governor title.
|✓
|✓
|Offmap Power/Character/Title
|-
|original_artifact_owner <br/> original_owner
|✓
|Scopes to the original owner of the artifact. Both scopes function identically.
|✓
|✓
|Artifact
|-
|owner
|✓
|Scopes to the owner of the province, title, or artifact
|✓
|✓
|Title, Province, Artifact
|-
|parent_religion_head
|✓
|Scopes to the religion head of the parent religion
|✓
|✓
|Character,Province
|-
|player_heir
|✓
|Scopes to the scope's heir as listed on the character sheet (i.e. the character you would be playing if you were playing the scope and the scope died) rather than the heir to the primary title of the scope.
|✓
|✓
|Character
|-
|plot_target_char
|✓
|Scopes to the character that's being plotted against
|✓
|✓
|Character
|-
|preferred_war_target
|✓
|Scopes to the character's attack target
|✓
|✓
|Character
|-
|previous_artifact_owner
|X
|Scopes to the previous owner of the artifact. Does not work on artifacts that have the <code>history = no</code> parameter.
|?
|?
|Artifact
|-
|quest_target
|✓
|Scopes to current target of the character's quest. Can be a character, province, or title depending on the quest.
|✓
|✓
|Character
|-
|random_allied_character
|X
|Scopes to an ally
|X
|✓
|Character
|-
|random_artifact_owner
|X
|Scopes to a random character from those who have ever owned the [[artifact]], including the current owner. Does not work on artifacts that have the <code>history = no</code> parameter.
|?
|?
|Artifact
|-
|random_backed_character
|✓
|Scopes to a random character the character is backing. Cannot be used as a trigger
|X
|✓
|Character
|-
|random_bloodline_member
|X
|Scopes to a random member of the current bloodline
|?
|?
|Bloodline
|-
|random_character
|X
|Scopes a random character in the game, excluding offmap rulers. Cannot be used as a trigger. Note: This scope doesn't apply commands to <code>ROOT</code>.
|X
|✓
|Any
|-
|random_child <br/> random_child_even_if_dead
|✓
|Scopes to a random child of the character. Cannot be used as a trigger
|X
|✓
|Character
|-
|random_close_relative
|X
|Scopes to a random close relative of the character. 
|
|✓
|Character
|-
|random_courtier
|✓
|Scopes to a random courtier of the character, including prisoners. Cannot be used as a trigger.
|X
|✓
|Character
|-
|random_courtier_or_vassal
|✓
|Scopes to a random courtier or vassal of the character. 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 <br/> 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_host_courtier
|✓
|Scopes to a random character in the same court. Shorter version of host = { random_courtier = { ... } }
|X
|✓
|Any
|-
|random_independent_ruler
|✓
|Scopes to a random independent ruler. Doesn't include <code>ROOT</code>.
|X
|✓
|Any
|-
|random_known_enemy_plotter
|X
|
|X
|✓
|Character
|-
|random_lover
|✓
|Scopes to a random lover.
|X
|✓
|Character
|-
|random_neighbor_independent_ruler
|✓
|Scopes to a random independent ruler whose realm neighbors the realm you are in.
|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
|X
|Scopes to a random playable ruler.
|X
|✓
|Any
|-
|random_player
|✓
|Scopes to a random player.
|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_pupil
|✓
|Scopes to a random character that the scope is educating.
|X
|✓
|Character
|-
|random_quester
|X
|Scopes to a random character with a quest.
|X
|✓
|Any
|-
|random_quester_targetting_this
|X
|Scopes to a random character with a quest targeting the current scope.
|X
|✓
|Character, Title, Province
|-
|random_quest_target
|X
|Scopes to all characters, provinces, and titles that are a target of a quest. Note that the script should either be able to handle all three types or filter the target type in the limit.
|X
|✓
|Any
|-
|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 <br/>random_sibling_even_if_dead
|✓
|Scopes to a random sibling of the character.
|X
|✓
|Character
|-
|random_society_member
|✓
|Scopes to a random member of the society. Note: if current scope is not a society, will scope to a random character that is in any society (?).
|X
|✓
|Society/Any
|-
|random_spouse <br/> 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_tributary
|X
|Scopes to all tributaries of the scope
|X
|✓
|Character
|-
|random_unit_leader
|✓
|Scopes to a random leader (flank or subunit) in a unit scope. In character uses the unit that character is in. If the unit is in combat, every unit on the same side in the battle is included.
|?
|?
|Character, Unit
|-
|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 <br/> real_father_even_if_dead
|✓
|Scopes to the character's real father, if the character's known father is not their genetic parent.  This will select the genetic parent even if the cuckolding is unknown.  If character's known father is their actual father, produces no result.  See <code>true_father</code> or <code>true_father_even_if_dead</code> if you would prefer to return the actual father every time.
|✓
|✓
|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, <code>owner</code> 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
|-
|title_to_get_rid_of
|✓
|Scopes to titles over the demesne limit
|✓
|✓
|Title
|-
|top_liege
|✓
|Scopes to a character's independent liege. Includes <code>ROOT</code> if independent.
|✓
|✓
|Character
|-
|trade_post_owner
|✓
|Scopes to the owner of the trade post
|✓
|✓
|Province, Title
|-
|true_father
|X
|Scopes to the real_father if one exists; otherwise it scopes to the father.
|✓
|✓
|Character
|-
|true_father_even_if_dead
|X
|
|✓
|✓
|Character
|-
|twin
|X
|Scopes to the character's twin. WARNING: If mods add additional twins (triplets, etc.), these scopes may produce unpredictable results.
|✓
|✓
|Character
|-
|twin_even_if_dead
|X
|
|✓
|✓
|Character
|-
|}

=== Title ===

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).

Extra holdings (trade posts, hospitals and forts) do not have a corresponding holding/title scope, and are instead managed from their parent province scope<ref>[[forum:589686/page-1586#post-23235019]]</ref>.

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

{| class="wikitable sortable"
!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_). <br/>
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<ref>https://forum.paradoxplaza.com/forum/index.php?posts/19782549</ref>
|✓
|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 to which the character is the current heir
|✓
|X
|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_quest_target
|X
|Scopes to all characters, provinces, and titles that are a target of a quest. Note that the script should either be able to handle all three types or filter the target type in the limit.
|✓
|✓
|Any
|-
|any_realm_title
|✓
|Scopes to all titles within a character or title's realm
|✓
|X
|Character
|-
|any_title
|✓
|Scopes to all titles
|X
|✓
|Any
|-
|any_title_under
|✓
|Scopes to all titles held by the character or characters they control
|X
|✓
|Character
|-
|blood_brother
|✓
|
|✓
|✓
|Character
|-
|capital_holding
|✓
|Scopes to the character's capital holding title. Note: this is different from <code>capital_scope</code> 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, or scopes from province to corresponding county title
|✓
|✓
|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
|✓
|✓
|Title
|-
|dejure_liege_title
|✓
|Scopes to the title a character or title de jure belongs to
|✓
|✓
|Character, title
|-
|duchy
|✓
|Scopes to the duchy a province belongs to. (From county scope, you must use <code>dejure_liege_title</code> instead)
|✓
|✓
|Province
|-
|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
|-
|governor_title
|X
|Scopes to the governor title of the scope. Scope can be the offmap power itself, the offmap power ruler, or the governor.
|✓
|✓
|Offmap Power/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 <code>create_title</code> 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
|-
|quest_target
|✓
|Scopes to current target of the character's quest. Can be a character, province, or title depending on the quest.
|✓
|✓
|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_direct_de_jure_vassal_title
|✓	
|Scopes to a random title that is dejure part of the scoped title's realm
|X
|✓
|Title
|-
|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_quest_target
|X
|Scopes to all characters, provinces, and titles that are a target of a quest. Note that the script should either be able to handle all three types or filter the target type in the limit.
|X
|✓
|Any
|-
|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 <code>top_liege</code> for titles.
|✓
|✓
|Character, title
|-
|succ_law_title
|✓
|Scopes to a title where <code>has_law</code> trigger can be used to check succession law.
|✓
|✓
|Title
|-
|thirdparty_title_scope
|✓
|Only valid if thirdparty title is involved in the war
|✓
|✓
|War
|-
|}

=== Province ===

Province scopes are all scopes that target provinces. 

Extra holdings (trade posts, hospitals and forts) are targeted via province scope, using conditions/commands with the name of the extra holding in it (<code>has_fort</code>, <code>fort_has_building</code>, etc.)<ref>[[forum:589686/page-1586#post-23235019]]</ref>

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

{| class="wikitable sortable"
!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).  <br/>
For instance: 290 = { # Uppland }
|✓
|✓
|Any
|-
|any_connected_province
|✓
|Scopes to all provinces in the targeted sub-realm that are connected to this province. Takes the same parameters as the <code>is_connected_to</code> [[Conditions|trigger]], except for <code>target</code>.
|?
|?
|Province
|-
|any_demesne_province
|✓
|Scopes to all provinces in a character's demesne.
|✓
|✓ (v2.6.1)
|Character
|-
|any_disconnected_province
|✓
|Scopes to all provinces in the targeted sub-realm that aren't connected to this province. Takes the same parameters as the <code>is_connected_to</code> [[Conditions|trigger]], except for <code>target</code>.
|?
|?
|Province
|-
|any_neighbor_province
|✓
|Scopes to all border provinces, including sea tiles.
|✓
|✓
|Province
|-
|any_province
|X
|Scopes to all provinces. '''WARNING CPU HEAVY'''
|✓
|✓
|Any
|-
|any_fort
|X
|Scopes to all of a character's forts
|✓
|✓
|Character
|-
|any_hospital
|X
|Scopes to all of a character's hospitals
|?
|?
|Character
|-
|any_quest_target
|X
|Scopes to all characters, provinces, and titles that are a target of a quest. Note that the script should either be able to handle all three types or filter the target type in the limit.
|✓
|✓
|Any
|-
|any_realm_province
|✓
|Scopes to all provinces in a character or title's realm
|✓
|✓
|Character, title
|-
|any_trade_post
|✓
|Scopes to all of a character's trade posts
|✓
|?
|Character
|-
|any_trade_route_province
|✓
|Scopes to all other provinces on a trade route
|✓
|{{sup}}
|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 or barony title's province)
|✓
|✓
|Character, title, unit
|-
|plot_target_province
|✓
|Scopes to the province that the character's plot is targeting
|✓
|✓
|Character
|-
|quest_target
|✓
|Scopes to current target of the character's quest. Can be a character, province, or title depending on the quest.
|✓
|✓
|Character
|-
|random_connected_province
|X
|Scopes to a random province in the targeted sub-realm that is connected to this province. Takes the same parameters as the <code>is_connected_to</code> [[Conditions|trigger]], except for <code>target</code>.
|?
|?
|Province
|-
|random_demesne_province
|✓
|Scopes to a random province in the character's demesne.
|X
|✓
|Character
|-
|random_disconnected_province
|✓
|Scopes to a random province in the targeted sub-realm that isn't connected to this province. Takes the same parameters as the <code>is_connected_to</code> [[Conditions|trigger]], except for <code>target</code>.
|?
|?
|Province
|-
|random_fort
|X
|Scopes to all of a character's forts
|X
|✓
|Character
|-
|random_neighbor_province
|✓
|Scopes to a random bordering province. Unlike any_neighbor_province, this does NOT scope to sea tiles!
|X
|✓
|Province
|-
|random_province
|X
|Scopes to a random province province
|X
|✓
|Any
|-
|random_quest_target
|X
|Scopes to all characters, provinces, and titles that are a target of a quest. Note that the script should either be able to handle all three types or filter the target type in the limit.
|X
|✓
|Any
|-
|random_realm_province
|✓
|Scopes to a random province in the character or title's realm.
|X
|✓
|Character, title
|-
|random_trade_post
|?
|Scopes to a random trade post of the character or province.
|X
|?
|Character
|-
|sea_zone
|✓
|Scopes to ALL sea provinces bordering the currently scoped province
|✓
|✓
|Province
|-
|}

=== Offmap power ===

Offmap power scopes allow scoping to particular offmap powers, such as China.

{| class="wikitable sortable"
!Scope
!Used in vanilla
!Description
!Trigger
!Effect
!From scope
|-
|''%offmap_name%''
|✓
|Direct scoping to the offmap power by name.
|✓
|✓
|Any
|-
|offmap_power
|✓
|Scopes to the offmap power of the scope. Scope can be the offmap power ruler, the governor, or the governor title.
|✓
|✓
|Character/Title
|-
|}

=== War ===

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

{| class="wikitable sortable"
!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/Flank ===

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

{| class="wikitable sortable"
!Scope
!Used in vanilla
!Description
!Trigger
!Effect
!From scope
|-
|siege
|✓
|Scopes to the siege the character is participating in
|✓
|✓
|Character
|-
|combat
|✓
|Scopes to the flank the character is leading, as primary leader or subunit leader<ref>[[forum:774248/page-32#post-22178309]]</ref>
|✓
|✓
|Character
|-
|}

=== Unit ===

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 (<code>loot</code>, <code>set_looting</code>, <code>set_can_toggle_looting</code>).

{| class="wikitable sortable"
!Scope
!Used in vanilla
!Description
!Trigger
!Effect
!From scope
|-
|any_army
|✓
|Scopes to all armies belonging to the character.
|✓
|✓
|Character
|-
|any_controlled_unit
|X
|Scopes to all units controlled by 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_controlled_unit
|X
|Scopes to a unit controlled by 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
|-
|}

=== Religion ===

{| class="wikitable sortable"
!Scope
!Used in vanilla
!Description
!Trigger
!Effect
!From scope
|-
|''%religion_name%''
|X
|Scopes to a religion based on its name. Can also be used for religion groups, in which case it scopes to the first religion in the group.
For instance: catholic = { }
|✓
|✓
|Any
|-
|religion_scope
|✓
|Scopes to the religion of the current scope.
|✓
|✓
|Character/Province/Society
|-
|secret_religion_scope
|✓
|Scopes to the secret religion of the character.
|✓
|✓
|Character
|-
|true_religion_scope
|X
|Scopes to the true religion of the character.
|✓
|✓
|Character
|-
|}

Note: most scopes/commands/conditions that work in religion scope can also be used in character scope

=== Culture ===

{| class="wikitable sortable"
!Scope
!Used in vanilla
!Description
!Trigger
!Effect
!From scope
|-
|''%culture_name%''
|X
|Scopes to a culture based on its name. Can also be used for culture groups, in which case it scopes to the first culture in the group.
For instance: norse = { }
|✓
|✓
|Any
|-
|culture_scope
|✓
|Scopes to the culture of the character or province.
|✓
|✓
|Character/Province
|-
|gfx_culture_scope
|✓
|Scopes to the culturegfx of the character.
|✓
|✓
|Character
|-
|}

=== Society ===

{| class="wikitable sortable"
!Scope
!Used in vanilla
!Description
!Trigger
!Effect
!From scope
|-
|%society_name%
|?
|Scopes to a society statically, based on its name. Example: <code>the_satanists = { }</code>.
|✓
|✓
|Any
|-
|secret_religious_cult
|✓
|Scopes to the secret religious cult of the character's true religion, or otherwise the secret religious cult of the religion of the scope.
|✓
|✓
|Character/Province/Religion
|-
|society
|✓
|Scopes to the society the character is a member of
|?
|?
|Character
|-
|}

=== Artifact ===

{| class="wikitable sortable"
!Scope
!Used in vanilla
!Description
!Trigger
!Effect
!From scope
|-
|any_artifact
|✓
|Scopes to any artifact. Used within character scope.
|✓
|✓
|Character
|-
|new_artifact
|✓
|Scopes to the artifact just created using add_artifact.
|X
|✓
|Character
|-
|random_artifact
|✓
|Scopes to a random artifact. Used within character scope.
|X
|✓
|Character
|-
|}

=== Bloodline ===

{| class="wikitable sortable"
!Scope
!Used in vanilla
!Description
!Trigger
!Effect
!From scope
|-
|any_bloodline
|X
|Scopes to any created bloodline
|✓
|✓
|Any
|-
|any_owned_bloodline
|✓
|Scopes to any bloodline owned by the character
|✓
|?
|Character
|-
|new_bloodline
|✓
|Scopes to the newly created bloodline
|?
|✓
|
|-
|random_bloodline
|X
|Scopes to a random created bloodline
|✓
|✓
|Any
|-
|random_owned_bloodline
|✓
|Scopes to any bloodline owned by the character
|?
|✓
|Character
|-
|}

=== Wonder ===

{| class="wikitable sortable"
!Scope
!Used in vanilla
!Description
!Trigger
!Effect
!From scope
|-
|any_demesne_wonder
|✓
|Scopes to any wonder located which exists (or has begun construction) within your personal demesne
|✓
|✓
|Character
|-
|any_demesne_wonder_upgrade
|X
|Scopes to any wonder upgrade which exists (or has begun construction) located within your personal demesne.
|✓
|✓
|Character
|-
|any_previous_wonder_owner
|X
|Scopes to any character who previously owned this wonder.
|✓
|✓
|Wonder
|-
|any_realm_wonder
|✓
|Scopes to any wonder which exists (or has begun construction) within the borders of your realm
|✓
|✓
|Character
|-"
|any_realm_wonder_upgrade
|✓
|Scopes to any wonder upgrade which exists (or has begun construction) within the borders of your realm.
|✓
|✓
|Character
|-
|any_upgrade_on_wonder
|✓
|Scopes to any upgrade (completed or uncompleted) on wonder
|✓
|✓
|Wonder
|-
|any_wonder
|✓
|Scopes to any wonder which exists (or has begun construction) in the world
|✓
|✓
|Any
|-
|any_wonder_owner
|X
|Scopes to any character who owns a wonder.
|✓
|✓
|Any
|-
|any_wonder_upgrade
|X
|Scopes to any wonder upgrade which exists (or has begun construction) in the world.
|✓
|✓
|Any
|-
|location
|✓
|Scopes to the province of the wonder.
|✓
|✓
|Wonder or wonder upgrade
|-
|original_wonder_owner
|✓
|Scopes to the character who put down the first stones of the wonder (original creator/starter). From wonder scope.
|✓
|✓
|Wonder
|-
|previous_wonder_owner
|X
|Scopes to the character who was previously the owner of a wonder.
|✓
|✓
|Wonder
|-
|wonder
|✓
|Scopes to the parent wonder
|✓
|✓
|wonder upgrade, province
|-
|wonder_owner
|✓
|Scopes to the character who currently is the top liege (owner) of the wonder.
|✓
|✓
|Wonder
|-

|}

==References==

<references/>

[[Category:Modding]]
[[Category:Lists]]
{{ModdingNavbox}}