trigger · `has_variable`

Definition

Supported scope:any
Supported target:any

Description

Checks if a variable exists in a scope

实战 · 配合 · 坑

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

实战用法

has_variable 常用于检查某个 scope 上是否已经通过 set_variable 或 add_to_variable 写入过自定义变量，避免在变量不存在时直接读取导致脚本报错或产生意外行为。典型场景包括：在国家事件链中判断玩家是否已经完成了某个前置步骤（用变量作标记），或在 on_action 触发的 effect 里安全地访问动态生成的数值。

# 仅当该国已记录过"改革进度"变量时才允许选项可用
available = {
    has_variable = reform_progress
}

配合关系

[check_variable](/wiki/trigger/check_variable)：has_variable 先确认变量存在，再用 check_variable 比较其具体值，两者几乎总是成对出现，防止对空变量做数值判断。
[set_variable](/wiki/effect/set_variable)：在 effect 侧写入变量后，trigger 侧用 has_variable 验证写入是否已经发生，构成完整的"写—检"流程。
[if](/wiki/trigger/if)：将 has_variable 作为 if 的 limit 条件，实现"变量存在才执行后续逻辑"的分支保护。
[clear_variable](/wiki/effect/clear_variable)：清除变量后，has_variable 会返回假，可利用这一特性做"重置状态"判断，而无需额外设置布尔标记变量。

常见坑

直接用 check_variable 代替本触发器：新手常省略 has_variable 的前置检查，直接对可能不存在的变量做数值比较。若变量尚未被赋值，check_variable 的行为可能不符合预期（通常视为 0），在复杂事件链中容易产生隐蔽的逻辑错误。
变量名拼写不一致：has_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

has_variable is commonly used to check whether a custom variable has been written to a scope via set_variable or add_to_variable, preventing script errors or unexpected behavior from directly reading non-existent variables. Typical scenarios include: determining whether the player has completed a prerequisite step in a country event chain (using the variable as a marker), or safely accessing dynamically generated values in effects triggered by on_action.

# Only allow the option if this country has recorded the "reform_progress" variable
available = {
    has_variable = reform_progress
}

Synergy

[check_variable](/wiki/trigger/check_variable): has_variable first confirms the variable exists, then check_variable compares its specific value; the two almost always appear in tandem to prevent numeric comparisons on null variables.
[set_variable](/wiki/effect/set_variable): After writing a variable on the effect side, use has_variable on the trigger side to verify the write has occurred, forming a complete "write-check" workflow.
[if](/wiki/trigger/if): Use has_variable as the limit condition in an if statement to implement branch protection with "execute subsequent logic only if variable exists."
[clear_variable](/wiki/effect/clear_variable): After clearing a variable, has_variable returns false; this behavior can be leveraged to make "reset state" determinations without needing to set additional boolean flag variables.

Common Pitfalls

Using check_variable directly instead of this trigger: Beginners often skip the prerequisite check of has_variable and perform numeric comparisons directly on variables that may not exist. If a variable has not yet been assigned, check_variable behavior may not match expectations (typically treated as 0), easily producing subtle logic errors in complex event chains.
Variable name spelling inconsistencies: The parameter for has_variable is a string-form variable name that must match exactly with the name used during assignment (including capitalization). Cross-file references with inconsistent naming causing checks to always return false is a common debugging pitfall.

trigger · has_variable