effect · `add_power_balance_modifier`

Definition

Supported scope:any
Supported target:none

Description

adds static modifier to power balance

Example:
add_power_balance_modifier = {
	id = power_balance_id
	modifier = static_modifier_id # this must be defined in the static modifier database
}

实战 · 配合 · 坑

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

实战用法

add_power_balance_modifier 常用于势力平衡（Power Balance）系统的 mod 中，例如在某一事件选项触发后，为某一阵营施加持续性的加权修正，以反映外交、军事或意识形态上的长期影响。典型场景包括：当玩家完成某条国策时，给对应的权力天平添加一个有利修正。

# 在某国策完成后，为全球权力天平添加修正
focus = {
    id = strengthen_axis_influence
    ...
    completion_reward = {
        add_power_balance_modifier = {
            id = global_power_balance
            modifier = axis_influence_boost
        }
    }
}

配合关系

[has_power_balance_modifier](/wiki/trigger/has_power_balance_modifier)：在施加新修正前，先检测该修正是否已存在，避免重复叠加导致不预期的效果。
[remove_power_balance_modifier](/wiki/effect/remove_power_balance_modifier)：与本命令配对使用，用于在特定条件下移除之前添加的修正，实现动态的势力天平管理。
[is_power_balance_in_range](/wiki/trigger/is_power_balance_in_range)：在添加修正后，通过该触发器检查当前天平值是否落在期望区间，驱动后续的条件分支逻辑。
[remove_all_power_balance_modifiers](/wiki/effect/remove_all_power_balance_modifiers)：当需要完全重置某个势力天平的所有修正时（如剧本重置节点），与本命令形成清空-再添加的组合。

常见坑

modifier 字段指向的静态修正器必须预先在 static_modifiers 数据库中定义，否则游戏会静默忽略或报错；新手常误将普通修正器名称直接填入，导致修正不生效且难以排查。
id 字段对应的是 Power Balance 的标识符，而非修正器本身的名字，两者很容易混淆——id 指向你在 power_balance 定义文件中声明的那个天平对象，填错会导致修正被挂载到错误的天平甚至完全无效。

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_power_balance_modifier is commonly used in mods featuring the Power Balance system, such as applying persistent weighted modifiers to a faction after a certain event option triggers, reflecting long-term impacts in diplomacy, military affairs, or ideology. Typical scenarios include adding a favorable modifier to the corresponding power balance upon the player's completion of a specific national focus.

# Add a modifier to the global power balance upon focus completion
focus = {
    id = strengthen_axis_influence
    ...
    completion_reward = {
        add_power_balance_modifier = {
            id = global_power_balance
            modifier = axis_influence_boost
        }
    }
}

Synergy

[has_power_balance_modifier](/wiki/trigger/has_power_balance_modifier): Before applying a new modifier, first check whether the modifier already exists to avoid unintended stacking effects.
[remove_power_balance_modifier](/wiki/effect/remove_power_balance_modifier): Used in tandem with this command to remove previously added modifiers under specific conditions, enabling dynamic power balance management.
[is_power_balance_in_range](/wiki/trigger/is_power_balance_in_range): After adding a modifier, use this trigger to verify whether the current balance value falls within the expected range, driving subsequent conditional logic branches.
[remove_all_power_balance_modifiers](/wiki/effect/remove_all_power_balance_modifiers): When you need to completely reset all modifiers on a power balance (such as at scenario reset nodes), combine this command with a clear-then-add pattern.

Common Pitfalls

The modifier field must reference a static modifier previously defined in the static_modifiers database, otherwise the game will silently ignore it or report an error; beginners often mistakenly insert generic modifier names directly, causing the modifier to fail silently and becoming difficult to debug.
The id field refers to the Power Balance identifier, not the modifier's name itself—these two are easily confused. id points to the balance object you declared in your power_balance definition file; entering the wrong value causes the modifier to attach to the wrong balance or become completely ineffective.

effect · add_power_balance_modifier