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
        can_be_parachuted = yes # Used to define subunit as paratroopers.
        
        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_ship
  • 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 indicates combat readiness and how organized a unit is. 
                                # Units with no organisation can't fight or move effectively.

reliability = 0.9               # Reliability controls how often equipment will suffer random failures.

weight = 0.1                    # Weight controls how many transports a unit needs to embark.

maximum_speed = 4               # Maximum speed determines a units maximum speed in km/h.

supply_consumption = 0.02       # Supply consumption determmines how much supply a unit consumes per day

default_morale = 0.3            # Default morale determines how much extra organisation can be regained 
                                # hourly when not in combat

combat_width = 0.5              # Combat width determines how much this unit contributes to overall combat width.

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: ""

Icons[edit]

When adding a new unit it may appear, that your unit gets random icons in the division designer (like anti air icon, or what ever) This is caused, because the actual unit has no icon. You can provide sprites in /Hearts of Iron IV/interface/*.gfx. Create a new gfx file for your new unit and add following content for each unit

spriteTypes = {	

   spriteType = { 
     name = "GFX_<your unit name>_icon_medium"				
     textureFile = "gfx/interface/counters/divisions_large/<your unit name>_icon.dds"  ## Thats the paradox shepe, but you can use any path and file naming you want
     noOfFrames = 2
   }

   spriteType = { 
     name = "GFX_<your unit name>_icon_medium_white"						
     textureFile = "gfx/interface/counters/divisions_small/onmap_unit_<your unit name>_icon.dds" 
     noOfFrames = 2
   }

}


Modding
Documentation EffectsTriggersDefinesModifiersScopesLocalisationVariablesArraysOn actions
Scripting AIBookmarksBuildingsCosmetic tagsCountriesDivisionsDecisionsEquipmentEventsIdeasIdeologiesNational FocusesResourcesScripted GUITechnologyUnits
Map MapStatesSupply areasStrategic regions
Graphical InterfaceGraphical AssetsEntitiesPosteffectsParticlesFonts
Cosmetic PortraitsNamelistsMusicSound
Other Console commandsTroubleshootingMod structure