Imported from pfchrono/SimpleUnitFrames (.github/skills/wow-api-spells-abilities/SKILL.md). Install upstream with npx skills add pfchrono/SimpleUnitFrames --skill wow-api-spells-abilities. Copyright stays with the author.

Spell & Ability API (Retail — Patch 12.0.0)

Comprehensive reference for all Spell, SpellBook, ActionBar, Cooldown, Totem, Shapeshifting, and related APIs. Covers spell information, cooldowns, usability, range checking, spellbook navigation, action bar slot management, spell procs, diminishing returns, assisted combat, and global spell functions.

Source of truth: https://warcraft.wiki.gg/wiki/World_of_Warcraft_API#Spell SpellBook: https://warcraft.wiki.gg/wiki/World_of_Warcraft_API#SpellBook ActionBar: https://warcraft.wiki.gg/wiki/World_of_Warcraft_API#ActionBar Current as of: Patch 12.0.0 (Build 65655) — January 28, 2026 Scope: Retail only. No deprecated or removed functions.

Scope

This skill covers these API systems:

• C_Spell — Core spell information, cooldowns, charges, usability, range, type checks
• C_SpellBook — Spellbook navigation, skill lines, slot queries, spell lookup
• C_ActionBar — Action bar slot management, state queries, bar pages, overrides
• C_SpellActivationOverlay — Spell proc/activation glow detection
• C_SpellDiminish — Diminishing returns tracking for crowd control
• C_CooldownViewer — Cooldown viewer categories and layout
• C_AssistedCombat — Assisted combat (rotation helper) integration
• Totem — Totem query functions (GetTotemInfo, DestroyTotem)
• Shapeshifting — Form/stance functions (GetShapeshiftForm, GetShapeshiftFormInfo)
• Global Spell Functions — CastSpellByName, CastSpellByID, SpellIsTargeting, etc.

When to Use This Skill

Use this skill when you need to:

• Query spell info: name, description, icon, subtext, link, power cost
• Check spell cooldowns, charges, or GCD state
• Determine if a spell is usable, in range, or on cooldown
• Navigate the spellbook: enumerate skill lines, find spell slots, check known spells
• Manage action bars: query action type, usability, cooldown, texture for a slot
• Detect action bar pages, bonus bars, override bars, vehicle bars
• Check for spell procs / activation overlays (glowing buttons)
• Track diminishing returns on crowd control effects
• Query totem state, duration, or destroy totems
• Check or cast shapeshift forms and stances
• Cast spells programmatically (protected functions)
• Handle spell targeting (SpellIsTargeting, SpellTargetUnit, SpellStopCasting)
• Use the assisted combat (rotation helper) system
• Work with flyout menus and multi-cast totem spells

Reference Files

C_Spell — Core Spell API (Quick Reference)

The C_Spell namespace provides direct access to spell data by spellIdentifier — which can be a spellID (number) or spellName (string).

Wiki: https://warcraft.wiki.gg/wiki/World_of_Warcraft_API#Spell

Key Functions

Cooldowns & Charges

Usability & Range

Type Checks

Power Cost & Data

Spell Manipulation

Visibility & Display

Targeting & Trade

C_SpellBook — Spellbook Navigation (Quick Reference)

The C_SpellBook namespace manages the spellbook UI, skill lines, and per-slot queries. Functions take (spellBookItemSlotIndex, spellBookItemSpellBank) where spellBank is Enum.SpellBookSpellBank.Player or Enum.SpellBookSpellBank.Pet.

Wiki: https://warcraft.wiki.gg/wiki/World_of_Warcraft_API#SpellBook

Key Functions

Slot Usability & State

Slot Cooldowns & Charges

Spell Lookup

Other Slot Operations

C_ActionBar — Action Bar Slot Management (Quick Reference)

The C_ActionBar namespace manages the 120+ action bar slots. Actions are referenced by actionID (1–180) or slotID.

Wiki: https://warcraft.wiki.gg/wiki/World_of_Warcraft_API#ActionBar

Action Slot Layout

Core Queries

Action State Checks

Bar Pages & Overrides

Display & Count

Spell ↔ Action Lookups

Profession & Gear

Slot Management

Auxiliary Namespaces (Quick Reference)

C_SpellActivationOverlay — Spell Procs

Detects when a spell has a visual activation overlay (glowing border / proc alert).

Wiki: https://warcraft.wiki.gg/wiki/World_of_Warcraft_API#SpellActivationOverlay

C_SpellDiminish — Diminishing Returns

Tracks diminishing returns (DR) categories for crowd control and interrupt tracking.

Wiki: https://warcraft.wiki.gg/wiki/World_of_Warcraft_API#SpellDiminishUI

C_CooldownViewer — Cooldown Display

Provides categorized cooldown data for the cooldown viewer UI.

Wiki: https://warcraft.wiki.gg/wiki/World_of_Warcraft_API#CooldownViewer

C_AssistedCombat — Rotation Helper

The Assisted Combat system (new in 12.0) provides suggested spell rotations.

Wiki: https://warcraft.wiki.gg/wiki/World_of_Warcraft_API#AssistedCombat

C_LevelLink — Spell Level Lock

Checks if spells or actions are level-locked for scaling content.

Totem Functions

Totem functions query and manage totem/minion slots. Shamans have 4 totem slots; other classes may have totem-style minions (e.g., Death Knight ghouls, mushrooms).

Wiki: https://warcraft.wiki.gg/wiki/World_of_Warcraft_API#Totem

totem Slot Constants

EARTH_TOTEM_SLOT  = 2
FIRE_TOTEM_SLOT   = 1
WATER_TOTEM_SLOT  = 3
AIR_TOTEM_SLOT    = 4

Shapeshifting / Stances

Manages shapeshift forms (Druid forms, Warrior stances, Rogue stealth, Paladin auras, etc.).

Wiki: https://warcraft.wiki.gg/wiki/World_of_Warcraft_API#Shapeshifting
Category: https://warcraft.wiki.gg/wiki/World_of_Warcraft_API (Shapeshifting section)

Global Spell Casting Functions

These are category-level functions (not namespaced) for casting, targeting, and confirming spells.

Wiki: https://warcraft.wiki.gg/wiki/World_of_Warcraft_API (Spells category)

Casting (Protected)

Targeting (Protected)

Spell Confirmation

Action Button Helpers

Flyouts

Combat Pet Actions

Multi-Cast / Totem Bar

Misc Spell Helpers

Patch 12.0.0 — Secret Values Impact

Spell-related APIs are significantly affected by Secret Values in Patch 12.0.0:

C_Secrets Predicates for Spells

What Returns Secrets

• Cooldown times — C_Spell.GetSpellCooldown() may return secret start/duration when C_Secrets.ShouldSpellCooldownBeSecret() is true
• Spell cast info — UnitCastingInfo() / UnitChannelInfo() return secret fields when unit identity is restricted
• Totem info — GetTotemInfo() may return secret startTime/duration when the totem spell is secret

Safe Patterns

-- Safe: Pass cooldown secrets directly to Cooldown widget
local cdInfo = C_Spell.GetSpellCooldown(spellID)
myCooldownFrame:SetCooldown(cdInfo.startTime, cdInfo.duration)

-- Safe: Display spell name (concatenation works with secrets)
local name = C_Spell.GetSpellName(spellID)
myFontString:SetText(name)

-- UNSAFE: Cannot branch on cooldown values
local cdInfo = C_Spell.GetSpellCooldown(spellID)
if cdInfo.duration > 0 then end  -- ERROR if duration is secret

Common Patterns

Iterate All Spellbook Entries

local numLines = C_SpellBook.GetNumSpellBookSkillLines()
for skillIndex = 1, numLines do
    local info = C_SpellBook.GetSpellBookSkillLineInfo(skillIndex)
    for slotIndex = info.itemIndexOffset + 1, info.itemIndexOffset + info.numSpellBookItems do
        local itemInfo = C_SpellBook.GetSpellBookItemInfo(slotIndex, Enum.SpellBookSpellBank.Player)
        if itemInfo and itemInfo.itemType == Enum.SpellBookItemType.Spell then
            print(itemInfo.name, itemInfo.spellID)
        end
    end
end

Check If Spell Is Usable and in Range

local function CanCastOnTarget(spellID, unit)
    local isUsable, insufficientPower = C_Spell.IsSpellUsable(spellID)
    if not isUsable then return false, insufficientPower end

    if C_Spell.SpellHasRange(spellID) then
        local inRange = C_Spell.IsSpellInRange(spellID, unit)
        if inRange == false then return false end
    end

    local cdInfo = C_Spell.GetSpellCooldown(spellID)
    -- Note: cdInfo.duration may be a secret value in 12.0
    -- Cannot branch on it — pass to Cooldown widget instead
    return true
end

Display Action Button State

local function UpdateActionButton(button, actionID)
    if not C_ActionBar.HasAction(actionID) then
        button:Hide()
        return
    end

    button.icon:SetTexture(C_ActionBar.GetActionTexture(actionID))

    local isUsable, noMana = C_ActionBar.IsUsableAction(actionID)
    if isUsable then
        button.icon:SetVertexColor(1, 1, 1)
    elseif noMana then
        button.icon:SetVertexColor(0.5, 0.5, 1)
    else
        button.icon:SetVertexColor(0.4, 0.4, 0.4)
    end

    -- Use activation overlay for proc detection
    if C_SpellActivationOverlay.IsSpellOverlayed(C_ActionBar.GetSpell(actionID)) then
        button.overlay:Show()
    else
        button.overlay:Hide()
    end
end

Monitor Totem State

local function UpdateTotemFrame(slot)
    local haveTotem, name, startTime, duration, icon, modRate, spellID = GetTotemInfo(slot)
    if haveTotem then
        -- startTime/duration may be secret in 12.0
        myTotemIcon:SetTexture(icon)
        myTotemCooldown:SetCooldown(startTime, duration)  -- Widget accepts secrets
        myTotemName:SetText(name)
    end
end

Query Shapeshift Forms

local function ShowAvailableForms()
    local numForms = GetNumShapeshiftForms()
    for i = 1, numForms do
        local icon, active, castable, spellID = GetShapeshiftFormInfo(i)
        print(C_Spell.GetSpellName(spellID), active and "(Active)" or "")
    end
end

Related Events