effect · `random_owned_controlled_state`

Definition

Supported scope:COUNTRY
Supported target:none

Description

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

实战 · 配合 · 坑

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

实战用法

random_owned_controlled_state 常用于国家事件或决策中，对己方实际掌控的某块随机州施加效果，例如在战时随机一个州内建造工事、增加人力或添加修正。配合 prioritize 可优先从指定州中抽取，适合"优先强化核心工业州"之类的设计。

# 国家随机在一个已占领且满足条件的州内提升工厂建设
random_owned_controlled_state = {
    limit = {
        is_core_of = ROOT
        free_building_slots = {
            building = industrial_complex
            size > 0
            include_locked = no
        }
    }
    prioritize = { 111 112 }
    add_extra_state_shared_building_slots = 1
    add_building_construction = {
        type = industrial_complex
        level = 1
        instant_build = yes
    }
}

配合关系

is_core_of：在 limit 内筛选仅属于本国核心领土的州，避免把资源投入到占领地。
free_building_slots：检测目标州是否还有建筑槽位，防止建造指令因无空槽而静默失败。
add_state_modifier：与 random_owned_controlled_state 搭配，对随机选中的州附加临时或永久的州修正，常见于事件奖励或灾害惩罚场景。
set_state_flag：对选中的随机州打上标记，配合后续 has_state_flag 触发条件防止同一州被重复选中。

常见坑

忘记 limit 导致效果打到不期望的州：random_owned_controlled_state 从所有己方拥有且控制的州中随机，若不加 limit，敌占区以外的偏远海外州、殖民地等都可能被选中，结果往往出人意料；建议始终至少加一条 is_core_of 或 has_state_category 过滤。
prioritize 不等于"必选"：新手常误以为写进 prioritize 的州 ID 一定会被选中，实际上这些州也必须通过 limit 的检验才能被优先考虑；若目标州不满足 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_owned_controlled_state is commonly used in country events or decisions to apply effects to a random state that the country actually owns and controls — for example, constructing fortifications in a random state during wartime, adding manpower, or attaching modifiers. Pairing it with prioritize lets you bias the selection toward specific states, which is ideal for designs like "preferentially reinforce core industrial states."

# The country randomly picks one occupied state that meets the conditions and upgrades its factory construction
random_owned_controlled_state = {
    limit = {
        is_core_of = ROOT
        free_building_slots = {
            building = industrial_complex
            size > 0
            include_locked = no
        }
    }
    prioritize = { 111 112 }
    add_extra_state_shared_building_slots = 1
    add_building_construction = {
        type = industrial_complex
        level = 1
        instant_build = yes
    }
}

Synergy

is_core_of: Use inside limit to restrict selection to states that are core territory of the country, preventing resources from being funneled into occupied land.
free_building_slots: Checks whether the target state still has available building slots, guarding against construction commands silently failing due to no open slots.
add_state_modifier: Pairs naturally with random_owned_controlled_state to attach a temporary or permanent state modifier to the randomly selected state — commonly seen in event rewards or disaster penalty scenarios.
set_state_flag: Stamps a flag on the selected state so that a subsequent has_state_flag trigger condition can prevent the same state from being picked again.

Common Pitfalls

Forgetting limit and hitting unintended states: random_owned_controlled_state draws from all states the country owns and controls. Without a limit, remote overseas territories, colonies, and other peripheral states are all fair game, often producing surprising results. It is strongly recommended to always include at least one is_core_of or has_state_category filter.
prioritize does not mean "guaranteed selection": Beginners often assume that any state ID listed in prioritize will definitely be chosen. In reality, those states must still pass the limit check before they can be prioritized. If a target state fails the limit, the script silently falls back to other qualifying states without throwing an error, creating logic bugs that are easy to miss.

effect · random_owned_controlled_state