effect · `if`

Definition

Supported scope:any
Supported target:none

Description

a conditional effect

实战 · 配合 · 坑

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

实战用法

if 用于在事件选项、国策完成效果或 on_action 回调中，根据当前游戏状态有条件地执行一段效果，例如只有当玩家满足某个变量或旗帜条件时才触发特殊奖励。结合 else_if 和 else 子块，可以在同一个执行块里实现多分支逻辑，避免写多个互斥选项。

# 国策完成效果：根据阵营立场给予不同奖励
complete_effect = {
    if = {
        limit = {
            has_global_flag = allied_with_west
        }
        add_victory_points = {
            province = 3455
            value = 5
        }
    }
    else_if = {
        limit = {
            has_global_flag = allied_with_east
        }
        add_victory_points = {
            province = 3455
            value = 3
        }
    }
    else = {
        set_global_flag = neutral_path_taken
    }
}

配合关系

[has_global_flag](/wiki/trigger/has_global_flag)：最常放在 limit 块里检测全局旗帜，决定 if 分支是否执行，是最典型的条件守卫写法。
[check_variable](/wiki/trigger/check_variable)：在 limit 中用于比较数值型变量，配合 if 实现基于积分或计数器的分支效果。
[hidden_effect](/wiki/effect/hidden_effect)：常嵌套在 if 内部，将条件成立后不希望玩家看到的执行细节隐藏，保持日志/提示干净。
[custom_effect_tooltip](/wiki/effect/custom_effect_tooltip)：当 if 内部逻辑对玩家不可见时，与之配合在界面上显示人类可读的条件说明，改善 UX。

常见坑

忘记写 limit 块：if 必须包含 limit = { ... } 来声明触发条件，如果省略 limit，游戏会将该分支视为无条件执行，效果等同于直接写在外层，逻辑完全错误且不会报错，非常难排查。
在 limit 里写 effect 命令：limit 块只接受 trigger（条件判断），误将 set_variable 等 effect 写入其中不会生效，且部分版本下静默失败，导致分支永远不触发或脚本异常。

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

if is used within event options, focus completion effects, or on_action callbacks to conditionally execute a block of effects based on the current game state—for example, triggering special rewards only when the player meets certain variable or flag conditions. Combined with else_if and else subblocks, you can implement multi-branch logic within a single execution block, eliminating the need to write multiple mutually exclusive options.

# Focus completion effect: grant different rewards based on faction alignment
complete_effect = {
    if = {
        limit = {
            has_global_flag = allied_with_west
        }
        add_victory_points = {
            province = 3455
            value = 5
        }
    }
    else_if = {
        limit = {
            has_global_flag = allied_with_east
        }
        add_victory_points = {
            province = 3455
            value = 3
        }
    }
    else = {
        set_global_flag = neutral_path_taken
    }
}

Synergy

[has_global_flag](/wiki/trigger/has_global_flag): Most commonly placed inside the limit block to check global flags and determine whether the if branch executes; this is the quintessential conditional guard pattern.
[check_variable](/wiki/trigger/check_variable): Used within limit to compare numeric variables, paired with if to implement branch effects based on scores or counters.
[hidden_effect](/wiki/effect/hidden_effect): Frequently nested inside if to conceal execution details that should not be visible to the player after the condition is met, keeping logs and notifications clean.
[custom_effect_tooltip](/wiki/effect/custom_effect_tooltip): When the logic inside if is not visible to the player, pair it with this to display human-readable condition descriptions in the interface, improving UX.

Common Pitfalls

Forgetting to write the limit block: if must contain limit = { ... } to declare the trigger condition. If you omit limit, the game will treat that branch as unconditional execution, equivalent to writing it directly in the outer scope—the logic becomes completely wrong and produces no error message, making it extremely difficult to debug.
Writing effect commands inside limit: The limit block only accepts triggers (conditions), not effects. Placing commands like set_variable inside it will have no effect, and in some versions it fails silently, causing the branch to never trigger or the script to malfunction.

effect · if