effect · replace_unit_leader_trait

Hands-On Usage

replace_unit_leader_trait is commonly used in mod scenarios where you need to "swap out" a specific trait from a commander, such as replacing an initial weakness trait with an advanced trait after the unit leader experiences a particular event, without having to manually remove and re-add traits separately. The typical use case is executing the replacement directly on the current CHARACTER scope after an event triggers, which is more concise than a pair of remove_unit_leader_trait + add_unit_leader_trait commands.

# In a certain event option, replace the unit leader's trait after completing a special task
character_event = {
    id = my_mod.101
    option = {
        name = my_mod.101.a
        replace_unit_leader_trait = {
            trait = old_cautious_trait
            replace_with = bold_commander_trait
        }
    }
}

Synergy

• [has_trait](/wiki/trigger/has_trait): Check that the character actually possesses the target trait before executing the replacement, avoiding unexpected logic when the old trait doesn't exist.
• [add_unit_leader_trait](/wiki/effect/add_unit_leader_trait): Use as an alternative when you need to add rather than replace a trait; comparing the two approaches clarifies the design intent between "replacement" and "stacking" traits.
• [add_timed_unit_leader_trait](/wiki/effect/add_timed_unit_leader_trait): If you need to apply a temporary buff to the character after the replacement, this command can be used immediately afterward to achieve phased enhancement effects.
• [gain_xp](/wiki/effect/gain_xp): Trait replacements often accompany character growth narratives, so granting experience points simultaneously makes the character progression feel more complete.

Common Pitfalls

1. Executing replacement without confirming the old trait exists: If the character doesn't actually have the old trait specified in the trait field, the replacement won't produce the intended effect. Always wrap this in a [has_trait](/wiki/trigger/has_trait) check within a limit or if block for pre-validation.
2. Scope not on CHARACTER: Calling this command directly within a country or state scope will cause script errors or silent failures. Always switch to the correct CHARACTER scope first using every_character, random_character, or explicit character references before executing the command.