effect · set_state_category

Hands-On Usage

set_state_category is commonly used to dynamically change a state's development tier—for example, upgrading a remote region to city status in an industrialization event, or downgrading an urban center to ruins in a war damage event. It also works well in focus trees or decision systems, allowing players to unlock higher building slot caps through investment.

# In the complete_effect of a decision: upgrade the target state to city
complete_effect = {
    every_owned_state = {
        limit = {
            has_state_category = large_town
            is_core_of = ROOT
        }
        set_state_category = city
        add_extra_state_shared_building_slots = 2
    }
}

Synergy

• [has_state_category](/wiki/trigger/has_state_category): Check the current category before executing an upgrade or downgrade to avoid redundant operations on ineligible states or unintended skipping of tiers.
• [add_extra_state_shared_building_slots](/wiki/effect/add_extra_state_shared_building_slots): After upgrading a state's category, it's typical to simultaneously increase building slots to keep both effects logically consistent.
• [set_building_level](/wiki/effect/set_building_level): In downgrade penalty scenarios, reducing building levels alongside category downgrades often reinforces the destruction effect and should be paired together.
• [add_state_modifier](/wiki/effect/add_state_modifier): Append state modifiers (such as production bonuses) after an upgrade to provide tangible numerical support for the category change.

Common Pitfalls

1. Calling outside STATE scope: set_state_category only works within STATE scope. If mistakenly placed in COUNTRY scope (such as directly in a country_event option without wrapping it in every_owned_state), the game will throw a scope error or silently fail. Always verify the context has correctly switched to STATE before execution.
2. Misspelled category names: Category identifiers (rural, town, large_town, city, large_city, etc.) must match the game's definitions exactly. Typos won't trigger syntax errors but will simply not take effect. Cross-reference the vanilla files in the common/state_category directory to confirm correct names.