effect · clear_array

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

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