effect · set_leader_portrait

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

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