effect · `set_state_province_controller`

Definition

Supported scope:STATE
Supported target:any

Description

sets the controller of provinces belong to a state and fullfils a condition. no tooltip is built
set_state_province_controller = { 
 controller = ITA
  limit = { 
     # will be checked old controller of each province. will only update controller if true
  } 
}

实战 · 配合 · 坑

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

实战用法

set_state_province_controller 常用于事件或决议触发后，将某个州内部分省份的控制权转交给指定国家，而无需改变整州控制权，适合处理内战分裂、占领线重置或特殊战役脚本。与 set_state_controller_to 相比，它的优势在于可通过 limit 块对每个省份的旧控制者进行条件过滤，实现精细化控制。

# 在某州 scope 下：将该州内所有由 GER 控制的省份移交给ITA
set_state_province_controller = {
    controller = ITA
    limit = {
        is_controlled_by = GER
    }
}

配合关系

[is_controlled_by](/wiki/trigger/is_controlled_by)：在 limit 块内用来筛选当前省份的旧控制者，是最直接的配合触发器，确保只有符合条件的省份才会发生控制权转移。
[set_state_controller_to](/wiki/effect/set_state_controller_to)：当需要同时重置整州控制者时配合使用，两者分工明确——前者处理省级细节，后者处理州级归属。
[set_occupation_law](/wiki/effect/set_occupation_law)：控制权转移后往往需要立即设定占领法令，避免新控制者继承原有不合逻辑的占领政策。
[add_resistance](/wiki/effect/add_resistance)：接管省份后可能需要对新占领区域施加抵抗值，配合使用可还原真实的占领情景。

常见坑

忽略 limit 为空的后果：若 limit 块留空，脚本依然合法执行，但会将该州所有省份的控制权无条件转移，容易误操作影响本不该变动的省份，建议始终在 limit 中填写明确的 is_controlled_by 或其他条件。
混淆省级控制与州级所有权：该 effect 只改变省份的 controller（控制者），不会修改州的 owner（所有者），新手常误以为执行后目标国家就"占领"了该州，实际上所有权仍属原国家，若需同步转移所有权须额外调用 set_state_owner_to。

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

set_state_province_controller is commonly used in events or decisions to transfer control of specific provinces within a state to a designated country without changing the entire state's control, making it ideal for handling civil war splits, occupation line resets, or special campaign scripts. Compared to set_state_controller_to, its advantage lies in the ability to filter each province's previous controller through a limit block, enabling fine-grained control.

# Within a state scope: transfer all provinces controlled by GER in that state to ITA
set_state_province_controller = {
    controller = ITA
    limit = {
        is_controlled_by = GER
    }
}

Synergy

[is_controlled_by](/wiki/trigger/is_controlled_by): Used within the limit block to filter the current province's previous controller; this is the most direct synergistic trigger, ensuring only provinces meeting the condition undergo control transfer.
[set_state_controller_to](/wiki/effect/set_state_controller_to): Used in conjunction when resetting the entire state's controller is needed; both have clear divisions of labor—the former handles province-level details, the latter handles state-level ownership.
[set_occupation_law](/wiki/effect/set_occupation_law): After control transfer, it is often necessary to immediately set occupation laws to prevent the new controller from inheriting illogical occupation policies from the previous owner.
[add_resistance](/wiki/effect/add_resistance): After taking over provinces, resistance may need to be imposed on newly occupied areas; combined use can restore realistic occupation scenarios.

Common Pitfalls

Overlooking the consequences of an empty limit block: If the limit block is left empty, the script still executes legally but will unconditionally transfer control of all provinces in that state, easily causing unintended changes to provinces that should remain unaffected. It is recommended to always specify clear conditions such as is_controlled_by or others within the limit.
Confusing province-level control with state-level ownership: This effect only changes a province's controller, it does not modify the state's owner. Newcomers often mistakenly believe that after execution the target country has "occupied" the state, but ownership actually remains with the original country. If simultaneous transfer of ownership is needed, an additional call to set_state_owner_to is required.

effect · set_state_province_controller