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.
}

实战 · 配合 · 坑

实战内容由 AI 生成,并已对照 vanilla 命令词表校验 —— 请当作起点而非权威依据。上方的定义节才是游戏自带文档原文。

实战用法

unit_leader_event 常见于将领成长、战役剧情或特殊 trait 解锁系统中，例如当某位将领完成特定任务或达到技能阈值时，向其宿主国家触发一个专属剧情事件。典型场景是在将领获得某 trait 后延迟触发一个对话事件，让玩家在选项中选择该将领的后续发展方向。

# 当将领获得 trait 后，延迟触发事件
add_unit_leader_trait = brilliant_strategist
unit_leader_event = {
    id = my_mod.42
    days = 3
    random_hours = 24
}

配合关系

[has_trait](/wiki/trigger/has_trait)：在事件的 trigger 块中检测将领是否持有特定 trait，从而决定是否执行该 effect，使事件触发逻辑更精准。
[add_unit_leader_trait](/wiki/effect/add_unit_leader_trait)：常在同一效果块中先为将领添加 trait，再紧接着触发事件做剧情呈现，形成"动作→反馈"的完整链条。
[add_skill_level](/wiki/effect/add_skill_level)：与技能提升搭配，先提升将领技能等级，再用本 effect 触发成就或晋升相关事件。
[set_character_flag](/wiki/effect/set_character_flag)：在事件触发前设置 flag 防止重复触发，避免同一事件在多个游戏周期内反复弹出。

常见坑

Scope 写错导致静默失效：本 effect 必须在 CHARACTER scope 下调用，若在 COUNTRY 或 STATE scope 中直接使用，游戏不会报错但事件不会触发，排查时极难发现。
误以为事件 scope 是将领本身：被触发的事件实际属于宿主国家（owner country）而非将领，因此事件内部的 FROM 指向不一定是该将领，若需在事件中操作将领需通过额外手段（如 flag 或 saved 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

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

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.
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.

effect · unit_leader_event