effect · `add_raid_history_entry`

Definition

Supported scope:RAID_INSTANCE
Supported target:none

Description

Add history entry to a raid.
Example:
add_raid_history_entry = yes/no

实战 · 配合 · 坑

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

实战用法

在涉及突袭（Raid）玩法的 mod 中，当需要记录某次突袭任务的关键事件节点（如成功击溃守军、完成掠夺等）时，可以在对应的 RAID_INSTANCE scope 内调用此 effect，以便后续通过日志或 UI 追踪突袭进程。例如在突袭阶段结束时写入历史条目：

raid_event = {
    id = my_raid.10
    hidden = yes
    immediate = {
        add_raid_history_entry = yes
    }
}

配合关系

[raid_add_unit_experience](/wiki/effect/raid_add_unit_experience)：突袭完成后往往同时记录历史并奖励参战单位经验，两者常在同一执行块中先后触发。
[raid_damage_units](/wiki/effect/raid_damage_units)：在造成单位损伤后紧接着写入历史条目，用于记录战损事件，使突袭记录更完整。
[hidden_trigger](/wiki/trigger/hidden_trigger)：在写入历史条目之前，用隐藏触发器校验突袭当前状态是否满足记录条件，避免无效或重复写入。

常见坑

scope 错误：此 effect 只能在 RAID_INSTANCE scope 下调用，若在国家或省份 scope 中直接使用会静默失效甚至报错，务必确认已通过正确的 scope 切换进入突袭实例。
yes/no 滥用：新手容易以为传入 no 可以"撤销"历史条目，但该参数实际上只控制是否执行写入动作，历史记录一旦写入通常无法通过再次调用来删除或回滚。

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 mods involving Raid gameplay, when you need to record critical event milestones for a raid mission (such as successfully routing defenders or completing plunder), you can invoke this effect within the corresponding RAID_INSTANCE scope to enable subsequent tracking of raid progress through logs or UI. For example, writing a history entry at the conclusion of a raid phase:

raid_event = {
    id = my_raid.10
    hidden = yes
    immediate = {
        add_raid_history_entry = yes
    }
}

Synergy

[raid_add_unit_experience](/wiki/effect/raid_add_unit_experience): Upon raid completion, unit experience rewards are typically logged in history simultaneously, with both effects often triggered sequentially within the same execution block.
[raid_damage_units](/wiki/effect/raid_damage_units): Immediately after inflicting unit casualties, write a history entry to record combat losses, making the raid record more comprehensive.
[hidden_trigger](/wiki/trigger/hidden_trigger): Before writing a history entry, use hidden triggers to validate whether the raid's current state meets recording conditions, preventing invalid or duplicate writes.

Common Pitfalls

Scope errors: This effect can only be invoked within RAID_INSTANCE scope. Direct use in country or province scopes will silently fail or throw errors. Always confirm you have properly switched scope into the raid instance.
yes/no misuse: Beginners often assume passing no can "undo" a history entry, but this parameter merely controls whether the write action executes. Once a history record is written, it typically cannot be deleted or rolled back through subsequent calls.

effect · add_raid_history_entry