effect · `random_unit_leader`

Definition

Supported scope:COUNTRY
Supported target:none

Description

Executes children effects on a random Unit Leader of the country in scope, that fulfills the \"limit\" trigger.
tooltip=key can be added to override tooltip title.
ex: GER = {
  random_unit_leader = {
	tooltip = my_loc_key # Optional
	include_invisible = yes # Optional - default = no
    ... character scope effects ...
  }
}

实战 · 配合 · 坑

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

实战用法

常用于需要对国家内某位随机将领施加效果的场景，例如给符合条件的将领随机添加特质、提升技能，或在事件中奖励/惩罚某类将领。典型场景包括：MOD 中的战时随机事件（随机一名步兵将领获得战斗经验）、战役剧情触发（随机一名海军将领被晋升）等。

# 给德国一名随机拥有 "攻击型" 特质的将领额外添加一个特质
GER = {
    random_unit_leader = {
        limit = {
            has_trait = brilliant_strategist
            is_field_marshal = no
        }
        add_trait = aggressive_assaulter
        add_skill_level = 1
    }
}

配合关系

has_trait：在 limit 块中筛选具备特定特质的将领，确保效果只施加给目标群体中符合条件的人。
is_field_marshal：在 limit 中区分陆军元帅与军长/军团长，避免错误地选中高级将领。
add_unit_leader_trait：与本命令配合，是在角色 scope 下给随机将领增加特质的最常用效果之一。
add_skill_level：搭配使用可在同一个 random_unit_leader 块内同时完成特质与技能值的修改，减少重复调用。

常见坑

忘记加 limit 导致选中不期望的将领：若省略 limit 块，游戏会从该国所有单位领袖（包括海军将领、空军将领）中随机挑选，而非仅限于陆军将领，容易产生非预期结果；务必用 is_corps_commander、is_field_marshal、is_navy_leader 等触发器精确限定范围。
在非 COUNTRY scope 下调用：random_unit_leader 仅在国家 scope 下有效，若在州（state）或角色（character）scope 中直接调用会导致脚本报错或静默失效，需先用 PREV/ROOT 或显式国家 tag 切换回国家 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

Commonly used when you need to apply effects to a random unit leader within a country — for example, randomly granting a qualifying leader a new trait, boosting their skill level, or rewarding/penalizing a certain type of leader through an event. Typical scenarios include: wartime random events in mods (a random infantry general gains combat experience), or campaign story triggers (a random naval leader receives a promotion).

# Grant a random German general who has the "brilliant_strategist" trait an additional trait
GER = {
    random_unit_leader = {
        limit = {
            has_trait = brilliant_strategist
            is_field_marshal = no
        }
        add_trait = aggressive_assaulter
        add_skill_level = 1
    }
}

Synergy

has_trait: Used inside a limit block to filter for leaders with a specific trait, ensuring the effect only applies to qualifying members of the target pool.
is_field_marshal: Used inside limit to distinguish field marshals from corps commanders and army commanders, preventing high-ranking leaders from being selected unintentionally.
add_unit_leader_trait: Works hand-in-hand with this command and is one of the most common effects for adding a trait to a randomly selected leader within a character scope.
add_skill_level: Can be combined in the same random_unit_leader block to modify both traits and skill values in a single pass, avoiding redundant calls.

Common Pitfalls

Omitting limit and selecting unintended leaders: If the limit block is left out, the game will randomly pick from all unit leaders in the country — including naval and air leaders — rather than restricting to land generals. This easily produces unintended results. Always use triggers such as is_corps_commander, is_field_marshal, and is_navy_leader to precisely narrow the selection pool.
Calling the effect outside a COUNTRY scope: random_unit_leader is only valid within a country scope. Calling it directly inside a state or character scope will cause a script error or silent failure. You must first switch back to a country scope using PREV/ROOT or an explicit country tag before invoking it.

effect · random_unit_leader