effect · add_to_faction

Hands-On Usage

add_to_faction is commonly used in custom faction-building scripts to automatically recruit allied nations when the player or AI meets specific conditions—such as implementing historical scenarios where a nation joins the Axis or Allies. It can also serve as a reward effect upon decision completion or national focus completion, diplomatically binding the target nation to your faction.

# Pull a neighboring country into your faction after completing a focus
complete_national_focus = join_our_pact
country_event = {
    id = myfocus.1
}
# In the event option:
GER = {
    add_to_faction = HUN
}

Synergy

• [create_faction](/wiki/effect/create_faction): Before using add_to_faction, you must first ensure the faction exists. create_faction handles faction creation, and together they form the complete workflow of "establish faction → recruit members."
• [has_country_flag](/wiki/trigger/has_country_flag): Commonly used to check whether the target nation has already been invited or meets membership conditions, preventing duplicate recruitment logic from triggering.
• [give_guarantee](/wiki/effect/give_guarantee): Joining a faction is typically accompanied by diplomatic guarantees, strengthening defensive commitment relationships within the faction.
• [exists](/wiki/trigger/exists): Before execution, verify that the target nation exists in the current game to prevent script errors caused by the nation being eliminated or never spawning.

Common Pitfalls

1. Calling before the target nation exists: If the target nation has been eliminated or never spawned in the game, calling add_to_faction will silently fail or produce error logs. Always protect it with a [exists](/wiki/trigger/exists) check first.
2. Confusion over faction host scope: The scope of add_to_faction must be the faction creator (leader nation), not the nation being recruited. Beginners often mistakenly set the scope to the target nation, causing the effect to fail or write it in reverse as target = leader_nation.