effect · `raid_add_unit_experience`

Definition

Supported scope:RAID_INSTANCE
Supported target:THIS, ROOT, PREV, FROM, OWNER, CONTROLLER, OCCUPIED, CAPITAL

Description

Give experience to the units performing the raid (raid instance scope).

Will give experience to any type of unit assigned to the raid, e.g. divisions or air wings.
The value defines the progress towards the max level, e.g. 0.2 = gain 20% of the experience needed to reach max level.

Can use either an explicit value or a variable

ex.
raid_add_unit_experience = 0.2

实战 · 配合 · 坑

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

实战用法

在设计自定义突袭(Raid)玩法的 mod 中，当突袭任务达成特定里程碑（例如成功摧毁目标、完成指定回合数）时，可用此 effect 奖励参与部队的经验值，从而形成"打得越好、部队成长越快"的正向反馈。注意经验值以"距满级所需总量的比例"表示，因此可灵活按难度档位调整奖励幅度。

# 突袭任务成功结算时奖励参与单位经验
RAID_INSTANCE = {
    # 根据是否达成优秀评级给予不同奖励
    if = {
        limit = {
            hidden_trigger = { ... }   # 检查突袭达成条件
        }
        raid_add_unit_experience = 0.3  # 奖励30%进度的经验
    }
    else = {
        raid_add_unit_experience = 0.1  # 基础奖励10%进度
    }
}

配合关系

[add_raid_history_entry](/wiki/effect/add_raid_history_entry)：在给予经验的同时记录一条突袭历史日志，便于追踪"因何获得经验"，两者常共同出现在同一结算块中。
[raid_damage_units](/wiki/effect/raid_damage_units)：突袭往往伴随损耗，先用此命令对参与单位造成损伤，再用经验奖励作为"代价换成长"的补偿，逻辑上形成完整的战斗结算闭环。
[hidden_trigger](/wiki/trigger/hidden_trigger)：用于在授予经验前做隐式条件检查（如突袭是否成功、是否满足最低参与回合），避免无条件发放经验破坏平衡。
[meta_trigger](/wiki/trigger/meta_trigger)：当需要动态传参（如根据突袭等级变量决定奖励比例）时，配合 meta_trigger 构造参数化条件判断，使经验奖励量更具弹性。

常见坑

直接在 country/state scope 下调用：此 effect 仅在 RAID_INSTANCE scope 内有效，若误写在国家或省份 scope 下脚本会静默失效且不报错，需确保调用链已进入突袭实例 scope。
误将值理解为绝对经验量：传入的数值是"到达满级所需经验的比例"而非固定数值，填写 1.0 意味着直接满级——新手常填入与普通 add_experience 相同量级的大数，导致所有参与单位瞬间满级。

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

In custom Raid gameplay mods, when a raid mission reaches specific milestones (such as successfully destroying targets or completing designated rounds), use this effect to reward participating units with experience, creating a positive feedback loop of "better performance leads to faster unit growth". Note that experience is expressed as a "ratio of total experience required to reach max level", allowing flexible adjustment of reward magnitude based on difficulty tiers.

# Reward participating units with experience upon raid mission settlement
RAID_INSTANCE = {
    # Grant different rewards based on whether excellent rating is achieved
    if = {
        limit = {
            hidden_trigger = { ... }   # Check raid completion conditions
        }
        raid_add_unit_experience = 0.3  # Reward 30% progress experience
    }
    else = {
        raid_add_unit_experience = 0.1  # Base reward 10% progress
    }
}

Synergy

[add_raid_history_entry](/wiki/effect/add_raid_history_entry): Records a raid history log entry while granting experience, making it easy to track "why experience was gained". Both effects commonly appear together in the same settlement block.
[raid_damage_units](/wiki/effect/raid_damage_units): Raids typically involve casualties. First use this command to inflict damage on participating units, then use experience rewards as compensation for "paying a price for growth", logically forming a complete combat settlement loop.
[hidden_trigger](/wiki/trigger/hidden_trigger): Used for implicit condition checks before awarding experience (such as whether the raid succeeded or met minimum participation rounds), preventing unconditional experience distribution that breaks balance.
[meta_trigger](/wiki/trigger/meta_trigger): When dynamic parameter passing is needed (such as determining reward ratios based on raid level variables), combine with meta_trigger to construct parameterized condition judgments, making experience rewards more flexible.

Common Pitfalls

Calling directly under country/state scope: This effect only works within RAID_INSTANCE scope. If mistakenly written under country or state scope, the script silently fails without error reporting. Ensure the call chain has entered the raid instance scope.
Misinterpreting the value as absolute experience amount: The input value represents "the ratio of experience required to reach max level" rather than a fixed amount. Setting 1.0 means directly reaching max level—beginners often input the same magnitude as regular add_experience, causing all participating units to instantly max level.

effect · raid_add_unit_experience