Wiki

effect · unit_leader_event

Definition

  • Supported scope:CHARACTER
  • Supported target:none

Description

Fires a unit leader event for owner country.
Example:
unit_leader_event = {
	id = mtg_exile_leader_added.1 # 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 = mtg_exile_leader_added.1.t # Manually specify which tooltip to use for this effect.
}

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

unit_leader_event is commonly used in general progression systems, campaign narratives, or special trait unlock mechanics. For example, triggering an exclusive event for a general's nation when that general completes a specific objective or reaches a skill threshold. A typical scenario involves delaying an event trigger after a general acquires a trait, allowing the player to choose the general's development direction through event options.

When a general gains a trait, trigger an event with a delay:

add_unit_leader_trait = brilliant_strategist
unit_leader_event = {
    id = my_mod.42
    days = 3
    random_hours = 24
}

Synergy

  • [has_trait](/wiki/trigger/has_trait): Check whether a general possesses a specific trait within the event's trigger block to determine execution, making event logic more precise.
  • [add_unit_leader_trait](/wiki/effect/add_unit_leader_trait): Often used in the same effect block to add a trait first, then immediately trigger an event for narrative presentation, forming a complete "action → feedback" chain.
  • [add_skill_level](/wiki/effect/add_skill_level): Pair with skill increases by raising the general's skill level first, then use this effect to trigger achievement or promotion-related events.
  • [set_character_flag](/wiki/effect/set_character_flag): Set flags before event triggering to prevent duplicate triggers, avoiding the same event firing repeatedly across multiple game cycles.

Common Pitfalls

  1. Silent failure from incorrect scope: This effect must be called under the CHARACTER scope. If used directly in COUNTRY or STATE scope, the game will not report an error but the event will not trigger, making it extremely difficult to diagnose.
  2. Mistaking event scope for the general itself: The triggered event actually belongs to the general's nation (owner country) rather than the general, so FROM within the event does not necessarily reference the general. To manipulate the general within an event, additional methods (such as flags or saved scopes) must be used to pass the character.