effect · `add_to_faction`

Definition

Supported scope:COUNTRY
Supported target:THIS, ROOT, PREV, FROM, OWNER, CONTROLLER, OCCUPIED, CAPITAL

Description

adds specified country to faction

实战 · 配合 · 坑

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

实战用法

add_to_faction 常用于构建自定义阵营脚本中，当玩家或 AI 满足特定条件后自动拉入盟友，例如实现历史事件中某国加入轴心国或盟军的剧本。也可用于决策或国家焦点完成后的奖励效果，让目标国家在外交上绑定到己方阵营。

# 某国完成焦点后将邻国拉入自己的阵营
complete_national_focus = join_our_pact
country_event = {
    id = myfocus.1
}
# 在事件 option 中：
GER = {
    add_to_faction = HUN
}

配合关系

[create_faction](/wiki/effect/create_faction)：在使用 add_to_faction 之前，必须先确保阵营已存在，create_faction 负责创建阵营，两者构成"建立阵营→拉人入伙"的完整流程。
[has_country_flag](/wiki/trigger/has_country_flag)：常用来检查目标国是否已被邀请或是否满足加入条件，避免重复触发加入逻辑。
[give_guarantee](/wiki/effect/give_guarantee)：加入阵营后通常伴随外交保证，强化阵营内的防御承诺关系。
[exists](/wiki/trigger/exists)：在执行前判断目标国家是否存在于当前游戏中，防止因国家被消灭或未生成导致脚本报错。

常见坑

目标国尚未存在即调用：若目标国在游戏中已亡国或从未生成，直接调用 add_to_faction 会静默失败甚至产生错误日志，务必先用 [exists](/wiki/trigger/exists) 做保护判断。
阵营宿主混淆：add_to_faction 的 scope 必须是阵营创建者（领袖国），而非被拉入的国家；新手常误将 scope 写成目标国，导致效果无法生效或写成 target = 领袖国 的反向写法。

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

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

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.
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.

effect · add_to_faction