effect · `add_timed_unit_leader_trait`

Definition

Supported scope:CHARACTER
Supported target:none

Description

add a timed trait to unit leader

实战 · 配合 · 坑

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

实战用法

add_timed_unit_leader_trait 适合用于战役事件或成就系统中，给指挥官临时附加某种特质（例如"士气高昂"或"补给困难"），使其在特定时间窗口内表现出强化或削弱效果，时间一到自动消失，无需手动清除。常见场景包括：某次大型战役胜利后，奖励指挥官一段时间的进攻加成特质；或触发天气/疾病事件后，给指挥官施加临时减益。

# 某战役胜利事件中，给触发事件的角色附加一个限时特质
character_event = {
    id = my_mod.101
    hidden = yes
    immediate = {
        add_timed_unit_leader_trait = {
            trait = brilliant_strategist
            days = 180
        }
    }
}

配合关系

[has_trait](/wiki/trigger/has_trait) — 在添加限时特质前，先检查角色是否已拥有该特质或冲突特质，避免重复叠加或逻辑矛盾。
[remove_unit_leader_trait](/wiki/effect/remove_unit_leader_trait) — 若需要提前手动取消该限时特质（例如角色受伤或被解职时），可与本命令搭配使用作为清理手段。
[add_unit_leader_trait](/wiki/effect/add_unit_leader_trait) — 与永久版特质命令对比使用：当设计上希望特质永久保留时改用此命令，两者逻辑互补，便于在脚本中统一管理角色特质状态。
[is_corps_commander](/wiki/trigger/is_corps_commander) / [is_field_marshal](/wiki/trigger/is_field_marshal) — 在调用前用来限定角色的指挥官类型，确保所添加的特质对该角色类别有效，防止特质与角色职能不匹配。

常见坑

忘记指定 days 或填写了无效的时长：该 effect 的"限时"核心在于持续时间字段，若省略或写成 0，特质可能立即消失或产生未定义行为，一定要显式填写大于 0 的合法天数值。
在非 CHARACTER scope 下调用：此命令只对 CHARACTER scope 生效，若在 country scope 的事件 immediate 中直接写而未先通过 every_character、random_character 等切入角色 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

add_timed_unit_leader_trait is ideal for campaign events or achievement systems, granting commanders temporary traits (such as "high morale" or "supply shortages") that produce enhanced or weakened effects within a specific time window and automatically expire when the duration runs out, eliminating the need for manual cleanup. Common scenarios include: rewarding a commander with bonus offensive traits for a period after a major campaign victory, or inflicting temporary debuffs on a commander following a weather or disease event.

# In a campaign victory event, attach a time-limited trait to the triggering character
character_event = {
    id = my_mod.101
    hidden = yes
    immediate = {
        add_timed_unit_leader_trait = {
            trait = brilliant_strategist
            days = 180
        }
    }
}

Synergy

[has_trait](/wiki/trigger/has_trait) — Before adding a timed trait, first check whether the character already possesses that trait or conflicting traits to avoid duplicate stacking or logical contradictions.
[remove_unit_leader_trait](/wiki/effect/remove_unit_leader_trait) — If you need to manually cancel the timed trait early (such as when a character is wounded or dismissed), you can pair this command with the removal command as a cleanup measure.
[add_unit_leader_trait](/wiki/effect/add_unit_leader_trait) — Compare with the permanent trait variant: when your design calls for a trait to be retained permanently, use that command instead. The two commands are logically complementary, making it convenient to manage character trait states uniformly in your scripts.
[is_corps_commander](/wiki/trigger/is_corps_commander) / [is_field_marshal](/wiki/trigger/is_field_marshal) — Use these before invoking this effect to restrict the commander type, ensuring the added trait is valid for that character category and preventing trait-to-role mismatch.

Common Pitfalls

Forgetting to specify days or providing an invalid duration — The "time-limited" aspect of this effect hinges on the duration field. If omitted or set to 0, the trait may disappear immediately or produce undefined behavior. Always explicitly provide a valid number of days greater than 0.
Calling outside CHARACTER scope — This command only works in CHARACTER scope. If you write it directly in a country scope event's immediate block without first transitioning to character scope via every_character, random_character, or similar, the script will silently fail without error, leaving the effect completely untriggered.

effect · add_timed_unit_leader_trait