Please help with verifying or updating older sections of this article.
At least some were last verified for version 1.1.
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.
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
.
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
}
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
|
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
|
Scope
|
Description
|
To scope
|
Version added
|
house_head
|
|
character
|
1.0
|
Scope
|
Description
|
To scope
|
Version added
|
dynasty
|
|
character
|
1.0
|
dynast
|
dynasty head
|
character
|
1.0
|
Scope
|
Description
|
To scope
|
Version added
|
secret_owner
|
|
character
|
1.0
|
secret_target
|
|
character
|
1.0
|
Scope
|
Description
|
To scope
|
Version added
|
holy_order_patron
|
|
character
|
1.0
|
leader
|
|
character
|
1.0
|
title
|
|
landed title
|
1.0
|
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
|
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
|
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
|
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
|
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
|
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
|
Scope
|
Description
|
To scope
|
Version added
|
scheme_defender
|
|
character
|
1.0
|
scheme_owner
|
|
character
|
1.0
|
scheme_target
|
|
character
|
1.0
|
Scope
|
Description
|
To scope
|
Version added
|
councillor
|
|
character
|
1.0
|
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
|
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
|
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
|
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
|
Scope
|
Description
|
To scope
|
Version added
|
story_owner
|
|
character
|
1.0
|
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
|
Scope
|
Description
|
To scope
|
Version added
|
activity_owner
|
|
character
|
1.0
|
activity_province
|
|
province
|
1.0
|
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[edit | edit source]
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[edit | edit source]
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 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.
|
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.
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 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.