effect · `clear_array`

Definition

Supported scope:any
Supported target:none

Description

Clears the contents of array
Example: clear_array = array_name

实战 · 配合 · 坑

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

实战用法

clear_array 常用于需要在每次事件触发或循环迭代前重置动态数组内容的场景，例如在 AI 决策逻辑或动态列表构建中，先清空旧数据再重新填充，避免数组内容累积产生错误结果。典型场景是每月脉冲事件中重新统计符合条件的国家列表。

# 每次事件触发时，先清空旧的候选国家数组，再重新填充
immediate = {
    clear_array = candidate_countries
    every_country = {
        limit = { is_major = yes }
        add_to_array = { array = candidate_countries value = THIS }
    }
}

配合关系

[add_to_array](/wiki/effect/add_to_array)：清空数组后紧接着用其重新填充元素，是最典型的"重置并重建"组合。
[resize_array](/wiki/effect/resize_array)：若需要清空并同时预分配固定长度，可在 clear_array 后用 resize_array 初始化占位值。
[for_each_scope_loop](/wiki/effect/for_each_scope_loop)：遍历数组元素前先用 clear_array 确保数组干净，避免历史残留数据干扰循环逻辑。
[is_in_array](/wiki/trigger/is_in_array)：配合使用时，clear_array 保证每轮检查前数组状态可预期，使该触发器的判断结果准确可靠。

常见坑

误用于临时数组应改用 clear_temp_array：clear_array 操作的是持久化数组（保存在存档中），若只需要在单次事件内临时使用的数组应使用 [clear_temp_array](/wiki/effect/clear_temp_array)，否则会造成不必要的存档膨胀甚至数据污染。
清空不存在的数组不会报错但也无效：如果数组名拼写错误或尚未初始化，游戏不会给出任何提示，后续 add_to_array 填充看似正常，却可能在其他地方引用了同名但大小写不一致的"另一个"数组，导致难以排查的逻辑错误。

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

clear_array is commonly used in scenarios where dynamic array contents need to be reset before each event trigger or loop iteration. This is particularly useful in AI decision logic or dynamic list construction, where old data is cleared and then repopulated to avoid incorrect results from data accumulation. A typical use case is recalculating country lists that meet certain criteria in monthly pulse events.

# Clear the old candidate countries array before each event trigger, then repopulate it
immediate = {
    clear_array = candidate_countries
    every_country = {
        limit = { is_major = yes }
        add_to_array = { array = candidate_countries value = THIS }
    }
}

Synergy

[add_to_array](/wiki/effect/add_to_array): Immediately repopulating elements after clearing the array is the most typical "reset and rebuild" combination.
[resize_array](/wiki/effect/resize_array): If you need to clear and simultaneously preallocate a fixed length, you can use resize_array after clear_array to initialize placeholder values.
[for_each_scope_loop](/wiki/effect/for_each_scope_loop): Use clear_array before iterating through array elements to ensure the array is clean and prevent historical residual data from interfering with loop logic.
[is_in_array](/wiki/trigger/is_in_array): When used together, clear_array ensures the array state is predictable before each check, making the trigger's judgment results accurate and reliable.

Common Pitfalls

Misusing for temporary arrays—should use clear_temp_array instead: clear_array operates on persistent arrays (saved in save files). If you only need a temporary array for a single event, use [clear_temp_array](/wiki/effect/clear_temp_array) instead, otherwise it will cause unnecessary save file bloat and even data corruption.
Clearing a non-existent array will not error but has no effect: If an array name is misspelled or hasn't been initialized yet, the game provides no warning. Subsequent add_to_array operations appear to work normally, but may actually reference a different array with the same name but inconsistent casing elsewhere, leading to hard-to-debug logic errors.

effect · clear_array