Event modding

From Hearts of Iron 4 Wiki
Jump to navigation Jump to search

Events are defined in /Hearts of Iron IV/events. There are four different event types:

  • country_event
  • news_event
  • unit_leader_event
  • state_event

state_event is evaluated for each state, all other types on the country level. News events can be separately hidden by the player, so they should be purely informational.

Namespace[edit]

All events are defined in namespaces which need to to be declared first. Example: add_namespace = germany

Attributes[edit]

id[edit]

(Type: string) A unique identifier for the event.

title[edit]

(Type: string or triggered text) Can either be a plain localization key for the event's title or a block with a trigger: { text = event_1_t trigger = { date > 1940.1.1 }}, which will only use the given title if the trigger is true. Can appear multiple times.

desc[edit]

(Type: string or triggered text) Defines the event's description text. Same syntax as title.

picture[edit]

(Type: string) The picture to use in the event popup.

trigger[edit]

(Type: AND trigger, default: { }) The event can only happen if the trigger evaluates to true. The console command event overrides this trigger.

mean_time_to_happen[edit]

(Type: MTTH, default: { days = 1 }) Calculates a value in days (see below). Events are evaluated every 20 days per country and state. On each check the probability of the event firing is 20/MTTH.

fire_only_once[edit]

(Type: boolean, default: no) If false, the event can fire multiple times.

is_triggered_only[edit]

(Type: boolean, default: no) If true, the event cannot randomly happen through mean_time_to_happen, it must be triggered explicitly in an effect.

timeout_days[edit]

(Type: number, default: 13) Number of days for the recipient to respond. After the timeout, the first option gets selected.

fire_for_sender[edit]

(Type: boolean, default: yes) If false, the event will not be shown to the sending country, even if it is a major event.

hidden[edit]

(Type: boolean, default: no) The event will not be shown but can still cause other side effects, like triggering different events.

exclusive[edit]

(Type: boolean, default: no) TODO

major[edit]

(Type: boolean, default: no) If true, the event will be shown to all countries.

show_major[edit]

(Type: AND trigger, default: { }) Limits which countries a major event is shown to.

option[edit]

(Type: event option) An option for the event that the receiver can select, see below.

immediate[edit]

(Type: event option) This event option happens unconditionally when the event fires.

Option[edit]

Additionally to the attributes listed below, options may contain arbitrary effects.

name[edit]

(Type: string) The localization key of the option's name.

trigger[edit]

(Type: AND trigger, default: { }) Controls whether this option is available.

ai_chance[edit]

(Type: AI chance, default: { base = 1 }) The weight for the AI to pick this option. The probability of each option is its weight divided by the sum of all weights.

original_recipient_only[edit]

(Type: boolean, default: no) For major events, this option is only available to the direct recipient.

Mean time to happen[edit]

The mean time to happen (MTTH) is calculated by starting with a base value and applying a chain of modifiers.

Attributes[edit]

base[edit]

(Type: number (with 3 decimal places), default: 1) The base value of the calculation, before applying any modifiers.

factor[edit]

An alias for base.

days[edit]

(Type: number) Sets base to the specified value but does not recognize decimal places.

months[edit]

(Type: number) Sets base to 30 times the value but does not recognize decimal places.

years[edit]

(Type: number) Sets base to 365 times the value but does not recognize decimal places.

modifier[edit]

A modifier block combines its components like an AND trigger. The only exceptions are factor and add. Both are scoped variables, and if the trigger components evaluate to true, the current MTTH value is multiplied by factor before adding add. Can appear multiple times and all applicable modifiers are applied in the order they were defined in. The calculation stops early if the intermediate value is zero after applying a modifier. This means it is not possible to increase the value again using add after a previous modifier set the value to zero.

Example[edit]

	mean_time_to_happen = {
		days = 500
		modifier = {
			factor = 0.4 # If true multiply 500 by 0.4 = 200
			NOT = { country_exists = SOV }
		}
		modifier = {
			factor = 0.4 # If true multiply 200 by 0.4 = 40
			NOT = { country_exists = ENG }
		}
		modifier = {
			factor = 0.1 # If true multiply 40 by 0.1 = 4
			NOT = { country_exists = ENG }
			NOT = { country_exists = SOV }
		}
	}

Examples[edit]

Country event[edit]

country_event = {
        # A unique event ID.
        # nuke_dropped is the namespace, which helps with organization.
	id = nuke_dropped.0 
        title = nuke_dropped.0.t # The localisable text that appears as a header
        desc = nuke_dropped.0.d # The localisable main text body that appears
	picture = GFX_report_event_election_vote # Image displayed alongside the text.

	is_triggered_only = yes # Optional : if set to "yes" the event will only occur by command

	hidden = yes # Optional : if set to "yes" no one will see the event

	fire_only_once = yes # Optional : if set to "yes" the event will never occur more than once

	immediate = { # Optional : all the following will occur once the event occurs
		if = {
			limit = {
				tag = ITA
				has_government = fascism
				FROM = { state = 378 }
			}
			set_country_flag = duce_nukedem_flag
		}
		news_event = { id = nuke_dropped.1 days = 1 }
	}
	
	option = { # This is an example of an option that has no function
		name = dummy_nuke_option.1.a # The localisable text that appears on the button.
	}
        option = { # This is an example of an option that has a function
		name = dummy_nuke_option.1.b # The localisable text that appears on the button.
                add_political_power = 100
	}
	option = { # This is an example of an option that has a trigger
		trigger = {
			has_country_flag = nuked_before # This option will only appear if the condition is fulfilled.
		}
		name = dummy_nuke_option.1.c # The localisable text that appears on the button.
		add_stability = 0.05
	}
}

News event[edit]

news_event = {
	id = nuke_dropped.0 # The unique id. nuke_dropped is the namespace, which can be used for better organization, and is used in localisation.
	picture = GFX_news_event_nuke # Image displayed alongside the text.

	major = yes # Optional : if set to "yes" every country in the world will see this event

	is_triggered_only = yes # Optional : if set to "yes" the event will only occur by command

	hidden = yes # Optional : if set to "yes" no one will see the event

	fire_only_once = yes # Optional : if set to "yes" the event will never occur more than once

	immediate = { # Optional : all the following will occur once the event occurs
		if = {
			limit = {
				tag = ITA
				has_government = fascism
				FROM = { state = 378 }
			}
			set_country_flag = duce_nukedem_flag
		}
		news_event = { id = nuke_dropped.1 days = 1 }
	}
	
	option = { # This is an example of an option that has no function
		name = dummy_nuke_option.1.a # The localisable text that appears on the button.
	}
        option = { # This is an example of an option that has a function ( usually not done on a news event )
		name = dummy_nuke_option.1.b # The localisable text that appears on the button.
                add_political_power = 100
	}
}

Multiple descriptions[edit]

	desc = {                               #This is the first description, it will be used if the ace pilot is promoted in any country except the major ones (listed below).
		text = ace_promoted.1.d        #this is the localisable text name, which needs to be unique.
		trigger = {                    #this is needed trigger.
			NOT = { tag = GER }    #This means that the description will not trigger if the pilot is promoted in Germany, Italy, France, Japan, the United States, the United Kingdom or the Soviet Union.			
                        NOT = { tag = ITA }
			NOT = { tag = FRA }
			NOT = { tag = JAP }
			NOT = { tag = USA }
			NOT = { tag = ENG }
			NOT = { tag = SOV }
		}
	}
	desc = {    #This is the second description, it will be used if the ace pilot is promoted in any major country (of the ones listed below).
		text = ace_promoted.1.d_major
		trigger = {
			OR = {
				tag = GER       #This means that the description will only trigger if the pilot is promoted in Germany, Italy, France, Japan, the United States, the United Kingdom or the Soviet Union.
				tag = ITA       
				tag = FRA
				tag = JAP
				tag = USA
				tag = ENG
				tag = SOV
			}
		}
	}