effect · `release_from_captivity`

Definition

Supported scope:CHARACTER
Supported target:none

Description

Releases the scoped army leader from captivity. Has no effect if the leader is not captured.

### Example

var:target_leader = { release_from_captivity = yes }

实战 · 配合 · 坑

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

实战用法

release_from_captivity 常用于战争结束事件、停战谈判或特殊任务链中，将己方被俘的将领释放并恢复其可用状态。例如在停战协议触发时，批量释放本国所有被俘将领，或在剧情事件中通过外交手段换回特定指挥官。

# 停战事件中释放被俘将领
country_event = {
    id = armistice.1
    title = armistice.1.t
    desc = armistice.1.d

    option = {
        name = armistice.1.a
        every_country_with_original_tag = {
            limit = { tag = GER }
            every_character = {
                limit = {
                    is_army_leader = yes
                    is_general_captured = yes
                }
                release_from_captivity = yes
            }
        }
    }
}

配合关系

is_general_captured：执行释放前的标准前置判断，确认角色确实处于被俘状态，避免无效调用。
add_unit_leader_trait：释放后立即为该将领添加特质（如"战俘幸存者"），丰富剧情表达。
unit_leader_event：释放后向该角色触发专属事件，推进后续剧情或给予额外奖励。
set_character_flag：释放时打上标记，防止同一将领在同一局游戏中被重复释放或重复触发相关事件链。

常见坑

忘记限定 scope：此 effect 必须在 CHARACTER scope 下执行，若直接写在国家 scope 的 effect 块里而不经过 every_character 或 var:target_leader = { } 等方式切入角色 scope，脚本将报错或静默失效，不会自动遍历该国所有被俘将领。
跳过 is_general_captured 检查：官方说明虽然写明"未被俘则无效果"，但若在大规模循环中不加 limit = { is_general_captured = yes } 过滤，会对所有角色无差别调用，造成不必要的性能开销，在角色数量多的 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

release_from_captivity is most commonly used in end-of-war events, armistice negotiations, or special mission chains to free captured commanders and restore them to an available state. For example, when a ceasefire event fires, you can mass-release all captured leaders belonging to a country, or use it in a narrative event to represent a specific commander being exchanged through diplomatic means.

# Release captured leaders in an armistice event
country_event = {
    id = armistice.1
    title = armistice.1.t
    desc = armistice.1.d

    option = {
        name = armistice.1.a
        every_country_with_original_tag = {
            limit = { tag = GER }
            every_character = {
                limit = {
                    is_army_leader = yes
                    is_general_captured = yes
                }
                release_from_captivity = yes
            }
        }
    }
}

Synergy

is_general_captured: The standard prerequisite check before executing a release — confirms the character is actually captured, preventing unnecessary calls.
add_unit_leader_trait: Immediately assign a trait to the leader after release (e.g. "POW Survivor") to enrich narrative flavor.
unit_leader_event: Fire a dedicated event on the character after release to advance follow-up storylines or grant additional rewards.
set_character_flag: Set a flag at the moment of release to prevent the same leader from being released again or re-triggering related event chains within the same playthrough.

Common Pitfalls

Forgetting to scope into CHARACTER: This effect must be executed inside a CHARACTER scope. Writing it directly in a country-scope effect block without first entering a character scope via every_character, var:target_leader = { }, or a similar method will cause the script to error out or silently do nothing — it will not automatically iterate over all captured leaders in that country.
Skipping the is_general_captured check: The documentation notes that the effect does nothing if the character is not captured, but omitting a limit = { is_general_captured = yes } filter inside a large loop means the effect is called indiscriminately on every character. This creates unnecessary performance overhead that becomes especially noticeable in mods with large character rosters.

effect · release_from_captivity