Scopes

CK3 Scope Overview Chart

Scopes are used in scripting to select entities in order to check for Triggers or apply Effects.

These are the color-coded direct scopes as of 1.4.4, generated via automated export from the game files.

Uses

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,...), operators (AND), flow control statements (if, limit), or clause for complex conditions or commands (create_character, ...).

There are several types of scopes accessible from script. These include, but are not limited to: character, title/holding, province, war, unit, religion, faith, culture.

Scopes can be nested, 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.

In Jomini, Scopes can also be chained without nesting:

root.mother.father.killer = {
    #Things we want to do with the killer of the father of the mother of the root character.
}

We can also directly compare scopes for equality:

trigger = {
    root.mother = scope:other_character.mother
}

In CK3, the ability to save and recall scopes has been vastly simplified by the addition of the save_scope_as command, which can save a given scope under a name, to be recalled later:

<scope> = {
    save_scope_as = <scope_name>
}
scope:<scope_name> = {
    #Stuff to execute in the scope.
}

Saved scopes will stay saved within the current code chain, that is, they will remain accessible until every action/event/effect/etc that is run as a result of the current one has been evaluated to completion. They will only be accessible in the given code chain. For example, if there is an event chain that takes years to complete, a scope saved in the initial event will remain accessible until the concluding event, but will not be accessible to any other events that may occur during that time frame.

Triggers and effects in scopes are only evaluated and executed if the scope exists. This can be used with always = yes 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.

Example

Imagine an event wanted to show the portrait of a vassal who is marked as a VIP. First, the vassal must be added to a scope in the immediate block of the event.

immediate = {
    random_vassal = {
        limit = { #Any conditions the vassal must meet, leave blank if you want a truly random vassal to be selected }
        save_scope_as = very_important_person
    }
}

With the VIP added to the scope, they can then be referenced later on in the event (such as by showing their portrait, having something happen to them, etc). For this example, they will simply have their portrait shown in the event.

left_portrait = {
    character = scope:very_important_person
    animation = personality_honorable
}

List of scopes

Culture

Scope	Description	To scope	Version added
culture_head		character	1.0
culture_group	Usable in culture, landed title, character and province scopes.	culture group	1.0

Landed title

Scope	Description	To scope	Version added
title:%title id%		landed title	1.0
barony_controller	Usable in landed title and province scopes.	character	1.0
county_controller	Usable in landed title and province scopes.	character	1.0
current_heir		character	1.0
holder		character	1.0
lessee		character	1.0
previous_holder		character	1.0
culture	Usable in landed title, character and province scopes.	culture	1.0
culture_group	Usable in culture, landed title, character and province scopes.	culture group	1.0
controlled_faith		faith	1.0
faith	Usable in landed title, character, province and great holy war scopes.	faith	1.0
barony	Usable in landed title and province scopes.	landed title	1.0
county	Usable in landed title and province scopes.	landed title	1.0
de_facto_liege		landed title	1.0
de_jure_liege		landed title	1.0
duchy	Usable in landed title and province scopes.	landed title	1.0
empire	Usable in landed title and province scopes.	landed title	1.0
kingdom	Usable in landed title and province scopes.	landed title	1.0
lessee_title		landed title	1.0
title_capital_county		landed title	1.0
title_province		province	1.0
religion	Usable in landed title and province scopes.	religion	1.0

Dynasty house

Scope	Description	To scope	Version added
house_head		character	1.0

Dynasty

Scope	Description	To scope	Version added
dynasty		character	1.0
dynast	dynasty head	character	1.0

Secret

Scope	Description	To scope	Version added
secret_owner		character	1.0
secret_target		character	1.0

Holy order

Scope	Description	To scope	Version added
holy_order_patron		character	1.0
leader		character	1.0
title		landed title	1.0

Character

Scope	Description	To scope	Version added
commanding_army		army	1.0
knight_army		army	1.0
betrothed		character	1.0
concubinist		character	1.0
court_owner		character	1.0
designated_heir		character	1.0
employer		character	1.0
father		character	1.0
ghw_beneficiary		character	1.0
host		character	1.0
imprisoner		character	1.0
killer		character	1.0
liege		character	1.0
liege_or_court_owner		character	1.0
matchmaker		character	1.0
mother		character	1.0
player_heir		character	1.0
pregnancy_assumed_father		character	1.0
pregnancy_real_father		character	1.0
primary_heir		character	1.0
primary_partner		character	1.0
primary_spouse		character	1.0
real_father		character	1.0
realm_priest		character	1.0
top_liege		character	1.0
council_task		council task	1.0
culture	Usable in landed title, character and province scopes.	culture	1.0
culture_group	Usable in culture, landed title, character and province scopes.	culture group	1.0
dynasty		dynasty	1.0
house		dynasty house	1.0
joined_faction		faction	1.0
faith	Usable in landed title, character, province and great holy war scopes.	faith	1.0
capital_barony		landed title	1.0
capital_county		landed title	1.0
primary_title		landed title	1.0
capital_province		province	1.0
location	Usable in character, army and combat scopes.	province	1.0
religion		religion	1.0

Army

Scope	Description	To scope	Version added
army_commander		character	1.0
army_owner		character	1.0
location	Usable in character, army and combat scopes.	province	1.0

Province

Scope	Description	To scope	Version added
barony_controller	Usable in landed title and province scopes.	character	1.0
county_controller	Usable in landed title and province scopes.	character	1.0
province_owner		character	1.0
culture	Usable in landed title, character and province scopes.	culture	1.0
culture_group	Usable in culture, landed title, character and province scopes.	culture group	1.0
faith	Usable in landed title, character, province and great holy war scopes.	faith	1.0
barony	Usable in landed title and province scopes.	landed title	1.0
county	Usable in landed title and province scopes.	landed title	1.0
duchy	Usable in landed title and province scopes.	landed title	1.0
empire	Usable in landed title and province scopes.	landed title	1.0
kingdom	Usable in landed title and province scopes.	landed title	1.0
religion	Usable in landed title and province scopes.	religion	1.0

Faith

Scope	Description	To scope	Version added
religious_head		character	1.0
great_holy_war		great holy war	1.0
religious_head_title		landed title	1.0
religion	Usable in landed title and province scopes.	religion	1.0

Great holy war

Scope	Description	To scope	Version added
ghw_designated_winner		character	1.0
ghw_target_character		character	1.0
ghw_title_recipient		character	1.0
ghw_war_declarer		character	1.0
faith	Usable in landed title, character, province and great holy war scopes.	faith	1.0
ghw_target_title		landed title	1.0
religion	Usable in landed title and province scopes.	religion	1.0
ghw_war		war	1.0

Combat side

Scope	Description	To scope	Version added
side_commander		character	1.0
side_primary_participant		character	1.0
combat		combat	1.0
enemy_side		combat side	1.0

Scheme

Scope	Description	To scope	Version added
scheme_defender		character	1.0
scheme_owner		character	1.0
scheme_target		character	1.0

Council task

Scope	Description	To scope	Version added
councillor		character	1.0

Color

The scope "Color" is no longer supported since 1.5.

Scope	Description	To scope	Version added
blue		value	1.0
brightness		value	1.0
green		value	1.0
hue		value	1.0
red		value	1.0
saturation		value	1.0

War

Scope	Description	To scope	Version added
casus_belli		casus belli	1.0
claimant	Usable in war and casus belli scopes.	character	1.0
primary_attacker	Usable in war and casus belli scopes.	character	1.0
primary_defender	Usable in war and casus belli scopes.	character	1.0

Casus belli

Scope	Description	To scope	Version added
claimant	Usable in war and casus belli scopes.	character	1.0
primary_attacker	Usable in war and casus belli scopes.	character	1.0
primary_defender	Usable in war and casus belli scopes.	character	1.0
war		war	1.0

Combat

Scope	Description	To scope	Version added
combat_attacker		combat side	1.0
combat_defender		combat side	1.0
location	Usable in character, army and combat scopes.	province	1.0
combat_war		war	1.0

Story cycle

Scope	Description	To scope	Version added
story_owner		character	1.0

Faction

Scope	Description	To scope	Version added
faction_leader		character	1.0
faction_target		character	1.0
special_character		character	1.0
special_title		landed title	1.0
faction_war		war	1.0

Activity

Scope	Description	To scope	Version added
activity_owner		character	1.0
activity_province		province	1.0

Primitive scopes

These scope types by default have no direct scope links out of them, though they can chain into script values.

Scope	Example
Number	-1.0, 42, 69, some_script_value
Bool	yes/no
Flags	flag:some_flag

Variables, saved scopes, and list builders

Any scope can be stored in a variable via set_variable or saved as a "saved scope" via save_scope_as.

Any non-primitive scope can store a variable.

Only primitive scopes can be stored as "saved scope values".

"Lists" are the list equivalent of save_scope_as.

Variables and saved scopes

Variables and saved scopes are accessed as direct scopes via links (i.e. prefixes), and may depend on the scope on which they are stored.

Type	Setter	Getter	Description
Variable	set_variable = { name = some_name value = some_scope }	var:some_name	Sets the variable on the scope in which the set_variable effect is executed. For example if the variable is set on character:1 then it would be accessed via character:1.var:some_name. After the variable has been set, any other effect in the game that can access the carrying scope can also access the variable.
Local Variable	set_local_variable = { name = some_name value = some_scope }	local_var:some_name	Sets the local variable in the topscope ("top block") in which the set_local_variable effect is executed. For example if the variable is set in an immediate block of an event, then it can be accessed via local_var:some_name anywhere in that immediate block, but will not be accessible in the option blocks of that event.
Global Variable	set_global_variable = { name = some_name value = some_scope }	global_var:some_name	Sets the variable on the game state. Can be directly accessed via global_var:some_name from anywhere after the global variable has been set.
Saved Scope	save_scope_as = some_name	scope:some_name	Saved the scope on the topscope, like a local_variable. However, unlike local variables, saved scopes are inherited from block to block that are causally connected, so an event sent from an interaction that saved scope:actor and scope:recipient will always be able to access those scopes.
Saved Scope Value	save_scope_value_as = { name = some_name value = primitive_scope }	scope:some_name	Like saved scopes, but can only save primitive scopes.
Temporary scope	save_temporary_scope_as = some_name	scope:some_name	Syntax like saved scopes, but the setter is usable in triggers (not just effects) and expire after the block ends, like local variables.
Temporary scope value	save_temporary_scope_value_as = { name = some_name value = primitive_scope }	scope:some_name	Syntax like saved scope values, but the setter is usable in triggers (not just effects) and expire after the block ends, like local variables.

Note that saved scopes have special event localization integration, as you can for example chain data functions off them like [some_name.GetFirstName]. Variables can also be accessed, but doing this is more involved, for example [GetPlayer.MakeScope.Var('some_name').Char.GetFirstName] or [ROOT.Var('some_name').Char.GetFirstName].

Note that variables, local variables, and global variables come equipped with change_variable, change_local_variable and change_global_variable, respectively, but these are only usable if the variable in question has a primitive number as a value.

 change_variable = {name = some_name add = 5}

List builders

List builders are ways to access scopes from particular lists. Every list builder x comes with

Type	Syntax	Description
Trigger	any_x = {count > 0 <triggers go here>}	Checks whether the <triggers> are valid for (at least) count number of elements in the list builder. Also allows other comparison operators, and can use "percent = 0.4" (in decimal notation) instead of "count".
Effect	every_x = {limit = {<triggers go here>} <effects go here>}	Iteratively executes the effect for every scope in the list builder satisfying the limit.
Effect	random_x = {limit = {<triggers go here>} <effects go here> weight = {base = 1 <MTTH modifiers go here>}}	Executes the effect for a random scope in the list builder satisfying the limit and weighted by the weight. Can also use an alternative_limit block as a fallback if no elements satisfy the limit.
Effect	ordered_x = {limit = {<triggers go here>} <effects go here> order_by = script_value position = value min = value max = value}	Executes the effect for limit-satisfying elements in the sorted list (according to order_by) either at the given position or for positions between min and max.

Vanilla List Builders

There are many vanilla list builders, see the Effects or Triggers pages. These may or may not depend on the scope they are accessed in, for example every_sibling only makes sense for a character whereas every_religion_global can be accessed from any scope.

Dynamic lists

These are the list builder equivalents of saved scopes and variables. Note that vanilla uses local variable lists in some places, but there is never a use case for them that aren't covered by the other types, so they are omitted here.

The following are ways to deal how to add some scope called SCOPE to a list named NAME, how to iterate over elements of the list named NAME, and how to check whether a given SCOPE is a member of the list named NAME.

Name	Setter	Getter	Membership trigger	Singular equivalent
List	add_to_list = NAME	x_in_list = {list = NAME <effects/triggers go here>}	is_in_list = NAME	save_scope_as
Temporary_list	add_to_temporary_list = NAME	x_in_list = {list = NAME <effects/triggers go here>}	is_in_list = NAME	save_temporary_scope_as
Variable_list	add_to_variable_list = {name = NAME target = SCOPE}	x_in_list = {variable = NAME <effects/triggers go here>}	is_target_in_variable_list = {name = NAME target = SCOPE}	set_variable
Global_variable_list	add_to_global_variable_list = {name = NAME target = SCOPE}	x_in_global_list = {variable = NAME <effects/triggers go here>}	is_target_in_global_variable_list = {name = NAME target = SCOPE}	set_global_variable

In GUI Modding, Variable Lists and Global Variable Lists are accessible as datamodels via datamodel = "[Scope.GetList('NAME')]" and datamodel = "[GetGlobalList('NAME')]" respectively.

Scripted Lists

Scripted Lists are custom list builders defined in the common/scripted_list folder.

 example_scripted_list = {
   base = living_character
   conditions = {<triggers>}
 }

This generates triggers and effects like any vanilla list builder, allowing you to use x_example_scripted_list. NOTE: As of 1.4.4, scripted_lists cannot be accessed in script values. This is a bug.

References

Modding

Map	Map • Terrain

Audio

Music • Sound

Mechanics