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

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