effect · `while_loop_effect`

Definition

Supported scope:any
Supported target:any

Description

Runs the effect as long as a trigger is true
Example: while_loop_effect = {
	limit = { ... trigger ... } a trigger to test before each iteration
	break = break_name #optional (default 'break') set this temp variable to non zero to break the loop
 #effect 1
 #effect 2 ...
}

实战 · 配合 · 坑

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

实战用法

while_loop_effect 适合需要动态次数迭代的场景，例如持续消耗某个变量直到归零、或反复向数组追加元素直到满足条件。典型用途包括：按每日物资库存逐步扣减、不断累积计数直到达到阈值等，核心优势在于循环次数由触发器实时决定而非写死。

# 每轮减去 10 点，直到变量 my_counter 降至 0 以下
while_loop_effect = {
    limit = {
        check_variable = { var = my_counter value > 0 }
    }
    subtract_from_variable = { var = my_counter value = 10 }
}

配合关系

[check_variable](/wiki/trigger/check_variable) — 在 limit 里判断变量是否仍满足条件，是控制循环继续/终止的最常见方式。
[set_temp_variable](/wiki/effect/set_temp_variable) — 在循环体内用临时变量做中间计算，避免污染持久变量，循环结束后自动清理。
[add_to_variable](/wiki/effect/add_to_variable) / [subtract_from_variable](/wiki/effect/subtract_from_variable) — 循环内对变量做累加或递减，配合 limit 里的 check_variable 形成自然的计数器循环。
[if](/wiki/effect/if) — 在循环体内做条件分支，实现"满足子条件时执行不同效果，不满足时跳过"的细粒度控制。

常见坑

忘记在循环体内改变 limit 所依赖的变量，导致条件永远为真形成死循环，游戏进程挂起甚至崩溃；务必确认每次迭代都会推动变量向令 limit 为假的方向变化。
误以为 break 是关键字而直接写 break = 1，实际上 break 的值是一个临时变量名（默认名为 break），需要用 set_temp_variable = { break = 1 } 来赋值才能生效，直接写 break = 1 会被解析为字段赋值而非中断循环。

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

while_loop_effect is suited for scenarios requiring dynamic iteration counts, such as progressively consuming a variable until it reaches zero, or repeatedly appending elements to an array until a condition is met. Typical use cases include: gradually deducting daily supply reserves, or continuously accumulating a counter until reaching a threshold. The core advantage is that the loop count is determined dynamically by triggers in real-time rather than hardcoded.

# Subtract 10 points per iteration until the my_counter variable drops below 0
while_loop_effect = {
    limit = {
        check_variable = { var = my_counter value > 0 }
    }
    subtract_from_variable = { var = my_counter value = 10 }
}

Synergy

[check_variable](/wiki/trigger/check_variable) — Evaluates whether a variable still meets conditions within the limit block; this is the most common method for controlling loop continuation or termination.
[set_temp_variable](/wiki/effect/set_temp_variable) — Use temporary variables for intermediate calculations within the loop body to avoid polluting persistent variables; they are automatically cleaned up after the loop ends.
[add_to_variable](/wiki/effect/add_to_variable) / [subtract_from_variable](/wiki/effect/subtract_from_variable) — Increment or decrement variables within the loop, working in tandem with check_variable in the limit block to form a natural counter loop.
[if](/wiki/effect/if) — Perform conditional branching within the loop body to enable fine-grained control of "execute different effects when a sub-condition is met, skip otherwise".

Common Pitfalls

Forgetting to modify the variable that the limit condition depends on within the loop body, causing the condition to remain perpetually true and forming an infinite loop, which can freeze or even crash the game process. Always verify that each iteration pushes the variable in a direction that would make the limit condition false.
Mistakenly assuming break is a keyword and writing break = 1 directly — in reality, the value of break is a temporary variable name (default name is break), and you must use set_temp_variable = { break = 1 } to assign it and trigger the loop termination. Writing break = 1 directly will be parsed as a field assignment rather than breaking the loop.

effect · while_loop_effect