Scopes

From CK3 Wiki
Jump to navigation Jump to search
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[edit | edit source]

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

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

Culture[edit | edit source]

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

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

Scope Description To scope Version added
house_head character 1.0

Dynasty[edit | edit source]

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

Secret[edit | edit source]

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

Holy order[edit | edit source]

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

Character[edit | edit source]

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

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

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

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

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

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

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

Council task[edit | edit source]

Scope Description To scope Version added
councillor character 1.0

Color[edit | edit source]

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

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

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

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

Scope Description To scope Version added
story_owner character 1.0

Faction[edit | edit source]

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

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

Primitive scopes[edit | edit source]

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

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

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

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

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


Characters CharactersAttributesTraitsResourcesLifestyleDynastyCultureInnovationsModifiers
Realm & Governance VassalsCouncilCourtSchemesGovernmentLawsDecisionsTitlesBaronyCounty
Warfare WarfareCasus belliAllianceArmyHired forces
Faith ReligionFaithDoctrinesTenets
Meta ModdingPatchesDownloadable contentDeveloper diariesAchievementsJargon