effect · `set_leader_description`

Definition

Supported scope:CHARACTER
Supported target:any

Description

changes the description of unit leader. no tooltip is generated
set_leader_description = "DESC_KEY"

实战 · 配合 · 坑

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

实战用法

set_leader_description 常用于动态叙事类 mod，当将领经历特定事件（如晋升、负伤、叛变）后，为其角色档案注入符合当前剧情的传记文本，实现"活的"人物成长感。它也常见于历史还原 mod，用于在特定历史节点切换将领的官方简介以匹配不同时期的史实描述。

# 某将领在历史事件触发后更新其描述
character_event = {
    id = my_mod.100
    hidden = yes
    immediate = {
        FROM = {
            set_leader_description = "CHAR_ROMMEL_PROMOTED_DESC"
        }
    }
}

配合关系

[set_leader_name](/wiki/effect/set_leader_name)：两者经常同时调用，在叙事转折点同步更新将领的显示名称与传记描述，保持档案一致性。
[set_leader_portrait](/wiki/effect/set_leader_portrait)：切换肖像的同时替换描述文本，使视觉与文字两套呈现都跟随剧情演变。
[set_character_flag](/wiki/effect/set_character_flag)：先用 flag 记录"已触发描述更新"状态，再配合 [has_character_flag](/wiki/trigger/has_character_flag) 做条件判断，防止描述被重复覆盖。
[add_unit_leader_trait](/wiki/effect/add_unit_leader_trait)：为将领添加新特质的同时更新描述，让特质的背景故事通过传记文字得到解释。

常见坑

本地化 key 未定义就引用：set_leader_description 的参数必须是已在 .yml 本地化文件中声明的字符串 key，若 key 不存在游戏不会报错但档案页会显示空白或原始 key 名，极易被误认为脚本不生效。
在非 CHARACTER scope 下调用：该 effect 只对 CHARACTER scope 有效，若在 COUNTRY 或 STATE 等 scope 下误调用，游戏日志会抛出 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

set_leader_description is commonly used in narrative-driven mods to dynamically inject biographical text into a character's profile when they experience specific events (such as promotion, injury, or defection). This creates a sense of "living" character development. It's also frequently seen in historical accuracy mods, where it's used to swap out a leader's official biography at key historical moments to match period-appropriate historical descriptions.

# Update a leader's description after a historical event is triggered
character_event = {
    id = my_mod.100
    hidden = yes
    immediate = {
        FROM = {
            set_leader_description = "CHAR_ROMMEL_PROMOTED_DESC"
        }
    }
}

Synergy

[set_leader_name](/wiki/effect/set_leader_name): Often called together with this effect to synchronously update both the leader's display name and biographical description at narrative turning points, maintaining profile consistency.
[set_leader_portrait](/wiki/effect/set_leader_portrait): Pair portrait changes with description text replacement so that both visual and textual presentation evolve with the storyline.
[set_character_flag](/wiki/effect/set_character_flag): Use a flag to record the "description updated" state first, then combine with [has_character_flag](/wiki/trigger/has_character_flag) for conditional logic to prevent description text from being repeatedly overwritten.
[add_unit_leader_trait](/wiki/effect/add_unit_leader_trait): Update the description when adding new traits to a leader, allowing the trait's backstory to be explained through the biographical text.

Common Pitfalls

Referencing undefined localization keys: The parameter for set_leader_description must be a string key already declared in .yml localization files. If the key doesn't exist, the game won't throw an error, but the profile page will display blank or show the raw key name—easily mistaken for a script failure.
Calling outside CHARACTER scope: This effect only works within CHARACTER scope. If mistakenly called under COUNTRY or STATE scope, the game log will emit a scope mismatch warning and the command silently fails. When debugging, carefully verify the calling hierarchy.

effect · set_leader_description