trigger · `is_in_array`

Definition

Supported scope:any
Supported target:none

Description

Checks if an element is in array
Example: is_in_array = {
	array = array_name
	value = 42
}
#shorter usage: is_in_array = { array_name = 42 }

实战 · 配合 · 坑

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

实战用法

is_in_array 常见于需要追踪"已处理过的国家/州"或"已选择的选项列表"的 mod 场景，例如检查某个国家 TAG 或数值是否已被加入自定义队列数组，从而避免重复触发事件或效果。

# 检查当前国家的 TAG 变量是否已在"已访问国家"数组中
if = {
    limit = {
        is_in_array = {
            array = visited_countries_array
            value = THIS
        }
    }
    # 已在数组中，跳过处理
    custom_effect_tooltip = already_visited_tt
}

配合关系

[add_to_array](/wiki/effect/add_to_array) — 先将元素加入数组，再用 is_in_array 检查是否成功写入，或在后续 trigger 中防止重复添加。
[remove_from_array](/wiki/effect/remove_from_array) — 与 is_in_array 搭配形成"检查存在后再移除"的安全模式，避免对不存在的元素执行移除导致逻辑错误。
[collection_size](/wiki/trigger/collection_size) — 常在同一数组逻辑块中并用，先确认数组非空且含有目标元素，再做进一步的数量判断。
[check_variable](/wiki/trigger/check_variable) — 经常联合使用：check_variable 验证数值条件，is_in_array 验证成员资格，两者共同构成复合 guard 条件。

常见坑

数组名拼写与作用域不匹配：数组分为全局变量数组、国家变量数组和临时数组，若在错误 scope 下引用数组名（如在 country scope 下写了只在 global 下赋值的数组名），is_in_array 会始终返回 false 且不报错，极难排查。
用 value 比较对象引用而非数值时类型不符：当数组存储的是 scope 引用（如 TAG）时，直接填写字符串标签名并不等同于 scope 对象本身，需确保写入数组时与检查时使用的是同一类型（变量数值 vs. scope token），否则匹配永远失败。

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

is_in_array is commonly found in mod scenarios that require tracking "processed countries/states" or "selected option lists". For example, checking whether a country TAG or value has already been added to a custom queue array, thereby preventing duplicate event or effect triggers.

# Check if the current country's TAG variable is already in the "visited countries" array
if = {
    limit = {
        is_in_array = {
            array = visited_countries_array
            value = THIS
        }
    }
    # Already in array, skip processing
    custom_effect_tooltip = already_visited_tt
}

Synergy

[add_to_array](/wiki/effect/add_to_array) — First add elements to the array, then use is_in_array to verify successful insertion, or prevent duplicate additions in subsequent triggers.
[remove_from_array](/wiki/effect/remove_from_array) — Pair with is_in_array to form a safe "check-then-remove" pattern, avoiding logic errors from removing non-existent elements.
[collection_size](/wiki/trigger/collection_size) — Commonly used in the same array logic block: first confirm the array is non-empty and contains the target element, then perform further size comparisons.
[check_variable](/wiki/trigger/check_variable) — Frequently combined: check_variable validates numeric conditions, is_in_array validates membership, and both together form composite guard conditions.

Common Pitfalls

Array name spelling and scope mismatch: Arrays exist at global, country, and local scopes. Referencing an array name in the wrong scope (e.g., using an array name assigned only in global scope within a country scope) causes is_in_array to always return false silently, making debugging extremely difficult.
Type mismatch when comparing object references instead of values: When the array stores scope references (such as TAGs), directly writing a string tag name is not equivalent to the scope object itself. Ensure that the type used when inserting into the array matches the type used when checking (variable values vs. scope tokens), otherwise matching will always fail.

trigger · is_in_array