AI modding

AI in Hearts of Iron IV can be modified in many aspects. The following files and folders handle AI primarily:

• /Hearts of Iron IV/common/ai_areas
• /Hearts of Iron IV/common/ai_focuses
• /Hearts of Iron IV/common/ai_peace
• /Hearts of Iron IV/common/ai_strategy
• /Hearts of Iron IV/common/ai_strategy_plans
• /Hearts of Iron IV/common/ai_templates
• /Hearts of Iron IV/common/ai_attitudes.txt
• /Hearts of Iron IV/common/ai_personalities.txt

Many other places that present choices to the player have an AI chance attached to it, using the keyword ai_will_do.

AI chance

Found in numerous files, ai_will_do is an element that produces a number for the AI to use when weighing decisions. It is functionally very similar to mean_time_to_happen and uses the same modifier system described there. It has a different interpretation of base and factor though.

Note that the AI's interpretation of the resulting number is not the same in all use cases, but usually probability-proportional-to-size sampling.

base

(Type: scoped variable, default: 1) The base value of the calculation, before applying any modifiers.

factor

(Type: number (with 3 decimal places), default: 1) A final factor applied to the calculation.

Example

ai_will_do = {
    base = 10.5  # may also be a variable
    
    # If the country is Germany, set the value to 0,
    # causing an early end of the evaluation.
    modifier = { tag = GER factor = 0 }

    modifier = { is_major = yes add = 1 }

    modifier = {
        factor = 3
        add = 2.5
        tag = FRA
    }

    factor = 2
}

Assuming normal majors, the result is 0 for GER, 74 for FRA, 23 for other majors and 21 for minors.

AI area

The /Hearts of Iron IV/common/ai_areas directory controls the assignment of land provinces to named AI areas. These in turn are only used by the AI strategy area_priority described further below. Each land province is assigned to only one AI area. The first matching area is used. It is not necessary to assign an AI area to every land province, but the unassigned ones can not be referenced by the area_priority strategy.

The AI area is shown in the province debug tooltip.

Here is a generic example:

<area name> = {
    # Used to add continents
    continents = {
        <continent>
    }
    
    # Used to add specific strategic regions
    strategic_regions = {
        <strategic region ids>
    }
}

AI Focuses

See AI focuses#Modding

AI Peace

The /Hearts of Iron IV/common/ai_peace files controls how the AI handles peace.

There are five types of peace behaviour:

• civilwar
• democratic
• communist
• fascist
• default

There are five peace options, which are:

• annex
• liberate
• puppet
• take_states
• force_government

Here is a generic example:

<type>_peace = {
    # Determines when this peace AI is used by the AI (ROOT is taker, FROM is giver)
    enable = {
        <triggers>
    }
    
    # Random factors applied to AI decision making when determining which
    # peace option to use.
    annex_randomness = <int>
    liberate_randomness = <int>
    puppet_randomness = <int>
    take_states_randomness = <int>
    force_government_randomness = <int>
    
    # Weighting towards the option. (ROOT is taker, FROM is giver)
    <peace option> = {
        factor = <float>
        
        <triggers>
        
        modifier = {
            factor = <float>
            
            <triggers>
        }
    }
}

AI strategy

The strategic AI influences decision making in other AI components along certain strategic considerations (types) which can also be targeted. For example a country may strategically be interested in protecting another country, irrespective of the current diplomatic relation and alliance status. Or it may want to produce more units of a certain type.

In terms of structure, an AI strategy has just four attributes: type, value, id, and target. Only some types make use of id and/or target. All four attributes are integer numbers inherently, but if the type is specified first, the id attribute can reference respective values by name (see table below). target_country is another way to set target. It accepts a country index or a tag and will check in both cases that it refers to a valid country.

The AI creates dynamic strategies by itself but static strategies can be added as well. Static strategies are primarily defined with an AI strategy entry in /Hearts of Iron IV/common/ai_strategy or an AI strategy plan (see below). Country leader traits (in /Hearts of Iron IV/common/country_leader) can carry AI strategies that are enabled when the associated person becomes the ruler. Individual strategies can also be added directly using the add_ai_strategy effect (for example in event, national focuses etc.).

The effective AI strategies of a country are saved in save files, as the ai attribute of a country.

Types

When defining an ai_strategy, the type controls what aspect of AI strategy is altered. Additional ai_strategy's from LaR can be found in common/ai_strategy/default.txt

Type ID	Type	ID	Description
45	added_military_to_civilian_factory_ratio		Alters the Military-to-Civilian factory ratio.
28	air_factory_balance		Alters the Air factory ratio.
8	alliance	<tag>	Nudges diplomatic AI towards forming an alliance with another specified country.
3	antagonize	<tag>	Nudges diplomatic AI towards being meaner to another specified country.
33	area_priority	<ai_area>	Encourages the military AI to target specified AI area.
4	befriend	<tag>	Nudges diplomatic AI towards being nicer to another specified country.
10	build_airplane		Unused.
11	build_army	<unit role>	Orders the AI to build a type of division or equipment (as in air planes or ships) that belong to the specified unit role.
12	build_building	<building>	Orders the AI to build a specific building in a specific location. Uses target to specify the state location.
9	build_ship		Unused.
56	building_target	<building>	Orders the AI to build towards specified amount of <building>. This includes those already owned and acquired by trade (Civilian Factory).
1	colonize		Unused.
0	conquer	<tag>	Encourages the military AI to target specified tag.
6	consider_weak	<tag>	Nudges the AI disposition towards considering the specified tag weak.
17	contain	<tag>	Nudges the diplomatic AI towards taking actions against another country, such as guaranteeing their future potential enemies.
41	declare_war	<tag>	Nudges the AI disposition towards declaring war against the specified tag.
48	dockyard_to_military_factory_ratio		Alters the Dockyard-to-Military factory ratio.
49	dont_defend_ally_borders	<tag>	Nudges the AI disposition towards not defending the specified ally's borders.
44	dont_join_wars_with	<tag>	Nudges the AI disposition towards not defending the target country when the specified tag is involved. Uses target_country to define the target country.
29	equipment_production_factor	<unit type>	Alters the equipment production disposition for the specified unit type.
31	equipment_production_min_factories	<unit type>	Sets the minimum factory count needed to start equipment production for the specified unit type.
26	equipment_stockpile_surplus_ratio		Sets the base equipment stockpile surplus value.
30	equipment_variant_production_factor	<equipment>	Alters the equipment variant production disposition for the specified equipment.
2	explore		Unused.
46	factory_build_score_factor		Modifies the AI build disposition for a state. Uses target to specific the target state.
50	force_defend_ally_borders		Unused.
15	garrison	<integer> (scale of 100)	Used in ai_strategies/SOV.txt, USA.txt, ENG.txt how much of the army should be kept on garrison duty
32	ignore	<tag>	Nudges the AI disposition towards ignoring the specified tag.
42	ignore_army_incompetence		Sets the AI disposition towards ignoring army incompetence.
47	ignore_claim	<tag>	Sets AI ignorance of claims against the specified tag. Accepts 1 as a value.
7	influence		Unused.
18	invade	<tag>	Nudges the AI disposition towards invading the specified tag.
21	land_xp_spend_priority		Unused.
37	naval_avoid_region	<strategic region>	Alters AI avoidance of the specified strategic region navally.
35	occupation_policy	<tag>	Determines the occupation policy towards the specified tag. Accepts values 0 to 3.
40	pp_spend_amount	admiral relation guarantee decision etc.	Sets the amount allowed for spending Political Power on the specified action.
22	pp_spend_priority	admiral relation guarantee decision etc.	Sets the priority for spending Political Power on the specified action.
38	prepare_for_war	<tag>	it nudges the AI to plan an attack ahead of time for a possible war with target
5	protect	<tag>	Nudges the diplomatic AI of a country to try to defend another specified country.
13	research_tech	<technology>	Orders the AI to research a specific technology, if possible.
20	role_ratio	<unit role>	Out of the entire army, this is the ratio (in %) of that unit role that the army should have. Roles can be defined arbitrarily in ai_templates.
39	save_equipment	<equipment>	Makes the AI save equipment of the specified type to the set value.
34	send_volunteers_desire	<tag>	Alters AI disposition towards sending volunteers to the specified tag.
43	spare_unit_factor		Sets the spare unit factor. Used to encourage AI to send more units off to assist in allied fronts and not garrison their home territory.
36	support	<tag>	Alters AI disposition towards supporting the specified tag against partisans.
23	template_prio	<unit type>	Sets the template priority of the specified unit type for the AI.
24	template_xp_reserve		Sets the XP reserved needed for the AI to consider template changes.
61	force_build_armies		Added in 1.6.2, to force AI build armies... Mainly used for China to prepare for war against Japan
19	unit_ratio	<unit type>	Out of the entire army, this is the ratio (in %) of that unit type that the army should have.
25	equipment_design_priority
58	production_upgrade_desire_offset	<equipment>
	put_unit_buffers	See ai_strategy/default.txt	Used to tell AI to garrison certain states

AI strategy entry

A strategy entry contains one or more AI strategies and defines when and how they should apply. When a country checks an entry, it will only enable it if enable is true and abort is empty or false. An entry gets disabled if abort is non-empty and true. It also gets disabled if abort_when_not_enabled is set and enable is false.

A reversed entry works quite differently. The entry gets enabled for a source country if it is mentioned as an id in an ai_strategy and enable_reverse is empty or true. The entry then gets checked against targets. If target_array and/or targets is set, they are used as possible targets. Otherwise all countries are used as possible targets. The enable and abort triggers are checked for each possible target. If a target passes these checks, all ai_strategys of the entry are enabled for source, but replacing their id with target.

Attributes

• allowed: (type: AND trigger) Only evaluated once at the start of the game, so the conditions should be static (e.g. tag = GER or is_historical_focus_on = yes). If an entry is not allowed it never gets checked again, so this can be used to improve performance.
• enable: (type: AND trigger) Enables the entry (unless abort is also non-empty and true).
• abort: (type: AND trigger) If non-empty and true, disables the entry.
• abort_when_not_enabled: (type: yes/no, default: no) If enabled, the entry will be disabled when enable becomes false.
• ai_strategy: (type: AI strategy, may appear multiple times) an AI strategy to apply with this entry
• reversed: (type: yes/no, default: no) use reversed semantics as described above
• enable_reverse: type: AND trigger) an additional trigger for the source country to pass in a reversed trigger
• target_array: (type: variable) An array variable containing reverse targets, e.g. neighbors, exiles or enemies.
• targets: (type: list of variables) A list of individual reverse targets, e.g. { GER ENG FRA }

AI Strategy Plans

The /Hearts of Iron IV/common/ai_strategy_plans files defines specific overall AI behaviour for specific tags, used for historical plans by default.

Here is a generic example:

<strategy_plan> = {
    name = <name>       # Name of the plan
    desc = <desc>       # Description of the plan
    
    # When this plan is enabled.
    enable = {
        <triggers>
    }
    
    # When this plan is aborted.
    abort = {
        <triggers>
    }
    
    # Defines which national focuses the AI picks first during this plan.
    ai_national_focuses = {
        <focus> # AI picks top downwards
    }
    
    # Defines which technology categories the AI has weighting towards/against during this plan.
    research = {
        <category> = <weight>
    }
    
    # Defines which ideas the AI has weighting towards/against during this plan.
    ideas = {
        <idea> = <weight>
    }
    
    # Defines which traits the AI has weighting towards/against during this plan.
    traits = {
        <trait> = <weight>
    }
    
    # Defines AI strategies to apply during this plan. 
    ai_strategy = {
        <strategy attributes>
    }
    
    # Defines pick weights for specific focuses during this plan.
    focus_factors = {
        <focus> = <weight>
    }
    
    # Keep small, as it is used as a factor for some things (such as research needs)
    # Recommended around 1.0. Useful for relation between plans
    weight = {
        factor = 1.0
        modifier = {
            factor = 1.0
        }
    }
}

AI Templates

The /Hearts of Iron IV/common/ai_templates files defines the templates used by roles that are used by the AI to dictate the templates they use.

Roles are the core of the AI template system. They can be created arbitrarily, allowing modders to create custom roles.

Each template assigned to a role will form a group for the role, and then the fitness score of each available template is used to determine which is used at a specific moment for a specific role.

Here is a generic example:

<role_template_name> = {
    # Defines the actual role(s) the template covers.
    roles = {
        <roles>
    }
    
    # Restricts the template to only the specified tags. Optional.
    available_for = {
        <tags>
    }
    
    # Blocks the template for the specified tags. Optional.
    blocked_for = {
        <tags>
    }
    
    # Determines which existing templates are included in this role
    match_to_count = <float> # By default 0.5
    
    # Determines the importance of the role template, highest importance is the role used by the AI.
    upgrade_prio = {
        factor = <float> # Base factor
        
        # Modifies the base factor
        modifier = {
            factor = <float>
            
            <triggers>
        }
    }
    
    # A template that belongs to this role. Multiple are allowed per role template.
    <template_name> = {
        # Determines the importance of the template amoungst other templates listed within the same role.
        upgrade_prio = {
            factor = <float> # Base factor
            
            # Modifies the base factor
            modifier = {
                factor = <float>
                
                <triggers>
            }
        }
        
        # Determines which template the AI will assign to a deployment line for a role. Highest score wins.
        production_prio = {
            factor = <float> # Base factor
            
            # Modifies the base factor
            modifier = {
                factor = <float>
                
                <triggers>
            }
        }
        
        # Determines the requirement to upgrade in field
        can_upgrade_in_field = {
            <triggers>
        }
        
        custom_icon = <int>
        reinforce_prio = <int>
        target_width = <float>
        width_weight = <float>
        column_swap_factor = <float> 

        # Determines the weights for each stat for this template.
        # Order determines which stat the value affects.
        stat_weights = {
            <float> #-- default_morale
            <float> #-- defense
            <float> #-- breakthrough
            <float> #-- hardness
            <float> #-- soft_attack
            <float> #-- hard_attack
            <float> #-- recon
            <float> #-- entrenchment
            <float> #-- initiative
            <float> #-- casualty_trickleback
            <float> #-- supply_consumption_factor
            <float> #-- supply_consumption
            <float> #-- suppression
            <float> #-- suppression_factor
            <float> #-- experience_loss_factor
            <float> #-- equipment_capture_factor
            
            #-- Air Values
            <float> #-- air_attack
            
            #-- Common Values
            <float> #-- max_organisation
            <float> #-- max_strength
            <float> #-- maximum_speed
            <float> #-- armor_value
            <float> #-- ap_attack
            <float> #-- reliability
            <float> #-- reliability_factor
            <float> #-- weight
            <float> #-- build_cost_ic
        }
        
        # 
        target_template = {
            weight = <float>
            match_value = <float>
            
            support = {
                <support unit> = <amount>
            }
            
            regiments = {
                <unit> = <amount>
            }
        }
        
        allowed_types = {
            <units>
        }
        
        replace_at_match = <float>
        replace_with = <template>
        target_min_match = <float>
    }
}

模组制作