effect · `for_each_scope_loop`

Definition

Supported scope:any
Supported target:any

Description

Runs a loop on for each element of an array and changes scope to current element in each iteration
Example: for_each_scope_loop = {
	array = array_name
	break = break_name #optional (default 'break') set this temp variable to non zero to break the loop
	tooltip = loc #if defined, the effect will output a tooltip for sub effects using this localization as title
 #effect 1
 #effect 2 ...
}

实战 · 配合 · 坑

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

实战用法

for_each_scope_loop 最常用于遍历动态数组并对其中每个元素(国家、州等 scope 对象)执行批量操作，例如给一组目标国家同时施加惩罚、发放物资或触发事件。与 for_each_loop（遍历数值下标）不同，它直接将 scope 切换到数组元素本身，写法更简洁。

# 对存储在 target_countries 数组中的每个国家扣除政治权力
for_each_scope_loop = {
    array = target_countries
    add_political_power = -50
    if = {
        limit = { has_global_flag = war_penalty_active }
        add_stability = -0.05
    }
}

配合关系

[add_to_array](/wiki/effect/add_to_array) / [add_to_temp_array](/wiki/effect/add_to_temp_array)：循环前先将目标填入数组，是 for_each_scope_loop 的标准前置步骤。
[if](/wiki/effect/if)：在循环体内用条件判断过滤不满足条件的元素，避免对所有 scope 无差别执行。
[set_temp_variable](/wiki/effect/set_temp_variable)：在每轮迭代中记录或累加中间计算结果，方便循环结束后统一使用。
[find_highest_in_array](/wiki/effect/find_highest_in_array)：与循环配合，可先找到数组中的极值再决定循环内的操作逻辑。

常见坑

数组存放的不是 scope 对象而是纯数值：for_each_scope_loop 要求数组元素必须是可以切换 scope 的对象（如国家 TAG、州 ID），若数组里存的是普通数字变量，游戏会报错或静默失败，此时应改用 for_each_loop 搭配下标访问。
忘记 break 变量的作用域：break 字段指定的是一个临时变量名，若在循环外已有同名变量且不为零，循环会在第一次迭代时立即中断；建议在循环开始前用 set_temp_variable = { var = break_name value = 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

for_each_scope_loop is most commonly used to iterate through dynamic arrays and execute batch operations on each element (scope objects such as countries, states, etc.), such as simultaneously applying penalties to a set of target countries, distributing resources, or triggering events. Unlike for_each_loop (which iterates through numeric indices), it directly switches the scope to the array elements themselves, resulting in cleaner syntax.

# Deduct political power from each country stored in the target_countries array
for_each_scope_loop = {
    array = target_countries
    add_political_power = -50
    if = {
        limit = { has_global_flag = war_penalty_active }
        add_stability = -0.05
    }
}

Synergy

[add_to_array](/wiki/effect/add_to_array) / [add_to_temp_array](/wiki/effect/add_to_temp_array): Populate target elements into an array before the loop—this is the standard prerequisite step for for_each_scope_loop.
[if](/wiki/effect/if): Use conditional checks within the loop body to filter elements that do not meet conditions, avoiding indiscriminate execution across all scopes.
[set_temp_variable](/wiki/effect/set_temp_variable): Record or accumulate intermediate calculation results during each iteration for unified use after the loop completes.
[find_highest_in_array](/wiki/effect/find_highest_in_array): Combined with the loop, find extreme values in the array first before deciding the operation logic within the loop.

Common Pitfalls

Array contains pure numeric values instead of scope objects: for_each_scope_loop requires array elements to be objects that can have their scope switched (such as country TAGs or state IDs). If the array stores ordinary numeric variables, the game will error or fail silently. In such cases, use for_each_loop with index access instead.
Forgetting to clear the break variable's scope: The break field specifies a temporary variable name. If a variable with the same name already exists outside the loop and is non-zero, the loop will terminate immediately on the first iteration. It is recommended to explicitly reset it with set_temp_variable = { var = break_name value = 0 } before the loop begins.

effect · for_each_scope_loop