effect · modify_character_flag

Hands-On Usage

modify_character_flag is commonly used in scenarios requiring counting or cumulative tracking of character actions, such as recording the number of times a character completes a task, accumulating injury counts, or building up specific behavior points. Combined with subsequent trigger checks against thresholds, it can trigger special events or unlock traits. Note that this command can only modify existing flags; therefore, you typically need to first initialize the flag with an initial value using set_character_flag during the character setup phase, and then use this command to increment or decrement its value.

# Increment the count flag by 1 each time the character participates in an event
character_event = {
    id = my_mod.10
    hidden = yes
    immediate = {
        # Assume the "battle_count" flag has already been initialized when the character was created
        modify_character_flag = {
            flag = battle_count
            value = 1
        }
    }
}

Synergy

• [set_character_flag](/wiki/effect/set_character_flag): Must be used before modify_character_flag to create the flag and set its initial value; otherwise, this command will have no effect.
• [has_character_flag](/wiki/trigger/has_character_flag): Used to check whether a flag exists and whether its current value meets the threshold—an essential condition for triggering subsequent logic (such as unlocking traits or triggering events).
• [clr_character_flag](/wiki/effect/clr_character_flag): Used to reset or clear the flag after the count reaches the target value and completes a stage of logic, preventing infinite accumulation and unexpected behavior.
• [add_trait](/wiki/effect/add_trait): Often serves as the reward result after the count threshold is met; combined with the threshold check of has_character_flag, it adds the corresponding trait to the character when conditions are satisfied.

Common Pitfalls

1. Silent failure when flag doesn't exist: The most common beginner mistake is using modify_character_flag directly without first initializing the flag with set_character_flag. Since the game will silently skip without reporting an error, the counting logic fails entirely and is extremely difficult to debug.
2. Incorrect scope targeting: This command must be executed within CHARACTER scope. If called from COUNTRY or other scopes without properly switching the scope via character = { ... } or similar mechanisms, it will likewise fail silently.