Wiki

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 } }

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

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