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 ...] } }

实战 · 配合 · 坑

实战内容由 AI 生成,并已对照 vanilla 命令词表校验 —— 请当作起点而非权威依据。上方的定义节才是游戏自带文档原文。

实战用法

transfer_units_fraction 常用于傀儡独立、分裂内战或历史事件还原场景——例如某国从宗主国独立时，需要将一部分军队和库存装备移交给新生国家。也可用于玩家 mod 中模拟历史上的军队交接，如法国沦陷后维希法国继承残余兵力。

# 某国独立事件：将40%的陆军和20%的海军移交给新国家
country_event = {
    id = my_mod.1
}

# 在 immediate 块中执行
immediate = {
    transfer_units_fraction = {
        target = FROM          # 新独立的国家
        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  # 标记保留的将领
        }
    }
}

配合关系

[annex_country](/wiki/effect/annex_country) / [end_puppet](/wiki/effect/end_puppet)：独立或吞并流程中，先用 transfer_units_fraction 移交军队，再正式处理国家关系，避免兵力直接蒸发。
[add_equipment_to_stockpile](/wiki/effect/add_equipment_to_stockpile)：若 stockpile_ratio 设为 0 不移交库存，可额外手动给目标国补发特定装备，精细控制初始装备构成。
[has_army_size](/wiki/trigger/has_army_size)：在触发条件中先检查来源国是否有足够兵力，防止移交比例对小国产生负面边界效果。
[create_field_marshal](/wiki/effect/create_field_marshal) / [create_corps_commander](/wiki/effect/create_corps_commander)：配合 keep_unit_leaders 保留特定将领后，为目标国补充新的指挥官，使双方军队均有领导层。

常见坑

size 不是"保底"而是默认值：新手常误以为 size 是总量上限，实际上 army_ratio、navy_ratio、air_ratio、stockpile_ratio 各自独立覆盖 size，未单独指定的项才回退使用 size——漏写某个 ratio 并不代表该类型不移交，而是会按 size 比例移交。
keep_unit_leaders_trigger 的 scope 易搞混：触发器内 THIS 是被评估的将领角色（Character scope），而非国家；FROM 才是目标（接收方）国家，ROOT 是发送方——写成 ROOT 判断接收国 flag 会导致逻辑完全相反。

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

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.
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.

effect · transfer_units_fraction