effect · `random_neighbor_state`

Definition

Supported scope:STATE
Supported target:none

Description

Executes children effects on random neighbor state that fulfills the "limit" trigger.

实战 · 配合 · 坑

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

实战用法

random_neighbor_state 常用于扩张类 mod 中，让某个州随机向一个邻近州施加核心、索取领土，或传播抵抗/顺从效果，实现动态的地缘政治蔓延。也可用于事件中，让占领方随机在一个邻近州建造建筑或改变控制权，模拟战时资源整合。

# 在某个州事件中，随机选取一个由敌方控制的邻近州，为当前标签添加对其的核心
state_event = {
    id = my_mod.1
    ...
    option = {
        name = my_mod.1.a
        random_neighbor_state = {
            limit = {
                NOT = { is_owned_by = ROOT }
                is_controlled_by = ROOT
            }
            add_core_of = ROOT
            add_claim_by = ROOT
        }
    }
}

配合关系

any_neighbor_state：先用此触发器检测是否存在满足条件的邻近州，再用 random_neighbor_state 执行效果，避免在无合法目标时静默失败。
every_neighbor_state：当需要对所有邻近州批量执行相同操作时改用此命令，两者形成"随机一个 vs 全部"的对照选择。
add_core_of：最常见的内部效果，用于将随机选中的邻近州纳入某国核心范围，实现领土扩张逻辑。
transfer_state_to：在 limit 筛选后配合使用，将随机邻近州的所有权转移给指定国家，常见于事件驱动的领土重划剧本。

常见坑

忘记 limit 导致选中意外州：不加 limit 块时，游戏会从所有邻近州中随机抽取，包括己方控制或不相关的州，应始终通过 limit 明确筛选条件，若无合法目标则该 effect 静默跳过，不会报错也不会执行。
在 COUNTRY scope 下直接调用：random_neighbor_state 仅在 STATE scope 下有效，若在国家 scope（如 country_event 的 option 顶层）直接写会导致脚本报错或无效，必须先通过 random_state、capital_scope 等进入正确的 STATE scope 后再调用。

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_neighbor_state is commonly used in expansion-focused mods to have a state randomly impose cores on a neighboring state, claim territory, or spread resistance/compliance effects, simulating dynamic geopolitical expansion. It can also be used in events to let an occupying power randomly construct buildings or change control in a neighboring state, modeling wartime resource consolidation.

# In a state event, randomly select a neighboring state not owned by ROOT but controlled by ROOT,
# then add a core and claim on it for the current tag
state_event = {
    id = my_mod.1
    ...
    option = {
        name = my_mod.1.a
        random_neighbor_state = {
            limit = {
                NOT = { is_owned_by = ROOT }
                is_controlled_by = ROOT
            }
            add_core_of = ROOT
            add_claim_by = ROOT
        }
    }
}

Synergy

any_neighbor_state: Use this trigger first to check whether any qualifying neighboring state exists, then call random_neighbor_state to apply the effect — this prevents silent failures when no valid target is available.
every_neighbor_state: When you need to apply the same operation to all neighboring states at once, use this command instead. The two form a natural "one random vs. all" pairing.
add_core_of: The most common inner effect — adds the randomly selected neighboring state to a country's core territory, implementing expansion logic.
transfer_state_to: Used alongside a limit filter to transfer ownership of the randomly selected neighboring state to a specified country; frequently seen in event-driven territorial redistribution scenarios.

Common Pitfalls

Forgetting limit and selecting an unintended state: Without a limit block, the game draws randomly from all neighboring states, including those you own or that are otherwise irrelevant. Always use limit to define explicit selection criteria. If no valid target exists, the effect is silently skipped — no error is thrown and nothing is executed.
Calling it directly from a COUNTRY scope: random_neighbor_state is only valid within a STATE scope. Writing it at the top level of a country_event option will cause a script error or have no effect. You must first enter a valid STATE scope — for example via random_state or capital_scope — before calling it.

effect · random_neighbor_state