effect · `random_scope_in_array`

Definition

Supported scope:any
Supported target:any

Description

Runs the effect for a random element in array
Example: random_scope_in_array = {
	array = array_name
	limit = { ... trigger ... } a trigger to limit scopes
	break = break_name #optional (default 'break') set this temp variable to non zero to break the loop
 #effect 1
 #effect 2 ...
}

实战 · 配合 · 坑

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

实战用法

random_scope_in_array 常用于从动态构建的国家/州列表中随机抽取一个目标执行操作，例如在事件中随机选一个盟友提供援助、或从存储的省份列表中随机挑选一个执行破坏效果。与 for_each_scope_loop 不同，它只执行一次，避免批量触发的性能压力。

# 从预先存储的国家数组中随机取一个，向其转让一个州
random_scope_in_array = {
    array = candidate_countries
    limit = {
        is_in_array = { array = candidate_countries value = THIS }
        has_variable = ready_flag
    }
    save_event_target_as = chosen_target
}
# 随后在 event_target:chosen_target 作用域下使用 goto_state 等进一步操作

配合关系

add_to_array / add_to_temp_array：先将符合条件的目标逐一压入数组，再用 random_scope_in_array 从中抽取，是最典型的「收集后随机」流程。
save_event_target_as：在 block 内部将随机选中的 scope 保存为事件目标，方便在 block 外部的后续逻辑中复用同一目标。
set_temp_variable / set_variable：在 block 内记录被选中目标的某项数值，或利用 break 机制配合变量提前终止，实现"抽到满足条件的第一个即停止"的逻辑。
is_in_array：在 limit 块内交叉验证当前 scope 是否仍在另一个辅助数组中，用于在运行时过滤掉已被处理过的元素。

常见坑

忘记 array 中存的是 scope 还是数值：random_scope_in_array 要求数组元素必须是可切换的 scope（如国家、州），若数组里存的是普通数值（用 add_to_array = { array = x value = 3 } 压入的字面量），运行时无法切换 scope 会静默失败；存数值请改用 for_loop_effect 或 find_highest_in_array。
limit 中误用不存在的 trigger：limit 块是 trigger 上下文，只能写 trigger 白名单中的命令；例如想判断当前 scope 是否处于战争状态，应写 has_war = yes 而非杜撰的 is_at_war = yes，后者不会报错但永远为假，导致随机池意外为空。

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

random_scope_in_array is commonly used to pick a single random target from a dynamically built list of countries or states and perform an operation on it — for example, randomly selecting one ally to receive aid during an event, or picking a random province from a stored list to apply a sabotage effect. Unlike for_each_scope_loop, it executes only once, avoiding the performance overhead of bulk triggering.

# Pick a random country from a pre-built array and transfer a state to it
random_scope_in_array = {
    array = candidate_countries
    limit = {
        is_in_array = { array = candidate_countries value = THIS }
        has_variable = ready_flag
    }
    save_event_target_as = chosen_target
}
# Afterwards, use event_target:chosen_target scope for further operations such as goto_state

Synergy

add_to_array / add_to_temp_array: Push qualifying targets into an array one by one, then use random_scope_in_array to draw from it — this is the classic "collect then randomize" pattern.
save_event_target_as: Save the randomly selected scope as an event target inside the block, so the same target can be reused in subsequent logic outside the block.
set_temp_variable / set_variable: Record a value from the selected target inside the block, or combine with the break mechanism to stop early once a satisfactory target is found — effectively implementing "stop at the first match" logic.
is_in_array: Use inside a limit block to cross-check whether the current scope still exists in a secondary helper array, filtering out elements that have already been processed at runtime.

Common Pitfalls

Forgetting whether the array holds scopes or plain values: random_scope_in_array requires array elements to be switchable scopes (such as countries or states). If the array contains plain numeric values (pushed in via add_to_array = { array = x value = 3 }), the engine cannot switch scope and will fail silently. For numeric values, use for_loop_effect or find_highest_in_array instead.
Using non-existent triggers inside limit: The limit block is a trigger context and only accepts commands from the trigger whitelist. For example, to check whether the current scope is at war, write has_war = yes — not the invented is_at_war = yes. The latter will not throw an error but always evaluates to false, causing the random pool to be unexpectedly empty.

effect · random_scope_in_array