effect · `random_controlled_state`

Definition

Supported scope:COUNTRY
Supported target:none

Description

Executes children effects on random controlled state that fulfills the "limit" trigger. 
prioritize = { <stateID> <stateID> } to pick those states first if they fulfull the limit

实战 · 配合 · 坑

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

实战用法

random_controlled_state 常用于国家事件或决议中，对该国随机控制的某个省份/地区执行一次性效果，例如在占领区随机添加抵抗力量、资源或建筑。配合 limit 可精确筛选满足条件的州，prioritize 则能确保优先处理关键州（如首都周边）。

# 某国事件：在随机一个被控制但非本国核心的州增加抵抗
random_controlled_state = {
    limit = {
        NOT = { is_core_of = ROOT }
        is_controlled_by = ROOT
    }
    prioritize = { 42 43 }
    add_resistance = 15
    set_state_flag = resistance_triggered_flag
}

配合关系

is_controlled_by：在 limit 块中用于确认该州确实处于当前国家的控制下，避免筛选到敌占州。
is_core_of：在 limit 中排除或包含本国核心州，使效果只作用于占领地或殖民地。
add_resistance：最典型的子效果之一，对筛选出的随机受控州直接施加抵抗值。
set_state_flag：在被选中的州上打标记，防止同一事件链重复触发相同逻辑。

常见坑

scope 混淆：random_controlled_state 必须在 COUNTRY scope 下调用，若写在 STATE scope 的子块里会报错或静默失效；新手常在 every_state 内嵌套此指令，导致 scope 已是 STATE 而非 COUNTRY。
prioritize 不等于强制：prioritize 仅提升指定州被选中的优先级，若这些州不满足 limit 条件仍会被跳过，新手常误以为写了 prioritize 就一定会选中该州，从而省略 limit 的正确筛选条件。

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_controlled_state is commonly used in country events or decisions to apply a one-time effect to a randomly selected state controlled by that country — for example, adding resistance, resources, or buildings in occupied territories. Pair it with limit to precisely filter states that meet certain conditions, and use prioritize to ensure key states (such as those near the capital) are given selection priority.

# Country event: add resistance in a random controlled state that is not a core of ROOT
random_controlled_state = {
    limit = {
        NOT = { is_core_of = ROOT }
        is_controlled_by = ROOT
    }
    prioritize = { 42 43 }
    add_resistance = 15
    set_state_flag = resistance_triggered_flag
}

Synergy

is_controlled_by: Used inside a limit block to confirm the state is actually under the current country's control, preventing enemy-occupied states from being selected.
is_core_of: Used inside limit to exclude or include the country's own core states, so the effect only applies to occupied or colonial territories.
add_resistance: One of the most typical child effects — directly applies a resistance value to the randomly selected controlled state.
set_state_flag: Places a flag on the selected state to prevent the same event chain from triggering the same logic more than once.

Common Pitfalls

Scope confusion: random_controlled_state must be called from a COUNTRY scope. Writing it inside a child block that is already in STATE scope will cause an error or silent failure. A common beginner mistake is nesting this command inside every_state, at which point the scope is already STATE rather than COUNTRY.
prioritize is not a guarantee: prioritize only raises the likelihood that the specified states are selected — if those states do not satisfy the limit conditions, they will still be skipped. Beginners often assume that listing a state in prioritize guarantees it will be chosen, and consequently omit the correct filtering conditions from limit.

effect · random_controlled_state