effect · `replace_unit_leader_trait`

Definition

Supported scope:CHARACTER
Supported target:none

Description

add trait to unit leader

实战 · 配合 · 坑

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

实战用法

replace_unit_leader_trait 常用于需要「替换」将领某个特质的 mod 场景，例如让指挥官在经历特定事件后将初始缺陷特质换成进阶特质，而无需先手动移除再添加。典型场景是事件触发后直接对当前 CHARACTER scope 执行替换，比一对 remove_unit_leader_trait + add_unit_leader_trait 更简洁。

# 某事件 option 中，将领完成特殊任务后替换其特质
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
        }
    }
}

配合关系

[has_trait](/wiki/trigger/has_trait)：执行替换前先检查当前角色确实拥有目标特质，避免在不存在旧特质时触发异常逻辑。
[add_unit_leader_trait](/wiki/effect/add_unit_leader_trait)：当需要新增而非替换特质时作为备选；两者对比使用可以清晰区分"替换"与"叠加"两种设计意图。
[add_timed_unit_leader_trait](/wiki/effect/add_timed_unit_leader_trait)：在替换后若还需给角色附加一个临时 buff，可紧接使用该命令实现阶段性强化效果。
[gain_xp](/wiki/effect/gain_xp)：替换特质往往伴随角色成长叙事，同步给予经验值可使角色成长感更完整。

常见坑

未确认旧特质存在就执行替换：若角色根本没有 trait 字段所指定的旧特质，替换不会产生预期效果，建议始终用 [has_trait](/wiki/trigger/has_trait) 包裹在 limit 或 if 块中做前置判断。
scope 不在 CHARACTER 上：在国家或州省 scope 内直接调用此命令会导致脚本报错或静默失败，务必通过 every_character、random_character 或具名角色引用先切换到正确的 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

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

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

effect · replace_unit_leader_trait