effect · `clear_variable`

Definition

Supported scope:any
Supported target:none

Description

Clears a variable
Example: clear_variable = num_dogs

实战 · 配合 · 坑

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

实战用法

clear_variable 常用于 mod 中变量的生命周期管理，例如在某个事件流程结束后清除不再需要的计数器或临时状态标记，避免变量残留导致后续逻辑误判。也可以在循环或递归效果结束时，将用于迭代的变量重置干净，保持脚本状态整洁。

# 当外交谈判事件链结束时，清除用于追踪回合数的变量
country_event = {
    id = diplomacy.10
    option = {
        name = diplomacy.10.a
        # 处理结算逻辑...
        clear_variable = negotiation_rounds
    }
}

配合关系

[set_variable](/wiki/effect/set_variable)：set_variable 负责初始化或赋值变量，而 clear_variable 是其对应的"销毁"操作，两者构成变量完整的创建-销毁生命周期。
[has_variable](/wiki/trigger/has_variable)：在调用 clear_variable 之前，建议先用 has_variable 触发器确认变量存在，避免对不存在的变量执行清除时产生意外行为。
[if](/wiki/effect/if)：通常将 clear_variable 包裹在 if 条件块中，配合 has_variable 做保护性判断，是防御式脚本编写的标准模式。
[clear_array](/wiki/effect/clear_array)：如果同一套逻辑中同时使用了变量和数组来追踪状态，clear_variable 与 clear_array 往往成对出现，一并清理所有临时数据。

常见坑

清除后立即读取：新手有时在同一个 option 块中先 clear_variable，随后又在下方的触发器或效果中引用该变量（如 check_variable），此时变量已不存在会导致条件永远不满足或脚本报错，应确认清除时机在所有读取操作完成之后。
误将 scope 写入语法：clear_variable 的值直接是变量名字符串（如 clear_variable = num_dogs），不需要也不支持写成 var:num_dogs 或带 scope 前缀的形式，照搬 set_variable 的赋值语法会导致解析失败。

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

clear_variable is commonly used in mods for variable lifecycle management. For example, after an event chain concludes, you can clear counters or temporary state flags that are no longer needed, preventing variable residue from causing logic errors in subsequent checks. It can also reset iteration variables at the end of loops or recursive effects, keeping your script state clean.

# When a diplomatic negotiation event chain ends, clear the variable tracking round counts
country_event = {
    id = diplomacy.10
    option = {
        name = diplomacy.10.a
        # Handle settlement logic...
        clear_variable = negotiation_rounds
    }
}

Synergy

[set_variable](/wiki/effect/set_variable): set_variable initializes or assigns a variable, while clear_variable is its corresponding "destruction" operation. Together they form the complete create-destroy lifecycle of a variable.
[has_variable](/wiki/trigger/has_variable): Before calling clear_variable, it's recommended to first verify the variable exists using the has_variable trigger to avoid unexpected behavior when clearing a non-existent variable.
[if](/wiki/effect/if): It's standard practice to wrap clear_variable within an if conditional block paired with has_variable for defensive checks—a hallmark of defensive script writing.
[clear_array](/wiki/effect/clear_array): If the same logic uses both variables and arrays to track state, clear_variable and clear_array often appear together to clean up all temporary data at once.

Common Pitfalls

Reading immediately after clearing: Beginners sometimes call clear_variable first within the same option block, then reference that variable later (such as with check_variable). Since the variable no longer exists, the condition will never evaluate true or the script will error out. Always ensure variables are cleared only after all read operations are complete.
Incorrectly writing scope syntax: The value for clear_variable is simply the variable name as a string (e.g., clear_variable = num_dogs). It does not support syntax like var:num_dogs or scope-prefixed forms. Copying the assignment syntax from set_variable will cause parsing to fail.

effect · clear_variable