Wiki

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

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

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