effect · modify_unit_leader_flag

Hands-On Usage

modify_unit_leader_flag is used in mods to increment or decrement existing numeric unit leader flags, commonly employed in dynamic growth systems to track a leader's campaign count, casualty metrics, or special event scores. Note that this effect only works if the flag already exists; therefore, it should typically be paired with logic that pre-initializes the flag. The following example demonstrates incrementing a leader's battle count flag in a campaign-end event option:

# Within an event option in CHARACTER scope
option = {
    name = my_event.1.a
    # Ensure the flag exists before modifying its value
    modify_unit_leader_flag = {
        flag = battles_fought_count
        value = 1
    }
}

Synergy

• [set_unit_leader_flag](/wiki/effect/set_unit_leader_flag): Before calling modify_unit_leader_flag, you must first initialize the flag with an initial value using this command; otherwise the modification will fail silently.
• [has_unit_leader_flag](/wiki/trigger/has_unit_leader_flag): Use this trigger before modification to check whether the flag exists and inspect its current value, enabling conditional branch logic and avoiding ineffective calls.
• [clr_unit_leader_flag](/wiki/effect/clr_unit_leader_flag): Once a counter or score reaches a threshold, use this command to clear the flag, then pair it with set_unit_leader_flag to reset the loop counter.
• [modify_character_flag](/wiki/effect/modify_character_flag): The officially recommended alternative command with equivalent functionality but targeting the more universal CHARACTER scope; new mods should prioritize using this command instead of the older approach.

Common Pitfalls

1. Silent failure when flag does not exist: Beginners often forget that this effect only works when the flag already exists. If you fail to pre-initialize the flag with set_unit_leader_flag, the script will not error but the value will not change at all, resulting in difficult-to-diagnose logic bugs.
2. Misuse in COUNTRY scope: This effect only operates on the CHARACTER scope. If you call it directly in a country scope without first entering character scope via any_character or a specific character scope, the effect will not execute. Always verify the current scope type is correct.