wow-api-combat

战斗 API（Retail — Patch 12.0.0）

WoW Retail 中所有战斗相关 API 的综合参考。重要：战斗日志系统在 12.0.0 中发生了根本性变化。 插件不再能使用 COMBAT_LOG_EVENT_UNFILTERED。

来源： https://warcraft.wiki.gg/wiki/World_of_Warcraft_API 截至： Patch 12.0.0（Build 65655）— 2026 年 1 月 28 日 范围： 仅限 Retail。

重要：12.0.0 中的战斗日志变更

插件不再能使用 COMBAT_LOG_EVENT_UNFILTERED（CLEU）。

• 被污染的（插件）代码无法使用 CombatLogGetCurrentEventInfo()
• 旧的 COMBAT_LOG_EVENT 事件也无法使用
• 战斗日志聊天标签页中的消息现在是 KStrings（无法解析的转义序列）
• 伤害统计等插件必须使用 C_DamageMeter 或内置系统
• 新增了 COMBAT_LOG_EVENT_INTERNAL_UNFILTERED，但仅限 Blizzard 代码使用

新的战斗日志事件（面向插件）

事件	描述
COMBAT_LOG_MESSAGE	格式化后的战斗日志消息（仅显示文本）
COMBAT_LOG_ENTRIES_CLEARED	已清除战斗日志条目
COMBAT_LOG_APPLY_FILTER_SETTINGS	筛选设置已更改
COMBAT_LOG_REFILTER_ENTRIES	需要重新筛选条目
COMBAT_LOG_MESSAGE_LIMIT_CHANGED	消息上限已更改

---

范围

此技能涵盖：

• 战斗日志 — 新的 12.0.0 战斗日志系统、COMBAT_LOG_MESSAGE
• C_DamageMeter — 内置伤害／治疗统计系统
• 仇恨 — UnitThreatSituation、UnitDetailedThreatSituation
• C_LossOfControl — 失控状态追踪
• C_CombatText — 浮动战斗文字
• C_CombatAudioAlert — 战斗音频警报系统（无障碍功能）
• C_Secrets / C_CurveUtil / C_DurationUtil — 战斗数据的秘密值处理
• 遭遇战事件 — ENCOUNTER_STATE_CHANGED、ENCOUNTER_WARNING、时间线事件
• 观战者／解说员 — 用于观战模式的 C_Commentator

---

C_DamageMeter — 内置伤害统计

于 12.0.0 中新增。提供官方伤害／治疗统计数据，无需解析战斗日志。

函数

函数	返回值	描述
C_DamageMeter.GetCurrentSessionID()	sessionID	当前战斗会话
C_DamageMeter.GetSessions()	sessions	所有可用会话
C_DamageMeter.GetSessionInfo(sessionID)	sessionInfo	会话详情
C_DamageMeter.GetPlayerData(sessionID, unitGUID)	playerData	玩家伤害／治疗数据
C_DamageMeter.GetPartyData(sessionID)	partyData	所有队伍／团队数据
C_DamageMeter.ResetSessions()	—	清除所有会话

事件

事件	描述
DAMAGE_METER_COMBAT_SESSION_UPDATED	会话数据已更新
DAMAGE_METER_CURRENT_SESSION_UPDATED	当前会话已更改
DAMAGE_METER_RESET	会话已清除

模式：读取伤害统计数据

local frame = CreateFrame("Frame")
frame:RegisterEvent("DAMAGE_METER_COMBAT_SESSION_UPDATED")
frame:SetScript("OnEvent", function(self, event)
    local sessionID = C_DamageMeter.GetCurrentSessionID()
    if sessionID then
        local partyData = C_DamageMeter.GetPartyData(sessionID)
        -- partyData contains per-player damage/healing totals
    end
end)

---

仇恨 API

仇恨函数

函数	返回值	描述
UnitThreatSituation(unit [, target])	status	仇恨状态（0-3）
UnitDetailedThreatSituation(unit, target)	isTanking, status, scaledPercent, rawPercent, threatValue	详细仇恨信息
UnitThreatPercentageOfLead(unit, target)	percent	仇恨领先百分比

仇恨状态值

值	含义
0	不在仇恨列表中
1	在仇恨列表中，未坦怪且仇恨值不是最高
2	在仇恨列表中，未坦怪但仇恨值最高
3	正在坦怪（仇恨最高且已获得仇恨）
nil	单位不存在或没有仇恨列表

注意： 在 12.0.0 的副本中，非玩家单位的仇恨值可能是秘密值。请直接将这些值传递给 UI 小部件。

---

C_LossOfControl

跟踪玩家受到的群体控制效果。

函数	返回值	描述
C_LossOfControl.GetActiveLossOfControlData(index)	data	当前生效的 CC 效果数据
C_LossOfControl.GetActiveLossOfControlDataByUnit(unit, index)	data	单位的 CC 数据
C_LossOfControl.GetActiveLossOfControlDataCount()	count	当前生效的 CC 效果数量
C_LossOfControl.GetActiveLossOfControlDataCountByUnit(unit)	count	单位的 CC 效果数量

失控数据字段

• locType — CC 类型（STUN、FEAR、SILENCE 等）
• spellID — 导致 CC 的法术
• displayText — 本地化显示文本
• iconTexture — 法术图标
• startTime — CC 开始时间
• timeRemaining — 剩余持续时间（在 12.0.0 中可能是 DurationObject）
• duration — 总持续时间
• lockoutSchool — 被锁定的法术学派（适用于 SCHOOL_INTERRUPT 类型）
• priority — 显示优先级

事件

事件	描述
LOSS_OF_CONTROL_ADDED	施加了新的 CC 效果
LOSS_OF_CONTROL_UPDATE	CC 效果已更新

---

C_CombatText — 浮动战斗文本

函数	返回值	描述
C_CombatText.IsCombatTextEnabled()	enabled	是否启用 FCT？

战斗文本 CVar

CVar	描述
enableFloatingCombatText	启用/禁用 FCT
floatingCombatTextCombatDamage	显示伤害
floatingCombatTextCombatHealing	显示治疗
floatingCombatTextCombatDamageStyle	伤害显示样式

---

C_CombatAudioAlert — 战斗音频警报

新增的无障碍系统，可为战斗事件提供音频提示。它取代了以前需要解析战斗日志的部分功能。

函数	返回值	描述
C_CombatAudioAlert.IsEnabled()	enabled	是否启用音频警报？
C_CombatAudioAlert.SetEnabled(enabled)	—	启用/禁用

---

战斗数据的秘密值处理

C_Secrets — 秘密值判断函数

函数	返回值	描述
C_Secrets.ShouldUnitHealthBeSecret(unit)	isSecret	此单位的生命值是否为秘密值？
C_Secrets.ShouldUnitPowerBeSecret(unit [, powerType])	isSecret	能量值是否为秘密值？
C_Secrets.ShouldUnitPowerMaxBeSecret(unit [, powerType])	isSecret	最大能量值是否为秘密值？
C_Secrets.ShouldUnitSpellCastBeSecret(unit, spellIdentifier)	isSpellCastSecret	法术施法是否为秘密值？
C_Secrets.ShouldUnitSpellCastingBeSecret(unit)	isSpellCastingSecret	所有施法信息是否均为秘密值？

C_CurveUtil — 秘密值曲线

由于插件无法对秘密值进行数学运算，曲线可用于将秘密数值映射为视觉输出。

函数	返回值	描述
C_CurveUtil.CreateCurve()	curveObject	创建数值曲线
C_CurveUtil.CreateColorCurve()	colorCurveObject	创建颜色曲线

模式：不检查数值，将生命值映射为颜色

-- Create a color curve: green at 100% → red at 0%
local colorCurve = C_CurveUtil.CreateColorCurve()
-- Configure curve points (green → yellow → red)

local healthBar = CreateFrame("StatusBar", nil, parent)
local hp = UnitHealth(unit)         -- SECRET in instances
local maxHp = UnitHealthMax(unit)   -- SECRET in instances
healthBar:SetMinMaxValues(0, maxHp) -- widgets accept secrets
healthBar:SetValue(hp)              -- widgets accept secrets
-- Color is set by curve without addon seeing the actual number

C_DurationUtil — 持续时间对象

函数	返回值	描述
C_DurationUtil.CreateDuration()	durationObject	创建持续时间对象

-- Use DurationObject for cooldown display
local cooldown = CreateFrame("Cooldown", nil, parent, "CooldownFrameTemplate")
local duration = C_DurationUtil.CreateDuration()
cooldown:SetCooldownFromDurationObject(duration)

---

遭遇战事件

12.0.0 新增，这些事件取代了插件通过解析战斗日志跟踪遭遇战状态的做法。

事件	描述
ENCOUNTER_STATE_CHANGED	遭遇战状态发生变化（开怪、团灭、击杀）
ENCOUNTER_WARNING	内置遭遇战警报系统
ENCOUNTER_TIMELINE_EVENT_START	时间线事件开始
ENCOUNTER_TIMELINE_EVENT_UPDATE	时间线事件更新
ENCOUNTER_TIMELINE_EVENT_END	时间线事件结束

其他战斗事件

事件	描述
PLAYER_REGEN_DISABLED	进入战斗
PLAYER_REGEN_ENABLED	脱离战斗
PLAYER_ENTER_COMBAT	玩家开始自动攻击
PLAYER_LEAVE_COMBAT	玩家停止自动攻击
UNIT_COMBAT	单位受到／造成伤害或治疗
UNIT_THREAT_SITUATION_UPDATE	仇恨状态已更改
UNIT_THREAT_LIST_UPDATE	仇恨列表已更新
PLAYER_DEAD	玩家死亡
PLAYER_ALIVE	玩家释放灵魂
PLAYER_UNGHOST	玩家复活

---

解说员／观战者 API

C_Commentator 提供用于电竞观赛的观战模式功能。

主要函数

函数	返回值	描述
C_Commentator.IsSpectating()	isSpectating	是否处于观战模式？
C_Commentator.GetAllPlayerData(teamIndex)	playerData	队伍的所有玩家数据
C_Commentator.GetPlayerData(teamIndex, playerIndex)	data	特定玩家的数据
C_Commentator.GetTeamColorAndName(teamIndex)	color, name	队伍信息
C_Commentator.GetMatchDuration()	duration	比赛已进行的时间
C_Commentator.StartWargame(...)	—	开始一场战争游戏
C_Commentator.UpdatePlayerInfo()	—	刷新玩家数据

---

常见模式

检查战斗状态

local function IsInCombat()
    return UnitAffectingCombat("player")
end

-- Or use the lockdown check for secure frame operations
if InCombatLockdown() then
    print("In combat lockdown — restricted operations blocked")
end

根据仇恨为姓名板着色

-- Note: In 12.0.0 instances, threat values may be secret
local status = UnitThreatSituation("player", "target")
if not issecretvalue(status) then
    if status == 3 then
        -- Tanking — show red
    elseif status == 2 then
        -- Pulling aggro — show orange
    else
        -- Safe — show green
    end
end

显示失控状态

local frame = CreateFrame("Frame")
frame:RegisterEvent("LOSS_OF_CONTROL_ADDED")
frame:RegisterEvent("LOSS_OF_CONTROL_UPDATE")
frame:SetScript("OnEvent", function()
    local count = C_LossOfControl.GetActiveLossOfControlDataCount()
    for i = 1, count do
        local data = C_LossOfControl.GetActiveLossOfControlData(i)
        if data then
            print(data.displayText, data.timeRemaining)
        end
    end
end)

---

注意事项与限制

1. CLEU 已移除 — 不要注册 COMBAT_LOG_EVENT_UNFILTERED。在 12.0.0 中，插件代码不会收到此事件。
2. 无法解析战斗记录 — 受污染的代码无法使用 CombatLogGetCurrentEventInfo()。
3. KString 聊天消息 — 战斗记录聊天标签页的输出现在是无法解析的 KStrings。
4. 生命值是机密值 — 在副本中，UnitHealth() 会返回机密值。请直接将其传入 StatusBar:SetValue()。
5. 使用 DurationObjects — 不要手动计算冷却时间。请使用 C_DurationUtil.CreateDuration() 和 Cooldown:SetCooldownFromDurationObject()。
6. 内置伤害统计表 — 使用 C_DamageMeter 获取伤害／治疗数据，而不要解析战斗事件。
7. SendAddonMessage 已被拦截 — 无法在副本中发送插件消息。首领模块插件必须使用新的遭遇事件模式。
8. 单位身份受限 — 在战斗中的副本里，UnitName()、UnitClass() 可能会对敌方单位返回机密值。
9. 副本中的仇恨 — 仇恨值可能是机密值。直接传给控件，不要用它们进行分支判断。
10. 设计理念 — 插件不应在战斗中提供竞争优势。暴雪为大多数受限功能提供了内置替代方案。