effect · set_province_name

Hands-On Usage

set_province_name is commonly used in historical events or scenario mods when a province needs to be renamed due to war, treaties, or cultural changes (such as renaming German place names to Polish ones). It can also be used in dynamic territory events, combined with occupation logic to assign new wartime designations to frontline provinces.

# After a country acquires a province through treaty, rename the province
country_event = {
    id = my_mod.42
    immediate = {
        set_province_name = {
            id = 3210
            name = "Neu_Königsberg"
        }
    }
}

Synergy

• [reset_province_name](/wiki/effect/reset_province_name): Inverse operation to this command; used to restore the original province name when the player loses the territory or when an event is rolled back, preventing residual incorrect names.
• [add_victory_points](/wiki/effect/add_victory_points): Commonly used in combination within the same option; rename the province while adjusting its strategic value, ensuring narrative and mechanical changes take effect simultaneously.
• [custom_effect_tooltip](/wiki/effect/custom_effect_tooltip): Since province renaming provides minimal UI feedback, pair this command with it to display an explanatory tooltip to the player, improving mod readability.
• [set_victory_points](/wiki/effect/set_victory_points): In scenarios where province renaming is accompanied by changes in political significance, simultaneously reset the victory points to ensure the map state aligns with the new naming's meaning.

Common Pitfalls

1. id refers to province ID rather than state ID: Newcomers often confuse state ID (hundreds magnitude) with province ID (thousands magnitude), causing the command to fail silently or apply to the wrong province. Always verify the specific province number in /Hearts of Iron IV/map/definition.csv.
2. Name string lacks localization processing: Writing plaintext strings with spaces or special characters directly in the name field may cause parsing errors; it is recommended to use localization keys and define translations in the corresponding .yml files to ensure multi-language compatibility.