effect · set_state_controller

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

1. 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.
2. 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.