Wiki

effect · transfer_units_fraction

Definition

  • Supported scope:COUNTRY
  • Supported target:THIS, ROOT, PREV, FROM, OWNER, CONTROLLER, OCCUPIED, CAPITAL

Description

Transfer units (air, army, navy) to another country.
Also transfer the stockiled equipment (you can set it to zero if it is undesired) as well as unit leaders.

For 'keep  triggers', the scope is :
THIS = Character
FROM = Target country

Example:

transfer_units_fraction = { target = ROOT # the recipient size = 0.4 # [0,1] Default value for the ratio below if they are not specified stockpile_ratio = 0.3 # [0,1] Overrides size modifier for the stockpiled equipment and fuel army_ratio = 0.1 # [0,1] Overrides size modifier for army navy_ratio = 0.2 # [0,1] Overrides size modifier for navy air_ratio = 0.4 # [0,1] Overrides size modifier for air keep_unit_leaders = { # specify IDs of unit leaders that remain with the original country 700 701 } keep_unit_leaders_trigger = { # Trigger for unit leaders to remain with the original country # THIS is the unit leader being evaluated" # ROOT is the recipient" # FROM is the sender" # PREV is unset" [... triggers ...] } }

Hands-On Notes

Hands-on notes are AI-generated and checked against the vanilla command vocabulary — treat them as a starting point, not authoritative reference. The definition above is the game's own documentation.

Hands-On Usage

transfer_units_fraction is commonly used in puppet independence, civil war split scenarios, or historical event recreation—for example, when a nation gains independence from its overlord, a portion of its military units and stockpiled equipment must be transferred to the newly independent nation. It can also be used in player mods to simulate historical military transfers, such as Vichy France inheriting remnant forces after France's collapse.

# Independence event: transfer 40% of army and 20% of navy to the new nation
country_event = {
    id = my_mod.1
}

# Execute within the immediate block
immediate = {
    transfer_units_fraction = {
        target = FROM          # The newly independent nation
        size = 0.4
        army_ratio = 0.4
        navy_ratio = 0.2
        air_ratio = 0.0
        stockpile_ratio = 0.3
        keep_unit_leaders_trigger = {
            has_country_flag = stay_with_original  # Flag marking retained officers
        }
    }
}

Synergy

  • [annex_country](/wiki/effect/annex_country) / [end_puppet](/wiki/effect/end_puppet): During independence or annexation processes, use transfer_units_fraction first to transfer military units, then formally handle nation relations, preventing unit strength from simply vanishing.
  • [add_equipment_to_stockpile](/wiki/effect/add_equipment_to_stockpile): If stockpile_ratio is set to 0 to skip stockpile transfer, you can manually supplement the target nation with specific equipment afterward, allowing fine-grained control over initial equipment composition.
  • [has_army_size](/wiki/trigger/has_army_size): Check in trigger conditions whether the source nation has sufficient forces before transferring to prevent transfer ratios from creating adverse edge case effects on small nations.
  • [create_field_marshal](/wiki/effect/create_field_marshal) / [create_corps_commander](/wiki/effect/create_corps_commander): After retaining specific officers with keep_unit_leaders, supplement the target nation with new commanders to ensure both armies have proper leadership.

Common Pitfalls

  1. size is not a "minimum" but a fallback default: Beginners often mistakenly believe size is an upper limit on total units. In reality, army_ratio, navy_ratio, air_ratio, and stockpile_ratio each independently override size—only unspecified items fall back to using size. Omitting a specific ratio does not mean that unit type is excluded from transfer; rather, it will transfer according to the size ratio.
  2. keep_unit_leaders_trigger scope confusion: Within the trigger, THIS evaluates the individual officer character (Character scope), not the nation; FROM is the target (receiving) nation, and ROOT is the sending nation—writing ROOT to check the receiving nation's flags results in completely inverted logic.