effect · `set_province_controller`

Definition

Supported scope:COUNTRY
Supported target:THIS, ROOT, PREV, FROM, OWNER, CONTROLLER, OCCUPIED, CAPITAL

Description

set controller for province

实战 · 配合 · 坑

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

实战用法

set_province_controller 常用于领土转移、内战事件或剧本触发器中，将某个具体省份的控制权即时交给指定国家，而无需改变主权归属。典型场景如：某国内战爆发时，叛军一方通过事件立刻夺取首都所在省份的控制权，或在和平协议脚本中将占领的前线省份归还原主。

# 某国内战事件：叛军控制首都省份
country_event = {
    id = my_mod.1
    immediate = {
        # 此处 scope 为触发内战的叛军国家 (COUNTRY)
        set_province_controller = 1234  # 填写目标省份的 province ID
    }
}

配合关系

[controls_province](/wiki/trigger/controls_province) — 在执行控制权转移前先校验该省份当前是否已被某国控制，避免重复触发或逻辑冲突。
[declare_war_on](/wiki/effect/declare_war_on) — 战争宣告后立刻通过本命令将前线关键省份控制权置于进攻方，模拟闪击或奇袭的即时效果。
[damage_building](/wiki/effect/damage_building) — 夺取省份控制权的同时摧毁当地建筑，模拟战斗损耗或撤退焦土策略，使两者共同还原战场现实感。
[add_manpower](/wiki/effect/add_manpower) — 结合控制权转移给新控制国补充兵力，常用于叛军或傀儡政权初始化脚本中。

常见坑

混淆 province ID 与 state ID：本命令接受的是**省份（province）**的数字 ID，而非状态（state）ID；新手常把 state ID 填入此处，导致命令静默失败或指向错误地块，需在 map/definition.csv 和 history/states/ 中仔细核对两套 ID 体系。
scope 必须是 COUNTRY 而非 STATE：许多人习惯在 every_owned_state 等 state scope 内直接调用本命令，但它只能在 COUNTRY scope 下执行；若在 state scope 中使用，需先通过 OWNER/CONTROLLER 等目标跳回国家 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_province_controller is commonly used in territorial transfers, civil war events, or scenario triggers to immediately transfer control of a specific province to a designated nation without changing its sovereignty. Typical scenarios include: when a civil war breaks out in a country, the rebel faction uses an event to instantly seize control of the province containing the capital, or in peace agreement scripts to return occupied frontline provinces to their original owners.

# Civil war event: rebels seize control of the capital province
country_event = {
    id = my_mod.1
    immediate = {
        # Scope here is the rebel nation (COUNTRY) triggering the civil war
        set_province_controller = 1234  # Enter the province ID of the target province
    }
}

Synergy

[controls_province](/wiki/trigger/controls_province) — Before executing the control transfer, first verify whether the province is currently controlled by a specific nation to avoid duplicate triggers or logic conflicts.
[declare_war_on](/wiki/effect/declare_war_on) — Immediately after declaring war, use this command to place key frontline province control with the attacking side, simulating the instant effect of blitzkrieg or surprise attacks.
[damage_building](/wiki/effect/damage_building) — Destroy local buildings while seizing province control to simulate battle attrition or scorched earth tactics during retreat, allowing both effects to authentically recreate battlefield realism.
[add_manpower](/wiki/effect/add_manpower) — Combine control transfer with manpower replenishment for the new controlling nation, commonly used in rebel or puppet regime initialization scripts.

Common Pitfalls

Confusing province ID with state ID: This command accepts the numeric ID of a province rather than a state ID; beginners often enter the state ID here, causing the command to silently fail or point to the wrong tile. Carefully verify both ID systems in map/definition.csv and history/states/.
Scope must be COUNTRY, not STATE: Many people habitually call this command directly within every_owned_state and other state scopes, but it only executes under COUNTRY scope. If used within a state scope, you must first jump back to country scope via OWNER/CONTROLLER or similar target switches; otherwise the command will not take effect and will not produce an error.

effect · set_province_controller