effect · `set_country_leader_portrait`

Definition

Supported scope:COUNTRY
Supported target:any

Description

changes the portrait of country leader. no tooltip is generated
set_country_leader_name = {
  ideology = neutrality # can be ommitted. if so it will change the portrait of current ruler
  portrait = "GFX_portrait_italy_emperor_mussolini"
}

实战 · 配合 · 坑

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

实战用法

当你通过事件或决议动态更换某国领导人的肖像时（例如执政党更迭、历史事件触发后的外观刷新，或 cosmetic mod 中为非标准领导人补充立绘），可以使用此 effect 精准替换特定意识形态下的领导人头像，而不影响其他属性。以下示例在事件中将中立意识形态领袖的头像替换为自定义 GFX：

country_event = {
    id = my_mod.1
    hidden = yes
    immediate = {
        set_country_leader_portrait = {
            ideology = neutrality
            portrait = "GFX_portrait_my_custom_leader"
        }
    }
}

配合关系

[create_country_leader](/wiki/effect/create_country_leader)：通常先用此命令创建新领导人，再用 set_country_leader_portrait 修正或后期覆盖肖像，避免重建整个领导人对象。
[add_country_leader_trait](/wiki/effect/add_country_leader_trait)：在同一执行块中为领导人添加特质的同时刷新肖像，保持领导人数据的整体一致性。
[has_country_leader](/wiki/trigger/has_country_leader)：在触发条件中先确认对应意识形态的领导人确实存在，防止无效调用导致脚本静默失败。
[add_country_leader_role](/wiki/effect/add_country_leader_role)：为角色绑定国家领袖职位后，常需同步更新肖像以匹配新角色的视觉呈现。

常见坑

忽略 ideology 字段导致误改当前执政领袖：省略 ideology 时效果作用于当前在位领袖，若目标实为非执政意识形态的后备领袖（如尚未上台的共产党领导人），必须显式填写对应的意识形态子类型（如 leninism），否则肖像会被错误地套用到执政者身上。
GFX 键名未在 .gfx 文件中定义即引用：此 effect 不生成任何 tooltip，脚本不会报错，但游戏内会显示默认占位图甚至空白，排查时极难发现；务必先在 interface/ 目录的 .gfx 文件中确认对应的 spriteType 已正确声明后再引用。

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

When you dynamically change a country leader's portrait through events or decisions (such as ruling party transitions, appearance refreshes after historical events, or adding character art for non-standard leaders in cosmetic mods), you can use this effect to precisely replace the leader's portrait under a specific ideology without affecting other attributes. The following example replaces a neutrality ideology leader's portrait with a custom GFX in an event:

country_event = {
    id = my_mod.1
    hidden = yes
    immediate = {
        set_country_leader_portrait = {
            ideology = neutrality
            portrait = "GFX_portrait_my_custom_leader"
        }
    }
}

Synergy

[create_country_leader](/wiki/effect/create_country_leader): Typically use this command first to create a new leader, then use set_country_leader_portrait to correct or override the portrait afterward, avoiding the need to rebuild the entire leader object.
[add_country_leader_trait](/wiki/effect/add_country_leader_trait): Add traits to a leader while refreshing their portrait in the same execution block to maintain overall consistency of leader data.
[has_country_leader](/wiki/trigger/has_country_leader): First confirm in trigger conditions that a leader of the corresponding ideology actually exists to prevent invalid calls that cause scripts to fail silently.
[add_country_leader_role](/wiki/effect/add_country_leader_role): After binding a country leader position to a role, you often need to synchronously update the portrait to match the new role's visual presentation.

Common Pitfalls

Omitting the ideology field causes unintended changes to the current ruling leader: When ideology is omitted, the effect applies to the currently sitting leader. If your target is actually a backup leader of a non-ruling ideology (such as a Communist leader not yet in power), you must explicitly specify the corresponding ideology subtype (such as leninism), otherwise the portrait will be incorrectly applied to the ruling leader.
Referencing a GFX key name that is not defined in the .gfx file: This effect generates no tooltip and the script won't error, but the game will display a default placeholder or even a blank image, making it extremely difficult to troubleshoot. Always confirm that the corresponding spriteType has been correctly declared in the .gfx files in the interface/ directory before referencing it.

effect · set_country_leader_portrait