Wiki

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 }

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

  1. 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.
  2. 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.