effect · swap_ruler_traits

Hands-On Usage

swap_ruler_traits is commonly used in national focuses, decisions, or events to replace a country's leader traits, simulating shifts in a leader's personality or capabilities following a historical event (for example, shifting from "hardened diplomat" to "isolationist" after military defeat). This is ideal for history-focused mods, allowing dynamic repositioning of leaders at key narrative moments without destroying and rebuilding the entire leader character.

# After a decision is executed, replace moderate traits with more radical ones
country_event = {
    id = mymod.1
    option = {
        name = mymod.1.a
        swap_ruler_traits = {
            remove = trait_moderate_diplomat
            add = trait_ultranationalist_demagogue
        }
    }
}

Synergy

• [has_country_leader_with_trait](/wiki/trigger/has_country_leader_with_trait) — Check that the leader actually possesses the target trait before executing the swap, preventing silent failure if the remove field points to a non-existent trait.
• [add_country_leader_trait](/wiki/effect/add_country_leader_trait) — Use in conjunction when you need to layer a third new trait alongside the swap; the two have distinct responsibilities: one handles "replacement," the other handles "addition."
• [has_country_leader](/wiki/trigger/has_country_leader) — In scope transitions or multi-country scripts, confirm an active leader exists within the current scope first, preventing errors when executing commands on leaderless nations.
• [country_event](/wiki/effect/country_event) — Typically wrap swap_ruler_traits within an event option to trigger it; use the event popup to present narrative context to the player, enhancing immersion.

Common Pitfalls

1. The trait in remove must already be equipped on the current leader. If the leader does not actually possess that trait, the command will not error but the add will likewise fail silently, causing the new trait to disappear without warning—always protect with a conditional check using [has_country_leader_with_trait](/wiki/trigger/has_country_leader_with_trait) beforehand.
2. Scope must be COUNTRY, not character. Beginners often call this command directly inside every_character or create_country_leader blocks; you actually need to exit back to country scope first, otherwise it triggers a scope type mismatch error.