effect · `capture_by`

Definition

Supported scope:any
Supported target:ROOT

Description

Make the Unit Leader in scope be captured by the specified country (needs to be a general).
Optionally specify the province where the leader is held captive.

### Example

capture_by = GER

capture_by = FROM

capture_by = { country = GER province = 1234 }

实战 · 配合 · 坑

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

实战用法

capture_by 常用于战争事件或战役脚本中，模拟己方将领在战斗失利后被敌方俘虏的情景，也可用于 MOD 中设计特殊的将领命运剧情。以下示例展示一名将领被德国俘虏并关押于特定省份：

# 在某个 unit leader scope 下执行
capture_by = {
    country = GER
    province = 11
}

若不需要指定关押地点，也可直接使用简写形式：

capture_by = GER

配合关系

hidden_effect：将俘虏逻辑包裹在隐藏效果块中，避免玩家在事件选项中看到多余的提示文本，保持事件叙事的干净。
custom_effect_tooltip：配合 hidden_effect 使用，向玩家自定义显示"某将领已被俘"的友好提示，替代系统默认文本。
save_event_target_as：在进入 unit leader scope 之前，将该将领保存为事件目标，方便后续在其他 scope 中引用或做进一步处理。
effect_tooltip：在 option 块中预先提示俘虏效果的后果，让玩家在做选择前了解影响。

常见坑

Scope 必须是 Unit Leader 而非国家或省份：capture_by 只能在 unit leader scope 下执行，若在国家 scope 下直接调用则不会生效，需先通过迭代或事件目标切换到具体将领的 scope。
目标将领必须是 General（陆军将领），而非 Admiral（海军将领）：对海军上将使用此命令无效，MOD 中若要处理海军将领的特殊剧情，需要改用其他逻辑绕开此限制。

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

capture_by is commonly used in war events or campaign scripts to simulate a commander being captured by the enemy after a lost battle. It can also be used in mods to craft special narrative storylines around a commander's fate. The following example shows a commander being captured by Germany and held in a specific province:

# Executed within a unit leader scope
capture_by = {
    country = GER
    province = 11
}

If no holding location needs to be specified, the shorthand form can be used instead:

capture_by = GER

Synergy

hidden_effect: Wraps the capture logic inside a hidden effect block, preventing unnecessary tooltip text from appearing in event options and keeping the event narrative clean.
custom_effect_tooltip: Used alongside hidden_effect to display a player-friendly message such as "Commander has been captured," replacing the default system text.
save_event_target_as: Saves the commander as an event target before entering the unit leader scope, making it easy to reference or further process that commander in other scopes later.
effect_tooltip: Previews the consequences of the capture effect inside an option block, so the player understands the impact before making a choice.

Common Pitfalls

The scope must be a Unit Leader, not a country or province: capture_by can only be executed within a unit leader scope. Calling it directly from a country scope will have no effect — you must first switch to the specific commander's scope via iteration or an event target.
The target commander must be a General, not an Admiral: This command has no effect on naval commanders. If your mod needs to handle special storylines involving an Admiral, you will need to work around this limitation using alternative logic.

effect · capture_by