命令百科

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 侧用此命令检查某个值是否已存在于数组中，常用于去重或条件判断。

常见坑

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