effect · `add_contested_owner`

Definition

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

Description

Adds a contested owner to a state.
The effect can be used either from a country or a state scope and accepts the other as parameter.
The effect is localized with a localization environment containing `Country` and `State`.

### Example
The following example has the same end result and localization.

42 = { add_contested_owner = GER } GER = { add_contested_owner = 42 }

Standard scope accessors can also be used:

Assuming current scope is a state and FROM is a country scope

add_contested_owner = FROM

实战 · 配合 · 坑

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

实战用法

add_contested_owner 常用于领土争端、占领事件或外交危机类 mod 中，用来表示某国对一个州提出主权主张并进入"争议状态"，例如在战后和平会议脚本或民族自决事件里动态标记争议领土。以下示例模拟一个事件选项中德国对某州提出争议所有权：

# 在国家 scope 下，从 country 向 state 发起
GER = {
    country_event = {
        id = my_mod.1
    }
}

# 事件选项执行块
option = {
    name = my_mod.1.a
    # 对 42 号州添加 GER 的争议所有权
    42 = {
        add_contested_owner = GER
    }
}

配合关系

[has_contested_owner](/wiki/trigger/has_contested_owner)：检测某州是否已存在特定争议所有者，通常在 add_contested_owner 执行前用作前置条件判断，避免重复添加。
[remove_contested_owner](/wiki/effect/remove_contested_owner)：争议状态的逆操作，常在争端通过谈判或战争解决后配合触发，与 add_contested_owner 形成完整的争议生命周期。
[add_state_claim](/wiki/effect/add_state_claim)：在添加争议所有权的同时，为该国追加对目标州的宣称，两者语义互补，共同构建领土主张逻辑。
[state_event](/wiki/effect/state_event)：在争议所有权添加完成后，于目标州 scope 内触发后续事件（如居民抗议、驻军事件），推进剧情链。

常见坑

scope 与参数方向混淆：该 effect 要求 scope 与参数必须是"一个是 country，另一个是 state"的互补关系。新手容易在 country scope 下把参数也写成另一个 country tag，或在 state scope 下把参数也写成 state id，这两种写法都会导致脚本报错或静默失效。
对已有争议所有者重复添加：在没有用 [has_contested_owner](/wiki/trigger/has_contested_owner) 做检测的情况下多次执行同一组合，可能产生重复条目或意外日志警告，应在 limit 块中先行过滤。

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

add_contested_owner is commonly used in territory disputes, occupation events, or diplomatic crisis mods to represent a country asserting sovereignty over a state and entering a "contested" status. This is typically employed in post-war peace conference scripts or self-determination event chains to dynamically mark disputed territories. The following example simulates a scenario where Germany asserts a contested claim over a state within an event option:

# Initiate from country scope toward state
GER = {
    country_event = {
        id = my_mod.1
    }
}

# Event option execution block
option = {
    name = my_mod.1.a
    # Add GER as a contested owner to state 42
    42 = {
        add_contested_owner = GER
    }
}

Synergy

[has_contested_owner](/wiki/trigger/has_contested_owner): Detects whether a state already has a specific contested owner. Typically used as a precondition before executing add_contested_owner to avoid duplicate assignments.
[remove_contested_owner](/wiki/effect/remove_contested_owner): The inverse operation of contested status. Commonly triggered after a dispute is resolved through negotiation or war, forming a complete contested ownership lifecycle with add_contested_owner.
[add_state_claim](/wiki/effect/add_state_claim): While adding contested ownership, also assigns the country a direct claim on the target state. The two effects are semantically complementary and together construct territorial claim logic.
[state_event](/wiki/effect/state_event): After contested ownership is added, triggers follow-up events within the target state's scope (such as civilian protests or garrison events) to advance the event chain.

Common Pitfalls

Confusion over scope and parameter direction: This effect requires scope and parameter to maintain a complementary "one country, one state" relationship. Beginners often mistakenly write another country tag as the parameter in country scope, or a state ID as the parameter in state scope. Both approaches result in script errors or silent failures.
Duplicate addition of existing contested owners: Executing the same combination multiple times without checking [has_contested_owner](/wiki/trigger/has_contested_owner) first may create duplicate entries or unexpected log warnings. Use a limit block to pre-filter such cases.

effect · add_contested_owner