effect · finalize_border_war

Hands-On Usage

finalize_border_war is commonly used in mods to design border war settlement logic, such as forcing termination of a border conflict after one side meets specific conditions (casualty thresholds, triggered diplomatic events), without relying on vanilla's automatic determination process. Typical scenarios occur in the option block of an event, where the player's selection of "accept ceasefire" immediately settles or cancels the border war.

# Option block of a ceasefire event
option = {
    name = border_war_event.1.a
    trigger = {
        has_border_war_between = {
            state_a = 42
            state_b = 67
        }
    }
    finalize_border_war = yes
    custom_effect_tooltip = border_war_ceasefire_tt
}

Synergy

• [has_border_war_between](/wiki/trigger/has_border_war_between): Use before executing settlement to check whether a border war currently exists between the specified two states, preventing errors or logical anomalies from triggering when no border war is present.
• [cancel_border_war](/wiki/effect/cancel_border_war): Both can terminate border wars, but with different semantics; cancel_border_war is unconditional revocation, while finalize_border_war triggers formal settlement determination. Choose one based on your mod's settlement requirements; do not call both on the same border war.
• [set_border_war_data](/wiki/effect/set_border_war_data): Typically used to dynamically adjust war data after a border war begins, forming a complete "set parameters → settle" workflow when combined with finalize_border_war.
• [custom_effect_tooltip](/wiki/effect/custom_effect_tooltip): Since finalize_border_war itself does not generate readable tooltip text, you must use this to supplement player-visible effect descriptions at the UI level.

Common Pitfalls

1. Calling without checking whether the border war exists: If no active border war exists between the target states, executing finalize_border_war directly may cause script errors or silent failures. Always protect with a has_border_war_between condition check first.
2. Scope misunderstanding leading to unclear settlement targets: This effect supports any scope, but which border war is actually settled depends on context (such as the states set in start_border_war). If your mod has multiple concurrent border wars, ensure the current execution context can uniquely identify the target border war; otherwise, settlement behavior may not match expectations.