effect · `gain_xp`

Definition

Supported scope:CHARACTER
Supported target:any

Description

Grant experience to the scoped in unit leader. Cannot be used to remove experience.
The unit leader is promoted to the next skill level if applicable.
Example:
gain_xp = 5

实战 · 配合 · 坑

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

实战用法

gain_xp 常用于事件奖励场景，例如将领完成特定任务（赢得战役、完成训练事件）后给予经验奖励，使其更快升级。也可在焦点树或决策中奖励玩家培养的精英将领，配合其他 buff 强化角色成长感。

# 某将领完成战役任务事件后获得经验
country_event = {
    id = my_mod.1
    option = {
        name = my_mod.1.a
        # 令该国的某位将领获得经验
        random_army_leader = {
            limit = { is_corps_commander = yes }
            gain_xp = 10
        }
    }
}

配合关系

[skill](/wiki/trigger/skill) — 在给予经验前用于检查将领当前技能等级，避免对已满级将领浪费事件触发条件。
[add_skill_level](/wiki/effect/add_skill_level) — 当需要直接跨越多个等级时与 gain_xp 分工：前者精确控制经验积累，后者直接拔升等级，两者目的相近但机制不同，按需搭配。
[add_trait](/wiki/effect/add_trait) — 经验增长触发升级后，同步添加特质来模拟将领因战功获得技能专长的叙事效果。
[is_corps_commander](/wiki/trigger/is_corps_commander) / [is_field_marshal](/wiki/trigger/is_field_marshal) — 用于 limit 块筛选正确的将领 scope，确保经验只授予预期角色类型。

常见坑

不能用于扣除经验：该指令只能增加经验值，传入负数并不会按预期减少经验，若需降低将领能力应改用 [add_skill_level](/wiki/effect/add_skill_level) 配合负值或直接替换特质。
scope 必须是 CHARACTER：在国家 scope 下直接调用 gain_xp 会导致脚本报错或静默失效，必须先通过 random_army_leader、specific_character 等方式进入正确的角色 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

gain_xp is commonly used in event reward scenarios, such as granting experience to a general after completing a specific mission (winning a campaign, completing a training event) to allow faster leveling. It can also be used in focus trees or decisions to reward elite generals trained by the player, combined with other buffs to enhance character progression immersion.

# General gains experience after completing a campaign mission event
country_event = {
    id = my_mod.1
    option = {
        name = my_mod.1.a
        # Grant experience to a general in this country
        random_army_leader = {
            limit = { is_corps_commander = yes }
            gain_xp = 10
        }
    }
}

Synergy

[skill](/wiki/trigger/skill) — Check the general's current skill level before granting experience to avoid wasting event triggers on already maxed-out generals.
[add_skill_level](/wiki/effect/add_skill_level) — When needing to jump multiple levels at once, divide responsibilities between gain_xp and this effect: the latter provides precise experience accumulation control, the former directly raises levels. Their purposes are similar but mechanics differ; use as needed.
[add_trait](/wiki/effect/add_trait) — After experience growth triggers a level-up, simultaneously add traits to simulate the narrative effect of generals acquiring skill expertise through combat achievements.
[is_corps_commander](/wiki/trigger/is_corps_commander) / [is_field_marshal](/wiki/trigger/is_field_marshal) — Use in limit blocks to filter the correct general scope, ensuring experience is only granted to intended character types.

Common Pitfalls

Cannot be used to deduct experience: This command only adds experience; passing negative values will not reduce experience as expected. If you need to lower a general's abilities, use [add_skill_level](/wiki/effect/add_skill_level) with negative values instead or directly replace traits.
Scope must be CHARACTER: Calling gain_xp directly under a country scope causes script errors or silent failures. You must first enter the correct character scope via random_army_leader, specific_character, or similar methods before calling it.

effect · gain_xp