=== Structure ===

Note: this is very very incomplete...

event_namespace.42 = {
	type = character_event/letter_event/court_event/activity_event # Default to character, what type of event this is
	scope = scope_type # Optional, defaults to character, will make this event fire with a different expected root scope. none can be used to have no scopes set up.
	window = window_name # Optional, what special event file and widget in gui/event_windows should this event use, only used for character events

	# If you have a cooldown, the recipient will get a variable saved with that duration. The variable name will be the event ID
	# Anything that checks that an event is legal to fire will also check that the recipient doesn't have that variable
	cooldown = {
		days/weeks/months/years = script value
	}

	# DLC or Mod that this Event belongs to, shown in Event Window if set.
	content_source = X

	# Specify a character portrait to appear in the event on the specified position.
	left_portrait = X
	right_portrait = X
	center_portrait = X # not used in all event types
	lower_left_portrait = X
	lower_center_portrait = X
	lower_right_portrait = X
	sender = X # for letter events, required
	# X can be one of:
		X = event target
		X = {
			character = event target
			trigger = ... # optional, a trigger saying whether this portrait should be visible, in the scope of the portrait character, the event scope is accessible as root scope
			animation = animation name	# optional, the animation to show for this portrait. It's used if no triggered animations pass their trigger. The default animation will be used if nothing is this item is not specified.
			scripted_animation = key_of_scripted_animation # optional, instead of 'animation' you can also define a 'scripted_animation'

			# A list of triggered animations. The first triggered animation that passes the trigger check will be used.
			triggered_animation = {
				trigger = ...
				animation = animation name
				# Instead of 'animation' you can also define a 'scripted_animation'
				scripted_animation = key_of_scripted_animation

				### brief: camera ( database key, optional )
				# A camera type defined for a triggered animation will override the default
				# camera defined for the event portrait if that animation is chosen
				#
				camera = camera_name
			}
			triggered_animation = ...
			
			# A list of triggered outfits. The first triggered otfit that passes the trigger check will be used.
			triggered_outfit = {
				trigger = ...
				outfit_tags = ...
				remove_default_outfit = ...
				hide_info = ...
			}
			triggered_outfit = ...

			# Override camera to be used instead of the normal event ones
			camera = camera_key
			
			outfit_tags = { tag1 tag2 }	# Specifies outfit tags for this portrait in ascending priority (i.e. tag2 will "override" tag1 here if anything with tag2 is found in a specific portrait modifier category)
			remove_default_outfit = yes/no	# If set to yes, portrait modifier categories in which nothing matches any of the event tags will be disabled completely (no by default)
			hide_info = yes/no			# If set to yes, only the portrait will be shown, with no identifiable elements (no CoA, tooltips, clicks...) (no by default)
		}
	
	# Specify an artifact to appear in the event on the specified position
	artifact = {
		target = event target
		position = lower_left_portrait/lower_center_portrait/lower_right_portrait
		# Can't be in the same position as a portrait
		trigger = ... # Optional, as for character portraits
	}

	# This will be run if a queued event (or one triggered immediately from script) does not fulfil its trigger
	# Events failing to trigger from an on-action will *not* run this
	on_trigger_fail = {
		some effect
	}

	# Specify custom widgets to embed in the event. See section about Custom Widgets below.
	widgets = {
		widget = {
			# Trigger that controls the availability of the widget. Scope: same as the event, after immediate effect. Default: always = yes
			is_shown = {}
			# Name of the widget to use. Must be at the path <event_window_widgets>/<widget_name>.gui
			gui = "<widget_name>"
			# Name of the widget where this custome widget will be insert
			container = "<container_widget_name>"
			# Some widgets require a custom controller (see below). Default: default
			controller = <controller_type>
			# Effect to set up the scope as required by the controller. Scope: same as the event, after immediate effect, doesn't modify the event scope, though. Default: {}
			setup_scope = {}
		}
	}
	widget = { ... } 		# alternative syntax for a single widget. Follows the same info as the widget in the widgets parameter
	
	option = { # An option the player/AI can pick
		# Localization key for the event option button text
		name = X
		
		# The effects that will be run when picking the options. Written directly here with no label
		X..

		# A trigger that has to be fulfilled for this option to be valid.
		trigger = {}

		# If the event is invalid, but this trigger is valid, then the option will be shown (but disabled).
		# This behavior is also influenced by the EVENT_OPTIONS_SHOWN_HIDE_UNAVAILABLE or SCHEME_PREPARATION_OPTIONS_SHOWN_HIDE_UNAVAILABLE defines depending on event type.
		show_as_unavailable = {}

		# Highlights the event portrait of this character while this option is hovered. This is in addition to the automatic highlighting when hovering an event option that has an effect that affects portrait characters.
		highlight_portrait = scope:a_character

		reason = <flag> # Special reason for why this option is unlocked, can be any arbitrary string, is be checked in the UI to show special by reason

		# Parameters to impact the way ai-characters pick options to resolve their events
		# We have 2 mutually exclusive parameters; ai_chance, and ai_will_select where the only difference is the syntax for calculating the value
		ai_chance = { # See common/scripted_modifiers/_scripted_modifiers.info for more details
			base = 10
			modifier = {
				add = 5
				<trigger>
			}
			modifier = {
				factor = 0.5
				<trigger>
			}
		}

		ai_will_select = { # See common/script_values/_script_values.info for more details
			base = 10
			if = {
				limit = {
					<trigger>
				}
				add = 5
			}
			else_if = {
				limit = {
					<trigger>
				}
				multiply = 0.5
			}
		}
	}

	theme = ""					# Theme to use in the event. For a list, check: 00_event_themes.txt
	override_background = {		# A background that can be shown when the event pops up. This overrides the theme one. In case that there are multiples the first one that fits the trigger will be the one selected. In case none fits the ones inthe theme will be checked after.
		trigger = {}			# Receives the event scope to check if it's valid.
		reference = "" 			# Path to the texture
	}
	override_transition = {		# A transition that can be shown when the event pops up, before the event options and backgrounds. This overrides the theme one. In case that there are multiples the first one that fits the trigger will be the one selected. In case none fits the ones inthe theme will be checked after.
		trigger = {}			# Receives the event scope to check if it's valid.
		reference = "" 			# Path to the texture
	}
	override_effect_2d = {		# A 2d effect that can be put on top of the background. This overrides the theme one. In case that there are multiples the first one that fits the trigger will be the one selected. In case none fits the ones inthe theme will be checked after.
		trigger = {}			# Receives the event scope to check if it's valid.
		reference = "" 			# key to the effect
	}
	override_icon = {			# An icon that can be shown when the event pops up. This overrides the theme one. In case that there are multiples the first one that fits the trigger will be the one selected. In case none fits the ones inthe theme will be checked after.
		trigger = {}			# Receives the event scope to check if it's valid.
		reference = "" 			# Path to the texture
	}
	override_header_background = { # The header asset located behind the event icon. This overrides the header asset defined by the theme. If there are multiples defined here, the first one that passes its trigger will be selected. If none are valid, then the theme's header asset will be used
		trigger = {}
		reference = ""
	}
	override_sound = {			# A sound that can be played when the event pops up. This overrides the theme one. In case that there are multiples the first one that fits the trigger will be the one selected. In case none fits the ones inthe theme will be checked after.
		trigger = {}			# Receives the event scope to check if it's valid.
		reference = "" 			# Reference of the sound
	}
	orphan = yes 				# The game will not log an error about this event being unreferenced. Useful for debug events
}

=== Custom Widgets ===

Custom widgets can be embedded into events.
GUI files must be placed at the event_window_widgets path (see paths.settings). The name of the file must match the widget name.

Some widgets that modify the game require a custom controller. This should be documented in the widget's GUI file.
The data context type available in the GUI depends on the controller type.

Some controllers require special scope setup, which should be documented under Notes below. Use the setup_scope effect for that.

Available controllers:

Controller Type         | Data Context Name                      | Notes
------------------------+----------------------------------------+-------------------------------------------------------------------------------------------------------------
default                 | EventWindowWidget                      | Default controller, no special behavior
name_character          | EventWindowWidgetNameCharacter         | Changes a character's name. Scope must have the name_character_target saved scope.
text                    | EventWindowWidgetEnterText             | Saves some text onto the character.
event_chain_progress    | EventWindowWidgetChainProgress         | Displays progress through an event chain, needs event_chain_length and event_chain_progress scope values set
struggle_info           | EventWindowCustomWidgetStruggleInfo    | Displays information for the struggle, needs "start" scope value set
situation_info          | EventWindowCustomWidgetSituationInfo   | Displays information for the situation
