wow-api-combat（WOW API combat 文档）

Combat API (Retail — Patch 12.0.0)

Comprehensive reference for all combat-related APIs in WoW Retail. Critical: The combat log system was fundamentally changed in 12.0.0. COMBAT_LOG_EVENT_UNFILTERED is no longer available to addons.

Source: https://warcraft.wiki.gg/wiki/World_of_Warcraft_API Current as of: Patch 12.0.0 (Build 65655) — January 28, 2026 Scope: Retail only.

CRITICAL: Combat Log Changes in 12.0.0

COMBAT_LOG_EVENT_UNFILTERED (CLEU) is NO LONGER available to addons.

• CombatLogGetCurrentEventInfo() is unavailable to tainted (addon) code
• The old COMBAT_LOG_EVENT event is also unavailable
• Combat log chat tab messages are now KStrings (unparseable escape sequences)
• Addons like damage meters must use C_DamageMeter or the built-in system
• A new COMBAT_LOG_EVENT_INTERNAL_UNFILTERED exists but is restricted to Blizzard code

New Combat Log Events (Addon-Facing)

Scope

This skill covers:

• Combat Log — New 12.0.0 combat log system, COMBAT_LOG_MESSAGE
• C_DamageMeter — Built-in damage/healing meter system
• Threat — UnitThreatSituation, UnitDetailedThreatSituation
• C_LossOfControl — Loss of control tracking
• C_CombatText — Floating combat text
• C_CombatAudioAlert — Combat audio alert system (accessibility)
• C_Secrets / C_CurveUtil / C_DurationUtil — Secret value handling for combat data
• Encounter Events — ENCOUNTER_STATE_CHANGED, ENCOUNTER_WARNING, timeline events
• Spectator/Commentator — C_Commentator for spectator mode

C_DamageMeter — Built-in Damage Meter

New in 12.0.0. Provides official damage/healing meter data without needing combat log parsing.

Functions

Events

Pattern: Reading Damage Meter Data

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)

Threat API

Threat Functions

Threat Status Values

Note: In 12.0.0 instances, threat values for non-player units may be secret values. Pass them directly to UI widgets.

C_LossOfControl

Tracks crowd control effects on the player.

Loss of Control Data Fields

• locType — Type of CC (STUN, FEAR, SILENCE, etc.)
• spellID — Spell causing the CC
• displayText — Localized display text
• iconTexture — Spell icon
• startTime — When CC started
• timeRemaining — Duration remaining (may be DurationObject in 12.0.0)
• duration — Total duration
• lockoutSchool — School lockout (for SCHOOL_INTERRUPT type)
• priority — Display priority

Events

C_CombatText — Floating Combat Text

Combat Text CVars

C_CombatAudioAlert — Combat Audio Alerts

New accessibility system providing audio cues for combat events. Replaces some functionality that previously required combat log parsing.

Secret Value Handling for Combat Data

C_Secrets — Secret Predicates

C_CurveUtil — Curves for Secret Values

Since addons cannot do math on secret values, Curves allow mapping secret numbers to visual output.

Pattern: Health-to-Color Without Inspecting Value

-- 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 — Duration Objects

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

Encounter Events

New in 12.0.0, these replace addon combat log parsing for encounter state tracking.

Other Combat Events

Commentator / Spectator API

C_Commentator provides spectator mode functionality for esports viewing.

Key Functions

Common Patterns

Check Combat State

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

Threat-Based Nameplate Coloring

-- 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

Loss of Control Display

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)

Gotchas & Restrictions

1. CLEU is GONE — Do NOT register for COMBAT_LOG_EVENT_UNFILTERED. It will not fire for addon code in 12.0.0.
2. No combat log parsing — CombatLogGetCurrentEventInfo() is unavailable to tainted code.
3. KString chat messages — Combat log chat tab output is now KStrings that cannot be parsed.
4. Health is secret — UnitHealth() returns secret values in instances. Pass directly to StatusBar:SetValue().
5. Use DurationObjects — Don't do manual cooldown math. Use C_DurationUtil.CreateDuration() and Cooldown:SetCooldownFromDurationObject().
6. Built-in damage meter — Use C_DamageMeter for damage/healing data instead of parsing combat events.
7. SendAddonMessage blocked — Cannot send addon messages in instances. Boss mod addons must use new encounter event patterns.
8. Unit identity restricted — UnitName(), UnitClass() may return secrets for enemy units in instances during combat.
9. Threat in instances — Threat values may be secret. Pass to widgets directly; don't branch on them.
10. Design philosophy — Addons should NOT provide competitive advantage in combat. Blizzard provides built-in replacements for most restricted functionality.