- Overview
- API Structure
- API Categories
- New 12.0.0 APIs
- Secret Values System
- Lua Extensions
- Common API Patterns
- API Usage Examples
- API Migration Guide
- Finding API Documentation
This document provides comprehensive information about the World of Warcraft API structure and usage patterns.
Statistics:
- Total API Documentation Files: 513+
- Total Events: 1,700+
- API Systems: 200+
- Current Version: 12.0.0 (Midnight)
Modern WoW APIs use the C_* namespace pattern. These are table-based APIs that group related functions.
Example:
C_ChatInfo.GetChannelInfo(channelID)
C_Map.GetBestMapForUnit("player")
C_Timer.After(3, function() print("3 seconds passed") end)Benefits:
- Clear organization by functionality
- Less global namespace pollution
- Better IntelliSense support in IDEs
- Official and maintained by Blizzard
Older APIs exist in the global namespace. Many are still actively used, though Blizzard continues migrating them to C_* namespaces.
Examples:
UnitName("player")
GetItemInfo(itemID)
CreateFrame("Frame", "MyFrame", UIParent)Note: As of 12.0.0, many previously global functions have been moved to C_* namespaces. See the API Migration Guide section for details.
Functions for querying information about units (players, NPCs, pets, etc.)
Key Functions:
UnitName("unit") -- Get unit's name
UnitHealth("unit") -- Get current health (SECRET in combat - 12.0.0)
UnitHealthMax("unit") -- Get maximum health (SECRET in combat - 12.0.0)
UnitHealthMissing("unit") -- Get missing health (12.0.0)
UnitHealthPercent("unit", usePredicted, curveConstant) -- Get health % (NOT SECRET - 12.0.0)
UnitPower("unit", powerType) -- Get current power (SECRET in combat - 12.0.0)
UnitPowerMax("unit", powerType) -- Get maximum power (SECRET in combat - 12.0.0)
UnitPowerMissing("unit", powerType) -- Get missing power (12.0.0)
UnitPowerPercent("unit", powerType, curveConstant) -- Get power % (NOT SECRET - 12.0.0)
UnitClass("unit") -- Get class name and class file
UnitRace("unit") -- Get race name and race file
UnitLevel("unit") -- Get level
UnitExists("unit") -- Check if unit exists
UnitIsPlayer("unit") -- Check if unit is a player
UnitIsHumanPlayer("unit") -- Check if unit is a human player (12.0.0)
UnitIsDead("unit") -- Check if unit is dead
UnitAffectingCombat("unit") -- Check if in combat
UnitIsLieutenant("unit") -- Check if unit is a lieutenant (12.0.0)
UnitIsMinion("unit") -- Check if unit is a minion (12.0.0)
UnitCreatureID("unit") -- Get creature ID (returns nil when identity is secret, 12.0.1+)
UnitBuff("unit", index or "name") -- DEPRECATED 10.2.5; use C_UnitAuras
UnitDebuff("unit", index or "name") -- DEPRECATED 10.2.5; use C_UnitAuras
-- NOTE: In 12.0.0+, ALL aura data fields are SECRET during combat except auraInstanceID.
-- C_UnitAuras.GetUnitAuraBySpellID() and AuraUtil.FindAuraByName() return nil during combat.
-- See 12a_Secret_Safe_APIs.md for full aura secret values documentation.
UnitGetTotalAbsorbs("unit") -- Get absorb shield total (SECRET in combat - 12.0.0)
UnitGetTotalHealAbsorbs("unit") -- Get heal absorb total (12.0.0)
UnitGetIncomingHeals("unit", healer)-- Get incoming heals (SECRET in combat - 12.0.0)Secret Values in Unit APIs (12.0.0 - CRITICAL):
In WoW 12.0.0, the following Unit APIs return secret values during ANY combat (open world, dungeons, raids, PvP, all combat contexts):
UnitHealth(),UnitHealthMax()UnitPower(),UnitPowerMax()UnitGetTotalAbsorbs(),UnitGetIncomingHeals()
Secret values CANNOT be used for arithmetic, comparisons, or string concatenation:
-- THESE FAIL with secret values:
local percent = UnitHealth("target") / UnitHealthMax("target") -- ERROR!
if UnitHealth("target") > 0 then -- ERROR!
print("Health: " .. UnitHealth("target")) -- ERROR!Use UnitHealthPercent/UnitPowerPercent for custom UI calculations:
-- Returns NON-SECRET percentage (0-100)
local healthPct = UnitHealthPercent("target", false, CurveConstants.ScaleTo100)
local width = (healthPct / 100) * BAR_WIDTH -- Safe arithmetic!Native StatusBar frames accept secret values directly:
local bar = CreateFrame("StatusBar", nil, parent)
bar:SetMinMaxValues(0, UnitHealthMax("target")) -- Works with secrets!
bar:SetValue(UnitHealth("target")) -- Works with secrets!See 12a_Secret_Safe_APIs.md for the complete secret values reference, and 12_API_Migration_Guide.md for migration patterns.
New Event Callback System (12.0.0):
-- Register for unit-specific events without frame overhead
RegisterEventCallback("UNIT_HEALTH", function(unit)
print(unit .. " health changed")
end)
UnregisterEventCallback("UNIT_HEALTH", callbackID)
-- Unit-specific event registration
RegisterUnitEventCallback("UNIT_HEALTH", function(unit)
-- UnitHealth returns a secret value during combat; use issecretvalue() before arithmetic/concat
local health = UnitHealth("player")
if not issecretvalue(health) then
print("Player health changed to: " .. health)
end
end, "player")
UnregisterUnitEventCallback("UNIT_HEALTH", callbackID, "player")Unit Tokens:
"player"- The player"target"- Current target"pet"- Player's pet"party1"through"party4"- Party members"raid1"through"raid40"- Raid members"boss1"through"boss5"- Boss frames"arena1"through"arena5"- Arena opponents"mouseover"- Unit under mouse cursor"focus"- Focus target"vehicleNN"- Vehicle passengers
C_Item Namespace:
C_Item.GetItemInfo(itemID)
C_Item.GetItemCount(itemID, includeBank, includeCharges)
C_Item.IsItemInRange(itemID, "unit")
C_Item.GetItemQuality(itemLocation)C_ItemSocketInfo Namespace (11.2.5+):
-- Replaces global Socket APIs
C_ItemSocketInfo.GetSocketItemInfo(socketIndex)
C_ItemSocketInfo.GetNumSockets()
C_ItemSocketInfo.GetExistingSocketLink(socketIndex)
C_ItemSocketInfo.SocketContainerItem(bagID, slotIndex)
C_ItemSocketInfo.CompleteSocketing()
C_ItemSocketInfo.CloseSocketInfo()Global Functions:
GetItemInfo(itemID or "itemLink" or "itemString")
-- Returns: name, link, quality, iLevel, reqLevel, class, subclass,
-- maxStack, equipSloc, texture, sellPrice, classID, subclassID,
-- bindType, expacID, setID, isCraftingReagent
GetContainerItemInfo(bagID, slotIndex)
GetContainerNumSlots(bagID)
UseContainerItem(bagID, slotIndex)
PickupContainerItem(bagID, slotIndex)Bag IDs:
0- Backpack1-4- Bag slots5- Reagent bag (if equipped)BANK_CONTAINERor-1- Bank6-12- Bank bag slots
C_Spell Namespace:
C_Spell.GetSpellInfo(spellID) -- ONLY accepts numeric spell IDs (not names) in 12.0.0+
C_Spell.IsSpellInRange(spellID, "unit")
C_Spell.GetSpellCooldown(spellID) -- Returns cooldownInfo table (isActive, isEnabled, maxCharges now non-secret in 12.0.1)
C_Spell.DoesSpellExist(spellID)
-- New in 12.0.0
C_Spell.GetSpellChargeDuration(spellID) -- Duration per charge
C_Spell.GetSpellCooldownDuration(spellID) -- Base cooldown duration
C_Spell.IsExternalDefensive(spellID) -- External defensive cooldown
C_Spell.IsSpellCrowdControl(spellID) -- CC ability check
C_Spell.IsSpellImportant(spellID) -- Important spell marker
C_Spell.IsPriorityAura(spellID) -- Priority aura check
C_Spell.IsSelfBuff(spellID) -- Self-buff checkSee also: Cooldown Viewer Guide for the complete Cooldown Viewer/Manager system reference.
C_SpellBook Namespace (11.2.0+):
-- Replaces IsSpellKnown()
C_SpellBook.IsSpellKnown(spellID)
C_SpellBook.GetSpellBookItemInfo(slotIndex, spellBookType)
C_SpellBook.GetNumSpellBookSkillLines()C_SpellDiminish Namespace (12.0.0):
-- Diminishing returns tracking
C_SpellDiminish.GetDiminishingReturnsByUnit("unit")
C_SpellDiminish.GetDiminishingReturnsForSpell(spellID)
C_SpellDiminish.GetDiminishingCategory(spellID)Global Functions (REMOVED in 11.0.0 -- use C_Spell namespace instead):
-- REMOVED: GetSpellInfo(spellID or "spellName" or spellIndex, "bookType")
-- Use C_Spell.GetSpellInfo(spellID) or C_Spell.GetSpellName(spellID) instead
-- NOTE: C_Spell functions ONLY accept numeric spell IDs in 12.0.0+ (not spell names)
-- REMOVED: GetSpellCooldown(spellID or "spellName")
-- Use C_Spell.GetSpellCooldown(spellID) instead
-- DEPRECATED in 11.2.0: Use C_SpellBook.IsSpellKnown() instead
IsSpellKnown(spellID)
IsPlayerSpell(spellID)
CastSpellByID(spellID)
CastSpellByName("spellName")C_ChatInfo Namespace:
C_ChatInfo.GetChannelInfo(channelID)
C_ChatInfo.GetChannelInfoFromIdentifier(channelIdentifier)
C_ChatInfo.GetChannelRosterInfo(channelIndex, rosterIndex)
C_ChatInfo.CanPlayerSpeakLanguage(languageID)
-- 11.2.0+: SendChatMessage moved here
C_ChatInfo.SendChatMessage("message", "chatType", languageID, "channelOrTarget")
-- 12.0.0+: Emote functions moved from global
C_ChatInfo.DoEmote("emote", "target")
C_ChatInfo.CancelEmote()C_BattleNet Namespace (12.0.0):
-- Replaces global BN* functions
C_BattleNet.SendWhisper(presenceID, "message")
C_BattleNet.GetFriendInfo(friendIndex)
C_BattleNet.GetNumFriends()
C_BattleNet.GetFOFInfo(accountID)Global Functions (Legacy):
-- DEPRECATED in 11.2.0: Use C_ChatInfo.SendChatMessage() instead
SendChatMessage("message", "chatType", languageID, "channelOrTarget")Chat Types:
"SAY"- Say"YELL"- Yell"PARTY"- Party chat"RAID"- Raid chat"GUILD"- Guild chat"OFFICER"- Officer chat"WHISPER"- Whisper (requires target name)"CHANNEL"- Chat channel (requires channel ID)"EMOTE"- Emote"AFK"- AFK message"DND"- DND message
C_Map Namespace:
C_Map.GetBestMapForUnit("unit")
C_Map.GetPlayerMapPosition(uiMapID, "unit")
-- Returns: positionObject with :GetXY() method
C_Map.GetMapInfo(uiMapID)
-- Returns: info table with name, mapID, parentMapID, mapType, etc.
C_Map.GetWorldPosFromMapPos(uiMapID, mapPosition)C_Timer Namespace:
C_Timer.After(seconds, callback)
-- Execute callback after X seconds (once)
C_Timer.NewTimer(seconds, callback)
-- Returns timer object with :Cancel() method
C_Timer.NewTicker(interval, callback, iterations)
-- Repeating timer, optional iteration limitAlternative - Frame OnUpdate:
local frame = CreateFrame("Frame")
local elapsed = 0
frame:SetScript("OnUpdate", function(self, deltaTime)
elapsed = elapsed + deltaTime
if elapsed >= 1.0 then -- Every 1 second
-- Do something
elapsed = 0
end
end)C_QuestLog Namespace:
C_QuestLog.GetInfo(questLogIndex)
C_QuestLog.GetNumQuestLogEntries()
C_QuestLog.GetQuestObjectives(questID)
C_QuestLog.GetSelectedQuest()
C_QuestLog.SetSelectedQuest(questID)
C_QuestLog.IsQuestFlaggedCompleted(questID)C_Achievement Namespace:
C_AchievementInfo.GetAchievementInfo(achievementID)
C_AchievementInfo.GetNumAchievements()
C_AchievementInfo.GetCriteriaInfo(achievementID, criteriaIndex)C_AuctionHouse Namespace:
C_AuctionHouse.GetBrowseResults()
C_AuctionHouse.GetItemKeyInfo(itemKey)
C_AuctionHouse.SearchForItemKeys(itemKeys, sorts)
C_AuctionHouse.GetNumBids()
C_AuctionHouse.PlaceBid(auctionID, bidAmount)C_TradeSkillUI Namespace:
C_TradeSkillUI.GetRecipeInfo(recipeID)
C_TradeSkillUI.GetRecipeNumReagents(recipeID)
C_TradeSkillUI.GetRecipeReagentInfo(recipeID, reagentIndex)
C_TradeSkillUI.CraftRecipe(recipeID, numCasts)Replaces global action bar functions with a structured namespace.
-- Get action bar slot information
C_ActionBar.GetActionTexture(slot)
C_ActionBar.GetActionText(slot)
C_ActionBar.GetActionCooldown(slot) -- Returns cooldownInfo (isActive, isEnabled, maxCharges non-secret in 12.0.1; includes cooldown aura effects)
-- Action bar operations
C_ActionBar.HasAction(slot)
C_ActionBar.IsCurrentAction(slot)
C_ActionBar.IsAutoRepeatAction(slot)
C_ActionBar.IsUsableAction(slot)
C_ActionBar.IsConsumableAction(slot)
C_ActionBar.IsStackableAction(slot)
C_ActionBar.IsAttackAction(slot)
-- Pickup and placement
-- Note: PickupAction() and PlaceAction() remain LIVE globals in 12.0.0
-- (no C_ActionBar equivalents exist - still used by Blizzard's own code)
C_ActionBar.PutActionInSlot(slotID) -- places cursor action into slot
C_ActionBar.PickupSpellBookItem(slotIndex, bookType)
-- Action counts
C_ActionBar.GetActionUseCount(slot) -- NOT GetActionCount
C_ActionBar.GetActionCharges(slot)Structured access to combat log data.
-- Combat log event access
C_CombatLog.GetCurrentEventInfo()
C_CombatLog.GetNumCombatLogFilters()
C_CombatLog.GetCombatLogFilterInfo(filterIndex)
-- Combat log management
C_CombatLog.ClearCombatLog()
C_CombatLog.SetCombatLogFilterEnabled(filterIndex, enabled)Blizzard's official damage meter data. Data-retrieval functions have SecretArguments = "SecretWhenInCombat" -- returned values are secret during combat but readable afterward. See Blizzard UI Examples - Damage Meter for full data structures, enums, and workaround patterns.
-- Session discovery
C_DamageMeter.GetAvailableCombatSessions() -- Returns DamageMeterAvailableCombatSession[]
C_DamageMeter.IsDamageMeterAvailable() -- Returns isAvailable (bool), failureReason (string)
-- Session data (SecretWhenInCombat)
C_DamageMeter.GetCombatSessionFromID(sessionID, type) -- Returns DamageMeterCombatSession
C_DamageMeter.GetCombatSessionFromType(sessionType, type) -- Returns DamageMeterCombatSession
-- Spell breakdown per source (SecretWhenInCombat)
C_DamageMeter.GetCombatSessionSourceFromID(sessionID, type, sourceGUID)
C_DamageMeter.GetCombatSessionSourceFromType(sessionType, type, sourceGUID)
-- Management
C_DamageMeter.ResetAllCombatSessions()Access to encounter ability timers and phases.
-- Timeline data
C_EncounterTimeline.GetEncounterTimeline(encounterID)
C_EncounterTimeline.GetCurrentPhase()
C_EncounterTimeline.GetPhaseInfo(phaseIndex)
C_EncounterTimeline.GetAbilityTimers()
-- Ability predictions
C_EncounterTimeline.GetNextAbility()
C_EncounterTimeline.GetAbilityCooldown(abilityID)Built-in encounter warning system.
-- Warning management
C_EncounterWarnings.GetActiveWarnings()
C_EncounterWarnings.GetWarningInfo(warningID)
C_EncounterWarnings.AcknowledgeWarning(warningID)
-- Warning configuration
C_EncounterWarnings.IsWarningEnabled(warningType)
C_EncounterWarnings.SetWarningEnabled(warningType, enabled)Replaces IsEncounterInProgress() with expanded functionality.
-- Encounter state
C_InstanceEncounter.IsEncounterInProgress() -- Replaces global IsEncounterInProgress()
C_InstanceEncounter.GetEncounterID()
C_InstanceEncounter.GetEncounterName()
C_InstanceEncounter.GetEncounterDifficulty()
-- Instance information
C_InstanceEncounter.GetInstanceInfo()
C_InstanceEncounter.IsInInstance()
C_InstanceEncounter.GetBossInfo(bossIndex)Query addon restriction state (combat, encounters, M+, PvP, etc.) and check whether the current calling context is allowed to invoke protected functions.
-- Check whether an addon restriction type is currently active
-- (type is an Enum.AddOnRestrictionType value)
C_RestrictedActions.IsAddOnRestrictionActive(type) -- returns bool
-- Get the full restriction state for an addon restriction type
C_RestrictedActions.GetAddOnRestrictionState(type) -- returns AddOnRestrictionState
-- Check whether the current calling context may call protected functions
-- on the supplied FrameScriptObject. Pass silent=true to suppress blocked-
-- action error signaling if not allowed.
C_RestrictedActions.CheckAllowProtectedFunctions(object, silent) -- returns bool
-- For combat lockdown checks, use the global (not namespaced):
InCombatLockdown() -- returns boolRelated events: ADDON_ACTION_BLOCKED, ADDON_ACTION_FORBIDDEN,
ADDON_RESTRICTION_STATE_CHANGED, MACRO_ACTION_BLOCKED,
MACRO_ACTION_FORBIDDEN.
Text-to-speech accessibility features for combat.
-- Audio alerts
C_CombatAudioAlert.PlayAlert(alertType)
C_CombatAudioAlert.SpeakText("text")
C_CombatAudioAlert.SetAlertEnabled(alertType, enabled)
-- Configuration
C_CombatAudioAlert.GetVoiceSettings()
C_CombatAudioAlert.SetVoiceSettings(settings)Expanded transmog outfit management (replaces older transmog APIs).
-- Outfit management
C_TransmogOutfitInfo.GetOutfits()
C_TransmogOutfitInfo.GetOutfitInfo(outfitID)
C_TransmogOutfitInfo.CreateOutfit("name", sources)
C_TransmogOutfitInfo.DeleteOutfit(outfitID)
C_TransmogOutfitInfo.ModifyOutfit(outfitID, sources)
-- Application
C_TransmogOutfitInfo.ApplyOutfit(outfitID)
C_TransmogOutfitInfo.CanApplyOutfit(outfitID)
C_TransmogOutfitInfo.GetOutfitCost(outfitID)Access death recap data programmatically.
-- Death information
C_DeathRecap.GetDeathRecapInfo()
C_DeathRecap.GetDeathInfo(deathIndex)
C_DeathRecap.GetNumDeaths()
-- Damage sources
C_DeathRecap.GetDamageSources()
C_DeathRecap.GetDeathDetails()New player housing feature in Midnight. See dedicated Housing guide for full details.
-- Housing basics
C_Housing.GetPlayerHouse()
C_Housing.IsInHouse()
C_Housing.GetHouseInfo(houseID)
-- Furniture and decoration
C_Housing.GetPlacedFurniture()
C_Housing.PlaceFurniture(furnitureID, position, rotation)
C_Housing.RemoveFurniture(placementID)
-- Visitors
C_Housing.GetHouseVisitors()
C_Housing.InviteToHouse("playerName")
C_Housing.SetHousePermissions(permissionType, value)C_CurveUtil - Curve/Animation Utilities:
C_CurveUtil.GetCurveValue(curveID, progress)
C_CurveUtil.GetCurvePointCount(curveID)C_DurationUtil - Duration Formatting:
C_DurationUtil.FormatDuration(seconds)
C_DurationUtil.FormatShortDuration(seconds)
C_DurationUtil.ParseDuration("durationString")C_StringUtil - String Utilities:
C_StringUtil.SplitString(delimiter, "string")
C_StringUtil.TrimString("string")
C_StringUtil.FormatLargeNumber(number)C_ColorUtil - Color Utilities:
C_ColorUtil.CreateColor(r, g, b, a)
C_ColorUtil.GetColorFromHexString("hexColor")
C_ColorUtil.ConvertToHexString(r, g, b)New in 12.0.0, WoW introduces a "secret values" system that protects sensitive combat data from unauthorized addon access during ANY combat context (open-world combat, dungeons, raids, mythic+, PvP, battlegrounds, arenas, world bosses — all combat). This is part of Blizzard's ongoing effort to prevent automation and botting.
Secret values are wrapped data that cannot be directly read or manipulated by addon code. They're used for sensitive combat-related information that could be exploited for automation. Secret values are active during ALL combat contexts, not just instanced content.
-- Check if a value is a secret
issecretvalue(value)
-- Returns: true if value is a secret, false otherwise
-- Check if current context can access a secret value
canaccessvalue(secretValue)
-- Returns: true if the value can be accessed, false otherwise
-- Wrap a value as a secret (internal use)
secretwrap(value)
-- Returns: wrapped secret value
-- Remove secret values from varargs (for logging/display)
scrubsecretvalues(...)
-- Returns: transformed values with secrets replaced by nil-- Example: Accessing unit health during ANY combat
local function UpdateHealthDisplay()
local health = UnitHealth("target")
-- health is a secret value whenever the player is in combat (any combat context)
if issecretvalue(health) then
-- During combat: cannot use for arithmetic, comparisons, or concatenation
-- Use alternative approaches like percentage APIs or defer processing
return
else
-- Out of combat: normal usage allowed
print("Target health: " .. health)
end
endWhen a player is in ANY combat (not limited to instanced content), tainted addon code returns secret values for:
- Unit health/power data:
UnitHealth(),UnitHealthMax(),UnitPower(),UnitPowerMax(),UnitGetTotalAbsorbs(),UnitGetIncomingHeals()— all return secrets during combat anywhere (open-world, dungeons, raids, PvP) - Action bar state:
C_ActionBar.GetActionCooldown(),C_ActionBar.GetActionCharges(), and related cooldown/charge functions may return secret values during combat - Aura data: All aura data fields except
auraInstanceIDare secret during combat (not just instanced combat)
-- Display values that may be secret on FontStrings (12.0.0)
-- SetFormattedText handles secrets at the C++ level
myFontString:SetFormattedText("Health: %d", secretHealthValue)
-- Scrub secrets before logging
local health, power = scrubsecretvalues(UnitHealth("target"), UnitPower("target"))
-- health and power are now nil if they were secret, or the real number if not
if health then
print("Debug: " .. health)
else
print("Debug: health is secret")
end- Check before arithmetic: Always check
issecretvalue()before doing math with potentially secret values - Use
SetFormattedText(): For displaying values that may be secret on FontStrings — it handles secrets at the C++ level - Scrub for display: Use
scrubsecretvalues()before logging — secrets becomenil, not placeholder strings - Don't fight the system: If a value is secret, it's intentionally protected
Cooldown frame methods restricted with secret values:
SetCooldown(),SetCooldownFromExpirationTime(),SetCooldownDuration(),SetCooldownUNIX()— restrictedSetCooldownFromDurationObject()— the ONLY method that still accepts secret values
APIs now returning nil instead of secrets:
UnitCreatureID(unit)— returnsnilwhen unit identity is secretFrame:GetEffectiveAlpha()— returnsnilwith secret aspectsStatusBar:IsStatusBarDesaturated()— returnsnilwith secret aspectsTexture:IsDesaturated()— returnsnilwith secret aspects
Cooldown API fields now non-secret:
isEnabled,maxCharges— previously secret, now always accessibleisActive(new) — non-secret boolean indicating whether UI should render a cooldown
New APIs:
C_LossOfControl.GetActiveLossOfControlDuration(unitToken, index)— returns duration objectGetTotemDuration(slot)— returns duration object
Private aura APIs now combat-restricted:
C_UnitAuras.AddPrivateAuraAnchor(),RemovePrivateAuraAnchor(),SetPrivateWarningTextAnchor(),AddPrivateAuraAppliedSound(),RemovePrivateAuraAppliedSound()
Other restrictions:
string.formatprecision specifiers ("%.1s") restricted with secret stringsActionButton_ApplyCooldownsecure delegate removed (throws errors with secrets)- Cooldown aura spells baked into API results (obsoletes
C_UnitAuras.GetCooldownAuraBySpellID)
See also: Cooldown Viewer Guide for complete CooldownFrame API reference including secret value annotations.
Patch 12.0.5 (TOC 120005) builds on the 12.0.1 secret-value refinements. See 12_API_Migration_Guide.md for the full patch delta.
Aura classification fields NO LONGER secret during combat:
isHelpful,isHarmful,isRaid,isNameplateOnly,isFromPlayerOrPlayerPet— readable from tainted Lua during combat- Identifier fields (
name,spellId,icon, durations) remain secret auraInstanceIDre-randomizes on encounter / M+ / PvP entry — invalidate instance-id-keyed caches at those boundaries
New Cooldown frame methods (accept secret numbers via formatters):
cooldown:SetCountdownFormatter(formatter)— plug in aNumericFormattersubclass to customize countdown text renderingcooldown:SetCountdownMillisecondsThreshold(seconds)— below this threshold, numbers render with one decimal place
New numeric formatter types (accept secret numbers):
AbbreviatedNumberFormatter,NumericRuleFormatter,SecondsFormatter(all extendNumericFormatter)
Charge duration APIs — new ignoreGCD parameter:
C_Spell.GetSpellChargeDuration(spellID, ignoreGCD)C_ActionBar.GetActionChargeDuration(slot, ignoreGCD)C_SpellBook.GetSpellBookItemChargeDuration(spellBookItemSlotIndex, spellBookItemType, ignoreGCD)- Return zero-span duration at max charges (treated as fully elapsed by the framework)
Per-plate nameplate hit rect API:
nameplate:CanChangeHitTestPoints(),:SetHitTestPoints(anchors),:SetAllHitTestPoints(region),:GetHitTestPoints(),:ClearAllHitTestPoints(),:SetStackingBoundsFrame(frame)- Preferred over the global
C_NamePlate.SetNamePlateSize(w, h)— does not steal clicks from adjacent plates
Unit identity APIs stricter about secret tokens:
UnitName(unit)— no longer accepts secret unit tokensUnitSpellTargetName(unit)— returns names only for player unitsUnitTokenFromGUID(guid)— no longer returns arena/nameplate/boss/party/raid/targettarget/focustarget tokens when identities are secretUnitIsUnit(a, b)— returns secret if either istargettarget/focustarget; returns nil for forbidden comparisons (see 12_API_Migration_Guide.md for the allow-list)
Player stat APIs inherit aura secrecy:
- Stat-returning APIs now return secrets if the influencing auras are secret (previously unconditionally non-secret)
New Lua primitives:
table.freeze(tbl)— make a table read-only (mutation raises)table.isfrozen(tbl)— inspectAmbiguate(name, context)— now accepts secret string arguments from addons
Widget additions:
FontString:SetSmoothScaling(bool)/FontString:GetSmoothScaling()— per-FontString HiDPI-friendly smooth scaling
Secure button additions:
- New
"outfit"action type forSecureActionButtonTemplate— apply a transmog outfit via secure button (SetAttribute("type", "outfit")+SetAttribute("outfit", outfitNameOrID)) GetTransmogOutfitIndexavailable in the restricted addon environment
Miscellaneous:
GetRaidRosterInfo(index)returns"Unknown"(string) instead ofnilwhen name uncachedUNIT_CONNECTIONevent reliability fixed (previously missed some party connect/disconnect events)IsInInstance()correctly returnstrueinside delves- Addon execution throttles relaxed during
PLAYER_LOGOUTandADDONS_UNLOADING - New
Predicatestable in generated API docs describes per-API secret/taint restrictions
WoW includes custom Lua extensions beyond standard Lua 5.1.
-- 11.1.7+: Pre-allocate table size for performance
table.create(arraySizeHint, nodeSizeHint)
-- Creates a table with pre-allocated space
-- arraySizeHint: expected number of array elements
-- nodeSizeHint: expected number of hash table entries
-- Example usage
local myTable = table.create(100, 10) -- 100 array slots, 10 hash entries
for i = 1, 100 do
myTable[i] = i * 2
end
-- 11.2.5+: Count table entries (including non-array)
table.count(tbl)
-- Returns: number of entries in the table
-- More accurate than #tbl for mixed tables
-- Example
local mixed = {1, 2, 3, foo = "bar", baz = "qux"}
print(#mixed) -- Returns 3 (only array part)
print(table.count(mixed)) -- Returns 5 (all entries)
-- 12.0.5+: Read-only tables
table.freeze(tbl)
-- Makes the table read-only; subsequent writes raise an error
-- Returns the table reference
table.isfrozen(tbl)
-- Returns true if the table is frozen
-- Example
local config = table.freeze({ retries = 3, timeout = 5 })
-- config.retries = 5 -- ERROR: attempt to modify a frozen table
if table.isfrozen(config) then
-- Table is read-only
end
-- Standard WoW table functions
tinsert(table, [pos,] value) -- Insert into table
tremove(table [, pos]) -- Remove from table
wipe(table) -- Clear all table contents
CopyTable(table) -- Deep copy a table
tContains(table, value) -- Check if table contains value
tIndexOf(table, value) -- Find index of value-- Standard WoW string functions
strsplit(delimiter, string) -- Split string by delimiter
strjoin(delimiter, ...) -- Join strings with delimiter
strtrim(string) -- Remove leading/trailing whitespace
strmatch(string, pattern) -- Pattern matching
format(formatString, ...) -- String formatting (same as string.format)-- Blizzard extensions
Clamp(value, min, max) -- Clamp value between min and max
Lerp(startValue, endValue, amount) -- Linear interpolation
Round(value) -- Round to nearest integer
Saturate(value) -- Clamp between 0 and 1-- Type checking
type(value) -- Standard Lua type
issecurevariable(table, key) -- Check if variable is secure
issecure() -- Check if current execution is secure
-- Time
GetTime() -- Game time in seconds (high precision)
time() -- Real-world Unix timestamp
date(format, time) -- Format time as string
-- Debugging
debugstack(start, top, bottom) -- Get stack trace
debuglocals(level) -- Get local variables at stack levellocal name, realm = UnitName("player")
if not name then
-- Unit doesn't exist
return
endfor i = 1, C_QuestLog.GetNumQuestLogEntries() do
local info = C_QuestLog.GetInfo(i)
if info and not info.isHeader then
print(info.title)
end
endC_Timer.After(5, function()
print("Delayed message")
end)if C_Spell.DoesSpellExist(spellID) then
local info = C_Spell.GetSpellInfo(spellID)
end-- Check if new API exists before using
if C_ActionBar and C_ActionBar.GetActionTexture then
-- Use new 12.0.0 API
local texture = C_ActionBar.GetActionTexture(slot)
else
-- Fall back to legacy
local texture = GetActionTexture(slot)
endlocal function SafeHealthDisplay(unit)
local health = UnitHealth(unit)
if issecretvalue(health) then
return "Protected"
end
return tostring(health)
endCommon Types:
number- Lua numberstring- Lua stringcstring- C string (null-terminated)bool- Boolean (true/false)table- Lua tablefunction- Lua functionuiUnit- Unit token stringWOWGUID- WoW GUID stringluaIndex- 1-based indexFileDataID- File data ID numberitemID- Item ID numberspellID- Spell ID numbersecretvalue- Protected secret value (12.0.0)
| Old API (Deprecated) | New API (12.0.0+) |
|---|---|
GetActionTexture(slot) |
C_ActionBar.GetActionTexture(slot) |
HasAction(slot) |
C_ActionBar.HasAction(slot) |
IsCurrentAction(slot) |
C_ActionBar.IsCurrentAction(slot) |
IsUsableAction(slot) |
C_ActionBar.IsUsableAction(slot) |
DoEmote("emote") |
C_ChatInfo.DoEmote("emote") |
CancelEmote() |
C_ChatInfo.CancelEmote() |
BNSendWhisper(...) |
C_BattleNet.SendWhisper(...) |
BNGetFriendInfo(...) |
C_BattleNet.GetFriendInfo(...) |
IsEncounterInProgress() |
C_InstanceEncounter.IsEncounterInProgress() |
| Old Transmog APIs | C_TransmogOutfitInfo.* |
| Old API (Deprecated) | New API (11.2.5+) |
|---|---|
GetSocketInfo(index) |
C_ItemSocketInfo.GetSocketItemInfo(index) |
GetNumSockets() |
C_ItemSocketInfo.GetNumSockets() |
GetExistingSocketLink(index) |
C_ItemSocketInfo.GetExistingSocketLink(index) |
SocketContainerItem(bag, slot) |
C_ItemSocketInfo.SocketContainerItem(bag, slot) |
| Old API (Deprecated) | New API (11.2.0+) |
|---|---|
SendChatMessage(...) |
C_ChatInfo.SendChatMessage(...) |
IsSpellKnown(spellID) |
C_SpellBook.IsSpellKnown(spellID) |
-- Create compatibility layer for different WoW versions
local function GetActionTextureCompat(slot)
if C_ActionBar and C_ActionBar.GetActionTexture then
return C_ActionBar.GetActionTexture(slot)
else
return GetActionTexture(slot)
end
end
local function SendChatMessageCompat(msg, chatType, language, channel)
if C_ChatInfo and C_ChatInfo.SendChatMessage then
C_ChatInfo.SendChatMessage(msg, chatType, language, channel)
else
SendChatMessage(msg, chatType, language, channel)
end
end
local function IsSpellKnownCompat(spellID)
if C_SpellBook and C_SpellBook.IsSpellKnown then
return C_SpellBook.IsSpellKnown(spellID)
else
return IsSpellKnown(spellID)
end
endAll API documentation files are located at:
<WoW Install>\Interface\+wow-ui-source+ (<version>)\Interface\AddOns\Blizzard_APIDocumentationGenerated\
Each API documentation file follows this structure:
local SystemName = {
Name = "SystemName",
Type = "System",
Namespace = "C_SystemName", -- or "" for global
Functions = {
{
Name = "FunctionName",
Type = "Function",
Arguments = {
{ Name = "argName", Type = "number", Nilable = false },
},
Returns = {
{ Name = "result", Type = "bool", Nilable = false },
},
},
},
Events = {
{
Name = "EVENT_NAME",
Type = "Event",
LiteralName = "EVENT_NAME",
Payload = {
{ Name = "param1", Type = "number", Nilable = false },
},
},
},
Tables = {
{
Name = "StructureName",
Type = "Structure",
Fields = {
{ Name = "fieldName", Type = "string", Nilable = false },
},
},
},
}When working on:
- Chat systems: Read
ChatInfoDocumentation.lua,ChatConstantsDocumentation.lua - Items/Inventory: Read
BagConstantsDocumentation.lua,ItemDocumentation.lua,ItemSocketInfoDocumentation.lua - Combat/Spells: Read
ActionBarDocumentation.lua,SpellDocumentation.lua,CombatLogDocumentation.lua - UI Frames: Read
UIObjectDocumentation.lua,UIWidgetDocumentation.lua - Maps/Coords: Read
MapCanvasDocumentation.lua,AreaPoiInfoDocumentation.lua - Quests: Read
QuestLogDocumentation.lua,QuestInfoDocumentation.lua - Encounters: Read
EncounterTimelineDocumentation.lua,InstanceEncounterDocumentation.lua - Housing: Read
HousingDocumentation.lua