Wiki

effect · every_collection_element

Definition

  • Supported scope:any
  • Supported target:none

Description

Applies arbitrary effects to all elements of a collection. To learn more about collections,
see the documentation in "common/collections"

### General example

every_collection_element = { input = { input = collection_id # This can be a collection name or an inline definition of a collection limit = { # Trigger - limit effect execution to a subset of elements } } # Effects to be executed }


### Scoped example

TAG = { # Some collections require a scope every_collection_element = { input = { input = country:faction_members # for this collection, country scope is required limit = { # Trigger - limit effect execution to a subset of elements } } # Effects to be executed } }

实战 · 配合 · 坑

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

实战用法

every_collection_element 适合在需要对一组动态数据集合中的所有元素批量执行操作的场景，例如遍历自定义数组中存储的国家标签并逐一触发效果，或对预定义的 collection（如派系成员、某类省份组合）统一修改变量。常见于复杂 mod 中需要抽象化、复用化批量操作逻辑的情况。

# 遍历一个自定义 collection，对其中所有国家设置一个全局变量并记录日志
every_collection_element = {
    input = {
        input = my_target_countries_collection
        limit = {
            has_variable = mod_eligible
        }
    }
    set_variable = {
        var = collection_processed
        value = 1
    }
    log = "[This.GetName] processed by every_collection_element"
}

配合关系

  • any_collection_element — 在 limit 块或条件判断中用于检查集合内是否存在满足条件的元素，与 every_collection_element 形成"查询-执行"配对。
  • all_collection_elements — 用于验证集合内所有元素均满足某条件，可在执行 every_collection_element 前作前置校验，避免无效遍历。
  • set_variable — 批量遍历时最常见的操作内容，对每个元素写入或更新变量状态。
  • hidden_effect — 将 every_collection_element 包裹在 hidden_effect 内，避免在事件日志或工具提示中产生大量重复输出。

常见坑

  1. 忘记 input 的双层嵌套结构：every_collection_element 要求 input = { input = <collection_id> ... } 的双层写法，新手常直接写 input = collection_id 导致脚本报错或静默失效，务必保留外层的 input = {} 块。
  2. 在错误 scope 下使用需要特定 scope 的 collection：部分 collection（如 country:faction_members）必须在对应的国家 scope 下调用，若直接在 root scope 或错误 scope 中使用，collection 将无法正确解析，导致效果完全不执行且不会有明显报错提示。

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

every_collection_element is best suited for scenarios where you need to perform batch operations on all elements in a dynamic data collection — for example, iterating over country tags stored in a custom array and triggering effects on each one, or uniformly modifying variables across a predefined collection (such as faction members or a specific group of provinces). It appears frequently in complex mods where batch operation logic needs to be abstracted and reused.

# Iterate over a custom collection, set a global variable on every country within it, and log the result
every_collection_element = {
    input = {
        input = my_target_countries_collection
        limit = {
            has_variable = mod_eligible
        }
    }
    set_variable = {
        var = collection_processed
        value = 1
    }
    log = "[This.GetName] processed by every_collection_element"
}

Synergy

  • any_collection_element — Used inside a limit block or conditional check to determine whether at least one element in the collection meets a given condition. Pairs with every_collection_element as a "query-then-execute" pattern.
  • all_collection_elements — Verifies that every element in the collection satisfies a condition. Can serve as a pre-flight check before running every_collection_element to avoid unnecessary iteration.
  • set_variable — The most common operation performed during batch iteration; writes or updates a variable on each element.
  • hidden_effect — Wrapping every_collection_element inside hidden_effect prevents a flood of repetitive entries from appearing in the event log or tooltips.

Common Pitfalls

  1. Forgetting the double-nested input structure: every_collection_element requires the two-level syntax input = { input = <collection_id> ... }. Beginners often write input = collection_id directly, which causes a script error or silent failure. Always keep the outer input = {} block.
  2. Using a scope-dependent collection under the wrong scope: Some collections (such as country:faction_members) must be called from within the correct country scope. If invoked from the root scope or an incorrect scope, the collection will fail to resolve, the effect will not execute at all, and no obvious error message will be produced.