trigger · num_units

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

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