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)

Event Description

COMBAT_LOG_MESSAGE

Formatted combat log messages (display text only)

COMBAT_LOG_ENTRIES_CLEARED

Combat log entries cleared

COMBAT_LOG_APPLY_FILTER_SETTINGS

Filter settings changed

COMBAT_LOG_REFILTER_ENTRIES

Entries need refiltering

COMBAT_LOG_MESSAGE_LIMIT_CHANGED

Message limit changed

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

Function Returns Description

C_DamageMeter.GetCurrentSessionID()

sessionID

Current combat session

C_DamageMeter.GetSessions()

sessions

All available sessions

C_DamageMeter.GetSessionInfo(sessionID)

sessionInfo

Session details

C_DamageMeter.GetPlayerData(sessionID, unitGUID)

playerData

Player's damage/healing

C_DamageMeter.GetPartyData(sessionID)

partyData

All party/raid data

C_DamageMeter.ResetSessions()

— Clear all sessions

Events

Event Description

DAMAGE_METER_COMBAT_SESSION_UPDATED

Session data updated

DAMAGE_METER_CURRENT_SESSION_UPDATED

Current session changed

DAMAGE_METER_RESET

Sessions cleared

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

Function Returns Description

UnitThreatSituation(unit [, target])

status

Threat status (0-3)

UnitDetailedThreatSituation(unit, target)

isTanking, status, scaledPercent, rawPercent, threatValue

Detailed threat info

UnitThreatPercentageOfLead(unit, target)

percent

Threat lead percentage

Threat Status Values

Value Meaning

0 Not on threat table

1 On threat table, not tanking, not highest

2 On threat table, not tanking, highest

3 Tanking (highest threat with aggro)

nil Unit doesn't exist or has no threat table

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.

Function Returns Description

C_LossOfControl.GetActiveLossOfControlData(index)

data

Active CC effect data

C_LossOfControl.GetActiveLossOfControlDataByUnit(unit, index)

data

CC data for unit

C_LossOfControl.GetActiveLossOfControlDataCount()

count

Number of active CC effects

C_LossOfControl.GetActiveLossOfControlDataCountByUnit(unit)

count

CC count for unit

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

Event Description

LOSS_OF_CONTROL_ADDED

New CC effect applied

LOSS_OF_CONTROL_UPDATE

CC effect updated

C_CombatText — Floating Combat Text

Function Returns Description

C_CombatText.IsCombatTextEnabled()

enabled

FCT enabled?

Combat Text CVars

CVar Description

enableFloatingCombatText

Enable/disable FCT

floatingCombatTextCombatDamage

Show damage

floatingCombatTextCombatHealing

Show healing

floatingCombatTextCombatDamageStyle

Damage display style

C_CombatAudioAlert — Combat Audio Alerts

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

Function Returns Description

C_CombatAudioAlert.IsEnabled()

enabled

Audio alerts enabled?

C_CombatAudioAlert.SetEnabled(enabled)

— Enable/disable

Secret Value Handling for Combat Data

C_Secrets — Secret Predicates

Function Returns Description

C_Secrets.ShouldUnitHealthBeSecret(unit)

isSecret

Is health secret for this unit?

C_Secrets.ShouldUnitPowerBeSecret(unit [, powerType])

isSecret

Is power secret?

C_Secrets.ShouldUnitPowerMaxBeSecret(unit [, powerType])

isSecret

Is max power secret?

C_Secrets.ShouldUnitSpellCastBeSecret(unit, spellIdentifier)

isSpellCastSecret

Is spell cast secret?

C_Secrets.ShouldUnitSpellCastingBeSecret(unit)

isSpellCastingSecret

Is all casting secret?

C_CurveUtil — Curves for Secret Values

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

Function Returns Description

C_CurveUtil.CreateCurve()

curveObject

Create a numeric curve

C_CurveUtil.CreateColorCurve()

colorCurveObject

Create a color curve

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

Function Returns Description

C_DurationUtil.CreateDuration()

durationObject

Create a duration object

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

Event Description

ENCOUNTER_STATE_CHANGED

Encounter state changed (pull, wipe, kill)

ENCOUNTER_WARNING

Built-in encounter warning system

ENCOUNTER_TIMELINE_EVENT_START

Timeline event started

ENCOUNTER_TIMELINE_EVENT_UPDATE

Timeline event updated

ENCOUNTER_TIMELINE_EVENT_END

Timeline event ended

Other Combat Events

Event Description

PLAYER_REGEN_DISABLED

Entering combat

PLAYER_REGEN_ENABLED

Leaving combat

PLAYER_ENTER_COMBAT

Player starts auto-attack

PLAYER_LEAVE_COMBAT

Player stops auto-attack

UNIT_COMBAT

Unit took/dealt damage or healing

UNIT_THREAT_SITUATION_UPDATE

Threat status changed

UNIT_THREAT_LIST_UPDATE

Threat table updated

PLAYER_DEAD

Player died

PLAYER_ALIVE

Player released spirit

PLAYER_UNGHOST

Player resurrected

Commentator / Spectator API

C_Commentator provides spectator mode functionality for esports viewing.

Key Functions

Function Returns Description

C_Commentator.IsSpectating()

isSpectating

In spectator mode?

C_Commentator.GetAllPlayerData(teamIndex)

playerData

All player data for team

C_Commentator.GetPlayerData(teamIndex, playerIndex)

data

Specific player data

C_Commentator.GetTeamColorAndName(teamIndex)

color, name

Team info

C_Commentator.GetMatchDuration()

duration

Match elapsed time

C_Commentator.StartWargame(...)

— Start a wargame

C_Commentator.UpdatePlayerInfo()

— Refresh player data

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

• CLEU is GONE — Do NOT register for COMBAT_LOG_EVENT_UNFILTERED . It will not fire for addon code in 12.0.0.

• No combat log parsing — CombatLogGetCurrentEventInfo() is unavailable to tainted code.

• KString chat messages — Combat log chat tab output is now KStrings that cannot be parsed.

• Health is secret — UnitHealth() returns secret values in instances. Pass directly to StatusBar:SetValue() .

• Use DurationObjects — Don't do manual cooldown math. Use C_DurationUtil.CreateDuration() and Cooldown:SetCooldownFromDurationObject() .

• Built-in damage meter — Use C_DamageMeter for damage/healing data instead of parsing combat events.

• SendAddonMessage blocked — Cannot send addon messages in instances. Boss mod addons must use new encounter event patterns.

• Unit identity restricted — UnitName() , UnitClass() may return secrets for enemy units in instances during combat.

• Threat in instances — Threat values may be secret. Pass to widgets directly; don't branch on them.

• Design philosophy — Addons should NOT provide competitive advantage in combat. Blizzard provides built-in replacements for most restricted functionality.