effect · remove_unit_leader

Hands-On Usage

remove_unit_leader is commonly used in scripted events to remove a specific unit leader (e.g., character death, capture, retirement storyline), or to bulk-replace outdated leader IDs when restructuring a MOD's commander system. Before use, verify the target leader's numeric ID through debugging or log inspection, then pass it directly to the command.

country_event = {
    id = my_mod.5
    title = "将领阵亡"
    option = {
        name = "沉痛悼念"
        remove_unit_leader = 1200  # Remove leader with ID 1200
    }
}

Synergy

• [create_corps_commander](/wiki/effect/create_corps_commander) / [create_field_marshal](/wiki/effect/create_field_marshal): Create a new leader immediately after removing the old one to implement a leader "replacement" storyline, avoiding duplicate characters with the same name in the roster.
• [kill_operative](/wiki/effect/kill_operative): Both are "remove character from the world" type commands; when handling character death events, choose between them based on role—use remove_unit_leader for unit leaders and kill_operative for operatives to maintain logical consistency.
• [any_unit_leader](/wiki/trigger/any_unit_leader): Confirm the target leader actually exists before executing the removal using this trigger, preventing silent errors or log warnings when an ID doesn't exist.
• [remove_unit_leader_role](/wiki/effect/remove_unit_leader_role): If you only want to strip a leader of a specific position rather than delete the character entirely, prioritize this command instead; the two serve different purposes and should be chosen based on context.

Common Pitfalls

1. Hardcoded IDs fail in multiplayer/dynamic generation scenarios: remove_unit_leader relies on fixed numeric IDs; if the leader was dynamically generated via create_corps_commander or similar commands, its ID may vary across saves or game versions. Hard-coding the ID will fail to remove the intended leader—pair the command with variables or event trigger chains to ensure reliable ID sourcing.
2. Removal cannot be undone after execution: Once executed, the leader vanishes from the game permanently (not a death event, does not trigger death-related on_actions) and cannot be recovered through normal means. Always thoroughly verify ID accuracy in a test environment before deploying to production.