effect · if

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

1. 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.
2. 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.