effect · `leave_faction`

Definition

Supported scope:COUNTRY
Supported target:none

Description

Country leaves the faction

实战 · 配合 · 坑

实战内容由 AI 生成,并已对照 vanilla 命令词表校验 —— 请当作起点而非权威依据。上方的定义节才是游戏自带文档原文。

实战用法

leave_faction 常用于 mod 中设计"退出同盟"的事件或决策，例如让某个小国在特定政治条件下宣布中立、脱离轴心国或盟国阵营。典型场景包括：玩家触发事件后选择"退出公约"、或 AI 在战争局势不利时通过隐藏效果自动脱离派系。

# 决策选项：宣布脱离派系
option = {
    name = my_event.1.a
    leave_faction = yes
    add_political_power = -50
    add_stability = -0.05
}

配合关系

[has_country_flag](/wiki/trigger/has_country_flag)：在执行前先检查该国是否已被标记为"不得主动退出"，避免重复或冲突触发。
[dismantle_faction](/wiki/effect/dismantle_faction)：若该国同时是派系领袖，单纯 leave_faction 会导致孤立子派系，应先用 dismantle_faction 解散派系再处理后续逻辑。
[add_opinion_modifier](/wiki/effect/add_opinion_modifier)：退出派系后通常需要向原领袖添加负面观感修正，模拟外交破裂的现实影响。
[create_wargoal](/wiki/effect/create_wargoal)：配合派系领袖方的后续事件，允许其对背叛者宣战，增强叙事连贯性。

常见坑

对派系领袖直接使用会导致派系自动解散：HOI4 中派系领袖离开派系时，引擎会强制解散整个派系，若 mod 意图只是让领袖"换人"而非解散，应改用 dismantle_faction 配合 create_faction 重建，而非依赖 leave_faction。
scope 未切换到正确国家：leave_faction 的 scope 必须是要离开派系的那个国家本身，新手常在 ROOT 是派系领袖的情况下忘记用 PREV/FROM/every_faction_member 切换 scope，导致错误国家被踢出派系。

Hands-On Notes

Hands-on notes are AI-generated and checked against the vanilla command vocabulary — treat them as a starting point, not authoritative reference. The definition above is the game's own documentation.

Hands-On Usage

leave_faction is commonly used in mods to design events or decisions for "leaving an alliance". For example, allowing a minor nation to declare neutrality under specific political conditions, or breaking away from the Axis or Allied faction. Typical scenarios include: the player triggering an event and choosing to "withdraw from the pact", or the AI automatically leaving a faction through hidden effects when the war situation becomes unfavorable.

# Decision option: declare withdrawal from faction
option = {
    name = my_event.1.a
    leave_faction = yes
    add_political_power = -50
    add_stability = -0.05
}

Synergy

[has_country_flag](/wiki/trigger/has_country_flag): Check before execution whether the country has been flagged as "cannot voluntarily leave", preventing duplicate or conflicting triggers.
[dismantle_faction](/wiki/effect/dismantle_faction): If the country is simultaneously the faction leader, using leave_faction alone will result in orphaned sub-factions. Use dismantle_faction to dismantle the faction first before handling subsequent logic.
[add_opinion_modifier](/wiki/effect/add_opinion_modifier): After leaving the faction, typically add negative opinion modifiers to the former leader to simulate the realistic impact of diplomatic rupture.
[create_wargoal](/wiki/effect/create_wargoal): Pair with subsequent events on the faction leader's side to allow them to declare war on the betrayer, enhancing narrative coherence.

Common Pitfalls

Using directly on the faction leader causes automatic faction dissolution: In HOI4, when the faction leader leaves the faction, the engine forcibly dissolves the entire faction. If the mod intends only to "replace the leader" rather than disband the faction, use dismantle_faction combined with create_faction to rebuild instead of relying on leave_faction.
Scope not switched to the correct country: The scope of leave_faction must be the country that is leaving the faction itself. Beginners often forget to switch scope using PREV/FROM/every_faction_member when ROOT is the faction leader, causing the wrong country to be kicked from the faction.

effect · leave_faction