effect · `add_to_temp_array`

Definition

Supported scope:any
Supported target:none

Description

Adds an element to a temporary array
Example: add_to_temp_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_temp_array = { array_name = 42 }

实战 · 配合 · 坑

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

实战用法

add_to_temp_array 常用于在事件或决策执行期间临时收集一批符合条件的国家、数值或变量，然后通过循环统一处理，避免污染持久化数组。例如在计算参战国数量时，可将满足条件的国家逐一压入临时数组，随后用 for_each_scope_loop 遍历处理，函数结束后数组自动销毁，无需手动清理。

# 收集所有处于战争状态的主要国家到临时数组，再批量处理
every_country = {
    limit = { is_major = yes has_war = yes }
    add_to_temp_array = {
        array = warring_majors
        value = THIS
    }
}
for_each_scope_loop = {
    array = warring_majors
    add_to_temp_variable = { warring_count = 1 }
}

配合关系

[clear_temp_array](/wiki/effect/clear_temp_array)：在复用同名临时数组前先清空，防止上次执行残留的元素干扰当前逻辑。
[remove_from_temp_array](/wiki/effect/remove_from_temp_array)：压入元素后若发现某项不再满足条件，可动态将其移除，保持数组干净。
[for_each_scope_loop](/wiki/effect/for_each_scope_loop)：临时数组最典型的消费方，将数组内每个元素逐一带入 scope 执行后续 effect，与 add_to_temp_array 形成"收集→遍历"标准搭档。
[collection_size](/wiki/trigger/collection_size)：在 trigger 侧读取临时数组的元素数量，用于判断收集到的对象是否达到阈值后再决定执行哪条分支。

常见坑

误用为持久化存储：临时数组仅在当前事件/效果块执行期间存在，执行结束后即消失。新手有时期望下次事件触发时仍能读到数据，实际上数据已经丢失，持久化需求应改用 [add_to_array](/wiki/effect/add_to_array)。
忘记在循环外初始化导致重复累积：若同一个事件可能多次触发，且每次都向同名临时数组追加元素，但没有在逻辑入口处调用 [clear_temp_array](/wiki/effect/clear_temp_array)，会导致数组内容叠加，产生重复处理的 bug。

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_temp_array is commonly used during event or decision execution to temporarily collect a batch of countries, values, or variables that meet certain criteria, then process them uniformly through iteration, avoiding pollution of persistent arrays. For example, when calculating the number of belligerents, you can progressively push qualifying countries into a temporary array, then iterate through it using for_each_scope_loop to process them in batch. After the function completes, the array is automatically destroyed without manual cleanup.

# Collect all major countries in a state of war to a temporary array, then process in batch
every_country = {
    limit = { is_major = yes has_war = yes }
    add_to_temp_array = {
        array = warring_majors
        value = THIS
    }
}
for_each_scope_loop = {
    array = warring_majors
    add_to_temp_variable = { warring_count = 1 }
}

Synergy

[clear_temp_array](/wiki/effect/clear_temp_array): Clear a temporary array before reusing it under the same name to prevent residual elements from the previous execution from interfering with current logic.
[remove_from_temp_array](/wiki/effect/remove_from_temp_array): After pushing elements, if you discover a particular item no longer meets the criteria, you can dynamically remove it from the array to keep it clean.
[for_each_scope_loop](/wiki/effect/for_each_scope_loop): The most typical consumer of temporary arrays, iterating through each element in the array and bringing it into scope to execute subsequent effects. It forms the canonical "collect → iterate" pairing with add_to_temp_array.
[collection_size](/wiki/trigger/collection_size): Read the number of elements in a temporary array from the trigger side to determine whether the collected objects have reached a threshold before deciding which branch to execute.

Common Pitfalls

Mistakenly using it for persistent storage: Temporary arrays exist only during the current event or effect block execution and disappear once execution completes. Beginners sometimes expect to read the data when the next event triggers, but the data is already lost. Persistent storage requirements should use [add_to_array](/wiki/effect/add_to_array) instead.
Forgetting to initialize outside the loop, causing cumulative duplication: If the same event can trigger multiple times and each time pushes elements to a temporary array with the same name, but [clear_temp_array](/wiki/effect/clear_temp_array) is not called at the logic entry point, array contents will accumulate, causing bugs from duplicate processing.

effect · add_to_temp_array