trigger · `num_units`

Definition

Supported scope:CHARACTER
Supported target:none

Description

Check number of units commanded by the unit leader 
 num_units > 2

实战 · 配合 · 坑

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

实战用法

num_units 常用于判断某位指挥官当前统率的部队数量，从而决定是否触发特殊事件、解锁特质或激活某些奖励，例如"名将成长"类 mod 中根据麾下兵力规模动态授予荣誉称号。也可用于 limit 块内，限制只有真正在前线指挥大规模部队的将领才能获得相关 buff 或升级机会。

# 当指挥官统率的部队超过 2 支时，触发晋升事件
character_event = {
    id = my_mod.101
    trigger = {
        is_corps_commander = yes
        num_units > 2
    }
    # ...
}

配合关系

[is_corps_commander](/wiki/trigger/is_corps_commander) / [is_field_marshal](/wiki/trigger/is_field_marshal)：先确认角色身份再检查兵力数量，避免对非作战指挥官进行无意义判断。
[skill](/wiki/trigger/skill)：与技能等级联合使用，可构造"高级别且统率大军"的复合条件，用于筛选真正的精英将领。
[add_trait](/wiki/effect/add_trait)：满足兵力条件后为将领添加特质，是"根据战场规模成长"机制的标准实现搭档。
[add_skill_level](/wiki/effect/add_skill_level)：当兵力达到阈值时提升将领技能等级，常见于 RPG 化将领成长系统。

常见坑

混淆"部队数量"含义：num_units 统计的是该将领直接指挥的师级单位（division）数量，而非集团军或军团数，新手容易误以为是下属指挥官的数量，导致阈值设置严重偏高或偏低。
在非 CHARACTER scope 下调用：该 trigger 仅在 CHARACTER scope 下有效，若在 country 或 division 等 scope 中直接使用不会报错但始终返回假，排查时容易被忽略，务必确认当前 scope。

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

num_units is commonly used to determine the current number of divisions under a commander's control, enabling decisions on whether to trigger special events, unlock traits, or activate certain bonuses. For example, in "legendary general growth" mods, honorary titles can be dynamically granted based on the scale of forces under command. It can also be used within limit blocks to restrict relevant buffs or promotion opportunities to commanders who are genuinely leading large-scale forces on the front lines.

# Trigger a promotion event when the commander controls more than 2 divisions
character_event = {
    id = my_mod.101
    trigger = {
        is_corps_commander = yes
        num_units > 2
    }
    # ...
}

Synergy

[is_corps_commander](/wiki/trigger/is_corps_commander) / [is_field_marshal](/wiki/trigger/is_field_marshal): First confirm the character's role before checking unit count, avoiding meaningless checks on non-combat commanders.
[skill](/wiki/trigger/skill): Use in conjunction with skill level to construct compound conditions like "high rank and commanding large forces," useful for filtering truly elite officers.
[add_trait](/wiki/effect/add_trait): Add traits to commanders after satisfying unit count conditions, a standard implementation partner for "growth based on battlefield scale" mechanics.
[add_skill_level](/wiki/effect/add_skill_level): Increase commander skill levels when unit count reaches thresholds, commonly seen in RPG-style commander growth systems.

Common Pitfalls

Confusing the meaning of "unit count": num_units counts the number of division-level units directly commanded by the character, not subordinate commanders or corps. Newcomers often mistakenly think it refers to the number of subordinate commanders, leading to severely miscalibrated thresholds.
Calling outside CHARACTER scope: This trigger is only valid under CHARACTER scope. Using it directly in country or division scopes will not produce errors but always returns false, easily overlooked during debugging. Always verify the current scope.

trigger · num_units