effect · `set_leader_name`

Definition

Supported scope:CHARACTER
Supported target:any

Description

changes the name of unit leader. no tooltip is generated
set_leader_name = "James Boned"

实战 · 配合 · 坑

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

实战用法

set_leader_name 常用于动态叙事 mod 中，需要在特定剧情触发后为角色更换代号、化名或头衔的场景，例如特工身份暴露后改用真实姓名，或将程序化生成的将领重命名为玩家自定义名称。注意该命令不产生任何 tooltip，适合放在 hidden_effect 块中静默执行，避免日志刷屏。

# 示例：某特工任务完成后将代号改为真实姓名
character:SPY_AGENT_001 = {
    hidden_effect = {
        set_leader_name = "Heinrich Müller"
    }
}

配合关系

[set_leader_portrait](/wiki/effect/set_leader_portrait)：改名后通常需要同步更换头像，保持角色视觉一致性，两者常在同一 hidden_effect 块中连用。
[set_leader_description](/wiki/effect/set_leader_description)：重命名时往往也需要刷新角色背景描述，与 set_leader_name 搭配实现完整的"身份重塑"效果。
[set_character_flag](/wiki/effect/set_character_flag)：在改名前后设置标记，用于追踪角色是否已经过重命名，防止事件重复触发导致名字被反复覆盖。
[is_unit_leader](/wiki/trigger/is_unit_leader)：在调用改名前先用此触发器校验角色确实处于将领身份，避免对非将领角色执行无效操作。

常见坑

忘记 scope 必须是 CHARACTER：直接在 COUNTRY scope 下调用会静默失败且无报错，必须先通过 character:TAG_CHARACTER_TOKEN = { ... } 或事件 FROM 等方式切入正确的角色 scope。
与 set_character_name 混淆：set_character_name 修改的是角色的通用名（影响顾问、国家领袖等所有角色槽的显示），而 set_leader_name 只修改其作为单位指挥官时的名称；在同一角色身兼多职时误用两者会导致不同界面显示不一致。

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

set_leader_name is commonly used in dynamic narrative mods to rename characters, aliases, or titles in specific story contexts—such as changing a codename to a real name after an agent's cover is blown, or renaming procedurally generated commanders to player-defined names. Note that this command produces no tooltip and is well-suited for silent execution within hidden_effect blocks to avoid cluttering the log.

# Example: After a spy mission completes, change the codename to the real name
character:SPY_AGENT_001 = {
    hidden_effect = {
        set_leader_name = "Heinrich Müller"
    }
}

Synergy

[set_leader_portrait](/wiki/effect/set_leader_portrait): After renaming, it's usually necessary to update the portrait simultaneously to maintain visual consistency; these two are often used together in the same hidden_effect block.
[set_leader_description](/wiki/effect/set_leader_description): When renaming a character, it's common to refresh their background description as well, pairing with set_leader_name to achieve a complete "identity makeover" effect.
[set_character_flag](/wiki/effect/set_character_flag): Set a flag before or after renaming to track whether a character has already been renamed, preventing duplicate event triggers that could overwrite the name repeatedly.
[is_unit_leader](/wiki/trigger/is_unit_leader): Before calling rename, use this trigger to verify the character is actually in a commander role, avoiding ineffective operations on non-commander characters.

Common Pitfalls

Forgetting that scope must be CHARACTER: Calling directly under a COUNTRY scope will fail silently with no error message. You must first switch to the correct character scope via character:TAG_CHARACTER_TOKEN = { ... } or event FROM and similar methods.
Confusing with set_character_name: set_character_name modifies the character's generic name (affecting display across all character slots like advisors and national leaders), while set_leader_name only changes their name as a unit commander. Misusing both when a character holds multiple roles will cause inconsistent displays across different interfaces.

effect · set_leader_name