effect · set_faction_leader

Hands-On Usage

set_faction_leader is commonly used in mods to implement power transitions between nations or faction leadership transfers following story events, such as allowing a country to assume control of an alliance through national focuses or events, replacing the original leader. Typical scenarios include a player-backed puppet state rising to independence and becoming faction leader, or the original leader being eliminated and replaced by the strongest ally.

# A nation becomes faction leader of its faction upon completing a national focus
focus = {
    id = claim_faction_leadership
    ...
    completion_reward = {
        set_faction_leader = yes
    }
}

Synergy

• [create_faction](/wiki/effect/create_faction): If the current nation does not yet have a faction, it must first be created before set_faction_leader can be used to establish leadership, with the two effects typically chained in sequence.
• [dismantle_faction](/wiki/effect/dismantle_faction): In faction restructuring scenarios, you can dismantle the old faction first, then have a new nation rebuild and seize leadership, creating a complete workflow when combined with set_faction_leader.
• [has_country_flag](/wiki/trigger/has_country_flag): Use this to perform conditional checks before executing a leadership transfer, ensuring only nations with specific story flags trigger the effect and preventing logical conflicts.
• [add_to_faction](/wiki/effect/add_to_faction): After setting a new leader, other member nations typically need to be re-added to the faction; using both together ensures the faction's member structure remains intact.

Common Pitfalls

1. Using the effect when the nation is not in any faction causes errors or has no effect: set_faction_leader requires the executing nation to already be a member of some faction. If the nation has neither joined nor owns a faction, the command will not work. You must first use create_faction or add_to_faction to ensure a faction exists.
2. Accidentally calling it outside COUNTRY scope: This effect can only be executed within country scope. If mistakenly written in STATE or CHARACTER scope (for example, nested inside an every_owned_state block without switching back to country scope), it will cause script errors or fail silently.