effect · `set_leader_portrait`

Definition

Supported scope:CHARACTER
Supported target:any

Description

changes the portrait of unit leader. no tooltip is generated
set_leader_portrait = "GFX_portrait_italy_emperor_mussolini"

实战 · 配合 · 坑

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

实战用法

set_leader_portrait 常用于动态历史事件或 mod 剧情中，在特定条件触发后为角色更换肖像，例如让领袖在政变后使用新造型、或为通过 create_character 动态生成的角色指定特定立绘。由于本指令不生成 tooltip，适合放在 hidden_effect 中静默执行，避免日志面板出现多余提示。

# 示例：在事件中将某角色的肖像替换为新版本
character_event = {
    id = my_mod.100
    hidden = yes
    immediate = {
        # scope 已在 CHARACTER scope 内
        set_leader_portrait = "GFX_portrait_my_mod_leader_alt"
    }
}

配合关系

[set_character_name](/wiki/effect/set_character_name) / [set_leader_name](/wiki/effect/set_leader_name)：通常与换像一同使用，实现角色"外貌+姓名"整体替换，模拟身份转变或化名情节。
[set_leader_description](/wiki/effect/set_leader_description)：更换肖像的同时同步修改角色描述文本，保持人物卡片信息的一致性。
[is_corps_commander](/wiki/trigger/is_corps_commander) / [is_field_marshal](/wiki/trigger/is_field_marshal)：换像前用角色身份触发器做条件判断，确保只对正确的 CHARACTER scope 执行，防止脚本误作用于顾问或科学家。
[promote_character](/wiki/effect/promote_character)：晋升角色后立即更换肖像，体现职位变化带来的形象升级。

常见坑

Scope 错误：本指令必须在 CHARACTER scope 内执行，若误写在 COUNTRY scope 中（如直接在 country_event 的 option 块里不加 scope 转换），游戏会静默报错或无效果，新手容易因此以为立绘文件本身有问题。
GFX 名称未注册：填入的字符串必须在 interface/*.gfx 文件中已通过 spriteType 定义，若仅放置了图片文件而未声明 sprite，效果同样不生效且不会报明显错误，排查时需检查 error.log。

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_portrait is commonly used in dynamic historical events or mod storylines to change a character's portrait after specific conditions trigger—for example, giving a leader a new appearance after a coup, or assigning a specific portrait to a character dynamically generated via create_character. Since this command produces no tooltip, it is ideal for placement in hidden_effect blocks to execute silently and avoid extraneous notifications in the message log.

# Example: Replace a character's portrait with a new version in an event
character_event = {
    id = my_mod.100
    hidden = yes
    immediate = {
        # scope is already within CHARACTER scope
        set_leader_portrait = "GFX_portrait_my_mod_leader_alt"
    }
}

Synergy

[set_character_name](/wiki/effect/set_character_name) / [set_leader_name](/wiki/effect/set_leader_name): Typically used together with portrait changes to implement complete character replacement of both appearance and name, simulating identity transformation or alias scenarios.
[set_leader_description](/wiki/effect/set_leader_description): Change the portrait while simultaneously updating the character's description text, maintaining consistency across the character card information.
[is_corps_commander](/wiki/trigger/is_corps_commander) / [is_field_marshal](/wiki/trigger/is_field_marshal): Use character role triggers before portrait changes to conditionally validate execution, ensuring the script only affects the correct CHARACTER scope and prevents unintended application to advisors or scientists.
[promote_character](/wiki/effect/promote_character): Change the portrait immediately after promoting a character to reflect the visual upgrade corresponding to the rank change.

Common Pitfalls

Scope Mismatch: This command must execute within a CHARACTER scope. If mistakenly placed in a COUNTRY scope (such as directly in a country_event's option block without scope conversion), the game will silently error or produce no effect—newcomers often mistakenly assume the portrait file itself is defective.
GFX Name Not Registered: The string provided must be defined via spriteType in interface/*.gfx files. If only the image file is placed without sprite declaration, the effect will similarly fail to apply and produce no obvious error message. When troubleshooting, check the error.log.

effect · set_leader_portrait