Skip to content

Latest commit

 

History

History
1076 lines (868 loc) · 36.4 KB

01_API_Reference.md

File metadata and controls

1076 lines (868 loc) · 36.4 KB

WoW API Reference Guide

Table of Contents

  1. Overview
  2. API Structure
  3. API Categories
  4. New 12.0.0 APIs
  5. Secret Values System
  6. Lua Extensions
  7. Common API Patterns
  8. API Usage Examples
  9. API Migration Guide
  10. Finding API Documentation

Overview

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)

API Structure

Namespace APIs (C_* APIs)

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

Global APIs (Legacy)

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.

Common API Categories

1. Unit APIs

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

2. Item and Inventory APIs

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 - Backpack
  • 1-4 - Bag slots
  • 5 - Reagent bag (if equipped)
  • BANK_CONTAINER or -1 - Bank
  • 6-12 - Bank bag slots

3. Spell and Ability APIs

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 check

See 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")

4. Chat and Communication APIs

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

5. Map and Position APIs

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)

6. Timer and Frame APIs

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 limit

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

7. Quest APIs

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)

8. Achievement APIs

C_Achievement Namespace:

C_AchievementInfo.GetAchievementInfo(achievementID)
C_AchievementInfo.GetNumAchievements()
C_AchievementInfo.GetCriteriaInfo(achievementID, criteriaIndex)

9. Auction House APIs

C_AuctionHouse Namespace:

C_AuctionHouse.GetBrowseResults()
C_AuctionHouse.GetItemKeyInfo(itemKey)
C_AuctionHouse.SearchForItemKeys(itemKeys, sorts)
C_AuctionHouse.GetNumBids()
C_AuctionHouse.PlaceBid(auctionID, bidAmount)

10. Profession APIs

C_TradeSkillUI Namespace:

C_TradeSkillUI.GetRecipeInfo(recipeID)
C_TradeSkillUI.GetRecipeNumReagents(recipeID)
C_TradeSkillUI.GetRecipeReagentInfo(recipeID, reagentIndex)
C_TradeSkillUI.CraftRecipe(recipeID, numCasts)

New 12.0.0 APIs

C_ActionBar - Action Bar Management

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)

C_CombatLog - Combat Log Management

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)

C_DamageMeter - Official Damage Meter API (12.0.0)

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

C_EncounterTimeline - Boss Ability Timeline

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)

C_EncounterWarnings - Encounter Warnings

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)

C_InstanceEncounter - Encounter State

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)

C_RestrictedActions - Addon Restriction Management

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 bool

Related events: ADDON_ACTION_BLOCKED, ADDON_ACTION_FORBIDDEN, ADDON_RESTRICTION_STATE_CHANGED, MACRO_ACTION_BLOCKED, MACRO_ACTION_FORBIDDEN.

C_CombatAudioAlert - TTS Accessibility

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)

C_TransmogOutfitInfo - New Transmog System

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)

C_DeathRecap - Death Recap Information

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

C_Housing - Player Housing System

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)

Utility Namespaces

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)

Secret Values System

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.

What Are Secret Values?

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.

Built-in Functions

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

How Secrets Affect Addons

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

When Secrets Apply: During ANY Combat

When a player is in ANY combat (not limited to instanced content), tainted addon code returns secret values for:

  1. Unit health/power data: UnitHealth(), UnitHealthMax(), UnitPower(), UnitPowerMax(), UnitGetTotalAbsorbs(), UnitGetIncomingHeals() — all return secrets during combat anywhere (open-world, dungeons, raids, PvP)
  2. Action bar state: C_ActionBar.GetActionCooldown(), C_ActionBar.GetActionCharges(), and related cooldown/charge functions may return secret values during combat
  3. Aura data: All aura data fields except auraInstanceID are secret during combat (not just instanced combat)

Working with Secrets

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

Best Practices

  1. Check before arithmetic: Always check issecretvalue() before doing math with potentially secret values
  2. Use SetFormattedText(): For displaying values that may be secret on FontStrings — it handles secrets at the C++ level
  3. Scrub for display: Use scrubsecretvalues() before logging — secrets become nil, not placeholder strings
  4. Don't fight the system: If a value is secret, it's intentionally protected

12.0.1 Hotfix Changes

Cooldown frame methods restricted with secret values:

  • SetCooldown(), SetCooldownFromExpirationTime(), SetCooldownDuration(), SetCooldownUNIX() — restricted
  • SetCooldownFromDurationObject() — the ONLY method that still accepts secret values

APIs now returning nil instead of secrets:

  • UnitCreatureID(unit) — returns nil when unit identity is secret
  • Frame:GetEffectiveAlpha() — returns nil with secret aspects
  • StatusBar:IsStatusBarDesaturated() — returns nil with secret aspects
  • Texture:IsDesaturated() — returns nil with secret aspects

Cooldown API fields now non-secret:

  • isEnabled, maxCharges — previously secret, now always accessible
  • isActive (new) — non-secret boolean indicating whether UI should render a cooldown

New APIs:

  • C_LossOfControl.GetActiveLossOfControlDuration(unitToken, index) — returns duration object
  • GetTotemDuration(slot) — returns duration object

Private aura APIs now combat-restricted:

  • C_UnitAuras.AddPrivateAuraAnchor(), RemovePrivateAuraAnchor(), SetPrivateWarningTextAnchor(), AddPrivateAuraAppliedSound(), RemovePrivateAuraAppliedSound()

Other restrictions:

  • string.format precision specifiers ("%.1s") restricted with secret strings
  • ActionButton_ApplyCooldown secure 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.

12.0.5 Changes

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
  • auraInstanceID re-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 a NumericFormatter subclass to customize countdown text rendering
  • cooldown:SetCountdownMillisecondsThreshold(seconds) — below this threshold, numbers render with one decimal place

New numeric formatter types (accept secret numbers):

  • AbbreviatedNumberFormatter, NumericRuleFormatter, SecondsFormatter (all extend NumericFormatter)

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 tokens
  • UnitSpellTargetName(unit) — returns names only for player units
  • UnitTokenFromGUID(guid) — no longer returns arena/nameplate/boss/party/raid/targettarget/focustarget tokens when identities are secret
  • UnitIsUnit(a, b) — returns secret if either is targettarget/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) — inspect
  • Ambiguate(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 for SecureActionButtonTemplate — apply a transmog outfit via secure button (SetAttribute("type", "outfit") + SetAttribute("outfit", outfitNameOrID))
  • GetTransmogOutfitIndex available in the restricted addon environment

Miscellaneous:

  • GetRaidRosterInfo(index) returns "Unknown" (string) instead of nil when name uncached
  • UNIT_CONNECTION event reliability fixed (previously missed some party connect/disconnect events)
  • IsInInstance() correctly returns true inside delves
  • Addon execution throttles relaxed during PLAYER_LOGOUT and ADDONS_UNLOADING
  • New Predicates table in generated API docs describes per-API secret/taint restrictions

Lua Extensions

WoW includes custom Lua extensions beyond standard Lua 5.1.

Table Functions

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

String Functions

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

Math Functions

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

Utility Functions

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

Common API Patterns

1. Checking Return Values

local name, realm = UnitName("player")
if not name then
    -- Unit doesn't exist
    return
end

2. Iterating Collections

for i = 1, C_QuestLog.GetNumQuestLogEntries() do
    local info = C_QuestLog.GetInfo(i)
    if info and not info.isHeader then
        print(info.title)
    end
end

3. Using Callbacks

C_Timer.After(5, function()
    print("Delayed message")
end)

4. Checking Existence Before Use

if C_Spell.DoesSpellExist(spellID) then
    local info = C_Spell.GetSpellInfo(spellID)
end

5. API Version Checking

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

6. Handling Secret Values

local function SafeHealthDisplay(unit)
    local health = UnitHealth(unit)
    if issecretvalue(health) then
        return "Protected"
    end
    return tostring(health)
end

API Type Reference

Common Types:

  • number - Lua number
  • string - Lua string
  • cstring - C string (null-terminated)
  • bool - Boolean (true/false)
  • table - Lua table
  • function - Lua function
  • uiUnit - Unit token string
  • WOWGUID - WoW GUID string
  • luaIndex - 1-based index
  • FileDataID - File data ID number
  • itemID - Item ID number
  • spellID - Spell ID number
  • secretvalue - Protected secret value (12.0.0)

API Migration Guide

12.0.0 Migrations

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

11.2.5 Migrations

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)

11.2.0 Migrations

Old API (Deprecated) New API (11.2.0+)
SendChatMessage(...) C_ChatInfo.SendChatMessage(...)
IsSpellKnown(spellID) C_SpellBook.IsSpellKnown(spellID)

Compatibility Wrapper Example

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

API Documentation Files Location

All API documentation files are located at:

<WoW Install>\Interface\+wow-ui-source+ (<version>)\Interface\AddOns\Blizzard_APIDocumentationGenerated\

Using API Documentation Files

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

Reference When to Read Specific API Files

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