Unit modding

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

Units are the base object that equipment is applied to. Internally, units are actually sub-units of the hardcoded unit types, such as infantry, cavalry, fighter, etc.

Unit Categories[edit]

Unit categories are found in /Hearts of Iron IV/common/unit_tags/00_categories.txt.

Each unit is assigned a category that is used in technologies to apply effects to groups of units at once.

The following example from a technology grants bonuses to all units with the category_all_infantry category:

category_all_infantry = {
    hard_attack = 0.25
    ap_attack = 1
}

Units[edit]

Units are found in /Hearts of Iron IV/common/units/*.txt.

Units follow the following format:

sub_units = {
    <unit name> = {
        sprite = <entity> # Refers to <name>_entity in a gfx/entities/.*.asset file - Controls the unit used on the map
        
        # Controls the map icon category used for the unit
        map_icon_category = <type>

        priority = <int>    # Controls which icon is used if multiple subunits of the same type exist
        ai_priority = <int>

        active = yes / no       # Whether the unit is usable without explicit unlocking in technology
        cavalry = yes           # Used to define subunit as cavalry 
        special_forces = yes    # Used to define subunit as special forces
        marines = yes           # Used to define subunit as marine
        mountaineers = yes      # Used to define subunit as mountaineers
        
        transport = <equipment> # Sets the speed of subunit via equipment. Used for motorized/mechanized
        
        # How the unit is grouped division-wise, i.e. appearing in the Support tab. Not used for air or naval units
        group = <group> 
        
        # Internal types
        type = {
            <type>
        }
        
        # Categories the unit belongs to.
        categories = {
            <categories>
        }
        
        # Equipment that is required for this unit. Used when active = no
        essential = {
            <equipment>
        }
        
        # Equipment needed to produce this unit. Unit won't be available until the nation has this equipment
        need = {
            <equipment>
        }
        
        # Modifiers control the stats of the unit. More detail under the Stats section.
        <modifiers>
        
        # Modifiers that occur only in specific terrain
        <terrain> = {
            <modifiers>
        }
    }
}

You cannot add new internal, group or map icon types.

Internal Types[edit]

  • infantry
  • support
  • artillery
  • anti_tank
  • anti_air
  • armor
  • fighter
  • cas
  • naval_bomber
  • interceptor
  • suicide
  • tactical_bomber
  • strategic_bomber
  • air_transport
  • missile
  • submarine
  • screen_ship
  • capital_shop
  • carrier

Group Types[edit]

  • infantry
  • support
  • mobile
  • armor

Map Icon Types[edit]

  • infantry
  • armored
  • other
  • ship
  • transport
  • uboat

Stats[edit]

Units use modifiers to determine which stats they have and what special actions they may take.

Typically air units will not use any modifiers, whilst naval units use only supply_consumption and max_organisation.

Land units almost always use the following:

manpower = <int>
max_strength = <int>
training_time = <int>
weight = <float>
default_morale = <float>
max_organisation = <int>    
combat_width = <int>        
supply_consumption = <float>

For max_organisation, vanilla uses the following values:

  • infantry support: 20
  • armor: 10
  • armor support: 0
  • ship: 40
  • cavalry: 70

For combat_width, vanilla uses the following values:

  • infantry: 0
  • artillery: 0
  • armor support: 1
  • armor: 2

Modifiers[edit]

The following list is all the valid modifiers for use in units (and equipment):

Base[edit]

max_organisation = 20           # Organisation - Organisation indicates combat readiness and how organized a unit is. A unit with no organisation can't fight or move effectively.
reliability = 0.9               # Reliability - The lower the reliability, the more likely the equipment will suffer random failure
weight = 0.1                    # Weight - How much the unit will weigh. Heavier units will require more transports to ship and perform invasions effectively.
maximum_speed = 4               # Max Speed - How quickly this unit can traverse terrain under optimal circumtances, in kilometres per hour
supply_consumption = 0.02       # Supply use - How much supply a unit consumes per day
default_morale = 0.3            # Recovery Rate - How much extra organisation can be regained hourly when not in combat
combat_width = 0.5

Costs[edit]

lend_lease_cost = 1             # Space taken up in convoy
build_cost_ic = 0.4             # Production Cost - How much factory output this piece of equipment needs
manpower = 300                  # Manpower - Cost in manpower to produce
training_time = 120             # Training time - Time in days to train this unit

Offensive[edit]

# Offensive
attack = 0.1                    # Firepower - Amount of damage done per attack
soft_attack = -0.1              # Soft Attack - How many attacks the unit can make versus enemies with low hardness
hard_attack = -0.5              # Hard Attack - How many attacks the unit can make versus enemies with high hardness
air_attack = 1                  # Air Attack - How much damage we can do against airplanes. High Air Attack also helps to counter enemy Air Superiority effects
ap_attack = 1                   # Piercing - Having equal or greater Piercing to the targets Armor value allows you to do more damage.
breakthrough = 0.5              # Breakthrough - How many enemy attacks a unit can attempt to avoid while on the offensive, effectively allowing it to stay on the offense longer.

Defensive[edit]

# Defensive
defense = 0.1                   # Defense - How many enemy attacks a unit can avoid whilst on the defensive, effectively allowing it to stay on the defensive longer.
max_strength = 2                # HP - Strength represents how much damage this unit can suffer before it is destroyed
armor_value = 0                 # Armor - Armor that is higher than the opponents Piercing value reduces damage taken and allows more attacks to occur
hardness = 0.5                  # Hardness - Represents how much of your divsion is made up of armoured vehicles. High Hardness = High Hard Attacks, Low Soft Attack
entrenchment = 5                # Entrenchment - The ability to make proper defensive entrenchments before a hostile attack

Unique[edit]

movement = 0.1                  # Movement - Changes the unit's speed
experience_loss_factor = 0.1    # Exp. Loss - How much experience is lost in a division when they take casualities and have to replace them
casualty_trickleback = 0.2      # Trickleback - The proportion of losses in combat that can be saved and returned to the manpower pool
suppression_factor = 0.1        # Suppression bonus - Ability to supress local resistance
reliability_factor = 0.05       # Reliability - Applies to an equipment type's reliability and reduces the chance of breakdowns and accidents
recon = 1                       # Reconnaissance - Increases the chance that this unit can pick better tactics in battle
initiative = 0.2                # Initiative - The higher the initiative, the quicker it can reinforce into battle, and the quick is completes its planning

Boolean[edit]

can_be_parachuted = yes         # May be parachuted into battle
can_license = no                # Can be licesed
is_convertable = yes            # Can be converted
carrier_capable = yes           # Is usable in carriers (air only)

Navy-specific[edit]

naval_speed = 28                        # Max Speed - maximum speed in kilometres per hour of the ship, higher means faster in combat too
fire_range = 32                         # Fire Range - The range of the ship's main guns
torpedo_attack = 1                      # Torpedo attack - How much damage we can do when using the ship's torpedos
anti_air_attack = 5                     # Anti-air - How much anti-air firepower the ship carries for shooting down enemy planes
shore_bombardment = 8                   # Shore Bombard - A unit's ability to do shore bombardment to help out in land battles neighbouring its sea province when on Hold mission
evasion = 15                            # Evasion - Ability for ships to evade enemy fire through maneuvering. Evasion is checked against enemy evasion, so high evasion improves hits against high evasion targets
surface_detection = 12                  # Surface detection - Ability to detect surface vessels
sub_detection = 5                       # Sub detection - Ability to detect submarines
surface_visibility = 25                 # Surface Visibility - How hard to find this ship is
sub_visibility = 20                     # Sub Visibility - How easy it is to detect this submarine
naval_range = 3000                      # Naval Range - max distance in kilometres the ship can travel from it's nearest Naval Base
port_capacity_usage = 1                 # Port capacity usage - How much room the ship requires in port
search_and_destroy_coordination = 0.1
convoy_raiding_coordination = 0.1

Air-specific[edit]

air_attack = 50                         # Air Attack - amount of damage done against other planes
air_defence = 50                        # Air Defence - how many hits a plane takes before being shot down
air_range = 500                         # Range - How far away missions the plane can perform
air_agility = 10                        # Agility - How agile a plane is. Agility effects how easy it is to hit another plane, and avoid being hit
air_bombing = 300                       # Strategic Bombing - how good the plane is at bombing
air_superiority = 1                     # Air Superiority - How much the plane helps the overall air superiority of a strategic area
naval_strike_attack = 1.5               # Naval Attack - how much damage the plane does against ships
naval_strike_targetting = 0.5           # Naval Targeting - how likely the plane is to hit a ship
carrier_size = 0.05
default_carrier_composition_weight = 1

Localization[edit]

Each unit must be localized in a .yml file in the localisation folder within your mod.

<unit>: ""
<unit>_desc: ""
Modding
Documentation EffectsTriggersModifiersScopesLocalisation
Scripting AIBookmarksBuildingsCosmetic tagsCountriesDivisionsDecisionsEquipmentEventsIdeasIdeologiesNational FocusesResourcesTechnologyUnits
Map MapTerrainStatesSupply areasStrategic regions
Graphical InterfaceGraphical Assets
Cosmetic PortraitsNamelistsMusicSound
Other Console commandsTroubleshootingMod structure