Wiki

effect · for_loop_effect

Definition

  • Supported scope:any
  • Supported target:any

Description

Runs a same effects through a loop. example will run the effects for value_name = -3, 0, 3, 6, 9 and then terminate
Example: for_loop_effect = {
	start = -3 (default 0) start value of loop
	end = 10 (default 0) end value of loop
	compare = less_than_or_equals (default less_than) comparison type between start and end val
	add = 3 (default 1) value to add to current value after each iteration
	value = value_name #optional (default 'v') current value of iteration will be stored in this temp variable
	break = break_name #optional (default 'break') set this temp variable to non zero to break the loop
 #effect 1
 #effect 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

for_loop_effect is well-suited for scenarios requiring batch or repetitive execution of effects at regular intervals, such as incrementally adding variables to multiple provinces, dynamically populating arrays, or batch-creating units with incrementing parameters. The example below demonstrates how to sequentially accumulate 0, 10, 20, 30, 40 into a single variable:

for_loop_effect = {
    start = 0
    end = 50
    compare = less_than
    add = 10
    value = current_step
    add_to_variable = {
        var = my_total
        value = var:current_step
    }
}

Synergy

  • [set_temp_variable](/wiki/effect/set_temp_variable) — Initialize or reset intermediate temporary variables within the loop body to prevent residual values from previous iterations from interfering with current calculations.
  • [add_to_array](/wiki/effect/add_to_array) — Commonly used in loops to push each iteration's value (loop variable) into an array for subsequent processing via for_each_loop or find_highest_in_array.
  • [if](/wiki/effect/if) — Perform conditional checks within the loop body to decide whether to execute certain logic based on the current iteration value, or pair with the break variable to terminate the loop early.
  • [add_to_temp_variable](/wiki/effect/add_to_temp_variable) — Core companion when performing accumulation operations with iteration variables, safely stacking each round's increment onto the temporary variable.

Common Pitfalls

  1. Forgetting to reset the break variable: Once the break temporary variable is set to a non-zero value, the loop terminates; if the variable has been assigned elsewhere in the same event and not cleared, the loop will exit immediately on the next entry, causing the loop body to never execute. It is recommended to explicitly reset with set_temp_variable = { var = break_name value = 0 } before the loop.
  2. Confusion between end and compare boundaries: The default comparison method is less_than (strictly less than). If you set end to the same value as the final expected iteration target, the last iteration will not actually execute—you must either switch to less_than_or_equals or increment end by one, otherwise the final iteration will silently skip, creating a hard-to-detect off-by-one error.