effect · `set_state_controller`

Definition

Supported scope:COUNTRY
Supported target:none

Description

set controller for state

实战 · 配合 · 坑

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

实战用法

set_state_controller 常用于领土转让、内战分裂或剧本事件中强制将某个州的控制权交给指定国家，而不触发完整的战争占领逻辑。例如在和平协议替代事件或起义 mod 中，可以让某国瞬间"接管"特定地块：

# 在某国的 country_event option 中
option = {
    name = my_event.1.a
    # 将 STATE_42 的控制权交给 TAG
    42 = {
        set_state_controller = TAG
    }
}

注意该 effect 本身写在 COUNTRY scope 下，但实际调用时需要先切入对应的 STATE scope（如用州 ID 或 every_controlled_state）来指定目标州。

配合关系

[add_state_core](/wiki/effect/add_state_core) — 转移控制权后往往同步添加核心，使新控制方获得完整的合法性与人力加成，避免出现"控制但无核心"的尴尬状态。
[every_controlled_state](/wiki/effect/every_controlled_state) — 批量遍历某国当前控制的州并逐一调用 set_state_controller，适合内战或大范围领土重组场景。
[controls_state](/wiki/trigger/controls_state) — 执行前先用此触发器校验目标州是否真的在预期国家手中，防止脚本在存档状态不符时产生意外结果。
[transfer_state](/wiki/effect/transfer_state) — 若需要同时转移所有权（owner）而非仅控制权（controller），两者配合使用可实现完整的领土移交；单独使用 set_state_controller 只改控制方，owner 不变。

常见坑

混淆 controller 与 owner：set_state_controller 只改控制方，不改归属国（owner）。新手常误以为执行后该州就"属于"目标国，实际上税收、建筑归属等仍属原 owner，若要完整转让必须另行处理 owner。
Scope 层级写错：该 effect 定义在 COUNTRY scope，但需要在 STATE scope 内才能指定"哪个州"被设置，直接在顶层国家块里调用而不先进入州 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

set_state_controller is commonly used in territory transfers, civil war splits, or scripted events to forcibly assign control of a state to a designated nation without triggering full occupation war logic. For example, in peace deal replacement events or insurgency mods, you can instantly have a nation "take over" a specific territory:

# Within a country_event option for some nation
option = {
    name = my_event.1.a
    # Transfer control of STATE_42 to TAG
    42 = {
        set_state_controller = TAG
    }
}

Note that this effect is written under COUNTRY scope, but when actually called, you must first enter the corresponding STATE scope (such as using a state ID or every_controlled_state) to specify the target state.

Synergy

[add_state_core](/wiki/effect/add_state_core) — After transferring control, it's common practice to simultaneously add cores, granting the new controller full legitimacy and manpower bonuses, avoiding the awkward situation of "controlling but having no core."
[every_controlled_state](/wiki/effect/every_controlled_state) — Batch iterate through all states currently controlled by a nation and invoke set_state_controller on each, suitable for civil war or large-scale territory reorganization scenarios.
[controls_state](/wiki/trigger/controls_state) — Before execution, use this trigger to verify the target state is actually in the expected nation's hands, preventing script unexpected results when save state conditions don't match.
[transfer_state](/wiki/effect/transfer_state) — If you need to transfer both ownership (owner) rather than just control (controller), using both together achieves complete territory transfer; using set_state_controller alone only changes the controller while owner remains unchanged.

Common Pitfalls

Confusing controller with owner: set_state_controller only changes the controller, not the owner nation. Beginners often mistakenly think the state "belongs to" the target nation after execution, but in reality tax revenue, building ownership, etc. still belong to the original owner. To achieve complete transfer, you must separately handle the owner.
Incorrect scope hierarchy: This effect is defined in COUNTRY scope, but requires being inside STATE scope to specify "which state" gets set. Calling it directly at the top level nation block without first entering state scope will cause script errors or silent failure.

effect · set_state_controller