effect · `modulo_variable`

Definition

Supported scope:any
Supported target:none

Description

modulos a variable with another. Example: 
modulo_variable = { 
  var = variable_to_modulo 
  value = divisior 
}

实战 · 配合 · 坑

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

实战用法

modulo_variable 常用于需要"循环周期"逻辑的 mod 场景，例如将一个不断累加的计数器限制在某个范围内（如星期/月份轮转、棋盘格编号循环），或在随机事件中对某个变量取余以分配到离散档位。下面示例将 week_counter 对 7 取余，使其始终保持在 0–6 的星期索引范围内：

# 每次事件触发时推进计数，然后取余保持在 [0,6]
add_to_variable = { var = week_counter value = 1 }
modulo_variable = {
    var   = week_counter
    value = 7
}

配合关系

[add_to_variable](/wiki/effect/add_to_variable) — 通常先对变量执行累加，再用 modulo_variable 取余，形成"累加→归零循环"的标准组合。
[clamp_variable](/wiki/effect/clamp_variable) — 若取余结果在边界情况下需要额外保险（如除数可能为 0 导致行为异常时先夹紧再取模），两者配合可提高健壮性。
[check_variable](/wiki/trigger/check_variable) — 取余之后通常需要读取余数值来决定后续分支逻辑，check_variable 是最直接的判断手段。
[set_variable](/wiki/effect/set_variable) — 在取模前需要将变量初始化为确定值时使用，防止因变量未定义而产生意外结果。

常见坑

除数（value）为 0 会导致脚本报错或产生未定义行为：游戏引擎不会自动跳过除以 0 的运算，务必在执行前通过 [check_variable](/wiki/trigger/check_variable) 或 [clamp_variable](/wiki/effect/clamp_variable) 确保 value 不为零。
var 必须是已存在且已赋值的变量：如果目标变量从未被 set_variable 或 add_to_variable 初始化就直接取模，余数结果通常为 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

modulo_variable is commonly used in mod scenarios requiring "cyclic period" logic, such as constraining a continuously accumulating counter within a specific range (e.g., week/month rotation, chessboard-style index cycling), or distributing a variable across discrete tiers in random events via modulo operation. The example below applies modulo 7 to week_counter, keeping it within the week index range of 0–6:

# Increment the counter on each event trigger, then apply modulo to maintain [0,6]
add_to_variable = { var = week_counter value = 1 }
modulo_variable = {
    var   = week_counter
    value = 7
}

Synergy

[add_to_variable](/wiki/effect/add_to_variable) — Typically paired by first accumulating the variable, then using modulo_variable to take the remainder, forming a standard "accumulate→reset cycle" pattern.
[clamp_variable](/wiki/effect/clamp_variable) — If the modulo result requires additional safeguards at boundary cases (e.g., when the divisor might be 0, clamping before modulo prevents anomalous behavior), combining both improves robustness.
[check_variable](/wiki/trigger/check_variable) — After taking the modulo, you typically need to read the remainder value to determine subsequent branch logic; check_variable is the most direct means of comparison.
[set_variable](/wiki/effect/set_variable) — Use when initializing a variable to a definite value before modulo operation, preventing unexpected results from undefined variables.

Common Pitfalls

Division by zero in value causes script errors or undefined behavior: The game engine does not automatically skip division by zero operations. Always ensure value is non-zero before execution by using [check_variable](/wiki/trigger/check_variable) or [clamp_variable](/wiki/effect/clamp_variable).
var must be an existing and assigned variable: If the target variable is never initialized via set_variable or add_to_variable before taking modulo, the remainder result is typically 0 or unpredictable. Beginners often overlook the initialization step, mistakenly believing the script executed correctly.

effect · modulo_variable