N3OW/common/character_interactions/_character_interactions.info

=== Notes ===
This info is a WIP.

=== Structure ===

my_interaction = {
	interface_priority = number							# Used by interaction menu. Sorts interactions
														# by this (higher first), after categorization 
														# and placing in More... menu

	common_interaction = yes/no							# Used by interaction menu. Common interactions
														# are not never placed in the More... submenu

	category = interaction_category_hostile 			# Required! Used by interaction menu. Groups 
														# interaction in this category. 

	filter_tags = { string1 string2 }					# Used by ToggleFilteredCharacterInteractionMenu
														# to open a subset of the interaction menu with
														# only the interactions that have a matching
														# filter_tag or category
														# These are localized with _filter_tag_desc as a
														# suffix when they appear in the interaction menu

	icon = key 											# What icon to use. If an icon is used for more
														# than one interaction; please consider making
														# it general (such as icon_culture for 
														# interactions relating to culture or
														# icon_personal for personal schemes.).
														# Otherwise defaults to none/the my_interaction
														# key + related my_interaction.dds in
														# gfx/interface/icons/character_interactions

	override_background = { reference = relaxing_room }	# Used to define which image is used as the
														# background for the interaction window. These
														# can use triggers.
														#
														# Root is scope:actor for the interaction. If
														# there are no backgrounds defined or none are
														# valid, the interaction gui will default to
														# "study"


	is_highlighted = trigger							# Should the interaction be highlighted in
														# the interaction menu. Not highlighted if 
														# is_valid or is_valid_showing_failures_first is false

	highlighted_reason = loc_key						# Tooltip if highlighted in menu

	on_decline_summary = dynamic description			# Flavor text that is shown under acceptance
														# widget. Use it when you need to draw more
														# attention to the on decline effect

	special_interaction = type							# This interaction uses specialized GUI

	special_ai_interaction = type						# This interaction runs specialized code that
														# identifies the interaction by this

	interface = call_ally/marriage/grant_titles/etc. 	# What interface does the interaction use?

	custom_character_sort = { }							# What custom character sort options should the
														# interaction have available? Last one defined
														# will show up first in the dropdown list.
														#
														# Current Options:
														# 	candidate_score (requires a target title)
														# 	governor_efficiency									
	scheme = elope/murder/etc. 							# The type of scheme the interaction starts

	popup_on_receive = yes								# Have the interaction pop-up for the
														# recipient when received

	force_notification = yes/no							# Force diplomatic item if interaction is
														# auto-accept

	pause_on_receive = yes/no							# Pause the game on receive. It usually makes
														# sense to combine it with popup_on_receive

	ai_accept_negotiation = yes/no						# If the interaction is declined negotiations
														# will start. We don't show "won't accept", etc.
														# because there is still a possibility that the
														# interaction will be accepted via negotiation
														# event chain

	hidden = yes 										# Is the interaction hidden?

	use_diplomatic_range = yes/no/trigger				# Does this interaction check diplomatic range?
														# Yes by default

	can_send_despite_rejection = yes					# Interaction can be sent and the ai might reject

	ignores_pending_interaction_block = yes				# If the actor is a player and the recipient
														# already has received an interaction from them
														# pending a response, can this interaction be
														# sent anyway.
														# Defaults to no

	send_name = loc_key									# The name of the interaction in context of
														# it being seen once sent. Defaults to database
														# object key

	needs_recipient_to_open = yes						# Does the interaction need a recipient set to
														# be able to be allowed to open and be shown.
														# Defaults to no

	show_effects_in_notification = no					# Should the effects of the interaction be shown
														# in the notification window when an interaction
														# is sent.
														# Defaults to yes

	diarch_interaction = no								# If this interaction should be taken by diarch,
														# including unlanded one

	alert_icon = texture_path							# Default is gfx/interface/icons/
														# character_interactions/my_interaction_alert.dds

	icon_small = texture_path							# Default is gfx/interface/icons/
														# character_interactions/my_interaction_small.dds

	should_use_extra_icon = { always = yes }			# When to show an extra icon.
														# Tooltip key is <key>_extra_icon
	
	extra_icon = "gfx/<...>/hook_icon.dds"				# Icon to show when should_use_extra_icon is true

	target_type = type									# Possible types:
														# 	title
														#	artifact
														#	men_at_arms
														#	court_position_type
														#	count (default)

	target_filter = type								# See FAQ for possible types

	ai_intermediary_maybe = no							# The ai intermediary answer is randomized

	ai_maybe = yes										# The ai answer is randomized

	ai_min_reply_days = 4								# Minimum days before ai replies

	ai_max_reply_days = 9								# Maximum days before ai replies

	desc = loc_key 										# Short description of the interaction

	greeting = negative/positive						# Sets tone in request text

	intermediary_notification_text = loc_key			# Request text shown to the intermediary

	notification_text = loc_key							# Request text shown to the recipient

	prompt = loc_key 									# What text should be shown under the
														# portrait? (For example: "Pick a Guardian")

	cooldown = { years = x } 							# How long until the interaction can be
														# used again?

	cooldown_against_recipient = { years = x } 			# How long until the interaction can be
														# used again against recipient?

	ignore_recipient_recieve_cooldown = trigger			# Under what circumstances can an interaction
														# against a recipient be used despite there
														# being a cooldown for targeting that recipient?

	category_cooldown = { years = x } 					# Will apply a cooldown to all interactions in
														# the same category as this interaction
														#
														# If an interaction already has a cooldown,
														# the longer cooldown one will be applied

	category_cooldown_against_recipient = { years = x } # Will apply a cooldown to all interactions in
														# the same category as this interaction against
														# this recipient
														#
														# If an interaction already has a cooldown, the
														# longer cooldown will be applied

	is_shown = trigger									# Is the interaction available and visible
														# between scope:actor and scope:recipient

	is_valid_showing_failures_only = trigger			# Is the interaction valid to be selected in
														# it's current setup, trigger only displays
														# failures

	is_valid = trigger									# Is the interaction valid to be selected in
														# it's current setup

	has_valid_target_showing_failures_only = trigger 	# Is the target valid, trigger only displays
														# failures

	has_valid_target = trigger 							# Is the target valid

	can_be_picked = trigger 							# Can this character be picked as a valid target

	can_be_picked_title = trigger 						# Can this title be picked as a valid target

	can_be_picked_artifact = trigger 					# Can this artifact be picked as a valid target

	can_be_picked_regiment = trigger 					# Can this regiment be picked as a valid target

	auto_accept = yes/no/trigger						# Is the interaction automatically accepted,
														# or can recipient decide

	can_send = trigger									# Can the interaction be sent?

	can_be_blocked = trigger 							# Can the interaction be blocked by the
														# recipient (i.e. by a hook on the actor)

	redirect = {}										# This changes the redirection of characters
														# using the scopes actor, recipient,
														# secondary_actor and secondary_recipient

	populate_actor_list = {}							# Everyone sorted into the list 'characters' has
														# the potential of being shown to be selected.
														#
														# Uses the scopes actor, recipient,
														# secondary_actor and secondary_recipient.

	populate_recipient_list = {}						# Same as populate_actor_list

	localization_values = = {}							# To be able to use values in loc
														# (for example: RANSOM_COST =
														# scope:secondary_recipient.ransom_cost_value
														# lets you use $RANSOM_COST|0$ in loc)

	options_heading = loc_key							# Text shown above options block - describes all
														# options in general

	send_option = {										# Adds an option

		is_shown = trigger								# Is option shown. Independent trigger - don't
														# reference any other option flags to avoid
														# logic bugs

		is_valid = trigger								# Is option selectable

		current_description = desc						# Tooltip

		flag = flag_name								# If selected then scope:flag_name will be
														# set to yes

		localization = loc_key							# Loc_key for option label

		starts_enabled = trigger						# Trigger for whether this should be on when the
														# window opens. If not defined, defaults to off

		can_be_changed = trigger						# Trigger for whether this option can be changed
														# from its default

		can_invalidate_interaction = bool				# If yes then when the AI picks an interaction
														# it will do the full can send this entire
														# interaction check instead of the more
														# performance saving checking of recipient
														# refusal and ai will do, use with care and
														# profile it
	}

	# Options should avoid preventing an interaction from sending (except by the recipient refusing), as we assume that to be the case in the AI for performance reasons, use can_invalidate_interaction if you need it to be re-checked

	send_options_exclusive = yes/no 					# Are the options exclusive?

	secondary_scopes_optional = yes/no					# Are the secondary scope targets optional?

	on_send = effect									# Executes directly the interaction is sent

	on_accept = effect									# Executes when accepted by recipient
														# (only if intermediary accepts)

	on_decline = effect									# Executes when declined by recipient
														# (only if intermediary accepts)

	on_blocked_effect = effect 							# Executes when blocked by recipient
														# (only if intermediary accepts)

	pre_auto_accept = effect							# Only executes if the interaction was auto
														# accepted. Done before any other side effect
														# (E.G., hard coded ones like marriage)

	on_auto_accept = effect								# Only executes if the interaction was
														# auto accepted

	on_intermediary_accept = effect						# Executes when intermediary allows the
														# interaction to happen. It's followed by
														# recipient decision

	on_intermediary_decline = effect					# Executes when intermediary declines the
														# interaction. It prevents any effect from
														# being called on the recipient

	reply_item_key = loc_key 							# The key to the loc to show in the interaction
														# item tooltip. Receives the name of the
														# interaction in $INTERACTION$. Default value
														# "INTERACTION_REPLY_ITEM"


	### These loc keys are shown to the player when sending the interaction. The meaning is what is going to be the answer from the target.
	pre_answer_yes_key = loc_key 						# The key to the loc when the interaction is
														# going to be accepted.
														# Default value "ANSWER_YES"

	pre_answer_no_key = loc_key 						# The key to the loc when the interaction is
														# NOT going to be accepted.
														# Default value "ANSWER_NO"

	pre_answer_maybe_key = loc_key 						# The key to the loc when the interaction maybe
														# is accepted. Receives the acceptance value in
														# $VALUE$.
														# Default value "ANSWER_MAYBE"

	pre_answer_yes_breakdown_key = ANSWER_WILL_ACCEPT	# Summary header for acceptance breakdown for
														# recipient, when they accept

	pre_answer_no_breakdown_key = ANSWER_WILL_NOT_ACCEPT # Summary header for acceptance breakdown for
														 # recipient, when they decline

	pre_answer_maybe_breakdown_key = ANSWER_SUM_MAYBE	# Summary header for acceptance breakdown for
														# recipient, when it's randomized

	intermediary_breakdown_yes = ANSWER_WILL_ACCEPT		# Summary header for acceptance breakdown for
														# intermediary, when they accept

	intermediary_breakdown_no = ANSWER_WILL_NOT_ACCEPT	# Summary header for acceptance breakdown for
														# intermediary, when they decline

	intermediary_breakdown_maybe = ANSWER_SUM_MAYBE		# Summary header for acceptance breakdown for
														# intermediary, when it's randomized


	### These loc keys are shown to the player when answering an interaction.
	intermediary_answer_accept_key = ANSWER_YES			# Intermediary Accept interaction button text

	intermediary_answer_reject_key = ANSWER_NO			# Intermediary Decline interaction button text

	answer_block_key = ANSWER_BLOCK 					# Recipient Block interaction text

	answer_accept_key = ANSWER_YES 						# Recipient Accept interaction button text

	answer_reject_key = ANSWER_NO 						# Recipient Decline interaction button text

	answer_acknowledge_key = ANSWER_ACKNOWLEDGE 		# Recipient Acknowledge interaction button text.
														# Used for notifications when it's already
														# happened


	cost = {											# Scripted cost for the interaction. The
														# interaction will be disabled if the actor 
														# can't pay up, and the cost will be subtracted 
														# from the actor when the interaction is sent.
														# Renown can only be spent by the dynast.
		piety = {}
		prestige = {}
		gold = {}
		renown = {}
	}

	ai_instant_response = yes/no						# Will the AI respond instantly, and not pretend
														# to think about it for N days?

	ai_set_target = {}									# Set scope:target to make the AI target
														# something specific. Title targeting
														# interactions don't need this
	ai_targets = {
		ai_recipients = type 							# Which characters does the ai consider as
														# recipient for the interaction, can be scripted
														# multiple times to combine lists
														#
														# Available lists are in the "ai_targets"
														# section of this file (trying to add an invalid
														# list will trigger an error message with all
														# available )

		max = integer 									# Maximum number of targets to consider, unset
														# considers all of them, will consider random
														# targets that it filters too

		chance = 0-1									# A low chance, such as 0.25, randomly excludes
														# that number of characters from being checked -
														# this is useful for saving performance
	}

	ai_target_quick_trigger = {							# Quick triggers for the ai_targets

		adult = yes										# The target needs to be adult
	
		attracted_to_owner = yes						# The target needs to be attracted to owner
	
		owner_attracted = yes							# Owner needs to be attracted to the target
	
		prison = yes 									# Target must be in prison
	}

	ai_frequency = months								# How often should the ai consider doing this
														# interaction

	ai_potential = trigger								# Will the ai consider trying this interaction.
														# Root scope is the actor, and other event
														# target are not available

	ai_intermediary_accept = mtth						# Will the intermediary ai approve for this
														# interaction and forward it to the recipient

	ai_accept = mtth									# Will the ai accept a request for this
														# interaction

	ai_will_do = mtth									# How interested is the ai in sending this
														# interaction (tested after selecting targets)
														# 0-100 percent chance, will be clamped.
														#

	### Note that for title interactions, each individual target title will get evaluated, and the one giving the highest ai_will_do will get used. If the interaction has options, the combination of options that gives the highest ai_will_do will be used.
}

=== FAQ ===
Q:	What does the special interaction type arrange_marriage_interaction do?
A:	special_interaction = arrange_marriage_interaction will add extra marriage info to the interaction
	this info makes the game show the special marriage interfaces when setting up an interaction or replying to it.
	It's also used by the ai in knowing which interaction to use when setting up marriages.
	It automatically marries/betroths the secondary participants and sets up alliances and hands out prestige.

Q:	What does "secondary_actor = marriage" and "secondary_recipient = marriage" do?
A:	It states that the interaction has secondary participants (the one's actually getting married) and that
	we're allowed to change them in the interface. It also automatically redirects the interaction to the matchmaker
	so that the player can arrange a marriage with the son/daughter of another ruler and get the child as the
	secondary recipient and the ruler as the recipient (since they will be the ones accepting or not).
	It also sets up the list of characters to choose from from the actor/recipient with their courts and children.

Q:	What does "secondary_actor = marry_off" and "secondary_recipient = marry_off" do?
A:	Very similar to marriage, but with some expections:
	- The list of characters is calculated from all living characters that are allowed to marry.
	- The redirection makes the character you do the interaction with the secondary actor (since you're the one marrying them off)
	- There's the marriage redirection for whoever you select them to marry (ie mostly being the employer)

Q:	How and when are the character interaction triggers checked?
A:	These are the main triggers used by interactions:
	- is_shown
	- is_highlighted
	- is_valid_showing_failures_only
	- is_valid
	- has_valid_target_showing_failures_only
	- has_valid_target
	- can_be_picked
	- can_be_picked_title
	- can_be_blocked
	- can_send

Q:	What are the possible types for target_filter?
A:	Possible types:
	- actor_domain_titles
	- recipient_domain_titles
	- secondary_actor_domain_titles
	- secondary_recipient_domain_titles
	- actor_domain_titles_including_leases
	- recipient_domain_titles_including_leases
	- secondary_actor_domain_titles_including_leases
	- secondary_recipient_domain_titles_including_leases
	- actor_de_jure_titles
	- recipient_de_jure_titles
	- secondary_actor_de_jure_titles
	- secondary_recipient_de_jure_titles
	- actor_realm_titles
	- recipient_realm_titles
	- secondary_actor_realm_titles
	- secondary_recipient_realm_titles
	- actor_top_liege_de_jure_titles
	- recipient_top_liege_de_jure_titles
	- secondary_actor_top_liege_de_jure_titles
	- secondary_recipient_top_liege_de_jure_titles

	- actor_artifacts
	- recipient_artifacts
	- actor_artifacts_claimable
	- recipient_artifacts_claimable

	- actor_maa
	- recipient_maa
	- actor_personal_maa
	- recipient_personal_maa
	- actor_title_maa
	- recipient_title_maa

	- count (default)

Is there any other special behaviors set in code that these interactions are affected by?
When are the following conditions evaluated, are any of them checked during special circumstances (e.g. "not all scopes exist yet"):
is_shown
can_be_picked
is_valid_showing_failures_only
has_valid_target_showing_failures_only



=== Custom Widgets ===

=== FAQ ===
Q:	What does the special interaction type arrange_marriage_interaction do?
A:	special_interaction = arrange_marriage_interaction will add extra marriage info to the interaction
	this info makes the game show the special marriage interfaces when setting up an interaction or replying to it.
	It's also used by the ai in knowing which interaction to use when setting up marriages.
	It automatically marries/betroths the secondary participants and sets up alliances and hands out prestige.

Q:	What does "secondary_actor = marriage" and "secondary_recipient = marriage" do?
A:	It states that the interaction has secondary participants (the one's actually getting married) and that
	we're allowed to change them in the interface. It also automatically redirects the interaction to the matchmaker
	so that the player can arrange a marriage with the son/daughter of another ruler and get the child as the
	secondary recipient and the ruler as the recipient (since they will be the ones accepting or not).
	It also sets up the list of characters to choose from from the actor/recipient with their courts and children.

Q:	What does "secondary_actor = marry_off" and "secondary_recipient = marry_off" do?
A:	Very similar to marriage, but with some expections:
	- The list of characters is calculated from all living characters that are allowed to marry.
	- The redirection makes the character you do the interaction with the secondary actor (since you're the one marrying them off)
	- There's the marriage redirection for whoever you select them to marry (ie mostly being the employer)

Q:	How and when are the character interaction triggers checked?
A:	These are the main checks used by interactions:

	Can Send: If an interaction can be sent is tested like this:
		- check if set up for sending (this means that all targets and secondary actors/recipients that the interaction uses, must have been selected)
		- check diplomatic range (if interaction scripted to use it)
		- make special is shown checks decided by special_interaction =
		- Trigger: is_shown
		- check if the interaction is already being considered by the recipient
		- Trigger: is_valid_showing_failures_only
		- Trigger: has_valid_target_showing_failures_only
		- Trigger: can_send
		- Trigger: is_valid
		- Trigger: has_valid_target
		- make special can send checks decided by special_interaction =
		If it passes all the above, then we check if the interaction needs to be accepted (auto_accept = no or failing trigger and interactions that can be sent regardless like imprison)
		interactions that need acceptance cannot be sent to the ai unless it will accept.

	When populating a list of titles we look at this (examples: grant title, revoke title):
		- select domain or dejure title based on target_filter =
		- Trigger: can_be_picked_title with the full interaction scope and the title set as scope:target
		Note: can_be_picked_title is not checked when we try to send, it's a separate trigger that should be a fast way of deciding what can end up in the list to select from

	When populating a list of characters we look a this:
		- secondary_actor/secondary_recipient = decides what to base the list off (vassals, courtiers, marriage, dynasty, house, ...)
		If we're haven't picked a character already (many interactions wants us to pick two characters, such as marriage)
			- Trigger: can_be_picked with the current interaction scipe and the tested character set as root
		Else if we're picking character number two
			- Try setting the character as secondary_actor/secondary_recipient. The interaction should be fully set up after this.
			- Do a full Can Send test, but ignore the ai acceptance check.
		Note: can_be_picked is only there to filter out the first character we need to select and is not part of the Can Send test.

	Is Shown: is_shown is used by the interface to check if the interaction should be visible in the interaction list
	Is Valid: is_valid and is_valid_showing_failures_only are tested to see if an interaction should be enabled (clickable) or not in the menu


== ai_targets ==
The following are valid AI targets:
known_secrets - Characters who has a secret you know of
scheme_targets
hooked_characters
neighboring_rulers
peer_vassals
guests
dynasty
courtiers
councillors
prisoners
sub_realm_characters
realm_characters
vassals
liege
self
head_of_faith
spouses
family
children
primary_war_enemies
war_enemies
war_allies
scripted_relations - Any character you have a scripted relation with
activity_host - Host of your involved activity
activity_guests - Guests of your involved activity
contacts - People on your contact list (connected to task contracts)
domicile_location_top_ruler - Ruler of domicile location's Top Realm (for Domicile Owners)
domicile_location_top_realm_vassals - Vassals of domicile location's Top Realm (for Domicile Owners)
domicile_location_neighboring_top_rulers - Rulers of Neighboring Top Realms (for Domicile Owners, uses the top liege of the domicile's location to fetch neighboring realms)
domicile_location_neighboring_top_realm_vassals - Vassals of Neighboring Top Realms (for Domicile Owners, uses the top liege of the domicile's location to fetch neighboring realms)
top_realm_domicile_owners - Owners of domiciles located in Top Liege Realm (for unlanded Domicile Owners, uses the top liege of the location you're in)
sub_realm_domicile_owners - Owners of domiciles located within your own realm (for Landed Rulers)
nearby_domicile_owners - Nearby owners of domiciles (Uses a range value defined as NEARBY_DOMICILE_RANGE in 00_defines.txt)