effect · `remove_from_array`

Definition

Supported scope:any
Supported target:none

Description

Removes an element from an array using value or index
Example: remove_from_array = {
	array = array_name
	value = 42 #optional, use index or this. if neither it removes last element
	index = 3 #optional, use value or this. if neither it removes last element
}
#shorter usage: remove_from_array = { array_name = 42 }

实战 · 配合 · 坑

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

实战用法

remove_from_array 常用于动态管理自定义数组数据的 mod 场景，例如追踪"已完成任务 ID 列表"、"已解锁科技池"或"排队等待处理的国家/州省集合"。当某个条件触发后，需要将已处理完的元素从数组中剔除，避免重复执行逻辑时尤为必要。

# 从"待处理任务队列"中移除已完成的任务值
effect = {
    remove_from_array = {
        array = pending_missions
        value = 5   # 移除值为 5 的任务条目
    }
}

# 简写形式：移除 active_targets 数组中值为当前 scope 的元素
remove_from_array = { active_targets = THIS }

配合关系

[add_to_array](/wiki/effect/add_to_array)：与 remove_from_array 互为逆操作，通常先用 add_to_array 向数组注册数据，再在条件满足后用本命令清除对应条目。
[is_in_array](/wiki/trigger/is_in_array)：在执行移除前先用此触发器确认目标元素确实存在于数组中，避免对空数组或不含该值的数组做无效操作。
[for_each_scope_loop](/wiki/effect/for_each_scope_loop)：遍历数组内容进行批量判断后，配合 remove_from_array 在循环内有条件地逐一删除满足条件的元素。
[clear_array](/wiki/effect/clear_array)：当需要一次性清空整个数组而非逐条移除时作为替代方案，两者根据使用场景灵活选择。

常见坑

同时使用 value 和 index 会产生歧义：两个参数只应选其一，若同时填写，脚本行为可能不符合预期；而两者都不填时，游戏会默认移除数组的最后一个元素，这一隐式行为经常被新手忽视，导致误删数据。
对 temp array 用错命令：临时数组（temp_array）必须使用 [remove_from_temp_array](/wiki/effect/remove_from_temp_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

remove_from_array is commonly used in mod scenarios for dynamically managing custom array data, such as tracking "completed mission ID lists", "unlocked technology pools", or "queues of countries/states awaiting processing". When a certain condition is triggered and an element has been processed, it must be removed from the array to avoid redundant logic execution—this is especially critical in repeated iterations.

# Remove completed mission values from the "pending mission queue"
effect = {
    remove_from_array = {
        array = pending_missions
        value = 5   # Remove the mission entry with value 5
    }
}

# Shorthand form: remove the element with value equal to current scope from active_targets array
remove_from_array = { active_targets = THIS }

Synergy

[add_to_array](/wiki/effect/add_to_array): The inverse operation of remove_from_array. Typically use add_to_array first to register data into the array, then use this command to remove the corresponding entry once the condition is met.
[is_in_array](/wiki/trigger/is_in_array): Before executing removal, use this trigger to confirm that the target element actually exists in the array, avoiding unnecessary operations on empty arrays or arrays that don't contain the value.
[for_each_scope_loop](/wiki/effect/for_each_scope_loop): After iterating through array contents for batch evaluation, combine with remove_from_array to conditionally remove elements that meet criteria one by one within the loop.
[clear_array](/wiki/effect/clear_array): Use as an alternative when you need to clear the entire array at once rather than remove entries individually. Choose between the two based on your use case.

Common Pitfalls

Using both value and index creates ambiguity: Only one of these two parameters should be used. If both are specified, script behavior may be unexpected. Furthermore, when neither is provided, the game defaults to removing the last element of the array—this implicit behavior is frequently overlooked by beginners, leading to unintended data loss.
Using the wrong command for temp arrays: Temporary arrays (temp_array) must use [remove_from_temp_array](/wiki/effect/remove_from_temp_array) rather than this command. Mixing them causes script errors or silent failures. The two array command systems are strictly separated and not interchangeable.

effect · remove_from_array