effect · `random_state`

Definition

Supported scope:any
Supported target:none

Description

Executes children effects on a random state that fulfills the "limit" trigger.
State ids can be specified with the "prioritize" attribute and they will be
picked first if they fulfill the trigger.

实战 · 配合 · 坑

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

实战用法

random_state 常用于 mod 中的随机事件或决议效果，例如在全国随机挑选一个满足条件的州省添加建筑、资源或触发特定事件，避免效果每次都落在同一固定地点。配合 prioritize 可以优先选取特定州省（如首都、关键工业区），使逻辑更可控。

# 随机在一个己方控制的沿海州省修建一级海军基地
country_event = {
    id = my_mod.1
    immediate = {
        random_state = {
            prioritize = { 113 114 }   # 优先考虑的 state id
            limit = {
                is_controlled_by = ROOT
                is_coastal = yes
                free_building_slots = {
                    building = naval_base
                    size > 0
                    include_locked = no
                }
            }
            add_building_construction = {
                type = naval_base
                level = 1
                instant_build = yes
            }
        }
    }
}

配合关系

is_controlled_by — 在 limit 块内限制只筛选己方（或特定国家）控制的州省，避免效果意外施加到敌占区。
free_building_slots — 常用于建筑类效果前的合法性检查，确保目标州省有空余建筑槽再执行建造。
add_building_construction — 最典型的配套执行命令，在随机选中的州省内建造建筑。
state_event — 在随机选中的州省上触发一个州事件，配合 random_state 实现"随机地区爆发事件"的叙事效果。

常见坑

忘记写 limit 导致效果落在任意州省：random_state 不带 limit 时会从全图所有州省中随机选取，可能挑中敌国或无主地区，应始终至少加上 is_owned_by 或 is_controlled_by 等基础过滤。
误以为 prioritize 会保证必选：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_state is commonly used in mod random events or decision effects — for example, picking a random state across the country that meets certain conditions to add buildings, resources, or trigger a specific event, preventing the effect from always landing on the same fixed location. Pairing it with prioritize lets you favor particular states (such as the capital or key industrial regions), making the logic more predictable and controlled.

# Randomly construct a level-1 naval base in a coastal state controlled by the player's country
country_event = {
    id = my_mod.1
    immediate = {
        random_state = {
            prioritize = { 113 114 }   # state ids to consider first
            limit = {
                is_controlled_by = ROOT
                is_coastal = yes
                free_building_slots = {
                    building = naval_base
                    size > 0
                    include_locked = no
                }
            }
            add_building_construction = {
                type = naval_base
                level = 1
                instant_build = yes
            }
        }
    }
}

Synergy

is_controlled_by — Used inside a limit block to restrict selection to states controlled by your own country (or a specific nation), preventing the effect from accidentally applying to enemy-occupied territory.
free_building_slots — Commonly used as a validity check before building effects, ensuring the target state has available building slots before construction is triggered.
add_building_construction — The most typical companion effect, constructing a building in the randomly selected state.
state_event — Fires a state event on the randomly selected state, combining with random_state to achieve a narrative effect of "a random region experiencing an outbreak of events."

Common Pitfalls

Forgetting limit causes the effect to land on any state: When random_state is used without a limit, it selects randomly from every state on the map, potentially picking an enemy nation's state or an unclaimed region. You should always include at least a basic filter such as is_owned_by or is_controlled_by.
Mistaking prioritize for a guaranteed selection: States listed in prioritize are only "preferred candidates." If none of them satisfy the limit conditions, the game falls back to other states that do qualify; if no states qualify at all, the effect is silently skipped. Beginners often misread this as the logic not executing at all.

effect · random_state