effect · destroy_unit

Hands-On Usage

destroy_unit is used to permanently remove units within the current scope when specific events or decisions are triggered. This is commonly employed in scripted events (such as disbanding rebel forces after a civil war ends) or in mission chains to clean up temporary test units. Note that this effect operates directly on unit objects already in unit scope, and is typically used in conjunction with unit scope iteration.

# Event trigger: Civil war ends, destroy all rebel units
country_event = {
    id = civil_war.5
    ...
    option = {
        name = civil_war.5.a
        # Iterate through enemy faction units and destroy them one by one
        enemy_country = {
            every_unit = {
                destroy_unit = yes
            }
        }
    }
}

Synergy

Since there are no other cross-referenceable effects or trigger commands within the same scope in the current whitelist, there are no whitelisted companion commands to list. In actual development, this command typically relies on native game iteration blocks like every_unit to determine the scope of application, but these are not included in the whitelist provided here. Please refer to the official Wiki for a complete list.

Common Pitfalls

1. Incorrect scope targeting: Beginners often write destroy_unit = yes directly under country scope without first entering the specific unit scope (such as through every_unit iteration), resulting in script errors or no effect. Always verify that the current scope is the target unit itself.
2. Mistaking it for a reversible action: destroy_unit is permanent destruction and cannot preserve unit data like transferring units would. If you only want units to temporarily disappear or transfer control, consider other methods instead of this command, otherwise unit data will be completely lost.