Wiki

effect · set_character_name

Definition

  • Supported scope:COUNTRY, CHARACTER
  • Supported target:none

Description

"set name for the target character. Either localization key or direct name.
example:
set_character_name = {
	character = my_character # optional, use if not in a character scope
	name = my_name # either loc key or direct name
}
my_character = {
	set_character_name = my_name # only possible in character 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_character_name is commonly used in dynamic narrative scenarios, such as when a character acquires a new title, alias, or epithet after experiencing a specific event (for example, an underground leader changing identity after exposure, or a monarch formally renaming themselves upon coronation). Within a country scope, the target character must be specified via the character = field; within a character scope, you can pass the name string directly for more concise syntax.

# Within country scope, rename a specific character via event
country_event = {
    id = my_mod.10
    option = {
        name = my_mod.10.a
        # Use localization keys to support multiple languages
        set_character_name = {
            character = GER_my_spy
            name = GER_my_spy_alias
        }
    }
}

# Directly assign name within character scope (e.g., triggered by on_action)
GER_my_spy = {
    set_character_name = "Heinrich Braun"
}

Synergy

  • [set_portraits](/wiki/effect/set_portraits) — When renaming a character, their appearance typically needs to be updated simultaneously (such as disguises or identity changes); both are often called together to maintain visual consistency.
  • [set_nationality](/wiki/effect/set_nationality) — When a character defects or goes into exile, name and nationality are usually changed in tandem; using them together fully expresses an identity transition.
  • [add_country_leader_trait](/wiki/effect/add_country_leader_trait) / [remove_country_leader_trait](/wiki/effect/remove_country_leader_trait) — Renaming is frequently accompanied by adding or removing traits to reinforce the narrative sense of character "transformation."
  • [has_character_flag](/wiki/trigger/has_character_flag) — Used to check whether a rename has already been triggered, preventing the same character from being renamed repeatedly and causing logical conflicts.

Common Pitfalls

  1. Forgetting the character = field within country scope: Writing set_character_name = my_name directly in country scope is invalid syntax; you must use the curly brace form and specify character = .... Otherwise, the game will silently error or have no effect.
  2. Confusing localization keys with direct strings: The name parameter can be either a localization key (defined in a .yml file) or a quoted direct string. If not quoted and the key cannot be found in the localization file, the character's name will display as the raw key text rather than the intended content. Pay careful attention to which approach fits your use case.