effect · `add_to_variable`

Definition

Supported scope:any
Supported target:none

Description

Adds a value, a variable, or a [math expression](script_math_expression.md) to a variable.

### Examples

add_to_variable = { num_dogs = 42 } add_to_variable = { num_dogs = { value = num_cats multiply = 2 } }

实战 · 配合 · 坑

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

实战用法

add_to_variable 最常用于追踪累计数值的 mod 场景，例如记录玩家发动战争的次数、累计征召的人口，或动态积分系统中向某个变量叠加分值。它与 set_variable 的区别在于它是叠加而非覆盖，因此适合多个事件都可能触发、每次只贡献一部分数值的设计。

# 每次触发事件时，给国家的"战争积分"变量加上当前军事力量值
country_event = {
    id = my_mod.1
    option = {
        name = my_mod.1.a
        add_to_variable = {
            var = war_score_total
            value = army_strength  # 引用另一个变量作为增量
        }
    }
}

配合关系

[set_variable](/wiki/effect/set_variable)：在首次使用 add_to_variable 前，通常需要先用 set_variable 将目标变量初始化为 0，否则叠加到未定义变量上可能产生意外结果。
[clamp_variable](/wiki/effect/clamp_variable)：叠加操作容易让变量超出设计上限，配合 clamp_variable 可在每次叠加后将值约束在合法范围内。
[check_variable](/wiki/trigger/check_variable)：叠加后通常需要检测变量是否达到阈值以触发下一步逻辑，check_variable 是最直接的配套触发器。
[multiply_variable](/wiki/effect/multiply_variable)：在计算复合公式时（如带倍率的积分系统），先用 add_to_variable 累加基础值，再用 multiply_variable 应用系数。

常见坑

对未初始化变量叠加：若目标变量 var 从未被 set_variable 赋值，游戏会将其视为 0 开始叠加，表面上看似正常，但在某些版本或特定 scope 下可能导致 has_variable 检测不一致，建议始终在 on_startup 或事件触发前显式初始化变量。
value 字段误填变量名字符串：value 接受数字字面量或同 scope 下已定义的变量名（不加引号），若误将变量名写成带引号的字符串，游戏不会报错但只会读入 0 或报解析警告，导致变量始终不增加，排查时极易忽略。

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_variable is most commonly used in mod scenarios where you need to track cumulative values, such as recording how many wars a player has started, total population conscripted, or accumulating points in a dynamic scoring system to a specific variable. The key difference from set_variable is that it accumulates rather than overwrites, making it ideal for designs where multiple events can trigger and each contributes only a portion of the value.

# Each time the event fires, add the current military strength value to the nation's "war_score_total" variable
country_event = {
    id = my_mod.1
    option = {
        name = my_mod.1.a
        add_to_variable = {
            var = war_score_total
            value = army_strength  # Reference another variable as the increment
        }
    }
}

Synergy

[set_variable](/wiki/effect/set_variable): Before using add_to_variable for the first time, you typically need to initialize the target variable to 0 with set_variable first, otherwise accumulating onto an undefined variable may produce unexpected results.
[clamp_variable](/wiki/effect/clamp_variable): Accumulation operations can easily push a variable beyond its designed limit. Pairing with clamp_variable constrains the value to a legal range after each accumulation.
[check_variable](/wiki/trigger/check_variable): After accumulation, you usually need to check whether the variable has reached a threshold to trigger the next logic step; check_variable is the most straightforward companion trigger.
[multiply_variable](/wiki/effect/multiply_variable): When calculating composite formulas (such as a scoring system with multipliers), first use add_to_variable to accumulate base values, then apply the coefficient with multiply_variable.

Common Pitfalls

Accumulating onto uninitialized variables: If the target variable var has never been assigned by set_variable, the game treats it as starting from 0 and begins accumulating. While this may appear to work normally on the surface, in certain game versions or specific scopes it can cause inconsistent behavior with has_variable checks. It is recommended to always explicitly initialize variables in on_startup or before event triggers.
Mistakenly filling the value field with a quoted variable name string: The value field accepts numeric literals or variable names defined within the same scope (without quotes). If you accidentally write a variable name as a quoted string, the game will not error but will only read 0 or produce parsing warnings, causing the variable to never increment. This mistake is easy to overlook during debugging.

effect · add_to_variable