effect · `start_border_war`

Definition

Supported scope:any
Supported target:none

Description

start a border war between two states. Example:
start_border_war = {
	change_state_after_war = no #overrides the transfer of state at the end of war
	combat_width = 80 #combat width for border war
	minimum_duration_in_days = 14 #minimum duration for combat
	attacker = {
		state = 527 # state to start border war
		num_provinces = 4 #number of provinces we want border war to be
		on_win = japan_border_conflict.2 #effect to call if wins
		on_lose = japan_border_conflict.3 #effect to call if loses
		on_cancel = japan_border_conflict.4 #effect to call if cancels
		leader_score = { #score for selecting a leader
			base = 1
			modifier = {
				check_variable = { likes_border_wars = 1 }
				add = 2
			}
		}
		modifier = 0.5 #combat modifier (default value: 0.0)
		dig_in_factor = 0.5 #dig in modifier factor (default value: 1.0)
		terrain_factor = 0.5 #terrain modifier factor(default value: 1.0)
	}
	
	defender = {
		state = 408 # state to start border war
		num_provinces = 4 #number of provinces we want border war to be
		on_win = japan_border_conflict.2 #effect to call if wins
		on_lose = japan_border_conflict.3 #effect to call if loses
		on_cancel = japan_border_conflict.4 #effect to call if cancels
	}
}

实战 · 配合 · 坑

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

实战用法

start_border_war 常用于制作历史事件 mod 中模拟局部边境冲突（如诺门罕战役、查科战争等），让两国在不触发全面战争的前提下通过小规模省份争夺决出胜负。on_win/on_lose/on_cancel 三个回调事件是整个冲突结局分支的驱动核心，通常配合专属事件链实现不同结局。

# 触发苏日边境冲突（在 JAP scope 下调用）
start_border_war = {
    change_state_after_war = no
    combat_width = 60
    minimum_duration_in_days = 30
    attacker = {
        state = 527
        num_provinces = 3
        on_win   = jap_soviet_border.10
        on_lose  = jap_soviet_border.11
        on_cancel = jap_soviet_border.12
        modifier = 0.3
        dig_in_factor = 0.8
        terrain_factor = 0.7
    }
    defender = {
        state = 408
        num_provinces = 3
        on_win   = jap_soviet_border.20
        on_lose  = jap_soviet_border.21
        on_cancel = jap_soviet_border.22
    }
}

配合关系

[has_border_war_between](/wiki/trigger/has_border_war_between)：在事件或 focus 的 trigger 块中检测两国之间是否已存在边境战争，防止重复触发同一场冲突导致脚本报错。
[cancel_border_war](/wiki/effect/cancel_border_war)：当外交谈判或特定条件满足时手动终止边境战争，通常放在 on_cancel 回调事件的 option 里作为"外交解决"分支。
[finalize_border_war](/wiki/effect/finalize_border_war)：强制结算边境战争结果，配合计时器或特定事件触发，用于在 minimum_duration_in_days 到期后由脚本主动决出胜负。
[set_border_war_data](/wiki/effect/set_border_war_data)：在边境战争进行中动态调整战斗参数（如修正值），常与 start_border_war 分开放在后续事件里实现"战局转折"效果。

常见坑

两个 state 必须互相接壤：若 attacker 和 defender 所指定的州不共享陆地边界，效果会静默失败且不报错，新手往往误以为是事件触发条件问题而长时间排查错误方向。
on_win/on_lose 回调对象混淆：attacker 的 on_win 事件触发的 scope 是攻击方国家，defender 的事件触发的 scope 是防守方国家，若在回调事件中不加 [save_event_target_as](/wiki/effect/save_event_target_as) 保存对手引用，就很难在事件内操作对方国家，导致结局事件逻辑残缺。

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

start_border_war is commonly used in historical event mods to simulate localized border conflicts (such as the Battle of Khalkhin Gol or the Chaco War) without triggering a full-scale war, allowing two nations to settle disputes through small-scale province control. The three callback events on_win/on_lose/on_cancel are the core drivers of the entire conflict resolution system, typically paired with exclusive event chains to implement different outcomes.

# Trigger Sino-Soviet border conflict (called in JAP scope)
start_border_war = {
    change_state_after_war = no
    combat_width = 60
    minimum_duration_in_days = 30
    attacker = {
        state = 527
        num_provinces = 3
        on_win   = jap_soviet_border.10
        on_lose  = jap_soviet_border.11
        on_cancel = jap_soviet_border.12
        modifier = 0.3
        dig_in_factor = 0.8
        terrain_factor = 0.7
    }
    defender = {
        state = 408
        num_provinces = 3
        on_win   = jap_soviet_border.20
        on_lose  = jap_soviet_border.21
        on_cancel = jap_soviet_border.22
    }
}

Synergy

[has_border_war_between](/wiki/trigger/has_border_war_between): Check within event or focus trigger blocks whether a border war already exists between two nations, preventing duplicate triggers of the same conflict that cause script errors.
[cancel_border_war](/wiki/effect/cancel_border_war): Manually terminate an ongoing border war when diplomatic negotiations or specific conditions are met, typically placed in the on_cancel callback event option as a "diplomatic resolution" branch.
[finalize_border_war](/wiki/effect/finalize_border_war): Force the resolution of border war results, paired with timers or specific event triggers to actively determine the outcome after minimum_duration_in_days expires.
[set_border_war_data](/wiki/effect/set_border_war_data): Dynamically adjust combat parameters (such as modifiers) during an ongoing border war, often placed in subsequent events separate from start_border_war to create a "turning point" effect.

Common Pitfalls

The two states must share a border: If the states specified in attacker and defender do not share a land boundary, the effect fails silently without error, often causing newcomers to wrongly suspect event trigger conditions and waste time debugging in the wrong direction.
Confusion over on_win/on_lose callback scope: The on_win event triggered by the attacker fires in the scope of the attacking nation, while the defender's event fires in the scope of the defending nation. Without using [save_event_target_as](/wiki/effect/save_event_target_as) to preserve a reference to the opponent, it becomes difficult to manipulate the other nation within the event, resulting in incomplete outcome event logic.

effect · start_border_war