effect · `add_to_array`

Definition

Supported scope:any
Supported target:none

Description

Adds an element to an array
Example: add_to_array = {
	array = array_name
	value = 42 #optional, if not defined adds scope
	index = 3 #optional, default is end. otherwise elements are shifted
}
#shorter usage: add_to_array = { array_name = 42 }

实战 · 配合 · 坑

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

实战用法

add_to_array 常用于需要动态追踪一组国家、省份 ID 或数值的 mod 场景，例如记录"已被占领的核心州"列表或"参与同盟的所有国家 TAG"。配合循环和数组遍历，可以实现复杂的自定义逻辑，如统计满足条件的州数量并供后续效果读取。

# 将所有被敌方占领的核心州 ID 收集进数组，供后续处理
clear_array = { array = occupied_core_states }
every_state = {
    limit = {
        is_core_of = ROOT
        NOT = { is_owned_by = ROOT }
    }
    add_to_array = {
        array = occupied_core_states
        value = THIS
    }
}

配合关系

[clear_array](/wiki/effect/clear_array) — 在重新填充数组前先清空旧数据，防止数组无限增长或保留过期元素。
[remove_from_array](/wiki/effect/remove_from_array) — 与 add_to_array 对称使用，当某个元素不再满足条件时从数组中移除，维护数组的准确性。
[for_each_scope_loop](/wiki/effect/for_each_scope_loop) / [random_scope_in_array](/wiki/effect/random_scope_in_array) — 向数组写入元素后，常用这两个命令遍历或随机取出数组中的 scope 元素执行后续逻辑。
[is_in_array](/wiki/trigger/is_in_array) — 写入数组后，在 trigger 侧用此命令检查某个值是否已存在于数组中，常用于去重或条件判断。

常见坑

忘区分临时数组与持久数组：若只在事件内部临时使用，应改用 add_to_temp_array；使用 add_to_array 写入的数据会随存档持久保存，若忘记在适当时机调用 clear_array 清理，数组会跨事件不断累积旧数据导致逻辑错误。
value 省略时写入的是当前 scope 而非数值：不带 value 字段时，add_to_array 默认将当前 scope（如当前国家或州）作为元素写入；若本意是写入一个数字变量，必须显式指定 value = <变量或数字>，否则后续用 check_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

add_to_array is commonly used in mod scenarios where you need to dynamically track a set of countries, state IDs, or numeric values—for example, recording a list of "occupied core states" or "all country TAGs in an alliance." Combined with loops and array iteration, you can implement complex custom logic, such as counting states that meet certain conditions and making that count available to subsequent effects.

# Collect all core state IDs occupied by enemies into an array for subsequent processing
clear_array = { array = occupied_core_states }
every_state = {
    limit = {
        is_core_of = ROOT
        NOT = { is_owned_by = ROOT }
    }
    add_to_array = {
        array = occupied_core_states
        value = THIS
    }
}

Synergy

[clear_array](/wiki/effect/clear_array) — Clear old data before repopulating an array to prevent unlimited growth or retention of stale elements.
[remove_from_array](/wiki/effect/remove_from_array) — Use symmetrically with add_to_array to remove elements from the array when they no longer meet conditions, maintaining array accuracy.
[for_each_scope_loop](/wiki/effect/for_each_scope_loop) / [random_scope_in_array](/wiki/effect/random_scope_in_array) — After writing elements to an array, these two commands are commonly used to iterate over or randomly select scope elements from the array to execute subsequent logic.
[is_in_array](/wiki/trigger/is_in_array) — After writing to an array, use this command on the trigger side to check whether a given value already exists in the array; commonly used for deduplication or conditional checks.

Common Pitfalls

Confusing temporary arrays with persistent arrays: If you only need to use an array temporarily within an event, use add_to_temp_array instead. Data written with add_to_array persists with the save file; if you forget to call clear_array at the appropriate time, the array will accumulate stale data across events, leading to logic errors.
Omitting value writes the current scope, not a numeric value: When the value field is absent, add_to_array defaults to writing the current scope (such as the current country or state) as an element. If you intend to write a numeric variable, you must explicitly specify value = <variable or number>; otherwise, subsequent reads using check_variable or arithmetic operations on that array will fail due to type mismatch.

effect · add_to_array