effect · transfer_state

Hands-On Usage

transfer_state is most commonly used in peace negotiations, event-triggered territorial changes, and focus tree territory reward scenarios—for example, transferring a specific state to an ally or to oneself after a nation completes a certain national focus. It's worth noting that this effect simultaneously updates both owner and controller without requiring additional manual control adjustments.

# After focus completion, transfer STATE_42 to the current scope nation
focus = {
    id = claim_rhineland
    ...
    completion_reward = {
        42 = { transfer_state = ROOT }
    }
}

Synergy

• [add_state_core](/wiki/effect/add_state_core): After transferring a state, it's typically necessary to add a core for the receiving nation to avoid the high penalty of occupation status; these two are often used in tandem.
• [add_state_claim](/wiki/effect/add_state_claim): Add claims to the target nation before transfer to make territorial changes more narratively coherent and satisfy certain trigger conditions.
• [controls_state](/wiki/trigger/controls_state): Use before transfer to verify whether you actually control the state, preventing accidental transfer of states you don't control.
• [create_wargoal](/wiki/effect/create_wargoal): In scenario design, it's common to first satisfy conditions through war goals, then implement post-war territorial results with transfer_state.

Common Pitfalls

1. Reversed Scope: The scope of transfer_state is the receiving nation (COUNTRY), not the state itself—beginners often mistakenly assume it should be written under a state scope. The correct syntax is either <state_id> = { transfer_state = RECEIVER_TAG } or transfer_state = <state_id> under the receiving nation's scope. Confusing the direction causes scripts to silently fail or transfer to the wrong nation.
2. Neglecting Cores and Compliance: After transferring a state, the original owner's cores won't automatically be removed, and the receiving nation won't automatically gain cores. Without pairing this with add_state_core or removing old cores, the game will exhibit unexpected behaviors like occupation penalties or immediate AI defection.