effect · `free_operative`

Definition

Supported scope:COUNTRY, CHARACTER
Supported target:THIS, ROOT, PREV, FROM

Description

Free an operative
Can be used from a scope and a target that is either a country or a unit leader.
GER = { free_operative = PREV } # where PREV is an operative (unit leader)
free_operative = { captured_by = GER } # where the scope is an unit leader

实战 · 配合 · 坑

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

实战用法

free_operative 常用于情报 mod 中设计"越狱"或"外交谈判"剧情：当玩家完成某个国策或选项后，释放己方被捕特工回到可用状态。也可用于在 AI 事件中模拟交换俘虏的场景，让双方特工互相释放。

# 玩家选择"谈判释放特工"选项时
option = {
    name = spy_event.1.a
    # 从国家 scope 指定目标特工
    GER = {
        free_operative = PREV   # PREV 为先前被 capture_operative 捕获的特工
    }
}

# 或从特工自身 scope 释放
any_operative_leader = {
    limit = {
        has_captured_operative = yes   # 确认处于被捕状态
    }
    free_operative = { captured_by = ROOT }
}

配合关系

[capture_operative](/wiki/effect/capture_operative)：捕获与释放是一对互逆操作，剧本中通常先用 capture_operative 制造被捕事件，再由 free_operative 收尾。
[turn_operative](/wiki/effect/turn_operative)：释放前可先策反特工，形成"策反后放回"的经典反间谍剧情流程。
[kill_operative](/wiki/effect/kill_operative)：与 free_operative 互斥的结局选项，在同一个事件的不同 option 里分别放置，给玩家"释放还是处决"的抉择。
[has_captured_operative](/wiki/trigger/has_captured_operative)：释放前应用此 trigger 做 limit 校验，确保目标特工当前确实处于被捕状态，避免脚本在无效对象上执行。

常见坑

scope 与目标混淆：新手常忘记该 effect 支持两种写法——从国家 scope 传入特工作为值，或从特工 scope 内用 captured_by 指定抓获国。混用两种写法的字段会导致脚本静默失败，游戏日志中不报错但特工不会被释放。
对未被捕特工使用：若目标特工并非处于被捕状态，free_operative 不会产生任何效果，但不会报错，容易造成"以为释放了但实际没发生"的调试困境——务必在外层加 has_captured_operative 做条件限制。

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

free_operative is commonly used in espionage mods to design "prison break" or "diplomatic negotiation" storylines: when the player completes a certain national focus or option, the captured operative of your side is released back to available status. It can also be used in AI events to simulate prisoner exchange scenarios where operatives from both sides are mutually released.

# When player selects "negotiate operative release" option
option = {
    name = spy_event.1.a
    # Specify target operative from country scope
    GER = {
        free_operative = PREV   # PREV is the operative previously captured by capture_operative
    }
}

# Or release from operative's own scope
any_operative_leader = {
    limit = {
        has_captured_operative = yes   # Confirm operative is in captured state
    }
    free_operative = { captured_by = ROOT }
}

Synergy

[capture_operative](/wiki/effect/capture_operative): Capture and release are inverse operations. In scripts, typically use capture_operative to create a capture event first, then conclude with free_operative.
[turn_operative](/wiki/effect/turn_operative): Before releasing, you can first turn the operative, forming the classic counter-espionage storyline of "turn and release".
[kill_operative](/wiki/effect/kill_operative): Mutually exclusive outcome option with free_operative. Place them separately in different options of the same event to give players the choice of "release or execute".
[has_captured_operative](/wiki/trigger/has_captured_operative): Apply this trigger as a limit check before release to ensure the target operative is actually in captured state, avoiding script execution on invalid targets.

Common Pitfalls

Confusion between scope and target: Beginners often forget that this effect supports two syntaxes—passing the operative as a value from country scope, or specifying the capturing country with captured_by from operative scope. Mixing the two syntaxes causes silent script failure; the game log won't report errors but the operative won't be released.
Using on non-captured operatives: If the target operative is not in captured state, free_operative produces no effect but doesn't report an error, easily leading to the debugging frustration of "thought it was released but nothing happened"—always wrap with has_captured_operative as a condition check.

effect · free_operative