effect · `for_each_loop`

Definition

Supported scope:any
Supported target:any

Description

Runs a loop on for each element of an array
Example: for_each_loop = {
	array = array_name
	value = value_name #optional (default 'v') current value in array will be stored in this temp variable
	index = index_name #optional (default 'i') current index in array 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 ...
}

实战 · 配合 · 坑

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

实战用法

for_each_loop 最适合需要对同一个数组里的每个元素逐一执行操作的场景，例如遍历一个存储了多个 State ID 的数组并依次执行建设、给每个动态存储的国家 tag 添加修正器等。相比手动展开逻辑，它能让批量处理数组数据的代码保持简洁且易于维护。

# 示例：遍历一个存储省份 VP 的数组，逐一设置胜利点数
set_temp_variable = { my_array^0 = 3 }
set_temp_variable = { my_array^1 = 7 }
set_temp_variable = { my_array^2 = 15 }

for_each_loop = {
    array = my_array
    value = v        # 当前元素值存入 v
    index = i        # 当前下标存入 i
    # 在此对 v 执行操作，例如记录日志或做条件判断后 break
    if = {
        limit = { check_variable = { v = 7 } }
        set_temp_variable = { break = 1 }   # 找到目标值后提前退出
    }
}

配合关系

[add_to_temp_array](/wiki/effect/add_to_temp_array) / [add_to_array](/wiki/effect/add_to_array)：在循环执行前先填充数组，for_each_loop 才有元素可以遍历，两者是典型的"准备—消费"搭档。
[if](/wiki/effect/if)：在循环体内用 if 对当前元素 v 做条件判断，从而实现"只对满足条件的元素执行效果"的筛选逻辑。
[find_highest_in_array](/wiki/effect/find_highest_in_array) / [find_lowest_in_array](/wiki/effect/find_lowest_in_array)：先用这两个命令定位极值，再在 for_each_loop 内结合 break 提前退出，避免不必要的全量遍历。
[set_temp_variable](/wiki/effect/set_temp_variable)：循环体内常需要用它把中间计算结果或累加值写回临时变量，供后续逻辑使用。

常见坑

忘记 break 变量需要手动置零：break 默认名是 break，但如果上文某处已把它设为非零值，进入循环时会立刻跳出而不执行任何效果。养成习惯在循环前用 set_temp_variable = { break = 0 } 显式重置，或改用自定义名称避免命名冲突。
把 for_each_loop 当作 scope 切换器：循环体内的 scope 仍是进入循环时的 scope，v 和 i 只是普通临时变量（数值），不能直接把它们当作国家/省份 scope 来调用需要 scope 的命令；若要对存储的 tag 或 state ID 执行 scope 级操作，需要配合 random_scope_in_array 或 for_each_scope_loop 等专用命令。

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_each_loop is best suited for scenarios where you need to sequentially perform operations on each element in an array—for example, iterating through an array storing multiple State IDs to build improvements one by one, or adding modifiers to dynamically stored country tags. Compared to manually expanding logic, it keeps batch array processing code clean and maintainable.

# Example: Iterate through an array storing state victory points and set them one by one
set_temp_variable = { my_array^0 = 3 }
set_temp_variable = { my_array^1 = 7 }
set_temp_variable = { my_array^2 = 15 }

for_each_loop = {
    array = my_array
    value = v        # Current element value stored in v
    index = i        # Current index stored in i
    # Perform operations on v here, such as logging or conditional checks followed by break
    if = {
        limit = { check_variable = { v = 7 } }
        set_temp_variable = { break = 1 }   # Exit early after finding target value
    }
}

Synergy

[add_to_temp_array](/wiki/effect/add_to_temp_array) / [add_to_array](/wiki/effect/add_to_array): Populate the array before loop execution so for_each_loop has elements to iterate over; these form a classic "prepare-consume" partnership.
[if](/wiki/effect/if): Use if within the loop body to perform conditional checks on the current element v, enabling filtering logic that "only executes effects on elements meeting the condition."
[find_highest_in_array](/wiki/effect/find_highest_in_array) / [find_lowest_in_array](/wiki/effect/find_lowest_in_array): Use these commands first to locate extrema, then combine with break inside for_each_loop to exit early and avoid unnecessary full traversals.
[set_temp_variable](/wiki/effect/set_temp_variable): Frequently needed within the loop body to write intermediate calculation results or accumulated values back to temp variables for use by subsequent logic.

Common Pitfalls

Forgetting to manually reset the break variable: The default break variable name is break, but if something earlier set it to a non-zero value, the loop will exit immediately upon entry without executing any effects. Make it a habit to explicitly reset with set_temp_variable = { break = 0 } before the loop, or use a custom name to avoid naming collisions.
Treating for_each_loop as a scope switcher: The scope within the loop body remains the scope you entered with; v and i are just ordinary temp variables (numeric values) and cannot be directly used as country/state scopes to invoke scope-dependent commands. If you need to perform scope-level operations on stored tags or state IDs, pair it with dedicated commands like random_scope_in_array or for_each_scope_loop.

effect · for_each_loop