effect · `add_unit_bonus`

Definition

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

Description

Adds permanent subunit and subunit category bonuses for country.

Example:
add_unit_bonus = {
  category_light_infantry = { # Subunit category bonuses
	   soft_attack = 0.05
	   name = [LOC_KEY] # Optional localization key for the bonus name
	}
  
  cavalry = { # Subunit bonuses
	   soft_attack = 0.05
       hard_attack = 0.05
	   name = [LOC_KEY] # Optional localization key for the bonus name
	}
}

实战 · 配合 · 坑

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

实战用法

add_unit_bonus 适合用于国家焦点、科技决议或事件中，为特定国家永久强化某一兵种或兵种分类的战斗属性，例如给步兵专精国家额外增加轻步兵软攻击力，或为骑兵大国同时提升软攻和硬攻。注意该加成是永久性的，不同于动态修正器可以随时移除，因此适合作为"里程碑式"奖励而非临时增益。

# 在某个国家焦点完成时，强化轻步兵与骑兵
complete_national_focus = focus_infantry_doctrine
immediate = {
    add_unit_bonus = {
        category_light_infantry = {
            soft_attack = 0.05
            name = infantry_bonus_name
        }
        cavalry = {
            soft_attack = 0.05
            hard_attack = 0.05
            name = cavalry_bonus_name
        }
    }
}

配合关系

[add_tech_bonus](/wiki/effect/add_tech_bonus)：两者常在同一焦点或事件中同时触发，一个给技术研究加速，另一个直接给兵种属性加成，共同构成军事专精路线的奖励包。
[add_ideas](/wiki/effect/add_ideas)：思想理念通常携带全局修正，而 add_unit_bonus 针对具体兵种，二者组合可以实现"宏观+微观"的分层军事强化。
[add_dynamic_modifier](/wiki/effect/add_dynamic_modifier)：动态修正器可移除、可条件变化，与 add_unit_bonus 的永久性加成形成互补——临时作战状态用动态修正器，永久里程碑成就用本指令。
[has_completed_focus](/wiki/trigger/has_completed_focus)：常作为触发条件检查，确保只有完成了先决焦点的国家才能继续获得后续兵种奖励，避免顺序混乱。

常见坑

把兵种分类键名写错：category_light_infantry 这类带 category_ 前缀的键与直接写兵种名（如 cavalry）语法相同但含义不同，前者影响整个分类下的所有子单位，后者只影响该具体子单位。新手容易混用或拼错分类名导致加成静默失效，且游戏不会给出明显报错。
误以为可以通过再次调用来叠加同名 name 键覆盖旧加成：add_unit_bonus 是累加而非替换，多次触发会不断叠加数值。若设计上只想给一次奖励，必须配合 [has_country_flag](/wiki/trigger/has_country_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

add_unit_bonus is best used in national focuses, technology decisions, or events to permanently enhance combat attributes of specific unit types or unit categories for a particular nation. For example, you might grant additional soft attack to light infantry for an infantry-specialist nation, or simultaneously boost both soft and hard attack for a cavalry-focused great power. Note that this bonus is permanent in nature, unlike dynamic modifiers which can be removed at any time. This makes it suitable for "milestone-style" rewards rather than temporary buffs.

# Strengthen light infantry and cavalry upon completion of a national focus
complete_national_focus = focus_infantry_doctrine
immediate = {
    add_unit_bonus = {
        category_light_infantry = {
            soft_attack = 0.05
            name = infantry_bonus_name
        }
        cavalry = {
            soft_attack = 0.05
            hard_attack = 0.05
            name = cavalry_bonus_name
        }
    }
}

Synergy

[add_tech_bonus](/wiki/effect/add_tech_bonus): These two effects frequently trigger simultaneously within the same focus or event—one accelerates technology research while the other directly grants unit attribute bonuses, together forming the reward package for a military specialization path.
[add_ideas](/wiki/effect/add_ideas): National spirits typically carry global modifiers, while add_unit_bonus targets specific unit types. Combined, they enable "macro + micro" layered military strengthening.
[add_dynamic_modifier](/wiki/effect/add_dynamic_modifier): Dynamic modifiers are removable and condition-responsive, complementing add_unit_bonus's permanent bonuses—use dynamic modifiers for temporary combat states and this command for permanent milestone achievements.
[has_completed_focus](/wiki/trigger/has_completed_focus): Commonly serves as a trigger condition to ensure only nations that have completed prerequisite focuses continue receiving subsequent unit rewards, preventing sequence confusion.

Common Pitfalls

Misspelling unit category keys: Keys like category_light_infantry with the category_ prefix and direct unit names (such as cavalry) follow the same syntax but carry different meanings. The former affects all sub-units within that entire category, while the latter only affects that specific unit type. Newcomers often mix these up or misspell category names, causing bonuses to silently fail with no obvious error message from the game.
Assuming repeated calls with the same name key will override the previous bonus: add_unit_bonus is additive, not replacive. Multiple triggers will continuously stack values. If your design intends to grant the bonus only once, you must pair it with deduplication logic using [has_country_flag](/wiki/trigger/has_country_flag) or similar flagging mechanisms. Otherwise, repeatedly triggered events or decisions will cause bonuses to accumulate infinitely.

effect · add_unit_bonus