effect · `state_event`

Definition

Supported scope:STATE, COUNTRY
Supported target:none

Description

Fires a state event.
Example:
state_event = {
	id = usa.61 # The event to fire.
	# Optional Fields:
	hours = 12 # The number of hours to wait before firing the event.
	days = 5 # The number of days to wait before firing the event.
	months = 1 # The number of months to wait before firing the event, where a month is treated as 30 days.
		# Note:  hours, days, and months can all be used and will simply be added together.
	random_hours = 18 # A random amount of hours to be added to the delay before firing, from 0 up to but not including random_hours.
	random_days = 2 # A random amount of days to be added to the delay before firing, from 0 up to but one hour less than random_days.
		# Note:  random_hours and random_days can both be used and will simply be added together.
	random = 6 # Equivalent to random_hours; preserverd for backwards compatibility.
	random = { chance = 50 ... } # Specify a set of child effects to execute as part of this effect, with a percentage chance of randomly happening or not (as a group, not individually).
	tooltip = usa.61.t # Manually specify which tooltip to use for this effect.
	trigger_for = GER # Indicate which country this state effect applies to. Value can be any of the following:
		# controller - The country that currently controls the state.
		# owner - The country that currently owns the state.
		# occupied - The country that has been occupied in the state by the current controller.
		# from - The country of the from scope.
		# prev - The country of the prev scope.
		# root - The country of the root scope.
		# TAG - A hard-coded country tag such as GER or ENG.
}

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

state_event is commonly used in scenarios where event logic needs to be bound to a specific state rather than a country, such as occupation events, resource conflicts, and regional uprisings. When triggered within a STATE scope, it allows precise control over event ownership. The trigger_for field enables the event to be delivered to the correct party even when multiple countries share the same state (such as when an occupying force differs from the owner), making it especially suitable for mods related to occupation and resistance systems.

# Send a warning event to the country controlling a state when resistance exceeds threshold
every_controlled_state = {
    limit = {
        has_active_resistance = yes
        resistance_count_trigger > 50
    }
    state_event = {
        id = resistance.10
        days = 3
        trigger_for = controller
    }
}

Synergy

[has_active_resistance](/wiki/trigger/has_active_resistance): Commonly serves as a precondition for triggering state_event, checking whether active resistance exists in a state to avoid meaningless event triggers.
[compliance](/wiki/trigger/compliance): Checks compliance thresholds in event trigger conditions, working with state_event to implement narrative event chains with phased compliance changes.
[add_resistance](/wiki/effect/add_resistance): Frequently used in the option outcomes of state_event, adjusting state resistance values based on player choices to form a closed loop of "event → choice → state change."
[every_controlled_state](/wiki/effect/every_controlled_state): Serves as an outer loop to iterate through states, paired with state_event to batch-trigger events on all qualifying states one by one.

Common Pitfalls

Overlooking scope causes event failure to trigger: When using state_event in a COUNTRY scope without specifying trigger_for, the event's actual ownership becomes unclear; conversely, within a STATE scope you must ensure the current scope is indeed a state and not a country. Confusing the two will result in silent event failure with no error message.
Mixing random as both delay and conditional effect block: random = 6 denotes a random hour delay, whereas random = { chance = 50 ... } is a probability-based conditional effect block. These two syntaxes have completely different semantics, and mixing them indiscriminately in the same event will cause difficult-to-debug logic errors.

effect · state_event