effect · modify_state_flag

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

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