Wiki

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 }

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

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