Open main menu

Event modding

Events are the meat of every well-rounded mod; smaller and larger bits of story that can happen to a player during the campaign. In order to mod new ones in, you should start with an empty txt file in the events directory below your mod's root folder.



The overall structure is similar to that of a CK2 event, with some tweaks to the syntax and a whole lot of extra features, many of them optional. The barest possible event is laid out here, and each element is described individually in a later section.

example.1 = {
	desc = example.1.desc
	option = {
		name = example.1.a

There you go! Add this to your mod, trigger it from the in-game console using "event triggers [example.1]", and you have got yourself a working event! Everything else is optional, but necessary to really flesh out the events.

ID and namespaceEdit

The ID uniquely identifies your event.


These are top-level variables that determine your event's kind and appearance. They have a limited set of values.

Flag Meaning Possible values
type The kind of event. It determines what sort of scope the root is. * character_event
  • none (when an event doesn't use the root scope at all)
hidden Set this to true, and the event will not be shown at all; it will happen in the background. Useful for doing maintenance events that are not immediately relevant to the player. true, false


In Crusader Kings III, portraits are now in 3D, and can now be animated as well! What follows is a list of the different portrait positions, as well as a list of animations for them.

Portrait PositionsEdit

Portrait Positions
Portrait Position Description
left_portrait Shown on the left side of the event scene.
right_portrait Shown on the right side of the event scene.
lower_left_portrait Shown on the lower left part of the event scene.
lower_center_portrait Shown on the lower center part of the event scene.
lower_right_portrait Shown on the lower right part of the event scene.

Here is an example of all of the portrait positions in use at the same time, along with a screenshot:

example_event.1001 = {
	left_portrait = {
		character = ROOT # Whoever this is scoped to will show up in this event window position, exhibiting the chosen animation. 
		animation = fear # Take note that characters with SOME genetic traits (for example, gigantism, dwarfism) that change their character models have different animations, and if you assign one of THOSE animations to a character that does not have that model, crashes may occur.
	right_portrait = {
		character = ROOT
		animation = scheme
	lower_left_portrait = {
		character = ROOT
	lower_center_portrait = {
		character = ROOT
	lower_right_portrait = {
		character = ROOT


happiness dismissal prison_dungeon admiration
disgust schadenfreude stress personality_compassionate
pain ecstasy fear rage
anger flirtation_left shame boredom
shock worry scheme personality_bold
personality_callous personality_irrational personality_content flirtation
disbelief personality_cynical personality_rational personality_dishonorable
idle paranoia personality_vengeful disapproval
sick beg personality_zealous newborn
love sadness personality_honorable personality_forgiving
personality_greedy personality_coward severelyinjured severelywounded
war_attacker war_defender war_over_win grief


abduct_scheme alliance bastardy battle
befriend_scheme claim_throne_scheme corruption crown
culture_change death default diplomacy
diplomacy_family_focus diplomacy_foreign_affairs_focus diplomacy_majesty_focus dread
dungeon dynasty education fabricate_hook_scheme
faith family feast_activity friend_relation
friendly generic_intrigue_scheme healthcare hunt_activity
hunting intrigue intrigue_intimidation_focus intrigue_skulduggery_focus
intrigue_temptation_focus learning learning_medicine_focus learning_scholarship_focus
learning_theology_focus love lover_relation marriage
martial martial_authority_focus martial_chivalry_focus martial_strategy_focus
medicine mental_break mental_health murder_scheme
party pet physical_health pilgrimage_activity
pregnancy prison realm recovery
rival_relation romance_scheme secret seduce_scheme
seduction skull stewardship stewardship_domain_focus
stewardship_duty_focus stewardship_wealth_focus sway_scheme unfriendly
vassal war witchcraft

override_background, override_icon, override_sound, override_environment


alley_day alley_night armory army_camp
battlefield bedchamber burning_building corridor_day
corridor_night council_chamber courtyard docks
dungeon farmland feast gallows
garden market market_east market_india
market_tribal market_west physicians_study sitting_room
study tavern temple temple_church
temple_generic temple_mosque temple_scope terrain
terrain_activity terrain_scope throne_room throne_room_east
throne_room_india throne_room_mediterranean throne_room_scope throne_room_tribal
throne_room_west wilderness wilderness_desert wilderness_forest
wilderness_forest_pine wilderness_mountains wilderness_scope wilderness_steppe


When you've selected a background, the appropriate environment is automatically selected. Only overwrite it when necessary.

environment_body environment_council environment_cw_east_main
environment_cw_east_spouse environment_cw_east_throneroom_main environment_cw_east_throneroom_spouse
environment_cw_india_main environment_cw_india_spouse environment_cw_india_throneroom_main
environment_cw_india_throneroom_spouse environment_cw_mediterranean_main environment_cw_mediterranean_spouse
environment_cw_mediterranean_throneroom_main environment_cw_mediterranean_throneroom_spouse environment_cw_tavern
environment_cw_tavern_spouse environment_cw_tribal_main environment_cw_tribal_spouse
environment_cw_west environment_cw_west_spouse environment_event_alley
environment_event_alley_day environment_event_armory environment_event_battlefield
environment_event_bedchamber environment_event_church environment_event_corridor_day
environment_event_courtyard environment_event_desert environment_event_docks
environment_event_dungeon environment_event_farms environment_event_feast
environment_event_forest environment_event_forest_pine environment_event_gallows
environment_event_garden environment_event_genericcamp environment_event_market_east
environment_event_market_tribal environment_event_market_west environment_event_mosque
environment_event_mountains environment_event_sittingroom environment_event_standard
environment_event_steppe environment_event_study environment_event_study_physician
environment_event_tavern environment_event_temple environment_event_throne_room_west
environment_frontend_east_heir environment_frontend_east_main environment_frontend_east_secondary
environment_frontend_india_heir environment_frontend_india_main environment_frontend_india_secondary
environment_frontend_mediterranean_heir environment_frontend_mediterranean_main environment_frontend_mediterranean_secondary
environment_frontend_tribal_heir environment_frontend_tribal_main environment_frontend_tribal_secondary
environment_frontend_west_heir environment_frontend_west_main environment_frontend_west_secondary
environment_head environment_hud environment_portrait_editor
environment_shoulders environment_standard environment_torso


This is an additional requirement for an event to work.


Runs when the trigger fails.


Explain how a description can be composed of multiple strings; with stuff like first_valid, and all the alternatives.


This is a block of effect script: it will be ran immediately as your event is triggered, before the title, description, portraits, are even evaluated let alone rendered. This block is useful for setting variables and saving scopes to use in your text or for portraits; or for functional effects that you want to happen without the player having any control over it.

"has happened" tooltip.


Name is required.


This is a block of effect script that runs after the event has ran its course and an option has been chosen.


What types of widgets are there, with screenshots for each of what they look like.


on_actions are divided into two main types: (1) Those that are called from Code and (2) Those that are called from Script.

On_actions from CodeEdit

Name Description From Code Expected Scope Other
on_prestige_level_loss Yes None
on_rank_down Yes None
on_weight_changed Yes Character
on_faith_monthly Yes Faith
on_knight_combat_pulse Yes Character
on_war_invalidated Yes None
on_war_transferred Yes Character
on_divorce Yes None
on_leave_court Yes Character
on_guest_ready_to_move_to_pool Yes Character
on_guest_arrived_from_pool Yes Character
on_siege_completion Yes Character
on_war_won_attacker Yes Character
on_alliance_added Yes None
on_pregnancy_mother Yes Character
on_raid_action_start Yes None
on_county_faith_change Yes Landed Title
on_title_gain_usurpation Yes None
on_release_from_prison Yes Character
random_yearly_playable_pulse Yes Character
on_raid_action_completion Yes Army
on_death Yes Character
on_birth_father Yes None
on_betrothal_broken Yes None
on_war_white_peace Yes None
three_year_playable_pulse Yes Character
on_defeat_raid_army Yes Army
on_army_enter_province Yes Character
on_join_court Yes Character
on_fired_from_council Yes Character
on_raid_loot_delivered Yes Army
on_pregnancy_ended_mother Yes None
on_title_lost Yes None
on_title_gain Yes Character
on_character_culture_change Yes Character
on_birth_child Yes Character
on_holy_order_hired Yes None
on_great_holy_war_invalidation Yes Great Holy War
on_combat_end_loser Yes Combat Side
on_concubinage Yes None
on_commander_combat_pulse Yes Character
random_yearly_everyone_pulse Yes Character
five_year_everyone_pulse Yes Character
on_perks_refunded Yes None
quarterly_playable_pulse Yes None
on_prestige_level_gain Yes None
on_faith_created Yes Character
on_holy_order_new_lease Yes None
on_title_gain_inheritance Yes None
on_game_start Yes None
on_character_faith_change Yes Character
on_combat_end_winner Yes Combat Side
on_courtier_decided_to_move_to_pool Yes Character
on_culture_era_changed Yes None
on_birthday Yes Character
on_faith_conversion Yes Character
on_raid_action_weekly Yes None
on_explicit_claim_gain Yes Character
on_courtier_ready_to_move_to_pool Yes Character
on_potential_great_holy_war_invalidation Yes Great Holy War
on_holy_order_destroyed Yes None
on_war_won_defender Yes None
yearly_global_pulse Yes None
on_great_holy_war_countdown_end Yes GreaT Holy War
yearly_playable_pulse Yes Character
three_year_pool_pulse Yes Character
on_pregnancy_father Yes None
on_piety_level_loss Yes None
on_piety_level_gain Yes None
on_siege_looting Yes None
on_title_destroyed Yes None
on_army_monthly Yes None
on_game_start_after_lobby Yes None
on_imprison Yes Character
on_birth_mother Yes Character
on_dynasty_created Yes None
on_alliance_removed Yes None
on_county_occupied Yes None
on_rank_up Yes None
on_vassal_become_powerful Yes None
on_join_war_as_secondary Yes Character
on_explicit_claim_lost Yes Character
on_alliance_broken Yes None
on_natural_death_second_chance Yes None
on_leave_council Yes Character
on_county_culture_change Yes None
on_war_started Yes None
on_marriage Yes Character
on_great_holy_war_participant_replaced Yes Character
five_year_playable_pulse Yes Character
on_birth_real_father Yes None
on_game_start_with_tutorial Yes None

On_actions Not From CodeEdit


Triggering the eventEdit

Should probably become its own page.

Techniques and design patternsEdit

Pinging events, message events.

Other fancy ideas.