effect · `add_dynamic_modifier`

Definition

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

Description

adds a dynamic modifier to the containing scope (country / state / unit-leader / special-project).
Updates the cooldown if exists.
Optionaly you can give a scope that will restrict the dynamic modifier to it.
example :
12 = {
  add_dynamic_modifier = {
    modifier = dynamic_modifier_name
    days = 42 # will be temporary if specified, can be variable
    scope = GER # optional, state/countrytag or a variable containing that. 
				# if specified the dynamic variable will target that scope
				# in this example : adds the modifier to state 12 but only applies for country GER
  }
}

实战 · 配合 · 坑

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

实战用法

add_dynamic_modifier 常用于需要根据变量动态调整数值的场景，例如根据某国工业水平或资源量实时缩放增益/减益、为特定国家或州添加限时 debuff（如战争破坏、封锁惩罚）等。它与静态 add_state_modifier / add_ideas 的核心区别在于 modifier 的数值来自变量，可随游戏进程实时变化。

# 为德国添加一个持续 60 天、绑定到 GER 的动态修正
42 = {
    add_dynamic_modifier = {
        modifier = war_damage_modifier
        scope = GER
        days = 60
    }
}

配合关系

[remove_dynamic_modifier](/wiki/effect/remove_dynamic_modifier)：添加动态修正后，在条件满足时移除它，构成"添加→条件触发→移除"的完整生命周期管理。
[force_update_dynamic_modifier](/wiki/effect/force_update_dynamic_modifier)：当绑定变量在回合内发生变化后，强制刷新动态修正的实际数值，避免显示或计算滞后。
[has_dynamic_modifier](/wiki/trigger/has_dynamic_modifier)：在触发器中检查某 scope 是否已持有该动态修正，防止重复叠加或用于分支判断。
[add_days_remove](/wiki/effect/add_days_remove)：若需在事件或决策中临时延长已存在的动态修正持续时间，可配合使用来修改倒计时。

常见坑

忘记 scope 字段导致修正作用对象错误：当在州(STATE) scope 下调用时，不指定 scope 意味着修正对所有拥有该州的国家生效；若只想对特定国家生效必须显式写 scope = TAG，否则会出现修正意外扩散到其他国家的 bug。
变量未初始化就添加动态修正：动态修正依赖的变量若在添加时尚未被赋值（为 0 或不存在），modifier 会以默认值 0 计算，表现上"没有效果"，新手常误以为脚本写错，实际上应确保在 add_dynamic_modifier 之前已通过 set_variable 或相关 effect 为对应变量赋初值。

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_dynamic_modifier is commonly used in scenarios where modifier values need to be dynamically adjusted based on variables, such as scaling bonuses/penalties in real-time according to a country's industrial capacity or resource levels, or applying temporary debuffs to specific countries or states (e.g., war damage, blockade penalties). Its core difference from static modifiers like add_state_modifier / add_ideas is that the modifier's numerical values come from variables and change in real-time as the game progresses.

# Add a dynamic modifier to Germany lasting 60 days, bound to the GER scope
42 = {
    add_dynamic_modifier = {
        modifier = war_damage_modifier
        scope = GER
        days = 60
    }
}

Synergy

[remove_dynamic_modifier](/wiki/effect/remove_dynamic_modifier): After adding a dynamic modifier, remove it when conditions are met, forming a complete lifecycle management of "add → condition trigger → remove".
[force_update_dynamic_modifier](/wiki/effect/force_update_dynamic_modifier): When the bound variable changes within a tick, force the dynamic modifier to refresh its actual numerical value, preventing display or calculation lag.
[has_dynamic_modifier](/wiki/trigger/has_dynamic_modifier): Check in a trigger whether a scope already possesses the dynamic modifier, preventing accidental stacking or used for branching logic.
[add_days_remove](/wiki/effect/add_days_remove): If you need to temporarily extend the duration of an existing dynamic modifier in an event or decision, use this in combination to modify the countdown.

Common Pitfalls

Forgetting the scope field causes the modifier to apply to the wrong target: When called under a state (STATE) scope without specifying scope, the modifier affects all countries that own that state; if you only want it to affect a specific country, you must explicitly write scope = TAG, otherwise the modifier may unexpectedly spread to other countries.
Adding a dynamic modifier when its variable is not initialized: If the variable that a dynamic modifier depends on has not been assigned a value when the modifier is added (is 0 or doesn't exist), the modifier will calculate with a default value of 0, appearing to have "no effect". Beginners often mistakenly think the script is wrong, but you should ensure that the corresponding variable is initialized with a value via set_variable or related effects before calling add_dynamic_modifier.

effect · add_dynamic_modifier