Effects

Effects are used in order to affect the game dynamically from within scopes.

Passing arguments to scripted effects

It is possible to pass an argument to a scripted effect by adding it in curly brackets after the effect is called, where you would normally write "yes."

Calling a scripted effect with an argument

   change_color_effect = { my_argument = color }

Defining the argument within the scripted effect Arguments within scripted effects must be surrounded by a dollar character on either side. This is the name of the argument used, without any dollar signs, when called.

e.g.:

  change_color_effect = {
  change_country_color = $my_argument$
  }

List of Effects

Note that this list has been generated programmatically from the output of the "script_docs" console command. Using script_docs, effects supported from multiple scopes are given as being supported from "none" scope only, but this is probably not the case.

Name	Description	Usage	Supported Scopes	Supported Targets
add_building_level	adds one level of the specified Building		province
clear_variable_list	Empties the list	clear_variable_list = variable_name	none
remove_global_variable	Removes a variable	remove_variable = variable_name	none
remove_friend	Removes a friend from the character		character	character
random_in_list	Iterate through all items in list. list = name or variable = name	random_in_list = { limit = { <triggers> } (optional) weight = { mtth } <effects> }	none
ordered_sub_unit	Iterate through all subunits in a unit	ordered_sub_unit = { limit = { <triggers> } order_by = script_value position = int/min = int max = script_value <effects> }	unit	subunit
add_zeal	Adds zeal skill		none
change_variable	Changes the value or a numeric variable	change_variable = { name = X operation = Y } Where X is the name of the numeric variable to modify Where the valid operations are add, subtract, multiply, divide and modulo Where Y is a fixed point value, script value or event target of a value type	none
banish	Banishes a character to another country		character	country
add_research	adds research for a country { technology = table value = percent(0		country
destroy_unit	Destroys the unit from the current scope		unit
add_nickname	gives a nickname to a character		character
move_family	Moves a family to another country		family	country
random_navy	Iterate through all navies in a country	random_navy = { limit = { <triggers> } (optional) weight = { mtth } <effects> }	country	unit
remove_unit_modifier	Removes a modifier from a Unit		unit
every_area_province	Iterate through all provinces in a area	every_area_province = { limit = { <triggers> } <effects> }	area	province
add_health	adds or subtracts health from a character		character
set_culture	Set the culture for this character		character	culture
random_pops_in_province	Iterate through all pops in a province	random_pops_in_province = { limit = { <triggers> } (optional) weight = { mtth } <effects> }	province	pop
declare_war_with_wargoal	Declares a war between this country and the target country		country
ordered_country_state	Iterate through all states in a country	ordered_country_state = { limit = { <triggers> } order_by = script_value position = int/min = int max = script_value <effects> }	country	state
every_sibling	Iterate through all siblings	every_sibling = { limit = { <triggers> } <effects> }	character	character
death	kills a character, death = { killer = X death_reason = Y }, where X is a character and Y is one of the death reason keys		character
add_tyranny	gives (or takes) Tyranny to a country		country
every_country	Iterate through all existing countries	every_country = { limit = { <triggers> } <effects> }	none	country
change_mercenary_employer	Changes a characters employer, if they are mecenary		character	country
random_ownable_province	Iterate through all ownable provinces in the world	random_ownable_province = { limit = { <triggers> } (optional) weight = { mtth } <effects> }	none	province
every_region_area	Iterate through all areas in a region	every_region_area = { limit = { <triggers> } <effects> }	region	area
add_claim	gives the targetcountry a claim on the province.		province	country
break_if	conditionally break execution of effects, break_if = { X }, where X is a trigger		none
random_character	Iterate through all characters in a country	random_character = { limit = { <triggers> } (optional) weight = { mtth } <effects> }	country	character
add_civic_power	Adds CIVIC Power		none
add_subunit_morale	gives (or takes) morale to a subunit		subunit
assert_read	Conditionally cause an assert during read time	assert_read = X, where X is yes or the string to be printed in the assert	none
end_pregnancy	end a pregnancy		character
add_truce	adds a truce for a country towards another country	add_truce = { target = X duration = Y }	country	country
add_to_variable_list	Adds the event target to a variable list	add_to_variable_list = { name = X target = Y } Where X is the name of the variable Where Y is an event target	none
remove_country_modifier	Removes a modifier from a country		country
destroy_subunit	Destroys the unit from the current scope		subunit
move_country	Moves a character to another country (without message_popups)		character	country
remove_opinion	Removes an opinion modifier, remove_opinion = { modifier = X target = Z }	X is a scripted modifier name.	country
add_state_modifier	adds a modifier from a State		state
random_child	Iterate through all children	random_child = { limit = { <triggers> } (optional) weight = { mtth } <effects> }	character	character
random_army	Iterate through all armies in a country	random_army = { limit = { <triggers> } (optional) weight = { mtth } <effects> }	country	unit
every_subject	Iterate through all subject countries	every_subject = { limit = { <triggers> } <effects> }	country	country
add_new_family	adds a new family with the specified name (must be valid from culture files)		country
random_region_state	Iterate through all states in a region	random_region_state = { limit = { <triggers> } (optional) weight = { mtth } <effects> }	region	state
switch	Switch on a trigger for the evaluation of another trigger with an optional fallback trigger.	switch = { trigger = simple_assign_trigger case_1 = { <effects> } case_2 = { <effects> } case_n = { <effects> } fallback = { <effects> }	none
random_neighbour_country	Iterate through all neighbour countries	random_neighbour_country = { limit = { <triggers> } (optional) weight = { mtth } <effects> }	country	country
add_opinion	Adds an opinion modifier, add_opinion = { modifier = X target = Z }	X is a scripted modifier name.	country
create_pop	Creates a specific poptype in a province		province
every_region_province	Iterate through all provinces in a region	every_region_province = { limit = { <triggers> } <effects> }	region	province
random_commander	Iterate through all commanders in a country	random_commander = { limit = { <triggers> } (optional) weight = { mtth } <effects> }	country	character
random_successor	Iterate through all successors in a country	random_successor = { limit = { <triggers> } (optional) weight = { mtth } <effects> }	country	character
ordered_family_member	Iterate through all members of a family	ordered_family_member = { limit = { <triggers> } order_by = script_value position = int/min = int max = script_value <effects> }	family	character
add_morale	gives (or takes) morale to a unit		unit
add_corruption	gives (or takes) Corruption to a character		character
change_country_color	changes the color of a country		country
change_country_adjective	changes the adjective of a country		country
set_variable	Sets a variable	set_variable = { name = X value = Y days = Z } Where X is the name of the variable used to then access it Where Y is any event target, bool, value, script value or flag (flag:W) An optional days where Z is the number of days or script value This variable will be accessible with <type_>var:X. With type being in a scope object or in a top scope	none
clamp_variable	Clamps a variable the specified max and min	clamp_variable = { name = X max = Y min = Z } Where X is the name of the variable Where Y and Z are script values	none
random_neighbor_province	Iterate through all neighbors of a province	random_neighbor_province = { limit = { <triggers> } (optional) weight = { mtth } <effects> }	province	province
random_sub_unit	Iterate through all subunits in a unit	random_sub_unit = { limit = { <triggers> } (optional) weight = { mtth } <effects> }	unit	subunit
remove_triggered_character_modifier	Removes a triggered modifier from a Character		character
ordered_rival	Iterate through all Rivals	ordered_rival = { limit = { <triggers> } order_by = script_value position = int/min = int max = script_value <effects> }	character	character
ordered_governor_state	Iterate through all states a governor is governor of	ordered_governor_state = { limit = { <triggers> } order_by = script_value position = int/min = int max = script_value <effects> }	character	state
add_friend	Adds a friend to the character		character	character
every_area_state	Iterate through all states in a area	every_area_state = { limit = { <triggers> } <effects> }	area	state
every_successor	Iterate through all successors in a country	every_successor = { limit = { <triggers> } <effects> }	country	character
round_global_variable	Rounds a variable to the nearest specified value	clamp_variable = { name = X nearest = Y } Where X is the name of the variable Where Y is a script value	none
ordered_region_province	Iterate through all provinces in a region	ordered_region_province = { limit = { <triggers> } order_by = script_value position = int/min = int max = script_value <effects> }	region	province
set_personal_loyalty	Sets the personal loyalty of a specific subunit to the target character		subunit	character
ordered_countries_at_war_with	Iterate through all countries at war with	ordered_countries_at_war_with = { limit = { <triggers> } order_by = script_value position = int/min = int max = script_value <effects> }	country	country
force_add_trait	Adds a trait to a character (will show tooltip even if already having the trait)		character
every_area	Iterate through all existing areas	every_area = { limit = { <triggers> } <effects> }	none	area
every_unit_in_province	Iterate through all units in a province	every_unit_in_province = { limit = { <triggers> } <effects> }	province	unit
remove_office	Removes a Office from a character		character
random_area_province	Iterate through all provinces in a area	random_area_province = { limit = { <triggers> } (optional) weight = { mtth } <effects> }	area	province
add_finesse	Adds finesse skill		none
set_capital	Changes the capital of a country		country	province
clear_saved_scope	Clears a saved scope from the top scope	save_scope_as = cool_scope -> clear_saved_scope = cool_scope	none
move_country_with_message	Moves a character to another country (with message popups)		character	country
add_rival	Adds a rival to the character		character	character
remove_trait	Removes a trait from a character		character
every_family	Iterate through all families in a country	every_family = { limit = { <triggers> } <effects> }	country	family
random_rival	Iterate through all Rivals	random_rival = { limit = { <triggers> } (optional) weight = { mtth } <effects> }	character	character
ordered_character	Iterate through all characters in a country	ordered_character = { limit = { <triggers> } order_by = script_value position = int/min = int max = script_value <effects> }	country	character
ordered_sibling	Iterate through all siblings	ordered_sibling = { limit = { <triggers> } order_by = script_value position = int/min = int max = script_value <effects> }	character	character
random_allied_country	Iterate through all allied countries	random_allied_country = { limit = { <triggers> } (optional) weight = { mtth } <effects> }	country	country
add_to_list	Adds the current scope to an arbitrarily	add_to_list = <string> NOTE, if adding a permanent target to a temporary list, the whole list becomes permanent	none
random_country_state	Iterate through all states in a country	random_country_state = { limit = { <triggers> } (optional) weight = { mtth } <effects> }	country	state
break	break execution of effects, break = yes/no/boolean event target		none
ordered_subject	Iterate through all subject countries	ordered_subject = { limit = { <triggers> } order_by = script_value position = int/min = int max = script_value <effects> }	country	country
remove_variable	Removes a variable	remove_variable = variable_name	none
add_manpower	gives (or takes) Manpower to a country		country
ordered_neighbour_country	Iterate through all neighbour countries	ordered_neighbour_country = { limit = { <triggers> } order_by = script_value position = int/min = int max = script_value <effects> }	country	country
add_gold	gives (or takes) gold to a character		character
set_pop_religion_same_as	sets the Religion of the pop to be the same as the Religion of the target		pop	pop
remove_province_modifier	Removes a modifier from a Province		province
change_global_variable	Changes the value or a numeric variable	change_variable = { name = X operation = Y } Where X is the name of the numeric variable to modify Where the valid operations are add, subtract, multiply, divide and modulo Where Y is a fixed point value, script value or event target of a value type	none
every_allied_country	Iterate through all allied countries	every_allied_country = { limit = { <triggers> } <effects> }	country	country
random_friend	Iterate through all friends	random_friend = { limit = { <triggers> } (optional) weight = { mtth } <effects> }	character	character
add_military_power	Adds MILITARY Power		none
damage_unit_percent	Applies the given damage to each Cohort in the unit as a percentage of their current strength		unit
remove_as_mercenary	Character stops being a Mercenary		character
refund_price	Refunds a Price from a country		country
set_conquered_by	makes the currrent province owned and controlled by the target country		province	country
adopt	Makes the currently scoped character adopt another character		character	character
every_neighbor_province	Iterate through all neighbors of a province	every_neighbor_province = { limit = { <triggers> } <effects> }	province	province
add_party_conviction	adds party conviction for a character		character
every_rival	Iterate through all Rivals	every_rival = { limit = { <triggers> } <effects> }	character	character
every_countries_at_war_with	Iterate through all countries at war with	every_countries_at_war_with = { limit = { <triggers> } <effects> }	country	country
ordered_family	Iterate through all families in a country	ordered_family = { limit = { <triggers> } order_by = script_value position = int/min = int max = script_value <effects> }	country	family
set_owned_by	makes the currrent province owned and controlled by the target country, without incurring any penalties		province	country
random_support_as_heir	Iterate through all supportasHeir	random_support_as_heir = { limit = { <triggers> } (optional) weight = { mtth } <effects> }	character	character
random_region_area	Iterate through all areas in a region	random_region_area = { limit = { <triggers> } (optional) weight = { mtth } <effects> }	region	area
marry_character	Marries two characters		character	character
random_country	Iterate through all existing countries	random_country = { limit = { <triggers> } (optional) weight = { mtth } <effects> }	none	country
assert_if	Conditionally cause an assert during run time	assert_if = { limit = { X } text = Y }, where X is a trigger and Y is an optional string	none
change_country_tag	changes the historical tag of a country		country
show_model	adds one level of the specified Building		province
set_unit_size	Sets the number of people in each Cohort in the Unit to the given percentage of maximum		unit
set_local_variable	Sets a variable	set_variable = { name = X value = Y days = Z } Where X is the name of the variable used to then access it Where Y is any event target, bool, value, script value or flag (flag:W) An optional days where Z is the number of days or script value This variable will be accessible with <type_>var:X. With type being in a scope object or in a top scope	none
add_permanent_province_modifier	adds a permanent modifier from a Province		province
add_religious_power	Adds RELIGIOUS Power		none
random_governor_state	Iterate through all states a governor is governor of	random_governor_state = { limit = { <triggers> } (optional) weight = { mtth } <effects> }	character	state
add_state_loyalty	adds state loyalty to a province		province
clear_global_variable_list	Empties the list	clear_variable_list = variable_name	none
set_family	Sets the Family of the character		character
random_family	Iterate through all families in a country	random_family = { limit = { <triggers> } (optional) weight = { mtth } <effects> }	country	family
ordered_area	Iterate through all existing areas	ordered_area = { limit = { <triggers> } order_by = script_value position = int/min = int max = script_value <effects> }	none	area
set_trade_goods	Sets the trade goods in a province		province
every_region	Iterate through all existing regions	every_region = { limit = { <triggers> } <effects> }	none	region
random_area_state	Iterate through all states in a area	random_area_state = { limit = { <triggers> } (optional) weight = { mtth } <effects> }	area	state
random	a random effect, random = { chance = X modifier = Y effects... }	where X is a chance of the enclosed effects being fired and can be modified by optional value modifier list (AKA MTTH) Y	none
create_character	creates a character in a country	create_character = { first_name = string culture = <culture> religion = <religion> add_trait = <traits> age = int female = bool family = <family> }	country	character
show_as_tooltip	Effect only shown in tooltips (but not executed)		none
ordered_region	Iterate through all existing regions	ordered_region = { limit = { <triggers> } order_by = script_value position = int/min = int max = script_value <effects> }	none	region
ordered_in_list	Iterate through all items in list. list = name or variable = name	ordered_in_list = { limit = { <triggers> } order_by = script_value position = int/min = int max = script_value <effects> }	none
ordered_navy	Iterate through all navies in a country	ordered_navy = { limit = { <triggers> } order_by = script_value position = int/min = int max = script_value <effects> }	country	unit
change_unit_owner	Destroys the unit from the current scope		unit	country
ordered_allied_country	Iterate through all allied countries	ordered_allied_country = { limit = { <triggers> } order_by = script_value position = int/min = int max = script_value <effects> }	country	country
remove_subunit_loyalty	Removes the personal loyalty of a specific subunit		subunit
save_scope_as	Saves the current scope as an arbitrarily	save_event_target_as = <string>	none
unlock_unit	Unlocks a locked Unit		unit
random_sibling	Iterate through all siblings	random_sibling = { limit = { <triggers> } (optional) weight = { mtth } <effects> }	character	character
add_ruler_conviction	Adds ruler conviction		character
random_region_province	Iterate through all provinces in a region	random_region_province = { limit = { <triggers> } (optional) weight = { mtth } <effects> }	region	province
random_parent	Executes on a random parent		character
hide_model	hides dynamic object on map		province
ordered_in_local_list	Iterate through all items in local list. list = name or variable = name	ordered_in_local_list = { limit = { <triggers> } order_by = script_value position = int/min = int max = script_value <effects> }	none
random_country_sub_unit	Iterate through all subunits in all units in a country	random_country_sub_unit = { limit = { <triggers> } (optional) weight = { mtth } <effects> }	country	subunit
round_local_variable	Rounds a variable to the nearest specified value	clamp_variable = { name = X nearest = Y } Where X is the name of the variable Where Y is a script value	none
set_global_variable	Sets a variable	set_variable = { name = X value = Y days = Z } Where X is the name of the variable used to then access it Where Y is any event target, bool, value, script value or flag (flag:W) An optional days where Z is the number of days or script value This variable will be accessible with <type_>var:X. With type being in a scope object or in a top scope	none
every_governorship_state	Iterate through all states in a governorship	every_governorship_state = { limit = { <triggers> } <effects> }	governorship	state
add_subunit_strength	gives (or takes) Strength to a subunit		subunit
every_province	Executes on every province		none
ordered_pops_in_province	Iterate through all pops in a province	ordered_pops_in_province = { limit = { <triggers> } order_by = script_value position = int/min = int max = script_value <effects> }	province	pop
ordered_commander	Iterate through all commanders in a country	ordered_commander = { limit = { <triggers> } order_by = script_value position = int/min = int max = script_value <effects> }	country	character
every_region_state	Iterate through all states in a region	every_region_state = { limit = { <triggers> } <effects> }	region	state
release_prisoner	Release the target character if imprisoned, release_prisoner = { target = X }, where X is a character		country
add_to_local_variable_list	Adds the event target to a variable list	add_to_variable_list = { name = X target = Y } Where X is the name of the variable Where Y is an event target	none
pay_price	Pays a Price from a country		country
set_pop_type	Set the pop_type for this pop		pop
every_support_as_heir	Iterate through all supportasHeir	every_support_as_heir = { limit = { <triggers> } <effects> }	character	character
remove_list_global_variable	Removes the target from a variable list	remove_list_variable = { name = X target = Y } Where X is the name of the variable Where Y is an event target	none
if	Executes enclosed effects if limit criteria are met	if = { limit = { <triggers> } <effects> }	none
clear_local_variable_list	Empties the list	clear_variable_list = variable_name	none
every_governor_state	Iterate through all states a governor is governor of	every_governor_state = { limit = { <triggers> } <effects> }	character	state
every_commander	Iterate through all commanders in a country	every_commander = { limit = { <triggers> } <effects> }	country	character
ordered_area_province	Iterate through all provinces in a area	ordered_area_province = { limit = { <triggers> } order_by = script_value position = int/min = int max = script_value <effects> }	area	province
change_law	Changes a law in a country		country
random_province	Executes on a random province		none
make_subject	makes the target a subject of the current scope		country
every_unit	Iterate through all units in a country	every_unit = { limit = { <triggers> } <effects> }	country	unit
every_in_global_list	Iterate through all items in global list. list = name or variable = name	every_in_global_list = { limit = { <triggers> } <effects> }	none
add_stability	gives (or takes) Stability to a country		country
ordered_army	Iterate through all armies in a country	ordered_army = { limit = { <triggers> } order_by = script_value position = int/min = int max = script_value <effects> }	country	unit
every_owned_province	Iterate through all owned provinces in a country	every_owned_province = { limit = { <triggers> } <effects> }	country	province
every_in_list	Iterate through all items in list. list = name or variable = name	every_in_list = { limit = { <triggers> } <effects> }	none
ordered_unit_in_province	Iterate through all units in a province	ordered_unit_in_province = { limit = { <triggers> } order_by = script_value position = int/min = int max = script_value <effects> }	province	unit
set_as_governor	sets the governor of a province to the specified character		province	character
ordered_child	Iterate through all children	ordered_child = { limit = { <triggers> } order_by = script_value position = int/min = int max = script_value <effects> }	character	character
add_province_modifier	adds a modifier from a Province		province
every_parent	Executes on every parent		character
remove_unit_loyalty	Removes the personal loyalty of all cohorts in a unit		unit
lock_unit	Locks a Unit for the specified number of days		unit
damage_unit_morale_percent	Applies the given morale damage to each Cohort in the unit as a percentage of their current morale		unit
reset_scoring	Moves a family to another country		none	country
set_pop_culture	Set the culture for this pop		pop	culture
random_unit_in_province	Iterate through all units in a province	random_unit_in_province = { limit = { <triggers> } (optional) weight = { mtth } <effects> }	province	unit
else_if	Executes enclosed effects if limit criteria of preceding 'if' or 'else_if' is not met, and its own limit is met	if = { limit = { <triggers> } <effects> } else_if = { limit = { <triggers> } <effects> }	none
set_graphical_culture	sets the graphical culture of a country		country
every_friend	Iterate through all friends	every_friend = { limit = { <triggers> } <effects> }	character	character
add_to_temporary_list	Adds the current scope to an arbitrarily	add_to_temporary_list = <string> NOTE, if adding a temporary target to a permanent list, the list will stay permanent	none
remove_command	Removes command from a character		character
every_family_member	Iterate through all members of a family	every_family_member = { limit = { <triggers> } <effects> }	family	character
random_governorship_state	Iterate through all states in a governorship	random_governorship_state = { limit = { <triggers> } (optional) weight = { mtth } <effects> }	governorship	state
random_living_character	Executes on a random living character		none
make_pregnant	makes a character pregnant		none
add_loyalty	gives (or takes) Loyalty to a character		character
set_pop_religion	Set the Religion for this pop		pop	religion
imprison	Imprisons the target character as this character's prisoner, imprison = { target = X }, where X is a character		country
reverse_add_opinion	Adds an reverse opinion modifier, reverse_add_opinion = { modifier = X target = Z }	X is a scripted modifier name.	country
add_unit_modifier	adds a modifier from a Unit		unit
round_variable	Rounds a variable to the nearest specified value	clamp_variable = { name = X nearest = Y } Where X is the name of the variable Where Y is a script value	none
hidden_effect	Effect not shown in tooltips		none
add_prestige	gives (or takes) Prestige to a family		family
remove_as_governor	Character stops being a governor		character
set_culture_same_as	sets the culture of the character to be the same as the culture of the target		character	character
ordered_ownable_province	Iterate through all ownable provinces in the world	ordered_ownable_province = { limit = { <triggers> } order_by = script_value position = int/min = int max = script_value <effects> }	none	province
clamp_local_variable	Clamps a variable the specified max and min	clamp_variable = { name = X max = Y min = Z } Where X is the name of the variable Where Y and Z are script values	none
custom_label	just a tooltip, the scope as object (for grouping, localization)		none
pay_gold	the scope character pays gold to the target character, pay_gold = { target = X gold = Y }		character
ordered_country_sub_unit	Iterate through all subunits in all units in a country	ordered_country_sub_unit = { limit = { <triggers> } order_by = script_value position = int/min = int max = script_value <effects> }	country	subunit
every_country_sub_unit	Iterate through all subunits in all units in a country	every_country_sub_unit = { limit = { <triggers> } <effects> }	country	subunit
every_in_local_list	Iterate through all items in local list. list = name or variable = name	every_in_local_list = { limit = { <triggers> } <effects> }	none
ordered_region_state	Iterate through all states in a region	ordered_region_state = { limit = { <triggers> } order_by = script_value position = int/min = int max = script_value <effects> }	region	state
add_civilization_value	adds civilisation to a province		province
add_party_support	adds party support for a country		country
random_area	Iterate through all existing areas	random_area = { limit = { <triggers> } (optional) weight = { mtth } <effects> }	none	area
set_gender_equality	sets gender equality for a country		country
random_subject	Iterate through all subject countries	random_subject = { limit = { <triggers> } (optional) weight = { mtth } <effects> }	country	country
random_in_local_list	Iterate through all items in local list. list = name or variable = name	random_in_local_list = { limit = { <triggers> } (optional) weight = { mtth } <effects> }	none
change_local_variable	Changes the value or a numeric variable	change_variable = { name = X operation = Y } Where X is the name of the numeric variable to modify Where the valid operations are add, subtract, multiply, divide and modulo Where Y is a fixed point value, script value or event target of a value type	none
add_character_modifier	adds a modifier to a Character		character
ordered_support_as_heir	Iterate through all supportasHeir	ordered_support_as_heir = { limit = { <triggers> } order_by = script_value position = int/min = int max = script_value <effects> }	character	character
while	Repeats enclosed effects while limit criteria are met or until set iteration count is reached	while = { limit = { <triggers> } <effects> } while = { count = 3 <effects> } Default max of 1000.	none
add_to_global_variable_list	Adds the event target to a variable list	add_to_variable_list = { name = X target = Y } Where X is the name of the variable Where Y is an event target	none
every_character	Iterate through all characters in a country	every_character = { limit = { <triggers> } <effects> }	country	character
add_charisma	Adds charisma skill		none
create_state_pop	Creates a specific poptype with the countrys religion/culture in a province		province
clamp_global_variable	Clamps a variable the specified max and min	clamp_variable = { name = X max = Y min = Z } Where X is the name of the variable Where Y and Z are script values	none
remove_rival	Removes a rival from the character		character	character
create_country	creates a country in the given province		none	province
change_government	Removes a modifier from a country		country
ordered_region_area	Iterate through all areas in a region	ordered_region_area = { limit = { <triggers> } order_by = script_value position = int/min = int max = script_value <effects> }	region	area
create_unit	Creates a Unit with a single cohort for a Country given by the current scope.	The cohort will be of the first defined type in the unit type db. Optional properties: name [string, defaults to generated name] navy [bool, defaults to no] mercenary [bool, defaults to no] location [Province, defaults to capital of country scope] commander [Character, defaults to none] attachto [Unit, will not attach by default]	country	unit
define_pop	sets up a pop culture/religion/type possible to set.		province
add_oratory_power	Adds ORATORY Power		none
add_loyal_subunit	Adds a subunit to a Unit		unit
every_sub_unit	Iterate through all subunits in a unit	every_sub_unit = { limit = { <triggers> } <effects> }	unit	subunit
ordered_owned_province	Iterate through all owned provinces in a country	ordered_owned_province = { limit = { <triggers> } order_by = script_value position = int/min = int max = script_value <effects> }	country	province
random_region	Iterate through all existing regions	random_region = { limit = { <triggers> } (optional) weight = { mtth } <effects> }	none	region
change_country_name	changes the name of a country		country
ordered_governorship_state	Iterate through all states in a governorship	ordered_governorship_state = { limit = { <triggers> } order_by = script_value position = int/min = int max = script_value <effects> }	governorship	state
random_family_member	Iterate through all members of a family	random_family_member = { limit = { <triggers> } (optional) weight = { mtth } <effects> }	family	character
every_navy	Iterate through all navies in a country	every_navy = { limit = { <triggers> } <effects> }	country	unit
else	Executes enclosed effects if limit criteria of preceding 'if' or 'else_if' is not met	if = { limit = { <triggers> } <effects> } else = { <effects> }	none
ordered_unit	Iterate through all units in a country	ordered_unit = { limit = { <triggers> } order_by = script_value position = int/min = int max = script_value <effects> }	country	unit
add_trait	Adds a trait to a character		character
add_road_towards	adds a road towards the target		province	province
every_country_state	Iterate through all states in a country	every_country_state = { limit = { <triggers> } <effects> }	country	state
ordered_in_global_list	Iterate through all items in global list. list = name or variable = name	ordered_in_global_list = { limit = { <triggers> } order_by = script_value position = int/min = int max = script_value <effects> }	none
random_list	a random list effect	random_list = { X1 = { trigger = { enables/disable this effect} modifier/compare_modifier/opinion_modifier = Y1 effect1 } X2 = { trigger = { enables/disable this effect} modifier/compare_modifier/opinion_modifier = Y2 effect2 } ... } Selects one effect from the list and fires it. The effects are weighted by numbers X1, X2... (the higher the number, the higher the chance of the effect being picked). The chances can be modified by optional value modifier lists Y1, Y2... (AKA MTTH)	none
clear_ambition	Clear the ambition for this character		character
every_neighbour_country	Iterate through all neighbour countries	every_neighbour_country = { limit = { <triggers> } <effects> }	country	country
add_prominence	gives (or takes) Prominence to a character		character
add_treasury	gives (or takes) Treasury to a country		country
add_triggered_character_modifier	adds a cancellable modifier to a Character		character
remove_local_variable	Removes a variable	remove_variable = variable_name	none
every_state_province	Iterate through all provinces in a state	every_state_province = { limit = { <triggers> } <effects> }	state	province
remove_party_leadership	remove the leader from a party in a country		country
add_martial	Adds martial skill		none
add_popularity	gives (or takes) Popularity to a character		character
remove_claim	removes the targetcountry's claim on the province.		province	country
set_character_religion	Set the religion for this character		character	religion
every_living_character	Executes on every living character		none
debug_log_scopes	Log the current scope to the game log when this effect executes yes = full scope info, no=only current scope		none
set_pop_culture_same_as	sets the culture of the pop to be the same as the culture of the target		pop	pop
ordered_country	Iterate through all existing countries	ordered_country = { limit = { <triggers> } order_by = script_value position = int/min = int max = script_value <effects> }	none	country
break_alliance	country in scope breaks any applicable alliance with the target		none	country
change_country_flag	changes the flag of a country		country
ordered_state_province	Iterate through all provinces in a state	ordered_state_province = { limit = { <triggers> } order_by = script_value position = int/min = int max = script_value <effects> }	state	province
set_ambition	Set the ambition for this character		character
set_primary_culture	Sets primary culture for a country		country	culture
every_child	Iterate through all children	every_child = { limit = { <triggers> } <effects> }	character	character
ordered_area_state	Iterate through all states in a area	ordered_area_state = { limit = { <triggers> } order_by = script_value position = int/min = int max = script_value <effects> }	area	state
random_state_province	Iterate through all provinces in a state	random_state_province = { limit = { <triggers> } (optional) weight = { mtth } <effects> }	state	province
remove_all_offices	Removes all Offices from a character		character
give_office	Gives a Office to a character		character
ordered_neighbor_province	Iterate through all neighbors of a province	ordered_neighbor_province = { limit = { <triggers> } order_by = script_value position = int/min = int max = script_value <effects> }	province	province
set_controller	makes the currrent province controlled by the target country, if province owner and target are at war		province	country
add_subunit	Adds a subunit to a Unit		unit
create_family	creates a family for the target character		country	character
add_country_modifier	adds a modifier from a country		country
move_pop	moves the pop to target province.		pop	province
remove_list_local_variable	Removes the target from a variable list	remove_list_variable = { name = X target = Y } Where X is the name of the variable Where Y is an event target	none
add_aggressive_expansion	adds or removes aggressive expansion for a country		country
add_centralization	gives (or takes) centralization to a country		country
add_legitimacy	gives (or takes) Legitimacy to a country		country
every_pops_in_province	Iterate through all pops in a province	every_pops_in_province = { limit = { <triggers> } <effects> }	province	pop
trigger_event	triggers an event or on_action	trigger_event = { id = X days/months/years = Y } (for events) or trigger_event = { on_action = X days/months/years = Y } (for on_actions) Days/months/years are optional and equal to 0 if not specified. If specified, Y can be a value or an inclusive interval "{ A B }" from which the duration will be picked randomly.	none
debug_log	Log a string to the debug log when this effect executes, debug_log = message, the message can be a localization string with ROOT, SCOPE and PREV available		none
set_as_ruler	sets the ruler of a country to the specified character		country	character
set_as_coruler	sets the co ruler of a country to the specified character		country	character
every_army	Iterate through all armies in a country	every_army = { limit = { <triggers> } <effects> }	country	unit
add_war_exhaustion	gives (or takes) war exhaustion to a country		country
custom_tooltip	just a tooltip, the scope as subject (for grouping, localization)		none
random_in_global_list	Iterate through all items in global list. list = name or variable = name	random_in_global_list = { limit = { <triggers> } (optional) weight = { mtth } <effects> }	none
remove_list_variable	Removes the target from a variable list	remove_list_variable = { name = X target = Y } Where X is the name of the variable Where Y is an event target	none
random_unit	Iterate through all units in a country	random_unit = { limit = { <triggers> } (optional) weight = { mtth } <effects> }	country	unit
random_countries_at_war_with	Iterate through all countries at war with	random_countries_at_war_with = { limit = { <triggers> } (optional) weight = { mtth } <effects> }	country	country
random_owned_province	Iterate through all owned provinces in a country	random_owned_province = { limit = { <triggers> } (optional) weight = { mtth } <effects> }	country	province
set_as_commander	sets the commander of a unit to the specified character		unit	character
save_temporary_scope_as	Saves the current scope as an arbitrarily	save_temporary_event_target_as = <string>	none
remove_character_modifier	Removes a modifier from a Character		character
ordered_friend	Iterate through all friends	ordered_friend = { limit = { <triggers> } order_by = script_value position = int/min = int max = script_value <effects> }	character	character
remove_from_list	Removes the current scope from a named list remove_from_list = <string>		none
kill_pop	Kill the pop in the current scope		pop
remove_state_modifier	Removes a modifier from a State		state
ordered_successor	Iterate through all successors in a country	ordered_successor = { limit = { <triggers> } order_by = script_value position = int/min = int max = script_value <effects> }	country	character
remove_as_researcher	Character stops being a researcher		character
set_country_religion	Sets religion for a country		country

Script Values

For many effects that use numeric values, Imperator supports script values, which can be: - Simple Values - Ranges - Formulas

Simple Values

Simple values are strings that define a value, which can then be used in place of an explicit value. For example:

medium_gold_amount = 50

This is defined in the common/script_values folder, and can then be used in effects such as add_treasury like so:

add_treasury = medium_gold_amount

Ranges

Ranges allow for values to be randomised between two specified values. For example:

add_treasury = { 10 50 }

This would give a random amount of gold between 10 and 50.

Formulas

Formulas allow mathematical operations to be performed on values in a simple manner. For example, if you wanted to scale a value based on a ruler's zeal:

add_treasury = {
    value = 50
    multiply = root.current_ruler.zeal
}

This would set the base value to 50 and then multiply it by the current ruler's Zeal value.

Here is the format of formulas:

<effect> = {
    value = <int> / <float> / <scope>       # Set base value
    add = <int> / <float> / <scope>         # Add to value
    subtract = <int> / <float> / <scope>    # Subtract from value
    multiply = <int> / <float> / <scope>    # Multiply value
    divide = <int> / <float> / <scope>      # Divide value
    max = <int> / <float> / <scope>         # Cap positive values to this value
    min = <int> / <float> / <scope>         # Cap negative values to this value
    
    ceiling = yes   
    floor = yes     
    round = yes
    
    # Random float between min and max
    fixed_range = {
        min = <num>
        max = <num>
    }
    
    # Random integer between min and max
    integer_range = {
        min = <num>
        max = <num>
    }
    
    # Effect scopes can be used within a formula
    <effects>
}

Note that you can nest formulas within one another.

Flow Control

These are effects that alter the flow of execution in some way.

Hidden Effect

It is possible to hide the automatic tooltip that effect generate, especially if you want the result of the effect to be hidden to the player.

You can do this by using the hidden_effect scope around the effects you wish to hide. The format is as follows:

hidden_effect = {
    <effects>
}

Tooltip

It is possible to display the automatic tooltip that effects generate without actually executing the effects.

You can do this by using the tooltip scope around the effects. The format is as follows:

show_as_tooltip = {
    <effects>
}

If, Else if and Else

The if, else_if and else scopes are used to introduce effects within an effect scope that hidge on a set of trigger values.

The format of a basic IF scope:

if = {
    limit = {
        <triggers>
    }
    
    <effects>
}

The format for the combination of IF, ELSE_IF and ELSE scopes:

if = {
    limit = {
        <triggers>
    }
    <effects>
}   
 
# optional - executed when the trigger values return false, and the else_if trigger values return true
else_if = {
    limit = {
        <triggers
    }
    <effects>
}
    
# optional - executed when the trigger values return false
else = {
    <effects>
}

Note that you can nest if scopes, allowing for multiple layers of triggers and effects.

Switch

The switch scope is used in conjuction with triggers. You list each trigger value you wish to act on, and add the effects within.

The format is as follows:

switch = {
    trigger = <trigger>
    <trigger value> = { <effect> }
    <trigger value> = { <effect> }
    
    # Used if none of the trigger cases are met
    fallback = {
        <effect>
    }
}

While

The while scope is used to repeat execution of a set of effects whilst a set of trigger values remain true.

The format is as follows

while = {
    limit = {
        <triggers>
    }
    
    <effects>
    
    count = <int>   # Define how many iterations the while loop should undergo, otherwise it will use the default max of 100,000.
}

Note:

• A while scope loop will continue for 100,000 loops if the trigger values never become false. After which, it will terminate.

Due to the nature of execution flow in game, you ideally need to add effects within the while scope effect section that make the trigger values false. There is no way to reduce the execution rate, so the effects will be triggered multiple times a second otherwise.

Break

The break effect can be used to stop execution of effects in the current scope. The format is as follows:

break = yes

This can be done conditionally by using the break_if scope. The format is as follows:

break_if = {
    limit = {
        <triggers>
    }
    
    weight = {
        <mtth>
    }
    
    <effects>
}

Random and Random Lists

It is possible to randomly execute effects with both the random and random_list scopes.

The random scope is used to add a single random roll to a set of effects. The format is as follows:

random = { 
    chance = 50 

    # Modify the random chance if the triggers are met. Optional.
    modifier = {
        factor = <value>
        
        <triggers>
    }
    
    <effects>
}

The random_list scope is used to add different sets of effects to a single random roll. The format is as follows:

random_list = {
    # Add as many entries as need
    <weight> = {
    
        # Removes this entry in the list if the triggers are met. Optional.
        trigger = {
            <triggers>
        }
        
        <effects>
    }
}

Debugging

These are effects that are used for debugging:

Log

You can log strings to game.log by using the following effect:

debug_log = <string>

You can log scopes as well with the following effect:

debug_log_scopes = <bool>

For debug_log_scopes, yes will return full scope info, where as no will return only the current scope info.

Assert

You can assert with the following effect:

assert_read = <string> / <bool>

You can also assert conditionally with assert_if, which follows this format:

assert_if = {
    limit = { <triggers> }
    text = <string>
}

Modding

Audio

Music • Sound