effect · `modify_unit_leader_flag`

Definition

Supported scope:CHARACTER
Supported target:none

Description

modify unit leader flag. Only modifies if flag already exists.
Example: _modify_unit_leader_flag_ = { flag = <name> value = <number> }
This effect is deprecated in favor of modify_character_flag.

实战 · 配合 · 坑

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

实战用法

modify_unit_leader_flag 用于在 mod 中对已存在的数值型将领标记进行累加或递减操作，常见于动态成长系统中追踪将领的战役次数、伤亡计数或特殊事件积分。需要注意的是该效果只在 flag 已经存在的情况下才会生效，因此通常与预先设置 flag 的逻辑搭配使用。以下示例展示在一场战役结束事件中为将领的战斗计数标记加一：

# 在某个 CHARACTER scope 的事件 option 中
option = {
    name = my_event.1.a
    # 先确保 flag 存在，再修改其值
    modify_unit_leader_flag = {
        flag = battles_fought_count
        value = 1
    }
}

配合关系

[set_unit_leader_flag](/wiki/effect/set_unit_leader_flag)：在调用 modify_unit_leader_flag 之前，必须先用此命令初始化 flag 并赋予初始值，否则修改操作将静默失败。
[has_unit_leader_flag](/wiki/trigger/has_unit_leader_flag)：在修改前用此触发器检查 flag 是否已存在及其当前值，实现条件分支逻辑，避免无效调用。
[clr_unit_leader_flag](/wiki/effect/clr_unit_leader_flag)：当计数或积分达到阈值后，可用此命令清除 flag，配合 set_unit_leader_flag 重置循环计数。
[modify_character_flag](/wiki/effect/modify_character_flag)：官方推荐的替代命令，功能相同但面向更通用的 CHARACTER scope，新 mod 应优先使用此命令替换旧写法。

常见坑

flag 不存在时静默失败：新手常忘记该效果仅在 flag 已存在时才生效，如果没有事先用 set_unit_leader_flag 初始化，脚本不会报错但数值根本不会改变，导致难以排查的逻辑 bug。
在 COUNTRY scope 中误用：该效果仅作用于 CHARACTER scope，若在国家 scope 下直接调用而未先通过 any_character 或具体角色 scope 进入角色 scope，效果将无法执行，需确认当前 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_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

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

effect · modify_unit_leader_flag