effect · `set_faction_upgrade`

Definition

Supported scope:COUNTRY
Supported target:none

Description

Set either a member upgrade for the specified tag

### Examples

TAG = { set_faction_upgrade = token }

实战 · 配合 · 坑

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

实战用法

set_faction_upgrade 常用于派系类 mod 中，当玩家或 AI 国家满足特定条件时（如完成国策、达到贡献阈值），为其解锁派系专属升级令牌，从而触发派系内的特殊加成或机制。例如在一个多派系竞争 mod 里，完成某条国策后自动授予该国升级权限：

focus = {
    id = my_faction_focus
    ...
    completion_reward = {
        TAG = {
            set_faction_upgrade = my_faction_upgrade_token
        }
    }
}

配合关系

[faction_upgrade_level](/wiki/trigger/faction_upgrade_level)：检测当前派系升级等级，常作为 set_faction_upgrade 的前置条件判断，防止重复授予或实现分级解锁逻辑。
[has_completed_faction_goal](/wiki/trigger/has_completed_faction_goal)：确认派系目标已完成后再执行升级设置，保证升级授予的合理触发时机。
[add_faction_goal](/wiki/effect/add_faction_goal)：与升级配合使用，先为派系添加新目标，再在目标达成时通过 set_faction_upgrade 发放对应升级，形成完整的派系进程链。
[add_faction_influence_score](/wiki/effect/add_faction_influence_score)：升级后同步调整影响力分数，体现升级带来的实际派系地位变化。

常见坑

token 拼写必须与 faction_upgrade 定义中完全一致，哪怕大小写或下划线一个字符不同，游戏不会报错但升级静默失效，极难排查。
scope 必须是实际存在的国家标签，在 every_faction_member 等迭代块内使用时，需确保每个成员都确实应当获得该升级，否则误授给不相关成员会导致派系逻辑混乱。

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

set_faction_upgrade is commonly used in faction-themed mods. When a player or AI nation meets specific conditions (such as completing a focus tree, reaching a contribution threshold), it grants them faction-exclusive upgrade tokens, triggering special bonuses or mechanics within the faction. For example, in a multi-faction competition mod, completing a certain focus tree automatically grants upgrade permissions to that nation:

focus = {
    id = my_faction_focus
    ...
    completion_reward = {
        TAG = {
            set_faction_upgrade = my_faction_upgrade_token
        }
    }
}

Synergy

[faction_upgrade_level](/wiki/trigger/faction_upgrade_level): Checks the current faction upgrade tier, commonly used as a precondition for set_faction_upgrade to prevent duplicate grants or implement tiered unlock logic.
[has_completed_faction_goal](/wiki/trigger/has_completed_faction_goal): Confirms the faction goal is completed before executing upgrade assignment, ensuring upgrades are granted at the appropriate trigger moment.
[add_faction_goal](/wiki/effect/add_faction_goal): Works in conjunction with upgrades—first add a new goal to the faction, then distribute corresponding upgrades via set_faction_upgrade when the goal is achieved, forming a complete faction progression chain.
[add_faction_influence_score](/wiki/effect/add_faction_influence_score): Synchronizes influence score adjustments after upgrade, reflecting the actual faction status change brought by the upgrade.

Common Pitfalls

Token spelling must match exactly with the definition in faction_upgrade—even a single character difference in capitalization or underscores will cause the upgrade to silently fail without error messages, making it extremely difficult to debug.
Scope must be an actually existing country tag—when used within iteration blocks like every_faction_member, ensure each member genuinely deserves the upgrade; otherwise, mistakenly granting it to unrelated members will cause faction logic confusion.

effect · set_faction_upgrade