effect · add_timed_unit_leader_trait

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

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