trigger · has_unit_leader

Hands-On Usage

has_unit_leader is commonly used to check whether a specific unit leader remains under a particular country's command. For example, it can be used in events or decisions to determine whether a key story character (such as a leader with a specific ID) is still alive and not captured, thereby deciding whether to trigger subsequent story chains. It can also be used in the available block to lock a decision, allowing execution only when the player possesses that leader.

# Example: A decision is only available when possessing a leader with ID 500
decision_example = {
    available = {
        has_unit_leader = 500
    }
    ...
}

Synergy

• [any_unit_leader](/wiki/trigger/any_unit_leader): When precise ID matching is unnecessary and you only need to check whether a leader exists that meets certain conditions, the two form a complementary pair — has_unit_leader provides exact pinpointing while any_unit_leader enables generalized filtering.
• [every_unit_leader](/wiki/effect/every_unit_leader): After confirming the leader exists, use every_unit_leader to batch-add traits or modify attributes to them. Using them together ensures operations are safe and error-free.
• [has_character](/wiki/trigger/has_character): If a leader simultaneously exists as an advisor or character, has_character can detect their character status. Using both together allows you to cover multi-faceted identity checks for the same person.
• [add_trait](/wiki/effect/add_trait): After confirming the leader exists, add traits to them to avoid executing trait additions when a leader doesn't exist, which could cause script errors or silent failures.

Common Pitfalls

1. Confusion over ID sources: This trigger uses the leader's numeric ID (id = XXX), not the name field or character key. Beginners often mistakenly use localized names or character keys as parameters, causing the condition to never be satisfied.
2. Not suitable for tooltip display: The official documentation explicitly states this trigger is for debugging purposes only and should not display tooltips to players. Placing it in a trigger_tooltip block to show players will result in missing or garbled description text. Use other more intuitive conditions as readable alternatives instead.