effect · `modify_state_flag`

Definition

Supported scope:STATE
Supported target:none

Description

modify state flag. Only modifies if flag already exists.
Example: modify_state_flag = { flag = <name> value = <number> }

实战 · 配合 · 坑

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

实战用法

modify_state_flag 常用于需要对某个州的数值型标记进行累加或递减的场景，例如追踪某州被轰炸的次数、建设进度计数器，或记录占领时间等动态数值。与直接使用 set_state_flag 覆盖不同，它只在 flag 已存在时才操作，天然具备"不初始化则不执行"的安全性，适合多事件链共享同一计数器。

# 每次触发该事件时，将州的"破坏计数"标记值累加 1
state_event = {
    id = my_mod.5
    hidden = yes
    immediate = {
        modify_state_flag = {
            flag = infrastructure_damage_count
            value = 1
        }
    }
}

配合关系

[has_state_flag](/wiki/trigger/has_state_flag)：在执行 modify_state_flag 前先检查 flag 是否存在，确保不会因 flag 未初始化而导致无声失效，两者形成"判断-修改"的标准搭档。
[set_state_flag](/wiki/effect/set_state_flag)：用于在计数器首次初始化时创建 flag（设初值），之后才能交由 modify_state_flag 持续累加，两者构成"创建-递增"的完整生命周期。
[clr_state_flag](/wiki/effect/clr_state_flag)：当计数器达到阈值或任务完成时清除 flag，与 modify_state_flag 共同管理 flag 的完整生命周期。
[state_event](/wiki/effect/state_event)：将修改 flag 的逻辑封装为隐藏事件定期触发，实现跨时间轴的动态数值追踪。

常见坑

flag 不存在时静默失效：如果目标 flag 从未被 set_state_flag 初始化过，modify_state_flag 不会自动创建它，也不会报错，修改直接被忽略。新手常误以为它与 set_state_flag 等效而省略初始化步骤，导致计数器始终不生效。
作用域必须是 STATE：此命令只能在 STATE scope 下执行，若在 COUNTRY 或 CHARACTER 等 scope 内调用会导致脚本报错或无效，需确保先通过 every_state、random_state 等方式正确切换到目标州的 scope。

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

modify_state_flag is commonly used in scenarios where you need to increment or decrement a numeric flag value for a particular state, such as tracking the number of times a state has been bombed, maintaining a construction progress counter, or recording occupation duration and other dynamic values. Unlike directly using set_state_flag which overwrites the flag, it only operates when the flag already exists, naturally providing "safe-by-default" behavior where uninitialized flags are simply skipped. This makes it ideal for sharing a single counter across multiple event chains.

# Each time this event triggers, increment the state's "infrastructure_damage_count" flag by 1
state_event = {
    id = my_mod.5
    hidden = yes
    immediate = {
        modify_state_flag = {
            flag = infrastructure_damage_count
            value = 1
        }
    }
}

Synergy

[has_state_flag](/wiki/trigger/has_state_flag): Check whether the flag exists before executing modify_state_flag to ensure the operation doesn't silently fail due to an uninitialized flag. These two form the standard "check-then-modify" pairing.
[set_state_flag](/wiki/effect/set_state_flag): Used to create the flag on its first initialization (setting an initial value), after which modify_state_flag can continuously increment it. Together they form the complete "create-then-increment" lifecycle.
[clr_state_flag](/wiki/effect/clr_state_flag): Clear the flag when the counter reaches a threshold or a task completes, working alongside modify_state_flag to manage the flag's full lifecycle.
[state_event](/wiki/effect/state_event): Encapsulate the flag modification logic as a hidden event that triggers periodically, enabling dynamic value tracking across the timeline.

Common Pitfalls

Silent failure when flag doesn't exist: If the target flag has never been initialized by set_state_flag, modify_state_flag will not automatically create it and will not produce an error either—the modification is simply ignored. Beginners often mistakenly assume it works like set_state_flag and skip the initialization step, resulting in the counter never working.
Scope must be STATE: This command can only be executed within a STATE scope. Calling it within COUNTRY or CHARACTER scope will cause script errors or have no effect. Always ensure you switch to the target state's scope first using methods like every_state or random_state.

effect · modify_state_flag