effect · set_leader_name

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

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