146 KiB
ClassicAPI — Lua Reference
Per-function reference for the calls ClassicAPI adds to the WoW 1.12.1 Lua environment. See the project README for installation and build instructions.
Contents
- Spell
GetSpellInfo(spellID)/GetSpellInfo(slot, bookType)C_Spell.GetSpellInfo(spellID)C_Spell.GetSpellName(spellID)C_Spell.GetSpellTexture(spellID)FindSpellBookSlotByID(spellID)GetSpellLink(spellID)/GetSpellLink(slot, bookType)C_Spell.GetSpellLink(spellID)C_Spell.GetSpellDescription(spellID)IsPassiveSpell(spellID)/IsPassiveSpell(slot, bookType)C_Spell.IsSpellPassive(spellID)IsPlayerSpell(spellID)IsSpellKnown(spellID, [isPet])IsUsableSpell(spell)/IsUsableSpell(slot, bookType)C_Spell.IsSpellUsable(spellID)GetSpellSchool(spellID)CastAutoRepeatSpell(name | spellID)
- Macros
- GameTooltip
- Quest
- Faction
- FriendList
- Item
C_Item.IsBound(itemLocation)C_Item.GetItemID(itemLocation)GetInventoryItemID(unit, slot)GetInventoryItemDurability(invSlot)C_Item.GetItemFamily(item)C_Item.GetItemCount(itemInfo, [includeBank], [includeUses])GetItemIcon(itemID)/C_Item.GetItemIcon(itemLocation)/C_Item.GetItemIconByID(item)C_Item.GetItemInfoInstant(item)C_Item.IsItemDataCachedByID(item)/C_Item.IsItemDataCached(itemLocation)C_Item.RequestLoadItemDataByID(item)/C_Item.RequestLoadItemData(itemLocation)C_Item.GetItemSpell(item)OffhandHasWeapon()C_Item.IsEquippableItem(item)C_Item.IsEquippedItem(item)C_Item.EquipItemByName(itemInfo [, dstSlot])C_Item.DoesItemExist(itemLocation)/C_Item.DoesItemExistByID(item)C_Item.GetItemName(itemLocation)/C_Item.GetItemNameByID(item)C_Item.GetItemQuality(itemLocation)/C_Item.GetItemQualityByID(item)C_Item.GetCurrentItemLevel(itemLocation)/C_Item.GetDetailedItemLevelInfo(item)C_Item.GetItemLink(itemLocation)C_Item.GetItemInventoryType(itemLocation)/C_Item.GetItemInventoryTypeByID(item)C_Item.IsLocked(itemLocation)C_Item.GetItemGUID(itemLocation)
- Container
- EquipmentSet
- Overview & file format
C_EquipmentSet.CanUseEquipmentSets()C_EquipmentSet.GetNumEquipmentSets()C_EquipmentSet.GetEquipmentSetIDs()C_EquipmentSet.GetEquipmentSetID(name)C_EquipmentSet.GetEquipmentSetInfo(setID)C_EquipmentSet.GetIgnoredSlots(setID)C_EquipmentSet.GetItemIDs(setID)C_EquipmentSet.GetItemLocations(setID)C_EquipmentSet.CreateEquipmentSet(name [, icon])C_EquipmentSet.SaveEquipmentSet(setID [, icon])C_EquipmentSet.ModifyEquipmentSet(setID, newName)C_EquipmentSet.DeleteEquipmentSet(setID)C_EquipmentSet.IgnoreSlotForSave(slot)/UnignoreSlotForSave/IsSlotIgnoredForSave/ClearIgnoredSlotsForSaveC_EquipmentSet.EquipmentSetContainsLockedItems(setID)C_EquipmentSet.UseEquipmentSet(setID)EQUIPMENT_SETS_CHANGEDeventEQUIPMENT_SWAP_PENDINGeventEQUIPMENT_SWAP_FINISHEDevent
- Class
- Unit
- State
- CharacterList
- Chat
- AddOns
- Combat
- Table
- Input
- Talent
- Time
GetServerTime()C_DateAndTimeoverviewC_DateAndTime.GetCurrentCalendarTime()C_DateAndTime.GetCalendarTimeFromEpoch(epoch)C_DateAndTime.AdjustTimeByDays(date, days)/AdjustTimeByMinutes(date, minutes)C_DateAndTime.CompareCalendarTime(lhs, rhs)C_DateAndTime.GetServerTimeLocal()C_DateAndTime.GetSecondsUntilDailyReset()
- Events
- Globals
Spell
GetSpellInfo(spellID) / GetSpellInfo(slot, bookType)
Returns the same nine values as 3.3.5's GetSpellInfo, plus a 10th
value: spellID, for any spell ID — including spells the player
has not learned. Stock 1.12 has no GetSpellInfo Lua function at all
(only GetSpellName/GetSpellTexture, both of which take a spellbook
slot rather than an ID), so addons that need spell metadata for
arbitrary IDs (raid frames, debuff trackers, aura libraries) currently
can't get it.
Returns name, rank, icon, cost, isFunnel, powerType, castTime, minRange, maxRange, spellID. All read directly from Spell.dbc (with
SpellIcon.dbc, SpellCastTimes.dbc, and SpellRange.dbc for the
indirected fields). Cast time is in milliseconds; ranges are floats in
yards. isFunnel is a real boolean (true/false), matching 3.3.5's
behavior. Returns nil if the spell ID is out of range.
Two input forms are accepted:
GetSpellInfo(spellID)— direct DBC lookup by ID.GetSpellInfo(slot, bookType)— same shape as 1.12'sGetSpellName(slot, bookType).slotis 1-based,bookTypeis"spell"(player) or"pet". The slot is resolved to a spellID via the engine's spellbook array, then the same DBC reads run. Returnsnilfor empty / out-of-range slots.
local name, rank, icon, _, _, _, _, _, _, spellID = GetSpellInfo(133)
-- name="Fireball", rank="Rank 1", icon="Spell\\Fire\\...", spellID=133
-- spellbook overload
local _, _, _, _, _, _, _, _, _, id = GetSpellInfo(1, "spell")
-- id is the spellID at player spellbook slot 1
Note on the 10th return. Modern WoW (5.0+) added the spellID as the 14th return of its slimmer signature. We kept the existing 9 returns (so addons that worked against the previous signature still work) and just appended
spellIDat position 10.
C_Spell.GetSpellInfo(spellID)
Modern table-style accessor for the same data. Returns a Lua table of
the spell's metadata, or nil if the spell ID is out of range.
Table fields:
| Field | Type | Notes |
|---|---|---|
name |
string | Localized name |
iconID |
string | Icon path (e.g. "Interface\\Icons\\Spell_Fire_FlameBolt"). See note below. |
castTime |
number | Base cast time in milliseconds, or 0 for instant |
minRange |
number | Yards, or 0 if not applicable |
maxRange |
number | Yards, or 0 if not applicable |
spellID |
number | Echo of the input |
rank |
string | Localized rank (e.g. "Rank 1") — vanilla extra, not in modern's spec |
cost |
number | Base ManaCost — vanilla extra |
isFunnel |
boolean | True for funnel-channeled spells — vanilla extra |
powerType |
number | 0=mana, 1=rage, 2=focus, 3=energy, 4=happiness — vanilla extra |
local info = C_Spell.GetSpellInfo(133)
-- info.name = "Fireball"
-- info.iconID = "Interface\\Icons\\Spell_Fire_FlameBolt"
-- info.castTime = 1500
-- info.spellID = 133
-- info.rank = "Rank 1"
-- ... etc.
Deviation from modern. Modern WoW returns
iconIDas afileID:number. Vanilla 1.12 has no fileID system — assets are referenced by path strings. We surface the icon path here so it's directly usable withtexture:SetTexture(info.iconID). If you're backporting code that expects a number, this is the field to adjust.
Vanilla extras. The four fields beyond the modern spec (
rank/cost/isFunnel/powerType) are present because 1.12 has them inSpell.dbcand the previous-generationGetSpellInfoexposed them. Including them costs nothing and helps addons backporting from 3.3.5 where the same data was returned positionally.
Equivalent to the function of the same name introduced in 4.0.
C_Spell.GetSpellName(spellID)
Returns the localized name of spellID, or nil if the spell ID is out
of range or has no name in the current locale. Convenience accessor for
the name field of C_Spell.GetSpellInfo
when that's all you need — single field read, no DBC indirection beyond
the locale lookup.
local name = C_Spell.GetSpellName(133) -- "Fireball"
Equivalent to the function of the same name introduced in 10.0.
C_Spell.GetSpellTexture(spellID)
Returns the icon path string for spellID (read from SpellIcon.dbc
via the spell's SpellIconID field), or nil if the spell ID is out
of range or the icon record is empty.
Path string, not fileID. Modern WoW returns this as a
fileID:number. Vanilla 1.12 has no fileID system — see the same note onC_Spell.GetSpellInfo'siconIDfield. Pass directly totexture:SetTexture(...).
local path = C_Spell.GetSpellTexture(133)
-- path = "Interface\\Icons\\Spell_Fire_FlameBolt"
Equivalent to the function of the same name introduced in 10.0.
FindSpellBookSlotByID(spellID)
Inverse of 1.12's GetSpellName(slot, bookType). Given a spellID,
returns the 1-based slot it occupies in the player or pet spellbook,
along with the matching bookType so the result feeds directly into
slot-and-bookType APIs (GetSpellName, GetSpellTexture,
GameTooltip:SetSpell, etc.).
slot, bookType = FindSpellBookSlotByID(spellID)
- Returns
(slot, "spell")if the spell is in the player spellbook. - Returns
(slot, "pet")if it's only in the pet spellbook. - Returns
nilif the spellID isn't currently in either book.
Player book is searched first, so if a spell somehow appeared in both (unusual but possible for special pet-shared abilities), the player slot wins.
local slot, book = FindSpellBookSlotByID(133)
if slot then
GameTooltip:SetSpell(slot, book) -- shows full caster-scaled tooltip
end
Equivalent to the legacy function of the same name introduced in 3.0
(later renamed to FindSpellBookSlotBySpellID in 5.x).
GetSpellLink(spellID) / GetSpellLink(slot, bookType)
Returns the chat-style spell hyperlink and the spellID:
link, spellID = GetSpellLink(spellID)
= GetSpellLink(slot, bookType)
Format is |cff71d5ff|Hspell:ID:0|h[Name]|h|r — the standard 1.12
spell-link wrapper. The trailing :0 after the spellID matches modern
WoW's hyperlink shape (where the field is a sub-data slot for
pet-spellbook flags etc.); 1.12 ignores it during link parsing, but
addons grepping with |Hspell:(%d+): patterns will pick it up
correctly.
Two input forms, mirroring GetSpellInfo:
GetSpellLink(spellID)— direct DBC lookup.GetSpellLink(slot, bookType)— resolves the spellbook slot to a spellID first. Useful when iterating the player's known spells: caller gets back both the link AND the underlying ID without a separate lookup.
Returns nil if the spellID/slot doesn't resolve to a real spell.
local link = GetSpellLink(133)
DEFAULT_CHAT_FRAME:AddMessage("Cast " .. link .. "!")
-- Walking the spellbook to print every learned spell:
for slot = 1, GetNumSpellTabs() and 100 or 100 do
local link, id = GetSpellLink(slot, "spell")
if not link then break end
-- ...
end
C_Spell.GetSpellLink(spellID)
Modern table-namespace variant. Same link string as
GetSpellLink(spellID),
but returns only the link — no spellID echo since the caller already
had it on hand to make the call.
local link = C_Spell.GetSpellLink(133) -- "|cff71d5ff|Hspell:133:0|h[Fireball]|h|r"
Equivalent to the function of the same name introduced in 4.0.
C_Spell.GetSpellDescription(spellID)
Returns the formatted spell description for any spellID — including
spells the player has not learned. $s1/$s2/$o1/$d-style
placeholders are resolved to base-rank values; ranges and durations
appear as actual numbers (e.g. "14 to 22 Fire damage", not
"$s1 to $s2 Fire damage"). Returns nil if the spell ID is out of
range or has no description in the current locale.
The 1.12 client doesn't expose this from Lua at all — the only existing
path is the scan-tooltip hack (set a hidden tooltip via
SetHyperlink("spell:"..ID) and read each TextLeftN:GetText() line).
That's slow, GC-heavy, and shares the global scan tooltip with every
other addon. This function calls the engine's own description formatter
directly — same code path the in-game tooltip uses, no UI side effects.
local desc = C_Spell.GetSpellDescription(133) -- Fireball Rank 1
-- "Hurls a fiery ball that causes 14 to 22 Fire damage and an additional
-- 2 Fire damage over 4 sec."
Equivalent to the function of the same name introduced in 4.0.
No caster scaling. Values reflect the spell's base rank — caster level / spell power / talents are not applied. Modern WoW behaves the same way when called outside a unit context. If you need the "currently displayed" tooltip text with caster scaling, use
GameTooltip:SetSpellByIDand read line strings from there.
IsPassiveSpell(spellID) / IsPassiveSpell(slot, bookType)
Returns true if the spell is passive (no cast bar — applies its effect
as soon as it's learned/equipped), false otherwise. Returns nil for
invalid spell IDs / out-of-range slots.
Reads Attributes bit 6 (SPELL_ATTR_PASSIVE = 0x40) directly off the
Spell.dbc record. Used by aura libraries and talent code to decide
whether a spell needs cast-bar tracking.
IsPassiveSpell(6603) -- true (Auto Attack)
IsPassiveSpell(133) -- false (Fireball)
-- spellbook overload mirrors GetSpellInfo's
IsPassiveSpell(1, "spell") -- true/false depending on slot 1
Equivalent to the function of the same name introduced in 3.0. Modern
WoW renamed it to C_Spell.IsSpellPassive(spellID)
(word order flipped) when it moved into the C_Spell namespace; we
ship both forms.
C_Spell.IsSpellPassive(spellID)
Modern table-namespace form of IsPassiveSpell.
Same return semantics, but takes a spellID only — C_Spell.* calls
don't accept the older spellbook slot + bookType shape.
C_Spell.IsSpellPassive(6603) -- true (Auto Attack)
Equivalent to the function of the same name introduced in 10.0.
IsPlayerSpell(spellID)
Returns true if the player currently knows the given spellID, false
otherwise. Covers everything granted by SMSG_LEARNED_SPELL:
- Trained class abilities (the obvious case)
- Racial abilities
- Talent passives the player has invested in
- Profession recipes — including ones from vendors / discovered via tradeskill — without needing to have the trade skill window open
- Anything else the engine considers "known"
IsPlayerSpell(133) -- true if you have Fireball
IsPlayerSpell(2963) -- true for a tailor who knows Bolt of Linen
-- (works without opening the Tailoring window)
Only the current rank counts. For ranked spells (passives, trained ranks), only the spellID of the player's current rank returns
true— lower-rank IDs returnfalseeven though the player conceptually "has" them. Matches the same semantic Classic Era 1.15.x uses: a player with 5/5 Unbreakable Will seesIsPlayerSpell(14791)(rank 5) as true but rank 4 / rank 3 / etc. as false.This is by design — the engine's spell-knowledge bitmap stores one bit per spellID, and the highest-rank spellID is the one set when you train up. To check "do I have at least rank N", use the rank-N spellID specifically.
Reads a single bit from the engine's spell-knowledge bitmap at
[0x00B710FC] — (bitmap[spellID >> 5] & (1 << (spellID & 31))) != 0.
The same lookup the engine itself does internally. No spellbook walk,
no talent walk, no profession-window dependency.
Equivalent to the function of the same name introduced in 5.0.
IsSpellKnown(spellID, [isPet])
Returns true if the given spellID is currently in the player's (or
pet's) spellbook arrays — the same source the in-game spellbook UI
displays. Strict semantics: only counts spells that have a
spellbook button. isPet defaults to false.
IsSpellKnown(2050) -- true if Lesser Heal is trained
IsSpellKnown(2649, true) -- true if your hunter pet has Growl
IsSpellKnown(133) -- false on a Priest (Fireball is a Mage spell)
Not the same as
IsPlayerSpell. Modern WoW deliberately splits these two:IsSpellKnownis the strict "in the spellbook UI" check,IsPlayerSpellis the broad "any kind of known" query. The split matters because:
Spell type IsPlayerSpellIsSpellKnownTrained class ability (Fireball) truetrueActive talent grant (Mortal Strike) truetruePassive talent (Wand Spec, Imp Fireball) truefalseProfession recipe (Bolt of Linen) truefalseUse
IsPlayerSpellfor "do I have access to this effect at all"; useIsSpellKnownfor "is this in my spellbook so I can put it on an action bar".
Implementation walks VAR_PLAYER_SPELLBOOK (0x00B700F0) when
isPet=false or VAR_PET_SPELLBOOK (0x00B6F098) when isPet=true.
Verified to match 3.3.5's Script_IsSpellKnown semantics — that
function does the same spellbook walk in its inner helper at
0x0053B4E0 (player array [0x00BE6D88], pet array [0x00BE7D98],
same shape just different addresses).
Equivalent to the function of the same name introduced in 3.0.
IsUsableSpell(spell) / IsUsableSpell(slot, bookType)
Returns (usable, noMana) for a spell, matching the modern
3.0+ signature. Returns (1, nil) when the spell is castable,
(nil, 1) when only mana is preventing it, (nil, nil) for any
other reason (unknown spell, dead, etc.). Matches the 1.12-style
1/nil return convention used by the existing
Script_IsUsableAction.
Two arg shapes accepted:
IsUsableSpell(spellID)— direct spellID lookup.IsUsableSpell(slot, bookType)—bookTypeis"spell"(player) or"pet". Resolves to a spellID via the same engine spellbook arraysGetSpellInfo/GetSpellLinkwalk.
IsUsableSpell(133) -- Fireball: 1, nil if you have mana, nil, 1 if not
IsUsableSpell(1, "spell") -- player spellbook slot 1
What this function checks:
- Player knows the spell (engine's spell-knowledge bitmap — covers trained class abilities, talent passives, racials, profession recipes).
- Player is alive (HEALTH > 0).
- Spell is not on cooldown (engine's per-spell cooldown helper).
- Player has enough of the spell's power type for the base cost (mana / rage / focus / energy / happiness) — only this failure sets
noMana=true.- Player has all required reagents in bags (Spell.dbc Reagent[8] / ReagentCount[8]).
What this function doesn't check (different concerns or post-vanilla concepts): silence, GCD, stance/form, range, target type, line-of-sight, casting state.
Verified empirically on Turtle WoW for the mana branch: Renew rank 3 (cost 105) is reported usable at 144 mana and unusable at 39 mana, transitioning at exactly the cost boundary. Cooldown and reagent checks ship in the same implementation but haven't been exercised in-game; if you find an inconsistency, the reagent offsets (+0x110 / +0x130) and cooldown helper (
0x006E2EA0) are the components to verify.
Equivalent to the function of the same name introduced in 3.0.
C_Spell.IsSpellUsable(spellID)
Modern table-namespace form. Same logic as
IsUsableSpell(spellID)
but returns proper booleans (isUsable, insufficientPower) per
the C_Spell.* convention rather than 1/nil pairs.
local usable, noMana = C_Spell.IsSpellUsable(133)
-- usable=true, noMana=false → cast it
-- usable=false, noMana=true → drink up
-- usable=false, noMana=false → unknown spell, dead, or other block
Equivalent to the function of the same name introduced in 10.x.
GetSpellSchool(spellID)
Returns (schoolID, schoolName) for any spell — known to the player
or not. schoolID is 1-based; schoolName is the locale-independent
English name.
| schoolID | schoolName |
|---|---|
| 1 | "Physical" |
| 2 | "Holy" |
| 3 | "Fire" |
| 4 | "Nature" |
| 5 | "Frost" |
| 6 | "Shadow" |
| 7 | "Arcane" |
Reads directly from Spell.dbc record +0x04. Vanilla 1.12 stores
School as a single 0-based integer (no multi-school SchoolMask
combinations — that's a TBC+ thing), so a spell belongs to exactly
one school.
Returns nil for invalid spellIDs (out of range or unpopulated
Spell.dbc slot).
local id, name = GetSpellSchool(133) -- 3, "Fire" (Fireball)
local id, name = GetSpellSchool(116) -- 5, "Frost" (Frostbolt)
local id, name = GetSpellSchool(635) -- 2, "Holy" (Holy Light)
Useful for combat-log breakdown addons, dispel-eligibility checks,
resistance-aware aura libraries, and damage-meter school tagging.
Previously addons either maintained hardcoded spellID → school
tables or scanned tooltips for the first-line color tag.
CastAutoRepeatSpell(name | spellID)
Spammable variant of CastSpellByName for auto-repeat spells
(Shoot/Wand/Auto-Shot). Only calls into the engine's cast path when
no auto-repeat is currently active, so a held keybind doesn't toggle
the same spell back off the way CastSpellByName does.
| Engine state | Behavior | Return |
|---|---|---|
| Nothing auto-repeating | Starts the cast | true if the spell is now auto-repeating, else false (e.g. you passed a non-auto-repeat spell) |
| Already casting this spell | No-op | true |
| Already casting other spell | No-op | false |
Replaces the action-bar loop workaround:
-- Before
for i = 1, 120 do
if IsAutoRepeatAction(i) then return end
end
CastSpellByName("Shoot")
-- After
CastAutoRepeatSpell("Shoot")
CastAutoRepeatSpell("Shoot") -- by name (matches what CastSpellByName accepts)
CastAutoRepeatSpell(75) -- by spellID (Auto Shot rank 1)
String input matches the active spell's Spell.dbc name case-
insensitively and tolerates a trailing (Rank N) suffix the same
way CastSpellByName itself does — "Shoot" and "Shoot(Rank 1)"
both compare equal to a Shoot that's already auto-repeating.
Reads [VAR_ACTIVE_AUTO_REPEAT_SPELL] (0x00CEAC30) — the same
dword IsAutoRepeatAction's inner helper at 0x004E55B0 consults.
Delegates to Script_CastSpellByName (0x004B4AB0) for the cast
itself, so resolution semantics (which rank, target rules, etc.)
are identical to the engine's own global.
Using this from inside a macro action slot? See
CastAutoRepeatSpell as a macro cast line below for the additional
parser support that makes the slot tag correctly for action-bar UIs.
Macros
Engine-level extensions to how macros are parsed and dispatched. These
don't add new Lua functions — they teach the engine to recognize input
forms it didn't accept in stock 1.12. Macro authors get them for free
once ClassicAPI.dll is loaded.
Vanilla 1.12 doesn't support [target=...]-style macro conditionals
natively; we don't add those. If you have a separate DLL/addon that
does (nampower's conditional macros, SuperWoWhook, etc.), the
extensions below compose with it — that layer strips the bracket
clause and forwards the cleaned tail to CastSpellByName, which then
flows through our additions.
Numeric spellIDs in /cast and CastSpellByName
Pure-numeric input is now accepted anywhere a spell name would be:
/cast 5019 -- in a macro line; casts Shoot if known
CastSpellByName("5019") -- same effect from Lua / /run / chat
The spellID is resolved through Spell.dbc to the locale-resolved
name, then handed to the engine's existing name resolver — so all the
normal downstream behavior applies: the spellbook lookup gates on
"player knows this spell," action-bar UI sees the cast as if it had
been named, macros containing /cast 5019 get tagged with the right
spellID in the engine's spell-state cache (so IsCurrentAction(slot)
and IsAutoRepeatAction(slot) work for the macro slot).
| Input | Outcome |
|---|---|
/cast 5019 |
Casts Shoot if you know it (any rank, highest known) |
/cast 1234 |
Falls through as "unknown spell," same as /cast Foo |
/cast Shoot |
Unchanged from vanilla — names still work |
/cast 5019(Rank 1) |
Falls through — rank suffix with a numeric stem isn't supported (use the name form if you need a specific rank) |
Implemented as a single hook on the engine's name → spellbook-slot
resolver at 0x004B3950 — covers /cast, /castsequence aliases,
CastSpellByName, the macro parser's tagging path, and anywhere
else the engine resolves a spell name. Numeric input with garbage
trailing characters falls through unchanged.
CastAutoRepeatSpell as a macro cast line
Putting CastAutoRepeatSpell("Shoot") in a macro body now tags the
macro with Shoot's spellID the same way /cast Shoot or
CastSpellByName("Shoot") would. Without this, the macro casts
correctly but vanilla's macro parser doesn't know to associate the
slot with any spell — so action-bar UIs that call
IsCurrentAction(slot) / IsAutoRepeatAction(slot) (pfUI's
actionbar, ShaguTweaks, etc.) never light up the slot.
Recognized forms in a macro body:
CastAutoRepeatSpell("Shoot") -- by name (string)
CastAutoRepeatSpell(5019) -- not yet — macro parser only recognizes the string form
The numeric form works for the cast itself (via the function's
runtime resolution), but the macro parser only scans for the string
form when tagging. To get the slot to highlight when using the
spellID, write CastAutoRepeatSpell("Shoot") instead.
The engine's first-match-wins rule still applies — if your macro is:
/cast Wand
CastAutoRepeatSpell("Shoot")
…the macro is tagged with Wand (the engine recognized /cast Wand
on line 1; our additional pattern is only consulted when the engine
didn't find any of its own patterns).
Macro tagging happens at macro edit/save time. Existing macros need to be opened in the Macro UI and re-saved once after dropping in the new DLL to pick up the new parser behavior.
GameTooltip
GameTooltip:SetItemByID(itemID)
Modern method that renders an item tooltip from just an itemID. The
1.12 workaround was constructing an item hyperlink and calling
SetHyperlink — tooltip:SetHyperlink("item:" .. id .. ":0:0:0:0:0:0:0")
— which works but forces every caller to know the hyperlink format.
GameTooltip:SetOwner(UIParent, "ANCHOR_CURSOR")
GameTooltip:SetItemByID(6948) -- Hearthstone
GameTooltip:Show()
Implementation: snprintf the hyperlink string and dispatch to the
existing Script_GameTooltip_SetHyperlink (registry slot 12).
Item cache caveat. 1.12 lazy-loads item data into the client-side cache at
0x00C0E2A0— the cache is fed bySMSG_ITEM_QUERY_SINGLE_RESPONSEonly when the player encounters an item. For an itemID the player has never seen, the tooltip renders only the name; full data appears once the cache is warm.The fix is to ensure the item is cached before opening the tooltip:
if C_Item.IsItemDataCachedByID(itemID) then GameTooltip:SetItemByID(itemID) else C_Item.RequestLoadItemDataByID(itemID) -- register for ITEM_DATA_LOAD_RESULT(loadedItemID, success) -- and call SetItemByID once the matching itemID arrives endThis caching behavior matches what
C_Item.GetItemInfoInstantdocuments — same underlying cache. Modern WoW (5.0+) has the same caveat, just withC_Item.RequestLoadItemData(itemLocation)/Item:OnItemLoad-style continuation.
Equivalent to the function of the same name introduced in 8.0.
GameTooltip:SetUnitAura(unit, index, [filter])
Modern unified-aura method. 1.12 splits this into SetUnitBuff and
SetUnitDebuff; we dispatch to the right one based on the filter
string ("HARMFUL" → SetUnitDebuff, anything else → SetUnitBuff).
filter defaults to helpful when omitted, matching modern.
GameTooltip:SetOwner(UIParent, "ANCHOR_CURSOR")
GameTooltip:SetUnitAura("player", 1, "HELPFUL") -- first buff
GameTooltip:SetUnitAura("player", 1, "HARMFUL") -- first debuff
GameTooltip:SetUnitAura("player", 1) -- defaults to HELPFUL
GameTooltip:Show()
Pure dispatcher — no engine changes; the underlying logic is whatever
1.12's SetUnitBuff / SetUnitDebuff already does. Just lets you use
the modern call shape (which most aura libraries backport from)
without conditionally splitting on filter.
Equivalent to the function of the same name introduced in 6.0.
GameTooltip:SetSpellByID(spellID)
Renders a spell tooltip for any spellID, including spells the player has
not learned. The stock 1.12 GameTooltip:SetSpell(slot, bookType) only works
for entries in the player's spellbook (or pet book). SetSpellByID bypasses
the spellbook indirection and calls WoW's internal tooltip builder directly.
GameTooltip:SetOwner(UIParent, "ANCHOR_CURSOR")
GameTooltip:SetSpellByID(133) -- Fireball
GameTooltip:Show()
Equivalent to the function of the same name introduced in 3.0.
GameTooltip:SetTalentByID(talentID)
Renders a tooltip for the talent identified by Talent.dbc primary
key — the natural pair to
GetTalentIDByIndex.
Works for any class's talents, not just the player's.
Two-tier resolution:
| Tier | When it applies | Tooltip rendered |
|---|---|---|
| Player class (rich) | talentID belongs to one of the player's loaded tabs |
Full talent tooltip — name, "Rank N/M", description, prereqs, "click to learn" prompts |
| Cross-class (fallback) | talentID is from another class |
Spell tooltip for the talent's rank-1 spellID — name, cast time, range, mana cost, description |
The fallback exists because vanilla 1.12 only loads the local
player's class talent data into the engine's per-player TabInfo
arrays. For other classes, we look up the talent in Talent.dbc
directly and dispatch the rank-1 spell tooltip — functionally
"what does this talent do?" without the rank counter. Modern WoW
adds talent name and "Rank 0/N" decorations on top of the spell
description for cross-class; we don't replicate that here yet.
Silent no-op (no tooltip change) when:
talentIDdoesn't match any record inTalent.dbctalentIDisnil, non-numeric, or non-positive
-- Player's own class — rich tooltip
local talentID = GetTalentIDByIndex(1, 9) -- player's tab 1, talent 9
GameTooltip:SetOwner(UIParent, "ANCHOR_CURSOR")
GameTooltip:SetTalentByID(talentID)
GameTooltip:Show()
-- Other class — spell tooltip for the talent's primary ability
GameTooltip:SetTalentByID(2065) -- works regardless of player class
GameTooltip:Show()
Equivalent to the function of the same name introduced in 5.0.
GameTooltip:SetInventoryItemByID(itemID)
Renders the tooltip for the equipped instance of itemID —
walks character-pane slots 1..19, finds the matching item, and
shows it with its actual enchants, random-suffix stats, and
broken/locked state. Distinct from
SetItemByID, which shows the
clean ItemSparse data with no instance-specific decorations.
For example, on a pair of boots with a run-speed enchant equipped:
| Method | Renders |
|---|---|
SetItemByID(<bootsID>) |
Base boots tooltip — name, armor, durability, level req. No enchant. |
SetInventoryItemByID(<bootsID>) |
Same plus Enchanted: Minor Speed and any random-suffix lines. |
Silent no-op if the item isn't currently equipped — fall back to
SetItemByID for unworn items, or check via
C_Item.IsEquippedItem first.
When the player has duplicates of the same itemID equipped (matched MH/OH weapons, identical rings, identical trinkets), the lower-numbered slot wins — MAINHAND before OFFHAND, FINGER1 before FINGER2, TRINKET1 before TRINKET2. Matches modern client behavior (verified empirically).
local _, _, _, _, _, _, _, _, _, _, _, _, _, link = GetItemInfo(itemID)
GameTooltip:SetOwner(UIParent, "ANCHOR_CURSOR")
if C_Item.IsEquippedItem(itemID) then
GameTooltip:SetInventoryItemByID(itemID) -- shows enchants/suffix
else
GameTooltip:SetItemByID(itemID) -- shows base stats
end
GameTooltip:Show()
Equivalent to the function of the same name introduced in 8.0.
Quest
GetQuestIDFromLogIndex(index)
Returns the questID (Quest.dbc row ID) for the entry at the given 1-based
quest log index. In 3.3.5 this came as the 9th return of GetQuestLogTitle;
in 1.12 it isn't returned at all, even though the engine has it internally.
- Returns the questID for real quests.
- Returns
0for header rows (zone / category dividers). - Returns
nilif the index is out of range.
for i = 1, GetNumQuestLogEntries() do
local title, level, questTag, isHeader, isCollapsed, isComplete
= GetQuestLogTitle(i)
local questID = GetQuestIDFromLogIndex(i) -- 0 for headers
-- ...
end
C_QuestLog.RequestLoadQuestByID(questID)
Asks the engine to fetch the static data for questID (title, description,
objectives, reward text) from the server if not already cached. Returns no
values — fire-and-forget, matching modern WoW's signature.
Fires QUEST_DATA_LOAD_RESULT(questID, success) when the data lands in the
cache. Synchronously fired when the data was already cached
(so polling code paths still work), asynchronously fired after
SMSG_QUEST_QUERY_RESPONSE lands when the engine had to round-trip to the
server.
Vanilla quirk: the engine has no native bool format code —
successarrives as1/0(number), nottrue/false, just likeITEM_DATA_LOAD_RESULT. Idiomatic check isif success == 1 then ....
Vanilla limitation: for invalid questIDs (ones the server doesn't have), the 1.12 server silently drops the query — it doesn't send a "not found" response packet. The engine's pending callback never resolves, so
QUEST_DATA_LOAD_RESULTdoesn't fire withsuccess=0either. Modern Classic Era servers explicitly respond with an error for invalid IDs, which is why modernRequestLoadQuestByIDreliably firessuccess=false; vanilla doesn't. Addons that need to handle "request timed out" should use their own timer (the Lua polyfill at!!!ClassicAPI/Util/QuestUtil.luauses a 180-second wait).
local f = CreateFrame("Frame")
f:RegisterEvent("QUEST_DATA_LOAD_RESULT")
f:SetScript("OnEvent", function()
-- vanilla 1.12: event payload is in `arg1`, `arg2`, ... globals
if event == "QUEST_DATA_LOAD_RESULT" and arg2 == 1 then
local questID = arg1
-- title/description/objectives are now in the engine's quest cache
end
end)
C_QuestLog.RequestLoadQuestByID(2)
C_QuestLog.GetTitleForQuestID(questID)
Returns the title (string) for questID from the engine's quest static-info
cache, or nil if the data isn't loaded. Doesn't require the quest to be
in the player's quest log — works for any questID once its data has been
fetched. Header rows are excluded (their titles live in QuestSort.dbc,
not in this cache); for those you'd use the existing GetQuestLogTitle.
The cache is populated lazily — by the engine's own quest-log path when
the player has the quest, or explicitly by
C_QuestLog.RequestLoadQuestByID. If the title isn't there yet, queue a
load and read on the event:
local f = CreateFrame("Frame")
f:RegisterEvent("QUEST_DATA_LOAD_RESULT")
f:SetScript("OnEvent", function()
if event == "QUEST_DATA_LOAD_RESULT" and arg2 == 1 then
local title = C_QuestLog.GetTitleForQuestID(arg1)
if title then
-- title is now available
end
end
end)
C_QuestLog.RequestLoadQuestByID(215)
Equivalent to the function of the same name introduced in 5.0.
Faction
GetFactionIDByIndex(factionIndex)
Returns the factionID (Faction.dbc row ID) for the entry at the given 1-based
displayed-faction index. Modern WoW (5.0+, including Classic Era 1.15.x)
returns this as the 14th value of GetFactionInfo; older clients (1.12
through 3.3.5) don't expose it from Lua at all, even though the engine
uses it internally to look up Faction.dbc.
- Returns the factionID for real factions.
- Returns
0for header / category rows ("Other","Inactive", etc.) — matching the modern Classic Era client, which puts0inGetFactionInfo'sfactionIDslot for those rows. - Returns
nilif the index is out of range.
The "headers normalize to 0" rule deliberately matches modern WoW
(5.0+) behavior. The 1.12 engine actually returns 0 for some header
types ("Other") and -1 for others ("Inactive"-style pseudo-rows);
we collapse both to 0 so the user-facing convention is consistent.
for i = 1, GetNumFactions() do
local name, _, _, _, _, _, _, _, isHeader = GetFactionInfo(i)
if not isHeader then
local factionID = GetFactionIDByIndex(i)
-- ...
end
end
GetFactionInfoByID(factionID)
Returns the same eleven values as GetFactionInfo(factionIndex), keyed by
factionID instead of displayed index:
name, description, standingID, barMin, barMax, barValue,
atWarWith, canToggleAtWar, isHeader, isCollapsed, hasRep
Works for any factionID present in Faction.dbc, not just factions the
player has rep with:
- In the player's reputation list — full data, identical to
GetFactionInfo(displayedIndex). - Not in the reputation list — name and description from
Faction.dbc, Neutral defaults for the rep fields:standingID = 4,barMin = 0,barMax = 3000,barValue = 0, all flagsnil. Matches what 3.3.5'sGetFactionInfoByIDreturns for unencountered factions. - Invalid factionID (out of range or empty DBC slot) —
nil.
local name, _, standing = GetFactionInfoByID(69) -- Darnassus
-- name = "Darnassus", standing = 5 (Friendly), etc. (encountered)
local name = GetFactionInfoByID(574) -- Caer Darrow (faction that can't be encountered in standard Vanilla)
-- name = "Caer Darrow" — works even if you never had rep with it
Equivalent to the function of the same name introduced in 3.0.
GetFactionParentID(factionID)
Returns the parent factionID for a faction in a hierarchy (e.g.
Stormwind's parent is Alliance Forces; The Defilers's parent is
Horde Forces). Returns 0 for top-level factions with no parent,
or nil for invalid factionIDs.
GetFactionParentID(72) -- 469 (Stormwind → Alliance)
GetFactionParentID(469) -- 0 (Alliance is top-level)
GetFactionParentID(99999) -- nil
Modern WoW returns this as the 13th value of GetFactionInfoByID;
we expose it as its own getter since 1.12's GetFactionInfo doesn't
have the slot.
Reads Faction.dbc ParentFactionID at record +0x48 directly —
no displayed-list dependency, works for any faction in the DBC
regardless of whether the player has rep with it.
Equivalent to the function of the same name introduced in 3.0 (as
the 13th return of GetFactionInfoByID).
C_Reputation.GetFactionStandings()
Returns a flat { [factionID] = currentStanding } table covering
every faction in the player's reputation list. currentStanding is
the same value GetFactionInfo puts in its barValue slot — `base
- delta` from the rep slot, signed.
Always returns a table (possibly empty); never nil.
local standings = C_Reputation.GetFactionStandings()
for factionID, standing in pairs(standings) do
print(GetFactionInfoByID(factionID), standing)
end
Unlike a GetNumFactions + GetFactionInfo walk, this skips header
rows entirely and doesn't depend on the player having opened the
reputation pane recently — it reads straight out of the per-faction
rep-slot array, which the engine keeps populated for every faction
the player has rep with.
If you need names instead of IDs, layer GetFactionInfoByID on top:
local byName = {}
for factionID, standing in pairs(C_Reputation.GetFactionStandings()) do
byName[GetFactionInfoByID(factionID)] = standing
end
This is a ClassicAPI-only call; modern WoW's closest equivalent is
the 11.x C_Reputation.GetFactions(), which returns an array of
struct tables rather than a flat map.
C_Reputation.GetWatchedFactionData()
Returns a table describing the faction shown above the XP bar, or
nil if no faction is being watched. Backports the modern
struct-style accessor — vanilla's GetWatchedFactionInfo() returns
the same data as a 5-tuple without the factionID, which is the field
modern callers rely on most.
Fields populated (a subset of the modern schema — only what 1.12's engine actually has):
| Field | Type | Notes |
|---|---|---|
factionID |
number | Faction.dbc record ID |
name |
string | Locale-applied |
description |
string | Locale-applied (may be "") |
reaction |
number | 1=Hated .. 8=Exalted |
currentReactionThreshold |
number | Band min standing value |
nextReactionThreshold |
number | Band max standing value |
currentStanding |
number | Current standing (base + delta) |
atWarWith |
boolean | At-war flag (rep slot flags bit 1) |
canToggleAtWar |
boolean | Can-toggle-at-war flag (bit 4) |
isWatched |
boolean | Always true (it IS the watched faction) |
isHeader |
boolean | Always false (factions only) |
Fields the modern API exposes but 1.12 has no source for —
isChild, isHeaderWithRep, isCollapsed, hasBonusRepGain,
canSetInactive, isAccountWide — are omitted rather than
fabricated. Addons that need to feature-detect can check
data.isAccountWide ~= nil.
local data = C_Reputation.GetWatchedFactionData()
if data then
print(string.format("%s (%d): %d / %d",
data.name, data.factionID,
data.currentStanding - data.currentReactionThreshold,
data.nextReactionThreshold - data.currentReactionThreshold))
end
Equivalent to the function of the same name introduced in 10.x; matches the Classic Era 1.15.x return shape for the fields it populates.
Implementation reads the watched RepListID from the player's
+0xE68 sub-struct, indexes the per-faction rep slot array at
0x00B73290 to recover the factionID, then derives the remaining
fields from Faction.dbc plus the static reaction-threshold tables
at 0x0080928C / 0x00809290.
C_Reputation.SetWatchedFactionByID(factionID)
Sets the faction shown above the XP bar by ID. The vanilla
SetWatchedFactionIndex(displayedIndex) accepts only a 1-based
displayed-list index, which forces addons to walk the index list
themselves. This wrapper takes a factionID directly.
factionID > 0— sets the watched faction. Works even for factions the player hasn't yet encountered (the rep bar will show nothing until the player gains rep, then displays normally).factionID == 0— clears the watched faction.factionID < 0— silent no-op.
Returns nothing. The engine's UI / event machinery refreshes
automatically — GetWatchedFactionInfo() reflects the new state
on the next call.
C_Reputation.SetWatchedFactionByID(72) -- Stormwind
print(GetWatchedFactionInfo()) -- "Stormwind", ...
C_Reputation.SetWatchedFactionByID(0) -- clear
print(GetWatchedFactionInfo()) -- (empty)
Implementation calls the engine's inner watched-faction setter
directly, bypassing Script_SetWatchedFactionIndex's
displayed-index round-trip.
C_Reputation.GetLastStandingChange()
Returns factionID, newStanding, repGained for the rep change
currently being fired, or nil if called outside that window.
Companion to FACTION_STANDING_CHANGED.
The triple is the same payload as the event's arg1, arg2, arg3, but
the getter is also live during the engine's
CHAT_MSG_COMBAT_FACTION_CHANGE dispatch on the same hook — useful
for addons that want to enrich the chat line with the factionID
(which vanilla's chat-event payload doesn't carry) without
double-registering for FACTION_STANDING_CHANGED:
local f = CreateFrame("Frame")
f:RegisterEvent("CHAT_MSG_COMBAT_FACTION_CHANGE")
f:SetScript("OnEvent", function()
local factionID, newStanding, repGained = C_Reputation.GetLastStandingChange()
if factionID then
-- factionID is the real ID, not a parsed-out name string
print(factionID, newStanding, repGained)
end
end)
Outside the in-flight FireNotify hook stack (i.e. anywhere except
inside a CHAT_MSG_COMBAT_FACTION_CHANGE or FACTION_STANDING_CHANGED
handler), returns nothing. There is no "last change" memory — the
state is cleared as soon as the dispatch returns.
This is a ClassicAPI-only call; modern WoW has no equivalent (modern
addons get the factionID from FACTION_STANDING_CHANGED directly, so
they don't need a separate getter).
FACTION_STANDING_CHANGED event
Fires once per reputation change with (factionID, newStanding, repGained):
| arg1 (factionID) | Faction.dbc row ID of the faction whose standing changed |
| arg2 (newStanding) | New total standing value (post-change barValue) |
| arg3 (repGained) | Signed delta — positive on gain, negative on loss |
Polyfills the modern event of the same name. Vanilla 1.12 exposes only
CHAT_MSG_COMBAT_FACTION_CHANGE, whose arg1 is the localized chat
string ("Your Stormwind reputation has increased by 100.") — addons
have to parse the text and reverse-resolve the faction name back to
an ID. This event lets addons skip that work.
Does not fire for the initial faction sync at login or /reload
— matches modern semantics. Only fires when a real reputation gain or
loss arrives from the server (SMSG_SET_FACTION_STANDING).
local f = CreateFrame("Frame")
f:RegisterEvent("FACTION_STANDING_CHANGED")
f:SetScript("OnEvent", function()
-- in vanilla 1.12 OnEvent receives no args; engine sets `event`
-- and `arg1..argN` as globals before invoking the handler.
if event == "FACTION_STANDING_CHANGED" then
local name = GetFactionInfoByID(arg1)
print(string.format("%s: %+d (now %d)", name, arg3, arg2))
end
end)
repGained is signed: positive for gains, negative for the rare loss
case (e.g. killing a Goblin Commodity Exchange NPC drops your rep
with Booty Bay).
Implementation notes
Hooks the engine's per-rep-change notify dispatcher at 0x0062C5F0
— the chokepoint called once per (factionID, signedDelta) from
the per-slot setter at 0x004D6330, gated by "value-actually-changed
AND notify-flag-set". The setter has already written the new delta
into the per-slot storage by the time the hook fires, so we read the
total back via FUN_REPUTATION_GET_STANDING(factionID) (0x004D6370)
to produce the newStanding payload.
The hook calls the original before firing our event so the engine's
CHAT_MSG_COMBAT_FACTION_CHANGE still fires first — no behavior
change for addons that depended on the chat text. A per-call
snapshot of (factionID, newStanding, repGained) is captured before
forwarding, which C_Reputation.GetLastStandingChange
exposes — so addons can read the structured payload from inside the
chat event without re-parsing the localized string.
FriendList
C_FriendList.SendWhoQueryByName(name)
Issues a /who name-filter query for a specific player. Results
buffer into the engine's WhoList so a normal WHO_LIST_UPDATE +
GetWhoInfo(i) flow can read them — no chat output, no
"Found N players matching..." system message.
Vanilla 1.12 exposes SendWho(query) and SetWhoToUI(flag) only as
separate primitives, so addons that want to silently look up a
single player's class/level/zone (e.g. to color an unknown name in
chat) have to manage state, cooldown timing, and friends-panel
suppression themselves. This collapses the invocation half of that
dance to one call with a clean true/false return.
Returns true if the query was sent, false if any of:
- the name was empty / nil
- the call is within the 5-second cooldown of a previous send
- the engine's WhoSystem isn't initialized yet (pre-login)
A false return is a no-op — the engine state isn't touched, no
pending flag is set, and the cooldown isn't extended. Safe to call
on every chat line that mentions an unknown player; the call will
naturally rate-limit.
The cooldown matches the server's: vanilla's CMSG_WHO is silent- dropped server-side at roughly 5-second granularity, so a faster client just wastes queries that won't get a response.
if C_FriendList.SendWhoQueryByName("Bob") then
-- query sent; result will arrive via WHO_LIST_UPDATE within ~1s
end
This call alone does not suppress the friends-panel popup on
response — for that, wrap FriendsFrame_OnEvent and gate on
C_FriendList.IsWhoQueryPending():
local original = FriendsFrame_OnEvent
_G.FriendsFrame_OnEvent = function()
if event == "WHO_LIST_UPDATE" and C_FriendList.IsWhoQueryPending() then
return
end
return original()
end
(Auto-suppressing the popup from C++ would require hooking the
engine's FrameScript_SignalEvent or the SMSG_WHO opcode handler —
both high-traffic / high-risk sites. The wrap above is reliable and
takes 5 lines, so it stays addon-side for now.)
Implementation reads the WhoSystem singleton from 0x00C28168 and
calls the inner sender at 0x005AEBB0
(__thiscall(this = WhoSystem, queryStr)), the same chokepoint
Script_SendWho tail-calls. The whoToUI flag at 0x00C2A12C is
flipped to 1 first so the SMSG_WHO handler routes results into the
list (WHO_LIST_UPDATE path) instead of printing to chat.
C_FriendList.IsWhoQueryPending()
Returns true within ~5 seconds of the most recent
SendWhoQueryByName that
returned true; otherwise false. Time-based — the engine doesn't
expose a "response arrived" hook to C++ yet, so the window is a
conservative upper bound on the response RTT, which in practice
lands within a few hundred ms.
The intended use is gating an addon-side FriendsFrame_OnEvent
wrap so the user-issued /who window still works while addon-
issued silent queries don't pop the panel — see the example under
SendWhoQueryByName.
Concurrent callers see a shared pending flag — if pfUI and another
addon both call SendWhoQueryByName close in time, both queries
contribute to the same pending window. This is acceptable for the
"suppress popup for any in-flight DLL-issued query" use case;
addons that need per-call tracking should manage their own ticket
state on top.
Item
C_Item.IsBound(itemLocation)
Returns true if the item at the given location is soulbound, false otherwise
(including when the slot is empty or the location is malformed). The 1.12
client tracks the soulbound bit on each item instance directly; previously
the only way to read it from Lua was a scan-tooltip hack
(SetBagItem + string-compare against the localized ITEM_SOULBOUND
constant) — slow, locale-fragile, and one of the hottest paths during bag
updates.
itemLocation is a table with one of these shapes (matching the modern
ItemLocation mixin):
{ equipmentSlotIndex = N } -- 1-based, character pane
{ bagID = B, slotIndex = S } -- both required
if C_Item.IsBound({equipmentSlotIndex = INVSLOT_HEAD}) then ... end
if C_Item.IsBound({bagID = 0, slotIndex = 1}) then ... end
C_Item.GetItemID(itemLocation)
Returns the itemID of the item at the given location, or nil if the slot
is empty or the location is malformed. Useful as the input to
GetItemInfoInstant/GetItemInfo when you only know which slot an item
came from (rather than its link or ID).
Accepts the same itemLocation shapes as IsBound:
local id = C_Item.GetItemID({equipmentSlotIndex = INVSLOT_HEAD})
if id then
local _, type, subtype = C_Item.GetItemInfoInstant(id)
-- ...
end
GetInventoryItemID(unit, slot)
Returns the itemID of the item equipped at slot (1-based) on unit,
or nil if the slot is empty / the unit isn't valid / the unit doesn't
expose its equipment to the local client. Same arg shape as 1.12's
GetInventoryItemLink(unit, slot) — drop-in for code that just needs
the ID and would otherwise have to parse the link string.
- For
"player"(and any token resolving to the local player, e.g."target"when self-targeted): walks the private inventory manager. Supports the full slot range (equipment 1..19, bag slots 20..23, bank slots, etc.) — same rangeGetItemBySlotaccepts internally. - For other player-controlled units (
"target","party1"..party4", inspect targets): reads the unit's broadcast visible-items array. Equipment slots 1..19 only. - For NPCs / creatures: returns
nil. The visible-items array isn't populated for non-player-controlled units in 1.12, so we gate this onUnitPlayerControlledto avoid the engine crash thatGetInventoryItemLinkitself would trigger on the same input.
local id = GetInventoryItemID("player", INVSLOT_HEAD)
if id then
local _, type, subtype = C_Item.GetItemInfoInstant(id)
-- ...
end
-- Inspect a party member without parsing a hyperlink:
local headID = GetInventoryItemID("party1", INVSLOT_HEAD)
GetInventoryItemDurability(invSlot)
Returns (current, maximum) durability for the player's equipped item
at invSlot (1-based, character-pane slots 1..19), or nothing if the
slot is empty or the item has no durability concept (rings, trinkets,
necks, backs, shirts, tabards, etc.).
current, maximum = GetInventoryItemDurability(invSlot)
local cur, max = GetInventoryItemDurability(INVSLOT_CHEST)
if cur then
-- cur, max are positive integers (e.g. 65, 65 for full chest)
end
-- Items without durability return nothing — both locals are nil:
local cur, max = GetInventoryItemDurability(INVSLOT_FINGER1)
-- cur == nil, max == nil
Player-only. Matches modern API: 3.3.5+
GetInventoryItemDurabilitytakes only the slot, no unit token. Inspect targets / party members' equipment durability isn't broadcast in 1.12, so we couldn't expose it for other units even if we wanted to.
(0, max)vs nothing. Items that have a durability concept but are currently broken (current == 0,max > 0) still return(0, max). The "nothing" return is reserved for items that have no durability fields populated at all —maxis the discriminator, matching the engine's ownGetInventoryItemBrokenlogic.
Reads ITEM_FIELD_DURABILITY (+0xA0) and ITEM_FIELD_MAXDURABILITY
(+0xA4) directly off the CGItem's m_objectFields descriptor at +0x114
— same descriptor C_Item.IsBound reads
FLAGS from. No DBC indirection.
Equivalent to the function of the same name introduced in 3.0.
C_Item.GetItemFamily(item)
Returns the BagFamily bitmask for an item — i.e., what kind of
specialty bag it belongs in. 0 means "general-purpose" (no specialty
bag preference). Returns nil if the item isn't in the cache.
familyBitmask = C_Item.GetItemFamily(item)
item accepts a numeric itemID or a string containing "item:NNN"
(the bare shorthand and full chat links both parse correctly), same as
C_Item.GetItemInfoInstant.
C_Item.GetItemFamily(2512) -- 1 (Wooden Arrow → quiver-family)
C_Item.GetItemFamily(2516) -- 2 (Light Shot → ammo pouch-family)
C_Item.GetItemFamily(6265) -- 4 (Soul Shard → soul bag-family)
C_Item.GetItemFamily(2447) -- 32 (Peacebloom → herb bag-family)
C_Item.GetItemFamily(6948) -- 0 (Hearthstone → general-purpose)
Bitmask values match modern WoW's encoding (1 << (familyID - 1)):
| Bit | Value | Family |
|---|---|---|
| 0 | 1 | Quiver (arrows) |
| 1 | 2 | Ammo Pouch (bullets) |
| 2 | 4 | Soul Shard Bag |
| 5 | 32 | Herb Bag |
| 6 | 64 | Enchanting Bag (modern) |
Encoding deviation under the hood. 1.12 actually stores the raw 1-based BagFamily ID (
arrow=1, bullet=2, soul shard=3, herb=6, …). Modern WoW (Wrath+) flipped to the bitmask form for the same field. We convert on the way out viabitmask = 1 << (rawID - 1), so callers backporting from modern see the encoding they expect — addons canband(family, FAMILY_BAG_HERB_BAG)directly.
Item-level data is reliable; bag-level is sparse. Individual loot items (arrows, bullets, shards, herbs) carry the field reliably, so
C_Item.GetItemFamilyworks for the auto-routing use case. Bag containers themselves (Soul Pouch, Enchanting Bag, Herb Pouch, etc.) leave the field at 0 in vanilla server data — at least on Turtle WoW. If you need to know "is this bag specialty", read the bag'ssubClassviaC_Item.GetItemInfoInstantinstead. The Quiver class is fully populated; everything else needs the subClass fallback.
nilvs0. Modern WoW returns0for items the cache lookup fails on; we returnnilso callers can distinguish "item not cached, retry after the event lands" from "item exists but has no family preference." Both are safe to treat as0for routing-logic purposes; the distinction helps debugging.
Auto-warmup on cache miss. First call for an uncached item returns
nilAND triggers the engine's cache fill in the background. Listen forGET_ITEM_INFO_RECEIVED(itemID, success)and retry once the matchingitemIDarrives. This matches Classic Era 1.15's observed behavior of "nil first call, value second call." We diverge from 1.15 in one detail: 1.15'sGetItemFamilydoesn't fire any event when the cache lands (silent fill), whereas we fireGET_ITEM_INFO_RECEIVEDto stay consistent with our other implicit- warmup paths (GetItemInfo,SetItemByID). Addons that already listen for that event get the notification for free.
Equivalent to the legacy global GetItemFamily (since 3.0) and the
modern C_Item.GetItemFamily introduced in 10.x.
C_Item.GetItemCount(itemInfo, [includeBank], [includeUses])
Returns the player's total count of itemInfo across bags (and
optionally bank slots).
count = C_Item.GetItemCount(itemInfo [, includeBank [, includeUses]])
itemInfo— numericitemIDor string containing"item:NNN"(full chat links work). Item names are NOT accepted (vanilla has no name → ID resolver).includeBank(optional, default false) — also walk bank slots (bag-1for the main bank, bags5..10for bank-bag slots).includeUses(optional, default false) — accepted but currently ignored. Returns the same value asfalseregardless. See note below.
local n = C_Item.GetItemCount(2589) -- Linen Cloth in bags
local n = C_Item.GetItemCount(2589, true) -- bags + bank
local n = C_Item.GetItemCount("item:2589") -- string form works too
includeUsesnot yet supported. Modern semantics: whentrue, multiplies each match by the item's spell-charges count (a stack of 5 wands × 50 charges each → 250). Implementing this needs theITEM_FIELD_SPELL_CHARGESdescriptor offset, which hasn't been verified empirically yet. The arg is accepted for API parity so backported code doesn't break, but currently bothtrueandfalseproduce the same number (sum of stack counts). Track [TODO #28] for charges support.
Equipped items don't count. Matches modern API. A wand in your ranged slot won't be counted; only items in bags and (optionally) bank.
Bank works cold — no banker visit required. The 1.12 server sends bank inventory at login alongside the rest of the player's data; only the engine's own
GetItemBySlotgates bank slots until the window opens. We bypass that gate by reading the GUID array directly out of the player invMgr and resolving each entry via the engine's object resolver — same pathGetItemBySlotwould take internally if the gate let us through. Counts are correct from session start.
Walks via the same Item::Location::ResolveBag chain
C_Container.GetContainerItemID
uses. Slot counts come from the engine's Script_GetContainerNumSlots
so custom server bag sizes work transparently. Stack counts read
directly off the CGItem's m_objectFields descriptor at +0x20
(ITEM_FIELD_STACK_COUNT, verified by decoding
Script_GetContainerItemInfo at 0x004F9670).
Equivalent to the legacy global GetItemCount (since 3.0) and the
modern C_Item.GetItemCount introduced in 10.x.
GetItemIcon(itemID) / C_Item.GetItemIcon(itemLocation) / C_Item.GetItemIconByID(item)
Three accessors that all return the icon path for an item, differing only in how you address the item:
| Function | Input |
|---|---|
GetItemIcon(itemID) |
numeric itemID (global) |
C_Item.GetItemIcon(itemLocation) |
{equipmentSlotIndex=N} or {bagID=B, slotIndex=S} |
C_Item.GetItemIconByID(item) |
numeric itemID OR "item:NNN" string (full chat links work) |
All three return the icon path string (e.g. "Interface\\Icons\\INV_Misc_Rune_01"),
or nil if the item isn't in the client-side cache, the slot is empty, or
the display info record is missing. The path is suitable for direct use
with texture:SetTexture(...).
local path = GetItemIcon(6948) -- "Interface\\Icons\\INV_Misc_Rune_01"
local path = C_Item.GetItemIcon({equipmentSlotIndex = INVSLOT_HEAD})
local path = C_Item.GetItemIconByID("|cff...|Hitem:6948:0:0:0|h[Hearthstone]|h|r")
iconID-vs-path deviation. Modern WoW returns these as afileID:number(specificallyiconFileIDin Classic Era 1.15.x). 1.12 has no fileID system — same situation asC_Spell.GetSpellTextureandC_Spell.GetSpellInfo'siconIDfield. We surface the path string everywhere for consistency.
Equivalent to the legacy global GetItemIcon (since 1.x) and the
C_Item.GetItemIcon / GetItemIconByID family added in 10.x.
C_Item.GetItemInfoInstant(item)
Modern-style accessor for the always-available subset of item info — the
fields that depend only on classification, not on player-specific state.
Returns immediately from the client-side item cache; no server round-trip,
no async polling. Returns nil if the item isn't in cache.
Accepts a numeric itemID or a string containing "item:NNN" (matches both
the bare "item:1234" shorthand and full chat links like
"|cff...|Hitem:1234:...|h[Name]|h|r"). Item names are not accepted —
vanilla itself has no name → ID resolver, and it's rarely the form addon code
actually has on hand.
Returns seven values:
itemID, itemType, itemSubType, itemEquipLoc, icon, classID, subClassID
itemType/itemSubTypeare the localized class / subclass names (e.g."Weapon"/"One-Handed Swords"), read fromItemClass.dbcandItemSubClass.dbc.itemEquipLocis the"INVTYPE_*"constant (e.g."INVTYPE_HEAD"), or""for non-equippable items.iconis a path string ("Interface\\Icons\\..."), matching what the rest of the 1.12 API returns. Modern WoW returns a numeric fileID here, but 1.12 has no fileID system, so a path is the only meaningful value.classID/subClassIDare the raw enum integers (e.g.2,7for one-handed swords).
local id, type, subtype, equipLoc, icon, classID, subClassID
= C_Item.GetItemInfoInstant(6948) -- Hearthstone
-- type="Miscellaneous", subtype="Junk", equipLoc="",
-- icon="Interface\\Icons\\INV_Misc_Rune_01", classID=15, subClassID=0
The actual class/subclass values reflect 1.12.1's data, which differs from
modern WoW. For example, vanilla had no Cloth subclass under Trade Goods —
Silk Cloth lives at (7, 0) in this client, not the modern (7, 5).
C_Item.IsItemDataCachedByID(item) / C_Item.IsItemDataCached(itemLocation)
Returns true if the item's static data is currently in the client-side
item cache, false otherwise. The "ByID" variant takes an itemID or
"item:NNN"-style string; the location variant takes the modern
{equipmentSlotIndex=} / {bagID=, slotIndex=} table.
These read the cache without firing a server query — pair with
RequestLoadItemData(ByID) if you need to ensure the data is loaded
before checking.
if not C_Item.IsItemDataCachedByID(itemID) then
C_Item.RequestLoadItemDataByID(itemID)
-- (poll IsItemDataCachedByID on a timer until true)
end
C_Item.RequestLoadItemDataByID(item) / C_Item.RequestLoadItemData(itemLocation)
Asks the engine to fetch the item's data from the server if not already
cached. Returns true if the request was initiated (or the input was
parseable to an itemID), false for malformed input. Fire-and-forget —
the engine handles the round-trip; the data lands in the cache when the
server responds.
Fires ITEM_DATA_LOAD_RESULT(itemID, success) when the data lands in
the cache, matching the modern API. Synchronously fired when the item
was already cached (so polling code paths still work), asynchronously
fired when the engine's SMSG response handler completes a network
fetch.
Vanilla quirk: the engine has no native bool format code —
successarrives as1/0(number), nottrue/false. Idiomatic check isif success == 1 then ....
local f = CreateFrame("Frame")
f:RegisterEvent("ITEM_DATA_LOAD_RESULT")
f:SetScript("OnEvent", function()
-- vanilla 1.12: event payload is in `arg1`, `arg2`, ... globals
if event == "ITEM_DATA_LOAD_RESULT" and arg2 == 1 then
local _, type = C_Item.GetItemInfoInstant(arg1)
-- ...
end
end)
C_Item.RequestLoadItemDataByID(2589)
C_Item.GetItemSpell(item)
Returns (spellName, spellID) for the on-use spell attached to an
item (potions, trinkets, scrolls, hearthstone, food/drink, etc.),
or nil for items without one (vendor trash, regular gear, weapons
with passive procs).
item accepts the same input shapes as GetItemInfo — a numeric
itemID, a chat-link "|cffffffff|Hitem:6948:0:0:0|h[...]|h|r"
fragment, or a "item:NNN" short form.
C_Item.GetItemSpell(6948)
-- "Hearthstone", 8690
C_Item.GetItemSpell(13442)
-- "Mighty Rage Potion", 17528
C_Item.GetItemSpell(11288) -- a soulstone (trigger=4, not ON_USE)
-- nil
C_Item.GetItemSpell(2589) -- Linen Cloth, no spell
-- nil
Returns the ON_USE spell only. Vanilla items can carry up to 5
spell entries in their ItemStats_C record, each with its own
trigger code:
| Trigger | Meaning | Surfaced by GetItemSpell? |
|---|---|---|
| 0 | ON_USE |
yes |
| 1 | ON_EQUIP (passive aura on gear) |
no |
| 2 | CHANCE_ON_HIT (weapon procs) |
no |
| 4 | SOULSTONE (on-death) |
no |
| 5 | ON_USE_NO_DELAY |
no (TODO: should we add this?) |
| 6 | LEARN_SPELL (recipes) |
no |
This matches modern WoW's GetItemSpell, which only reports on-use
triggers. Addons that need the other trigger types (proc auras,
recipe targets) should reach into the cache directly — the spell
slots are at ItemStats +0x11C (5 spell IDs) and +0x130 (5 trigger
codes).
Auto-warmup on cache miss. Items not yet in the local cache
return nil and silently kick off an SMSG_ITEM_QUERY_SINGLE
request. A second call after GET_ITEM_INFO_RECEIVED lands the
data. Same warmup pattern as C_Item.GetItemFamily and the rest of
our cache-backed accessors.
OffhandHasWeapon()
Returns true if the player has a one-handed weapon (or off-hand-only
weapon) equipped in the off-hand slot, false otherwise. Used by
dual-wield checks and any addon backporting modern weapon-equipment
logic.
Returns false for:
- Empty off-hand
- Shields (
INVTYPE_SHIELD) - Held items — tomes, orbs, librams (
INVTYPE_HOLDABLE) - Off-hand item data not yet cached (typically only on first login, before the engine has the item record; warms up after a peek)
Returns true for INVTYPE_WEAPON (any one-handed weapon — sword,
axe, mace, dagger, fist) and INVTYPE_WEAPONOFFHAND (off-hand-only
weapons). Two-handers occupy the main-hand slot exclusively, so they
never apply.
if OffhandHasWeapon() then
-- Apply mainhand+offhand poison, refresh dual-wield rotation, etc.
end
Equivalent to the function of the same name introduced in 3.0.
C_Item.IsEquippableItem(item)
Returns true if item can be equipped in any character-pane slot,
false otherwise. Reads m_inventoryType from the cached ItemStats
record — INVTYPE_NON_EQUIP (value 0) is the only "not equippable"
value, so any non-zero inventory type passes (head, neck, weapon,
shield, holdable, …).
item is an itemID number or "item:N..." link. Item names aren't
accepted — vanilla has no name→ID resolver, and equippability is an
itemID-keyed property anyway.
Returns false for uncached items (no async load fired). If you
need it to wait for the cache, call C_Item.RequestLoadItemDataByID
first and re-check on ITEM_DATA_LOAD_RESULT.
C_Item.IsEquippableItem(12640) -- Lionheart Helm → true
C_Item.IsEquippableItem(6948) -- Hearthstone → false
Equivalent to the function of the same name introduced in 1.10
(global in 4.3.4, namespaced under C_Item in modern Classic Era).
C_Item.IsEquippedItem(item)
Returns true if item is currently equipped in any of the 19
character-pane slots, false otherwise. Walks slots 1..19 in order and
short-circuits on the first match.
item accepts the same shapes as GetItemInfo:
| Form | Example | Match strategy |
|---|---|---|
| itemID | 2589 |
exact itemID equality |
| bare link | "item:2589:0:0:0" |
parses the first numeric field |
| chat link | \124cffffffff\124Hitem:2589:0:0:0\124h[Linen Cloth]\124h\124r |
extracts itemID after \124Hitem: |
| name | "Linen Cloth" |
case-insensitive match against the cached m_name[0] of each equipped item |
Returns false (no Lua error) for invalid input — nil, empty string,
or a string that doesn't parse as any of the above.
The name-match path requires the candidate equipped item to be in the client item cache; equipped items are always cached, so this is a non-issue in practice.
if C_Item.IsEquippedItem(2589) then
-- Linen Cloth is equipped (silly example — pick a wearable item)
end
-- From a chat link click:
if C_Item.IsEquippedItem(itemLink) then ...
-- By localized name:
if C_Item.IsEquippedItem("Thunderfury, Blessed Blade of the Windseeker") then ...
Equivalent to the function of the same name introduced in 3.x.
C_Item.EquipItemByName(itemInfo [, dstSlot])
Finds the first item in the player's bags matching itemInfo and
equips it. With dstSlot (a 1-based character-pane slot, 1..19),
equips to that specific slot; without, the engine auto-picks based on
the item's inventory type.
itemInfo accepts the same shapes as
C_Item.IsEquippedItem — itemID number,
bare "item:N" string, full chat link, or a localized item name. Name
matches are case-insensitive against the cached m_name[0].
Returns nothing. Silently no-ops when:
- the input is
nil, an empty string, or otherwise unparseable - no matching item is in bags (already-equipped items aren't moved — matches modern API behavior)
- the engine refuses the equip — combat, locked item, type mismatch
with
dstSlot, locked equipment slot, etc.
Walks bags 0..4 in order and stops on the first match, then dispatches
to the engine's PickupContainerItem + EquipCursorItem /
AutoEquipCursorItem path. The dispatch goes through the same secure-
action flow a direct Lua call would, so combat lockdown and the
standard equip-failure error messages behave identically.
Cursor-state guard. Because the dispatch path uses
PickupContainerItem internally, an item already on the cursor would
get swapped into the source bag slot. To avoid that side effect, the
function checks CursorHasItem() first and refuses to operate (no-op
return) when the cursor is non-empty. Callers must drop the cursor
before calling — ClearCursor() or completing the held action.
Background: vanilla 1.12 has a CMSG_SWAP_INV_ITEM (0x10D) packet
builder that would let us bypass the cursor entirely (matching 2.4.3's
ItemMgr::EquipByGUID semantic), but the only clean wrapper for it
in the binary is dead code with zero callers. Other 0x10D build sites
read from the engine's internal cursor-tracking globals, so they
can't be called safely from outside that state machine. Refusing the
swap when cursor is dirty is the safest available option until a
working bypass is found.
-- By itemID, auto-pick slot:
C_Item.EquipItemByName(2589)
-- By name, force into off-hand (slot 17):
C_Item.EquipItemByName("Linen Cloth", 17)
-- From a chat link:
C_Item.EquipItemByName(itemLink)
Equivalent to the function of the same name (as a global) introduced
in 3.x. The C_Item. namespace placement matches Dragonflight-era
addon conventions.
C_Item.DoesItemExist(itemLocation) / C_Item.DoesItemExistByID(item)
Existence checks straight off the engine's inventory manager (location
form) and item cache (ID form). No GetItemInfo chaining — both
functions read directly from the structures they need.
C_Item.DoesItemExist(itemLocation)—trueiff the equipment-slot or(bagID, slotIndex)location resolves to a populated inventory slot on the active player. Empty slots, missing bags, or malformed tables returnfalse.C_Item.DoesItemExistByID(item)—trueiff the cache currently has data foritem. Cache miss returnsfalseand kicks off the network query in the background; a follow-up call afterGET_ITEM_INFO_RECEIVEDwill succeed. Accepts a numericitemID, a bare"item:NNN..."string, or a full chat link.
if C_Item.DoesItemExist({equipmentSlotIndex = INVSLOT_HEAD}) then ... end
if C_Item.DoesItemExistByID(6948) then ... end
C_Item.GetItemName(itemLocation) / C_Item.GetItemNameByID(item)
Returns the cached display name as a string, or nil for empty /
uncached / invalid inputs. Reads m_name[0] straight off the
ItemStats_C cache record (+0x08) — no GetItemInfo round-trip.
Cache miss on the ByID form returns nil and fires the cache fill
so the next call (after GET_ITEM_INFO_RECEIVED) succeeds.
local name = C_Item.GetItemName({bagID = 0, slotIndex = 1})
local name = C_Item.GetItemNameByID(6948) -- "Hearthstone"
C_Item.GetItemQuality(itemLocation) / C_Item.GetItemQualityByID(item)
Returns the item's quality as an integer (0=Poor, 1=Common, 2=Uncommon,
3=Rare, 4=Epic, 5=Legendary), matching the LE_ITEM_QUALITY_*
constants. Single uint32 read at cache record +0x1C.
if C_Item.GetItemQualityByID(itemID) >= LE_ITEM_QUALITY_RARE then
-- highlight rare-or-better drop
end
C_Item.GetCurrentItemLevel(itemLocation) / C_Item.GetDetailedItemLevelInfo(item)
Returns the item's base ilvl from m_itemLevel (cache record +0x38).
Vanilla 1.12 has no per-instance scaling (no upgrades, no warforging),
so "current" and "base" item level are always identical — both APIs
return the same single value. Modern GetDetailedItemLevelInfo is
spec'd to return (current, isPreview, base); we push only the
current level, callers that care about the extra returns will see
nil for them.
local ilvl = C_Item.GetCurrentItemLevel({equipmentSlotIndex = INVSLOT_HEAD})
C_Item.GetItemLink(itemLocation)
Returns the fully-decorated per-instance hyperlink for the item at
the location — same string GetContainerItemLink(bag, slot) or
GetInventoryItemLink("player", slot) would return for the same
slot. Enchant ID, random-suffix, and any other per-instance data
attached to the CGItem are preserved.
local link = C_Item.GetItemLink({bagID = 0, slotIndex = 1})
-- "|cffa335ee|Hitem:16539:911:::::::70::::::::::|h[General's Silk Boots]|h|r"
-- ^^^ — enchant ID (Speed +15%) preserved
Implemented by reading the location table's fields and tail-calling
the engine's link script function (Script_GetContainerItemLink at
0x004F9930 for bag locations, Script_GetInventoryItemLink at
0x004C8C10 for equipment slots). The link string is built by the
engine off the live CGItem, so it always matches what other
addons see via the older positional-arg APIs.
C_Item.GetItemInventoryType(itemLocation) / C_Item.GetItemInventoryTypeByID(item)
Returns the numeric Enum.InventoryType straight off the cache
record's m_inventoryType field (+0x2C) — the integer sibling of
GetItemInfoInstant's 4th return (which gives the INVTYPE_* string).
| Value | Constant | Slot |
|---|---|---|
| 0 | INVTYPE_NON_EQUIP_IGNORE |
non-equippable |
| 1 | INVTYPE_HEAD |
head |
| 2 | INVTYPE_NECK |
neck |
| … | … | … |
| 20 | INVTYPE_ROBE |
chest (full-body robes) |
| 26 | INVTYPE_RANGEDRIGHT |
ranged |
| 27 | INVTYPE_QUIVER |
quiver/ammo pouch |
Vanilla items only produce values 0..28; the higher modern
constants (INVTYPE_PROFESSION_*, INVTYPE_EQUIPABLESPELL_*, etc.)
were introduced post-vanilla and are never returned. Modern
backport code that compares against the higher enum values still
resolves correctly because vanilla items just don't carry those
types.
local t = C_Item.GetItemInventoryTypeByID(19019) -- Thunderfury: 17 = INVTYPE_2HWEAPON
if t == 1 then -- head
...
end
C_Item.IsLocked(itemLocation)
Returns true if the equipped/bagged item is in a server-side locked
state — mid-trade, mid-mail-attach, picked up onto the cursor, etc.
Direct descriptor read: CGItem → m_objectFields (+0x114) →
ITEM_FIELD_FLAGS (+0x3C) → bit 2 (0x04).
if C_Item.IsLocked({bagID = 0, slotIndex = 1}) then
-- skip the action; slot is mid-transaction
end
No LockItem / UnlockItem companion. Vanilla 1.12 doesn't
provide a public Lua API for setting the lock flag — it's
exclusively server-driven via the SMSG_ITEM_TIME_UPDATE /
SMSG_ITEM_PUSH_RESULT packet family in response to actions like
PickupContainerItem. Modern backport code that calls
C_Item.LockItem / UnlockItem will hit the
!!!ClassicAPI/Util/ItemUtil.lua no-op shim and silently continue
— there's nothing useful we can do on the C side without a fake
state machine that wouldn't match server behavior.
C_Item.GetItemGUID(itemLocation)
Returns the per-instance 64-bit GUID of the item at the location,
formatted as "0xHHHHHHHHLLLLLLLL" (16 hex digits, hi dword first).
Same format UnitGUID uses — 1.12 GUIDs are plain qwords with no
"Item-Server-..."-style prefix scheme (modern's prefix format
arrived in 6.x). Returns nil for empty / invalid locations.
local guid = C_Item.GetItemGUID({equipmentSlotIndex = INVSLOT_HEAD})
-- "0x40000000000DEFCA"
Reads CGItem instance block at +0x08 → GUID qword at +0x00.
The GUID is stable per-character-session and survives moves between
bags / character pane, so it's the right identifier for "this exact
item instance" — equipment-set tracking, soulbind matching, or any
addon code that needs to follow a single item across slot moves.
Container
C_Container.GetContainerItemID(bagIndex, slotIndex)
Returns the itemID at the given bag/slot, or nil if the slot is empty
or the indices are out of range. Modern positional-arg form of the same
lookup C_Item.GetItemID({bagID=B, slotIndex=S}) performs.
bagIndex = 0— the player's main backpack.bagIndex = 1..4— the player's equipped bag slots.slotIndex— 1-based, capped at the bag's actual slot count (the engine'sPackBagSlotrejects out-of-range slots and returns nil cleanly).
for slot = 1, 16 do
local id = C_Container.GetContainerItemID(0, slot)
if id then
local _, type, subtype = C_Item.GetItemInfoInstant(id)
-- ...
end
end
C_Container.GetContainerItemDurability(containerIndex, slotIndex)
Bag/bank variant of GetInventoryItemDurability.
Same (current, maximum) return shape and the same "nothing for items
without durability" rule.
current, maximum = C_Container.GetContainerItemDurability(containerIndex, slotIndex)
containerIndex = 0— the player's main backpack.containerIndex = 1..4— the player's equipped bag slots.containerIndex = -1, 5..11— bank-frame slots, only addressable while the bank window is open.slotIndex— 1-based, capped at the bag's actual slot count.
for slot = 1, GetContainerNumSlots(0) do
local cur, max = C_Container.GetContainerItemDurability(0, slot)
if cur then
-- item at backpack slot has durability
end
end
Goes through the same bag-resolve chain
C_Container.GetContainerItemID
uses (engine's PackBagSlot → GetItemBySlot), then reads the same
durability fields off the descriptor.
Equivalent to the function of the same name introduced in 10.0.
C_Container.GetContainerNumFreeSlots(bagID)
Returns the number of empty slots in the given bag, plus the bag's
BagFamily bitfield (the type of items the bag is restricted to).
numberOfFreeSlots, bagType = C_Container.GetContainerNumFreeSlots(bagID)
bagID = 0— the player's main backpack. Always reports(freeCount, 0)— the backpack is unfamilied (general-purpose).bagID = 1..4— the player's equipped bag slots. Slot count and bagType come from the bag item's cachedItemStats_Crecord —m_containerSlotsandm_bagFamilyrespectively. If no bag is equipped (or the item somehow isn't cached):(0, 0).- Other
bagIDvalues (bank, keyring, out-of-range):(0, 0). Always returns two values, never nil.
local free, bagType = C_Container.GetContainerNumFreeSlots(0)
-- free = number of empty slots in backpack, bagType = 0
for bag = 0, 4 do
local free = C_Container.GetContainerNumFreeSlots(bag)
-- ...
end
Vanilla
bagTypeis sparse. On Turtle WoW (1.12.1), only Light Quiver actually carries a populated BagFamily field among the bags we tested. Soul Pouch, Enchanting Bag, Herb Pouch, etc. all return 0 here even though their classification clearly implies a family — the vanilla server data simply doesn't fill the field for those. For bag-category discrimination, prefer reading(class, subClass)fromC_Item.GetItemInfoInstant. The same field on individual loot items (arrows, bullets, shards, herbs) IS populated reliably — useC_Item.GetItemFamilyfor routing decisions.
The bitmask encoding matches modern.
bagTypeis the bit position (1 << (familyID - 1)), not the raw 1.12-stored familyID, so callers can bitwise-AND with itemFamily values fromC_Item.GetItemFamilydirectly. We convert internally — see that function's notes for the encoding-shift story.
Implementation walks the bag using
Item::Location::ResolveBag
internally and counts slots that resolve to a null CGItem * (i.e.,
empty). Cross-checked in-game against a manual
C_Container.GetContainerItemID walk; counts match.
Equivalent to the function of the same name introduced in 3.0.
C_Container.PlayerHasHearthstone()
Returns the itemID of the hearthstone if one is in the player's bags,
or nil otherwise.
itemID = C_Container.PlayerHasHearthstone()
if C_Container.PlayerHasHearthstone() then
-- player can hearth
end
Match logic. An item counts as a hearthstone if either:
- Its itemID is
6948(the vanilla Hearthstone — fast path, no cache lookup needed), or - Its on-use spell is spell
8690(the "Hearthstone" cast itself).
Rule 2 lets custom servers (Turtle WoW, etc.) ship reskinned
hearthstone items with different itemIDs and still have them
recognized — as long as their on-use is the Hearthstone spell.
The return is the actual matched itemID, not a hardcoded
constant, so code that wants to do something with the found id
(SetItemRef for chat-linking, GetItemInfo for the item's
name, etc.) gets the right value for any variant.
Cache dependency for rule 2. The on-use-spell check requires the item's
ItemStats_Crecord to be in the local cache. Items currently in the player's bags are always cached (the engine pre-fills the cache during bag sync), so the check is reliable for this code path. The fallback to rule 1 (vanilla itemID equality) covers the moment-of-login window before the cache is fully populated.
Walks bags 0..4 via the same chain
C_Container.GetContainerItemID
uses internally. Stops on first match.
Equivalent to the function of the same name introduced in 9.0.
C_Container.UseHearthstone()
Locates the hearthstone in bags and uses it. Returns true if the
hearthstone was found and the use call dispatched, false if no
hearthstone is in bags.
used = C_Container.UseHearthstone()
if not C_Container.UseHearthstone() then
print("No hearthstone in bags!")
end
truedoesn't guarantee the cast started. The return reflects "we had a hearthstone to try with and called the engine'sUseContainerItemon it." Whether the cast actually starts depends on cooldown, combat, movement, etc. — same downstream rules as callingUseContainerItem(bag, slot)manually. If you need to know whether the hearth completed, listen for the appropriate cast events (SPELLCAST_START/SPELLCAST_STOP).
Internally locates the hearthstone with the same walk
PlayerHasHearthstone uses, then dispatches to the engine's existing
Script_UseContainerItem Lua C function with (bagID, slot) set up
on the stack. No new use-item logic is introduced — this is a
convenience wrapper.
Equivalent to the function of the same name introduced in 9.0.
EquipmentSet
Backports the modern C_EquipmentSet.* namespace on top of a
client-side persistent store. Vanilla 1.12 had no equipment-set
functionality at all (Blizzard introduced it in 3.1.2 as
SaveEquipmentSet etc., then namespaced it into C_EquipmentSet in
Legion) — and even when it shipped natively, the data lived
server-side, synced via SMSG_EQUIPMENT_SET_LIST. Vanilla servers
don't speak that opcode and won't ever, so each character's sets are
kept in a per-character file under WTF\Account\.... The format
matches what VanillaMinimapTracking does for its tracking config.
Overview & file format
Sets are stored in
WTF\Account\<account>\<realm>\<character>\ClassicAPI_EquipmentSets.txt
in a line-oriented, human-readable format:
# ClassicAPI Equipment Sets v1
set 1
name=Tanking
icon=INV_Shield_06
slot 1 guid=0x0000000040000123
slot 2 ignored
slot 5 guid=0x0000000040000789
set 2
name=Healing
icon=Spell_Holy_HolyBolt
...
Identity is by item GUID, snapshotted at CreateEquipmentSet /
SaveEquipmentSet time. UseEquipmentSet searches every player-owned
container for those GUIDs and dispatches pickup→equip pairs for items
that aren't already where they belong. The search reads the
underlying GUID arrays directly (same trick C_Item.GetItemCount
uses for its includeBank=true path), so bank items resolve even
without the bank window being open — the bank gate at
VAR_BANK_GATE_GUID only suppresses GetItemBySlot, not the
underlying data.
One limitation worth knowing about:
- Equipping from the bank is not supported by vanilla's protocol
—
UseEquipmentSetskips bank items rather than try and fail. Retrieve the items first, then re-run.
Modern's signatures take a numeric iconFileID; we accept icon path
strings (e.g. "INV_Shield_06") since vanilla has no fileDataID
system. Same string-or-default fallback semantic as 4.3.4 native.
Cap is 10 sets per character, matching 4.3.4. The full list re- serializes on every mutation; a corrupted file is harmless (parse errors leave the in-memory list empty and the next save rewrites the file from scratch).
Note: this is a fresh client-side namespace, not a polyfill of some specific Blizzard build's behavior. The shape mirrors Classic Era 1.15.x's
C_EquipmentSet.*where it can, but anything that requires server-side state (cross-character sharing, the "Equipment Manager" specialization tab) isn't supported.
C_EquipmentSet.CanUseEquipmentSets()
Returns true unconditionally. Vanilla has no banker/feature gate
on equipment-set storage; we ship the feature for every character.
Equivalent to Classic Era's behavior.
C_EquipmentSet.GetNumEquipmentSets()
Returns the count of sets stored for the current character. Loads the file on first call after login.
C_EquipmentSet.GetEquipmentSetIDs()
Returns a numeric-keyed table of every setID in storage order (insertion-order; not alphabetical). Empty table when nothing's saved.
C_EquipmentSet.GetEquipmentSetID(name)
Returns the numeric setID for a set with the given name, or nil if
no set by that name exists. Names are exact (case-sensitive, no
trimming).
C_EquipmentSet.GetEquipmentSetInfo(setID)
Returns the nine values modern ships:
name, icon, setID, isEquipped,
numItems, numEquipped, numInInventory, numMissing, numIgnored
isEquipped is true when every resolvable item in the set is in
its target slot (missing items don't disqualify — useful so a set
that includes a bank-stored cloak still shows as equipped after you
swap in the rest). numItems excludes ignored slots; numIgnored
counts them separately. Returns nothing for an unknown setID.
C_EquipmentSet.GetIgnoredSlots(setID)
Returns a numeric-keyed table of slot indices (1..19) that the set
has flagged ignored. Empty table when no slots are ignored. Ignored
slots are recorded per-set at save time, by reading the global
IgnoreSlotForSave state — not retroactively editable on a saved set.
C_EquipmentSet.GetItemIDs(setID)
Returns a hash table { [slot] = itemID } for every set slot whose
item is currently resolvable. Missing items (GUID stored but client
can't find a CGItem) are omitted because vanilla doesn't keep an
itemID separate from the live CGItem record.
C_EquipmentSet.GetItemLocations(setID)
Returns a hash table { [slot] = locationCode }. Location codes use
the same bit-packed encoding Blizzard's FrameXML
EquipmentManager_UnpackLocation decodes (constants in
Blizzard_FrameXMLBase/Classic/Constants.lua):
| Bit/field | Meaning |
|---|---|
0x00100000 (PLAYER) |
Item is in a player slot (equipped or in a player bag) |
0x00200000 (BAGS) |
Item is inside a bag (player or bank) |
0x00400000 (BANK) |
Item is in the bank (main or bank bag) |
| bits 0..7 | Slot (1-based) within the container |
| bits 8..15 | Bag index — present only when BAGS bit is set |
PLAYER and BANK are mutually exclusive in the encoding (the
unpack uses if player elseif bank). Bank bags subtract 4 from the
bagID before storing so the field fits cleanly; unpack reverses this
to give back bag IDs 5..10. Composition:
| Location | Bits | Example |
|---|---|---|
| Equipped (paperdoll slot 1..19) | `PLAYER | slot` |
| Backpack / player bag 1..4 | `PLAYER | BAGS |
| Main bank slot 1..28 | `BANK | slot` |
| Bank bag 5..10 | `BANK | BAGS |
Special values returned in the table entry:
1— slot is ignored (GetIgnoredSlotslists these)-1— item is missing (was in the set, can't find now)
The packed codes pass cleanly through Blizzard's
EquipmentManager_UnpackLocation if you want to use the
shared-FrameXML helpers in your addon UI.
C_EquipmentSet.CreateEquipmentSet(name [, icon])
Snapshots the player's currently-equipped items into a new set and
returns its setID. Honors IgnoreSlotForSave — slots flagged ignored
at call time get the ignored marker instead of the equipped item's
GUID.
Returns the new setID on success. Returns nothing if:
- the name is empty or already in use
- the cap of 10 sets is reached
icon defaults to "INV_Misc_QuestionMark" if omitted.
C_EquipmentSet.SaveEquipmentSet(setID [, icon])
Overwrites an existing set's contents with the player's currently-
equipped items. Same ignored-slot handling as CreateEquipmentSet.
If icon is provided it replaces the set's previous icon; otherwise
the icon is left unchanged.
C_EquipmentSet.ModifyEquipmentSet(setID, newName)
Renames an existing set. Fails silently if the new name is empty, already in use by a different set, or the setID doesn't exist.
C_EquipmentSet.DeleteEquipmentSet(setID)
Removes the set. SetIDs are not reused — the next Create call
allocates one higher than any seen.
C_EquipmentSet.IgnoreSlotForSave(slot) / UnignoreSlotForSave / IsSlotIgnoredForSave / ClearIgnoredSlotsForSave
Global "skip this slot the next time CreateEquipmentSet or
SaveEquipmentSet runs" state, indexed by 1-based slot (1..19).
Persists for the rest of the session; not written to the WTF file.
Use it when building a set that should leave (say) the tabard slot
free — set the ignore flag, then call CreateEquipmentSet, then
optionally ClearIgnoredSlotsForSave() afterward.
C_EquipmentSet.EquipmentSetContainsLockedItems(setID)
Returns true if any item in the set is currently flagged "locked"
by the engine — a pending pickup or use is in flight that
UseEquipmentSet would race with. Reads bit 2 (0x04) of
ITEM_FIELD_FLAGS for each resolvable item in the set.
C_EquipmentSet.UseEquipmentSet(setID)
Walks the set and dispatches pickup→equip pairs for every item that
isn't already in its target slot. Items in the bank are skipped
silently (vanilla can't equip from bank). Missing items are skipped
silently. Returns true if the call ran (the set existed), false
otherwise.
Behavior: this is not a perfect swap solver. If two set items want each other's slots ("ring A in slot 11, ring B in slot 12, set swaps them") the cursor cleanup may stash one in a free bag slot instead of completing the cycle. Re-run
UseEquipmentSet(setID)and the next pass picks up the stashed item and finishes. The 4.3.4 native uses a temporary-bag-slot shuffle to nail this in one pass; we leave that as future work.
EQUIPMENT_SETS_CHANGED event
Fires (with no payload) after any mutation: Create, Save,
Modify, Delete, and the four *IgnoredSlot* calls. Addon UI
should re-read its set list / button state when this fires.
EQUIPMENT_SWAP_PENDING event
Fires with a single payload arg — setID — at the start of
UseEquipmentSet, right after the set-exists check passes and
before any pickup/equip work begins. Modern addons use this to
gate "swap in progress" UI state (grey out the set button, show
a spinner, etc.) until EQUIPMENT_SWAP_FINISHED arrives.
Doesn't fire if UseEquipmentSet is called with an unknown
setID — in that case only EQUIPMENT_SWAP_FINISHED(false, setID)
fires.
EQUIPMENT_SWAP_FINISHED event
Fires at the end of every UseEquipmentSet call with two payload
args: success (1 if the set existed and we dispatched the swap, 0
if the setID was unknown) and setID. Note this is "we ran the
dispatch" success — not "every item ended up in its target slot."
Items that were in the bank or that couldn't complete a swap cycle
in one pass still report success=1. Listen for this if you want to
re-paint the character pane / refresh tooltips after a swap.
Class
FillLocalizedClassList(table [, isFemale])
Fills the passed-in table with [classToken] = localizedClassName
pairs for every class in ChrClasses.dbc, and returns the same
table for chaining.
The table is mutated in place. Existing keys are overwritten; unrelated keys are preserved.
local classes = FillLocalizedClassList({})
-- classes.WARRIOR = "Warrior"
-- classes.MAGE = "Mage"
-- classes.PRIEST = "Priest"
-- ...
Modern API supports an optional isFemale boolean to fetch female-
form names. Vanilla 1.12 has no separate female-name array in
ChrClasses.dbc — Name[9] (one localized string per locale)
sits exactly between offsets +0x14 and +0x38, with the class
token immediately after, leaving no room. The arg is accepted for
signature parity but ignored; the same names are returned either way.
Most locales (English included) wouldn't differentiate the two
anyway, so callers won't typically notice.
Sparse class IDs (vanilla skips classID 6 — Death Knight didn't exist yet — and a few others) have NULL records and are silently skipped.
Equivalent to the function of the same name introduced in 3.0.
Unit
UnitGUID(unit)
Returns the unit's 64-bit GUID formatted as a hex string
"0xHHHHHHHHLLLLLLLL" (16 hex digits, hi dword first), or nil if the
resolved unit's GUID is empty (e.g. "target" with nothing targeted,
empty party/raid slot).
local guid = UnitGUID("player") -- "0x0000000000000777" (low IDs are local-realm characters)
local guid = UnitGUID("target") -- "0xF13000059A002553" (the F130... prefix tags creatures)
local guid = UnitGUID("party1") -- works even if party1 is on a different continent
Works for OOR party / raid members. Earlier versions of this
function returned nil for "partyN" / "raidN" when the member's
CGObject wasn't currently active in the client (e.g. on another
continent, in a different zone phase). We now read from the engine's
parallel group-roster GUID array (populated by SMSG_GROUP_LIST),
which is independent of unit visibility.
Vanilla format, not modern. Vanilla GUIDs are plain 64-bit integers — there's no
"Player-RealmID-CharacterID"/"Creature-0-0-MapID-..."prefix system that modern WoW uses (introduced in 6.0). Addons backporting modern GUID-parsing code will need to either accept the"0x..."form or extract the raw hex.
Errors on invalid unit tokens. Same behavior as vanilla's other unit-token functions (
UnitAffectingCombat,UnitName, etc.) — passing a string that doesn't match a known unit ID raises a Lua error rather than returning nil. Modern WoW silently returns nil; we match the engine's existing convention here. Unit tokens that resolve to "no current unit" (like"target"with nothing targeted) return nil cleanly via the GUID = 0 check.
GetPlayerInfoByGUID(guid)
Returns
localizedClass, englishClass, localizedRace, englishRace, sex, name, realm
for a player GUID the engine has cached, or nil on a cache miss.
local _, class, _, race, sex, name = GetPlayerInfoByGUID(UnitGUID("target"))
-- e.g. "WARRIOR", "NightElf", 2, "Sylphir"
GetPlayerInfoByGUID("0x0000000000000777") -- same shape for a literal GUID
guid is the "0xHHHHHHHHLLLLLLLL" string returned by UnitGUID.
Bare 8-hex "0xLLLLLLLL" (hi-dword zero) is also accepted.
Returns:
| 1 localizedClass | "Warrior" / "Krieger" etc. — from ChrClasses.dbc indexed by locale. |
| 2 englishClass | "WARRIOR" (uppercase tag, same value UnitClass returns as 2nd return on modern clients) — ChrClasses.dbc filename field. |
| 3 localizedRace | "Human" / "Mensch" / "Humain" etc. — from ChrRaces.dbc indexed by locale. |
| 4 englishRace | "Human", "Orc", "Dwarf", "NightElf", "Scourge" (vanilla's filename for what addons call Undead), "Tauren", "Gnome", "Troll" — from ChrRaces.dbc filename field. |
| 5 sex | 2 = male, 3 = female. Matches UnitSex convention (the cache stores 0/1; we add 2). |
| 6 name | Character name. |
| 7 realm | Realm name. Single-realm in vanilla, so usually the local realm. |
Cache coverage: the engine populates entries from
SMSG_NAME_QUERY_RESPONSE. Anything the client has already seen
populates the cache: chat (whispers, says, party chat), raid/group
events, guild updates, visible objects (target, party, raid in
zone). Names of offline friends never seen in chat are not
cached — GetPlayerInfoByGUID returns nil for them until the
client does something that triggers a name query. This module
deliberately does not trigger queries from a passive getter; a
future C_PlayerInfo.RequestLoadPlayerByID would do that
explicitly and fire a load-result event.
Persistent fallback: when
ClassicAPI.SetPersistentNameCacheEnabled(true)
has been opted into, a per-realm on-disk cache extends coverage
across sessions. On engine cache miss, GetPlayerInfoByGUID falls
back to the persistent cache and returns the cached name and
class (with realm as "" and race/sex slots zeroed — only the
two stored fields are recoverable, but for the common chat-coloring
use case that's enough). Returns nil only when both the engine
and persistent caches miss.
Implementation: calls the engine's get-or-fetch primitive at
0x0055F080 with a NULL callback (pure cache read). The cache
instance lives at 0x00C0E228; entry layout (name, realm, race,
sex, class) was reverse-engineered from the
SMSG_NAME_QUERY_RESPONSE write path at 0x0055F310.
C_PlayerInfo.RememberPlayer(guid, name, classToken)
Adds a (guid → name, classID) entry to the persistent name cache.
For the engine-driven coverage (chat / group / guild / visible
objects), no addon-side feeding is needed — those flow into the
cache automatically through the engine's SMSG_NAME_QUERY_RESPONSE
write path. This call exists for the other sources libunitscan-
style addons harvest from but the engine NameCache doesn't see
directly: /who results, mouseover, target snapshots, etc.
Returns true on success, false if the persistent cache isn't
enabled or the args are malformed.
guid—"0xHHHHHHHHLLLLLLLL"string (same formatUnitGUIDreturns). 8-hex"0xLLLLLLLL"is also accepted (hi-dword zero).name— 1–12 ASCII chars (vanilla character-name range). Tabs, newlines, and high bytes are stripped.classToken— uppercase token like"WARRIOR","MAGE". Looked up againstChrClasses.dbcfilename field, case-insensitive. Passing an unknown token keeps the entry's prior class (so a name-only sighting doesn't erase good class data).
-- Harvest /who results into the persistent cache
local function OnWhoUpdate()
for i = 1, GetNumWhoResults() do
local name, _, _, _, class = GetWhoInfo(i) -- class is localized
-- pfUI has L["class"][class] for localized→token mapping
local token = L["class"][class]
if token then
-- GetWhoInfo doesn't expose GUID; addons can pair this
-- with GetCurrentChatGUID() at the call site that
-- triggered the query, or skip RememberPlayer for /who
-- and rely on the engine populating from chat instead.
end
end
end
name-only updates (no classID) do not overwrite an existing
classID — useful for "I saw this name in a guild login system msg"
sightings that don't have class info but want to refresh the name.
The "deleted character recreated with same name, different class" collision case that name-keyed caches suffer from doesn't apply here: GUIDs are permanent for the life of a vanilla character, so the new character has a different GUID and gets a different cache entry.
ClassicAPI.SetPersistentNameCacheEnabled(enabled)
Opts into (or out of) the persistent name cache. enabled is a
boolean (numeric 0/1 also accepted). Persists to
WTF\Account\<account>\ClassicAPI.txt as
PersistentNameCacheEnabled=1/0, so the choice survives
client restarts.
When enabled:
- Every
SMSG_NAME_QUERY_RESPONSEthe engine processes is also written toWTF\Account\<account>\<realm>\ClassicAPI_NameCache.txt. - Lua-side
C_PlayerInfo.RememberPlayercalls become effective (they're no-ops when the cache is disabled). GetPlayerInfoByGUIDgains the cross-session fallback path documented above.
When disabled, the on-disk file is left in place (re-enabling later restores the prior contents); future writes are simply suppressed.
The cache file is shared across all characters on the same
account+realm — a 50-character bank alt's chat-scraping doesn't
double the storage cost. Format is tab-separated text
(guidHi guidLo classID name per line), about 30 bytes per
entry, hand-editable if you ever need to.
ClassicAPI.SetPersistentNameCacheEnabled(true)
Returns nothing.
ClassicAPI.GetPersistentNameCacheEnabled()
Returns the current state of the persistent name cache as a
boolean. false until
SetPersistentNameCacheEnabled
has been called (or its prior call survived in the on-disk settings
file).
if ClassicAPI.GetPersistentNameCacheEnabled() then
-- persistent fallback is active for GetPlayerInfoByGUID
end
UnitIsAFK(unit)
Returns true if the unit is currently AFK (toggled via /afk or
auto-set after idle timeout). Works for any player-controlled unit
— local self, target, party*, raid*, inspect targets. NPCs always
return false.
UnitIsAFK("player") -- true if you've /afk'd
UnitIsAFK("target") -- true if the targeted player is AFK
UnitIsAFK("party1") -- true if party member 1 is AFK
UnitIsAFK("npc") -- always false
How it works under the hood. Vanilla 1.12 doesn't broadcast PLAYER_FLAGS as a UpdateField (modern WoW does — that field was added 3.0+), but every nearby player's CGPlayer-side info struct at
[unit + 0xE68]carries it at byte +0x08. Same struct the engine reads when rendering the<AFK>prefix above a player's head. Verified against the in-game nameplate behavior.
Equivalent to the function of the same name introduced in 3.0.
UnitIsDND(unit)
Returns true if the unit is currently in DND mode ("Do Not Disturb",
toggled via /dnd). Same unit-coverage as UnitIsAFK — any
player-controlled unit, false for NPCs.
UnitIsDND("player")
UnitIsDND("target")
Equivalent to the function of the same name introduced in 3.0.
UnitIsFeignDeath(unit)
Returns true if the unit is feigning death (Hunter's Feign Death).
Reads UNIT_FIELD_FLAGS bit 29 (0x20000000) from the broadcast
descriptor — works for any unit since UNIT_FIELD_FLAGS is broadcast
in object updates.
UnitIsFeignDeath("target") -- true if a feigning hunter
Equivalent to the function of the same name introduced in 3.0.
UnitIsInMyGuild(unitOrName)
Returns 1 if the unit/character shares the player's guild, nil
otherwise. Accepts either a unit token ("player", "target",
"party1", etc.) or a literal character name ("Bob"), matching
3.3.5's Script_UnitIsInMyGuild (0x0060C4B0 in the Frostmourne
client).
UnitIsInMyGuild("player") -- 1 if you're in any guild
UnitIsInMyGuild("target") -- 1 if your target is a guildmate
UnitIsInMyGuild("party1") -- 1 if party member 1 is a guildmate
UnitIsInMyGuild("Bob") -- 1 if there's a guildmate named Bob
Resolution strategy:
- Calls
UnitName(input)vialua_pcallto canonicalize the input. Tokens resolve cleanly; literal names hit the engine's "Unknown unit name" error whichpcallswallows. - For valid tokens, attempts a fast direct comparison against the
player's guild-key field at
[unit + 0xE68 + 0x0C]— same fieldGetGuildInforeads, populated immediately on guild join for the local player and for any synced player-controlled unit. No roster fetch needed for nearby/loaded units. - Falls back to walking the engine's guild roster array (same
backing storage
GetGuildRosterInforeads) by name. Required for out-of-range party members, distant raid members, and literal name input — needsGuildRoster()to have been called and the server's response to have arrived.
Return convention matches 3.3.5: 1.0 / nil, not boolean. Both
work for if UnitIsInMyGuild(x) then checks.
The slow path reads the engine's full roster count
([0x00B73118], the same value GetNumGuildMembers(true) returns),
not the online-only count, so offline guildmates resolve too — the
"show offline" toggle doesn't affect lookup. The only requirement
is that GuildRoster() has been called and the server's
SMSG_GUILD_ROSTER response has arrived.
UnitIsPossessed(unit)
Returns true if the unit is currently possessed (priest's Mind Control, warlock's Subjugate Demon). Reads UNIT_FIELD_FLAGS bit
24 (0x01000000) — the standard vanilla UNIT_FLAG_POSSESSED per
emulator sources — directly off the unit's m_objectFields descriptor.
Works for any unit token since UNIT_FIELD_FLAGS is broadcast in
object updates.
UnitIsPossessed("target") -- true if mind-controlled
Distinct from UnitIsCharmed: charm covers any charm-type effect
(including pets summoned via mob-charm spells), possess is the
specific spell-driven take-over effect modern WoW splits out.
State
Player movement / visibility state queries that modern WoW exposes as no-arg globals. 1.12 doesn't bind them to Lua despite the engine tracking the underlying state — broadcast in UpdateFields for some (mount, stealth visibility), local-only for others (falling, swimming).
IsMounted()
Returns true if the player is currently mounted, false otherwise.
Reads UNIT_FIELD_MOUNTDISPLAYID from the player's broadcast
descriptor. The field holds a creature display ID (the model the
engine renders under the player) when mounted, and 0 otherwise.
if not IsMounted() then
CastSpellByName("Summon Dreadsteed")
end
Equivalent to the function of the same name introduced in 1.10.
IsStealthed()
Returns true if the player is currently in Stealth (Rogue) or
Prowl (Druid), false otherwise.
Reads bit 0x02 of the player visibility byte at descriptor
+0x17C and AND-gates with MountDisplayID == 0 to disambiguate
mount (which sets the same bit). Untested for Druid shapeshift
forms — if you find a false-positive there, file an issue and we'll
switch to walking the player's aura array for the actual stealth
spell.
if IsStealthed() then
-- defer the spell that would break stealth
end
IsFalling()
Returns true if the player is currently mid-jump or falling,
false otherwise.
Reads the local CGPlayer movement-flags word at +0x9E8 and tests
MOVEFLAG_FALLING | MOVEFLAG_FALLING_FAR (0x2000 | 0x4000). This
is client-side state (outbound MSG_MOVE_* data, never visible for
remote units), so the function only meaningfully applies to the
local player.
if not IsFalling() then
-- safe to bind ground-targeted spell
end
IsSwimming()
Returns true if the player is currently swimming (in liquid, with
the swim animation/movement set), false otherwise.
Same movement-flags word as IsFalling, testing MOVEFLAG_SWIMMING
(0x200000). Local-player only.
if IsSwimming() then
-- breath bar logic, mount-failure suppression, etc.
end
IsAssistingRitual()
Returns true if the local player is currently clicking a warlock
summoning portal (the channel-on-GameObject state with no castbar
UI, where movement breaks the channel), false otherwise.
This is distinct from spell channeling: the function fires for
participants who clicked the portal, not the warlock who cast
Ritual of Summoning. Vanilla has no Lua surface for this state —
the engine's SPELLCAST_CHANNEL_* events don't fire and
CastingInfo() returns nothing — so addons that want to react to
the player being committed to a ritual (e.g. suppress autorun
toggles, hide nameplate clicks, warn before movement) have no other
way to detect it.
Detection uses two state slots:
UNIT_CHANNEL_SPELL(descriptor+0x228) — the warlock's channel spell ID (698) is mirrored onto every clicker for the duration of the ritual.- A CGPlayer-local pointer at
+0xB4— the engine's "current spell cast target GameObject" slot, set to the portal GO while the clicker is engaged.
Either signal alone is ambiguous (the warlock channeling matches the first; mining and other GO-targeted casts match the second); the conjunction is portal-clicker-specific.
The engine fires SPELLCAST_CHANNEL_START / SPELLCAST_CHANNEL_STOP
on the portal click, even though there's no castbar — Blizzard's
vanilla castbar UI filters out spell ID 698 (Ritual of Summoning),
but the events themselves fire normally. Combine them with this
function for ritual-specific triggers:
local frame = CreateFrame("Frame")
frame:RegisterEvent("SPELLCAST_CHANNEL_START")
frame:RegisterEvent("SPELLCAST_CHANNEL_STOP")
frame:SetScript("OnEvent", function()
if event == "SPELLCAST_CHANNEL_START" and IsAssistingRitual() then
-- player just committed to a ritual portal
elseif event == "SPELLCAST_CHANNEL_STOP" then
-- channel ended; was it a ritual?
end
end)
Local-player only — the +0xB4 pointer lives on the CGPlayer
object, not in the broadcast descriptor, so the function can't
report state for target / party* / etc. Returns false when
called before the player object is initialized (login screen).
CharacterList
C_CharacterList.GetNumCharacters() / GetCharacterInfo(index)
Exposes the realm's character list (name, class, race, level, area,
sex, ghost flag) from anywhere in the game — vanilla's stock
GetNumCharacters / GetCharacterInfo are glue-only (registered
on the character-select FrameScript engine; the underlying data is
freed when the player enters the world).
GetCharacterInfo returns an 8-tuple: name, localizedRace, localizedClass, level, areaName, englishRace, sex, guid.
areaName is nil if the character's last-known area isn't in
AreaTable.dbc. guid is the 64-bit character GUID formatted as
a 16-hex-digit string ("0x" + hi + lo), same format as
UnitGUID returns.
for i = 1, C_CharacterList.GetNumCharacters() do
local name, _, class, level, area = C_CharacterList.GetCharacterInfo(i)
print(name, class, "Lv", level, "in", area or "?")
end
C_CharacterList.GetCharacters()
Returns a numeric-keyed array of CharacterInfo tables — same data
as GetCharacterInfo but as struct-style tables with named fields.
Easier to consume when iterating the whole list.
Each entry has:
name— character namelocalizedRace,englishRacelocalizedClasslevelareaName(only present if the character's last-known area is inAreaTable.dbc)sex(0or1)guid(16-hex-digit string, same format asUnitGUID)
for _, c in ipairs(C_CharacterList.GetCharacters()) do
print(c.name, c.localizedClass, "Lv", c.level, c.guid)
end
How it works. We hook the engine's char-list teardown function (
FUN_00472090) and snapshot the array contents into our own cache before the engine frees them. Every time the player visits character-select (including the implicit visit at every game launch), the cache refreshes. Memory-only — no filesystem persistence — so deleted characters disappear from the cache on the next char-select visit, and there's no stale data across game restarts (every launch hits char-select before world-enter).First-launch edge case. If the DLL is loaded mid-session somehow (e.g. injected after world-enter), the cache will be empty until the player goes back to character-select. Under normal use (DLL loaded at game start via VanillaFixes) the cache is populated before any addon Lua runs.
Chat
GetCurrentChatGUID()
Returns the sender's GUID for whichever CHAT_MSG_* event is
currently being dispatched, or nil if called outside a chat
event or for a synthetic chat with no real sender (e.g.
CHAT_MSG_SYSTEM).
Format matches UnitGUID: "0xHHHHHHHHLLLLLLLL" (16 hex digits,
hi dword first).
local f = CreateFrame("Frame")
f:RegisterEvent("CHAT_MSG_CHANNEL")
f:RegisterEvent("CHAT_MSG_SAY")
f:RegisterEvent("CHAT_MSG_WHISPER")
f:SetScript("OnEvent", function()
local guid = GetCurrentChatGUID()
if guid then
local _, class, _, race = GetPlayerInfoByGUID(guid)
DEFAULT_CHAT_FRAME:AddMessage(string.format(
"%s: %s [%s %s]", arg2, arg1, class or "?", race or "?"))
end
end)
Vanilla 1.12's CHAT_MSG_* events don't include the sender GUID
in their payload — that was added in 3.0+ as arg12. Addons that
need to identify chatters reliably (rather than by sender name,
which is locale-fragile and ambiguous across realms) currently
strcmp against an addon-maintained name cache. This function lets
them skip that work.
Implementation: hooks the engine's chat dispatcher at
FUN_CHAT_DISPATCH (0x0049A870), which receives the sender
GUID as args 11/12 of a 12-arg __fastcall. The hook stashes the
GUID into a static global before forwarding to the original
function; the engine then fires the appropriate CHAT_MSG_*
event synchronously inside that window, so GetCurrentChatGUID()
called from the addon's OnEvent sees the right GUID. The global
is restored to its prior value (not cleared) on hook return, so
nested chat dispatch (e.g. an addon calling SendChatMessage
from its handler) doesn't lose the outer context's GUID.
The function returns nil rather than "0x0000000000000000"
for synthetic chat (system messages, login banners, etc.) where
the GUID args are zero — matches the idiomatic
if GetCurrentChatGUID() then check.
AddOns
Six modern C_AddOns.* getters that splat the legacy
GetAddOnInfo(arg) 7-tuple (name, title, notes, enabled, loadable, reason, security) into single-field accessors. Most
bypass GetAddOnInfo entirely and call the engine's per-field
helpers directly.
All accept either a 1-based index (1..GetNumAddOns()) or an
addon directory name string.
C_AddOns.GetAddOnName(indexOrName)
Returns the addon's directory name as the engine sees it (the
folder name on disk). For numeric input, returns the engine's
canonical casing; for string input, echoes the input verbatim
once existence is confirmed. Returns nil for missing addons.
C_AddOns.GetAddOnName(1) -- "Atlas-TW"
C_AddOns.GetAddOnName("DebugTools") -- "DebugTools"
C_AddOns.GetAddOnName("garbage") -- nil
C_AddOns.GetAddOnTitle(indexOrName)
Returns the ## Title: from the addon's .toc file, with WoW
color-code escapes applied. nil for missing addons or addons
without a title field.
C_AddOns.GetAddOnTitle("DebugTools") -- "UI Debug Tools"
C_AddOns.GetAddOnNotes(indexOrName)
Returns the ## Notes: from the .toc. nil for missing
addons or addons without notes.
C_AddOns.GetAddOnNotes("DebugTools")
-- "Tools for developing addons (backport of Blizzard_DebugTools 3.3.5 to 1.12.1 / Lua 5.0)"
C_AddOns.IsAddOnLoadable(indexOrName)
Returns loadable, reason — a real boolean and a status string
(or nil).
reason comes from a small status table the engine consults when
populating GetAddOnInfo's 6th return: "DISABLED", "BANNED",
"CORRUPT", "INSECURE", "NOT_DEMAND_LOADED",
"INTERFACE_VERSION", "MISSING". nil when the addon is
loadable. The full modern signature accepts optional character
and demandLoaded arguments — those are ignored here since vanilla
1.12 has no per-character addon enable state.
C_AddOns.IsAddOnLoadable("DebugTools") -- true, nil
C_AddOns.IsAddOnLoadable("HardcoreTooltips") -- false, "DISABLED"
C_AddOns.IsAddOnLoadable("garbage") -- false, nil
C_AddOns.GetAddOnSecurity(indexOrName)
Returns "SECURE" for Blizzard-signed addons or "INSECURE" for
user addons. Returns nil for missing addons. Vanilla addons
loaded from Interface/AddOns/ are always insecure.
C_AddOns.GetAddOnSecurity("DebugTools") -- "INSECURE"
C_AddOns.DoesAddOnExist(indexOrName)
Returns true iff the engine's addon registry has a matching
entry, false otherwise. Cheap existence probe used by addons
doing soft-dependency checks.
The implementation goes through the registry directly rather than
dispatching to GetAddOnInfo — the engine echoes its input name
back as ret1 unconditionally (before the lookup), so a
GetAddOnInfo("garbage") ~= nil heuristic returns true for any
string. This wrapper avoids that.
C_AddOns.DoesAddOnExist("DebugTools") -- true
C_AddOns.DoesAddOnExist("garbage") -- false
Combat
InCombatLockdown()
Returns true if the local player is currently in combat, false
otherwise. Modern WoW gates secure-frame UI manipulation on this; 1.12
has no secure-frame system, so the function reduces to a plain
"is the player in combat" check. Useful for addons backporting modern
code that does e.g. if not InCombatLockdown() then SetBindingClick(...) end.
if not InCombatLockdown() then
-- safe to make UI changes
end
Equivalent to UnitAffectingCombat("player") but faster — reads the
UNIT_FLAG_IN_COMBAT bit directly off the player CGUnit's
m_objectFields, no token-resolution roundtrip.
Hooks
hooksecurefunc(name, callback) / hooksecurefunc(table, name, callback)
Modern post-call hook: the original function runs first, then
callback runs with the same args (return values discarded). The
original's return values propagate to the caller.
hooksecurefunc("GetSpellInfo", function(spellID)
print("GetSpellInfo called with " .. tostring(spellID))
end)
hooksecurefunc(GameTooltip, "SetInventoryItem", function(self, unit, slot)
-- runs after the engine fills the tooltip
print("inventory tooltip:", unit, slot)
end)
The "secure" label refers to taint-propagation behavior introduced in 3.0 for protected-frame manipulation. Vanilla 1.12 has no taint system, so the function is functionally equivalent to a plain "after-hook" — just preserves modern API parity for addons being backported from later expansions.
Implemented in pure C: builds a Lua C closure with (orig, callback)
as upvalues; the wrapper calls orig with LUA_MULTRET, then callback,
then returns orig's full result list. No return-count cap — works
correctly for functions returning any number of values.
Errors via lua_error on:
- Non-string
name - Non-function
callback target[name]not resolvable to a function (covers typos and hooking unknown frame methods)
Table
table.wipe(t)
Removes every key from t, leaving it empty but preserving its
internal hash and array capacity. Returns t for chaining.
local cache = {}
-- ... fill it up ...
table.wipe(cache) -- cache is now {}
local also_t = table.wipe(t2) -- also_t === t2 after wipe
Port of Blizzard's 3.3.5 implementation at VA 0x00852180 — same
pattern, just using 1.12's Lua 5.0 entry points instead of 5.1's.
Both Lua versions' lua_next walks the hash node array linearly,
so the canonical lua_next + rawset(k, nil) "during-iteration
removal" pattern works in practice even though it's technically
undefined per the Lua reference manual.
Errors on non-table input.
Input
1.12 ships IsShiftKeyDown / IsControlKeyDown / IsAltKeyDown but
they only report "any shift/ctrl/alt" — there's no built-in way to tell
left from right. These seven functions add the missing distinction
plus an IsModifierKeyDown() rollup.
IsLeftShiftKeyDown() / IsRightShiftKeyDown()
IsLeftControlKeyDown() / IsRightControlKeyDown()
IsLeftAltKeyDown() / IsRightAltKeyDown()
Each returns 1 when the corresponding key is physically down, nil
otherwise — matching the convention 1.12's own IsShiftKeyDown etc.
use.
if IsLeftShiftKeyDown() and not IsRightShiftKeyDown() then
-- left-shift-only binding
end
IsModifierKeyDown()
Returns 1 if any of the six modifier keys is down, nil
otherwise. Equivalent to
IsShiftKeyDown() or IsControlKeyDown() or IsAltKeyDown() but in one
call.
MODIFIER_STATE_CHANGED event
Fires on every modifier-key press and release with (key, down):
| arg1 (key) | LSHIFT, RSHIFT, LCTRL, RCTRL, LALT, RALT |
| arg2 (down) | 1 on press, 0 on release |
Only transitions fire — key autorepeat does not. Matches 2.4.3+ semantics.
local f = CreateFrame("Frame")
f:RegisterEvent("MODIFIER_STATE_CHANGED")
f:SetScript("OnEvent", function()
-- in vanilla 1.12 OnEvent receives no args; engine sets `event` and
-- `arg1..argN` as globals before invoking the handler.
if event == "MODIFIER_STATE_CHANGED" and arg1 == "LSHIFT" then
print("left shift", arg2 == 1 and "down" or "up")
end
end)
Implementation notes
L/R modifier distinction doesn't exist anywhere in the 1.12 engine's
own state — its IsShiftKeyDown chain bottoms out at
GetKeyState(VK_SHIFT) (the merged virtual key, 0x10), never the
L/R-aware VK_LSHIFT / VK_RSHIFT. The OS-level keystate does have
the distinction; we capture it by installing a WH_GETMESSAGE Win32
thread hook on the engine's message-pump thread, decoding each
WM_KEY{,SYS}{DOWN,UP} message (using MapVirtualKeyA(scancode, MAPVK_VSC_TO_VK_EX) to resolve VK_SHIFT to L/R and the KF_EXTENDED
bit in lParam for VK_CONTROL / VK_MENU), and maintaining a
6-bit cached bitmap that the seven query functions read.
The thread-message hook is per-thread, not per-HWND — it survives
renderer-state changes that recreate WoW's main window (e.g. toggling
vertical sync), where an SetWindowLongPtr-style WNDPROC subclass
would be left dangling.
Talent
GetTalentSpellID(tabIndex, talentIndex, [rank])
Returns the spellID for the talent at the given (tabIndex, talentIndex)
and rank, or nil if the talent index is out of range or the rank slot
is empty. 1.12's GetTalentInfo returns (name, icon, tier, column, currentRank, maxRank, ...) with no spellID; this fills the gap so
addons can chain into the spell APIs without maintaining their own
(class, tab, idx) → spellID lookup tables.
GetTalentSpellID(1, 9) -- 14751 (Inner Focus, single rank)
GetTalentSpellID(1, 1) -- 14525 (Wand Specialization, current rank)
GetTalentSpellID(1, 1, 1) -- 14524 (Wand Specialization rank 1)
GetTalentSpellID(1, 1, 2) -- 14525 (Wand Specialization rank 2)
-- chains into the spell APIs cleanly
GameTooltip:SetSpellByID(GetTalentSpellID(1, 9))
print(C_Spell.GetSpellName(GetTalentSpellID(1, 9))) -- "Inner Focus"
rank is optional. When omitted, defaults to the player's currentRank
by delegating to the engine's existing GetTalentInfo (5th return) —
that's the same player-state derivation the engine uses for talent UI
rendering, including the spell-knowledge checks that account for
talent-granted abilities. If currentRank is 0 (no points spent), falls
back to rank 1 so the function still produces the talent's canonical
spellID for unallocated talents.
When provided explicitly, returns the spellID at that rank regardless of how many points the player has invested. Useful for tooltip-on-hover scenarios where you want to preview "what rank 5 would do" without respec'ing.
Returns nil for:
- non-numeric or non-positive
tabIndex/talentIndex tabIndexortalentIndexout of range for the player's class- explicit
rankexceeding the talent's allocated max — e.g. asking for rank 5 on a 1-rank talent like Inner Focus
Reads the engine's per-tab talent arrays at [0x00BDCD28] (populated
at login from Talent.dbc filtered by class). The SpellRank[] array
lives at offset +0x10 of each TalentEntry (stride 0x54), with
one spellID per rank — vanilla populates indices 0..4 (ranks 1..5),
the higher slots stay zero.
Equivalent to one of GetTalentInfo's extended returns in modern WoW
(varies by version; the talent's spellID has been part of the tuple
since 5.0+).
GetTalentIDByIndex(tabIndex, talentIndex)
Returns the engine's hidden talentID — the primary key of the
Talent.dbc row — for the talent at the given (tab, idx). Returns
nil for out-of-range indices.
GetTalentIDByIndex(1, 9) -- 174 (Inner Focus, Discipline tier 3)
GetTalentIDByIndex(1, 1) -- 166 (first Discipline talent)
1.12's GetTalentInfo(tab, idx) returns
(name, icon, tier, column, currentRank, maxRank, ...) but NOT the
talentID. Modern WoW exposes it (and uses talentIDs as the natural
key for GetTalentInfoByID, talent build sharing strings, etc.); we
add this getter so addons that key on talentIDs from later expansions
work unmodified.
Reads TalentEntry+0x00 from the per-tab talent arrays at
[0x00BDCD28]. Same struct walk as GetTalentSpellID, just reads
a different field.
Equivalent to the talentID return slot of GetTalentInfo in modern
WoW (5.0+; not exposed at all in 1.12).
Time
GetServerTime()
Returns the current server clock as a Unix epoch timestamp (seconds since
1970-01-01 UTC), or nil before login (while the engine's game-time
struct is still BSS-zero).
local now = GetServerTime()
-- now = 1778260148 (Fri 2026-05-08 17:09:08 UTC)
Reads year/month/day/hour/minute from the engine's game-time struct at
0x00CE8538 (populated from SMSG_LOGIN_VERIFY_WORLD /
SMSG_LOGIN_SETTIMESPEED and advanced by the internal tick handler) and
converts via _mkgmtime. Stock GetTime() returns frame-relative
seconds-since-login and is useless for wall-clock alignment; this is the
right call for calendar / log-timestamp / cooldown-sync use cases.
Sub-minute accuracy. The 1.12 wire protocol carries time at minute granularity — the packed gametime field has no seconds — so the engine's clock only steps every minute. We interpolate within the minute using
GetTickCount: whenever we observe the engine's minute change, we anchor to the current tick and add(now - anchor) / 1000seconds for subsequent calls in that minute.The very first call after login lands at second
:00of the current minute (we have no way to know how far in we are when we first see it), so the cold-start value can be off by 0..59 seconds. After the first minute rollover we observe, the anchor lands at the rollover boundary and the timestamp is accurate to within a second of the engine's clock for as long as the session continues.
Equivalent to the function of the same name introduced in 3.0.
C_DateAndTime overview
Backport of the modern C_DateAndTime namespace — calendar-style
date math built on top of GetServerTime(). All seven functions
exchange CalendarTime tables with these fields (matching
Blizzard's TimeDocumentation.lua):
| Field | Range | Notes |
|---|---|---|
year |
full year, e.g. 2026 | |
month |
1..12 | luaIndex (1-based) |
monthDay |
1..31 | luaIndex (1-based) |
weekday |
1..7 | luaIndex; 1 = Sunday |
hour |
0..23 | |
minute |
0..59 |
Daily reset semantics.
GetSecondsUntilDailyResettreats reset as midnight in server wall-clock time. This is exactly whatGetServerTime() % 86400 == 0gives you — the engine's gametime components are converted to an epoch by treating them as UTC, so day boundaries in epoch math align with server-clock midnight.Weekly reset not implemented. Vanilla has no server-broadcast weekly reset schedule, and Turtle WoW realm schedules vary, so
C_DateAndTime.GetSecondsUntilWeeklyResetwould have to hardcode a weekday/hour that's wrong on some realms. Addons that need it can compute their own value from the daily reset + a CVAR.
C_DateAndTime.GetCurrentCalendarTime()
Returns the server clock as a CalendarTime table, or nothing before
login. Equivalent to GetCalendarTimeFromEpoch(GetServerTime()).
local t = C_DateAndTime.GetCurrentCalendarTime()
-- t = { year=2026, month=5, monthDay=11, weekday=2, hour=14, minute=30 }
C_DateAndTime.GetCalendarTimeFromEpoch(epoch)
Converts a Unix epoch (seconds since 1970-01-01 UTC) to a
CalendarTime table. Pure gmtime; no engine state touched.
C_DateAndTime.AdjustTimeByDays(date, days) / AdjustTimeByMinutes(date, minutes)
Returns a new CalendarTime offset from the input by the given number
of days (or minutes). Negative deltas walk backwards. Out-of-range
inputs (month=13, monthDay=32) normalize via the underlying
_mkgmtime / gmtime round-trip.
local today = C_DateAndTime.GetCurrentCalendarTime()
local tomorrow = C_DateAndTime.AdjustTimeByDays(today, 1)
local yesterday = C_DateAndTime.AdjustTimeByDays(today, -1)
C_DateAndTime.CompareCalendarTime(lhs, rhs)
Returns -1 if lhs < rhs, 0 if equal, 1 if lhs > rhs.
Compares by epoch conversion so denormalized inputs sort
consistently.
C_DateAndTime.GetServerTimeLocal()
Returns the server's wall clock re-interpreted as a Unix epoch in
the player's local timezone. Useful when you want to feed a
server-clock value into Lua's date(format, epoch) and have the
formatted string show the server's apparent hour/minute. If the
server reports 14:30 and the player is in UTC-5, this returns the
epoch that corresponds to 14:30 in UTC-5 (which is 19:30 UTC).
C_DateAndTime.GetSecondsUntilDailyReset()
Returns seconds until the next server midnight (00:00:00 in server wall-clock time). Returns 0 if called before login.
See the overview's "Daily reset semantics" note — this uses server midnight, not UTC midnight (though they happen to coincide for Turtle WoW since the server reports UTC-aligned components).
Events
C_EventUtils.IsEventValid(eventName)
Returns true if the named event exists in the engine's event-name table
and can be registered for, false otherwise. Equivalent to the modern
function of the same name; useful for addons that gate code behind feature
detection (e.g. registering for events that exist in some client builds
but not others).
if C_EventUtils.IsEventValid("PLAYER_LOGIN") then ... end -- true
if C_EventUtils.IsEventValid("COMBAT_LOG_EVENT") then ... end -- false (added in 3.x)
The check walks the engine's static event-name table at runtime, so it
sees events added by any loaded DLL that injects names by overwriting
.rdata strings in place — for example, on a Turtle WoW client running
SuperWoWhook, IsEventValid("UNIT_CASTEVENT") returns true because
SuperWoWhook patches the binary's event names with its own. This matches
what frame:RegisterEvent will actually accept, which is what addon code
needs to know.
BAG_UPDATE_DELAYED event
Fires (with no payload) once per frame in which any BAG_UPDATE
fired. Matches modern WoW's coalescing semantic exactly — register
for BAG_UPDATE_DELAYED instead of BAG_UPDATE and rescan once
per frame regardless of how many updates fired.
local f = CreateFrame("Frame")
f:RegisterEvent("BAG_UPDATE_DELAYED")
f:SetScript("OnEvent", function() RescanMyInventory() end)
A trade with 6 stacks (12 BAG_UPDATEs, all processed in one
frame) produces exactly 1 BAG_UPDATE_DELAYED at the end of the
frame — matches Classic Era 1.15.x's observed behavior.
Implemented by three hooks, none in regions other DLLs touch:
FUN_004F91A0/FUN_004F9370(bag subsystem at0x004F9xxx) — each just sets ag_pendingflag, no fireFUN_0066FD50(engine's per-frame world-subsystem update at0x0066xxxx, deep in the rendering pipeline, only one caller in the entire binary) — drains the flag at the tail of the world tick
The world-tick hook is a tail hook (run original first, then fire DELAYED), so the fire happens after every other per-frame world work completes. Addon callbacks see DELAYED after their normal event handlers.
Coverage limitation. The keyring
BAG_UPDATE(-2)path goes through a separate function (FUN_004F8DB0) that uses__thiscallwith an awkward register-arg shape. Keyring updates currently won't triggerBAG_UPDATE_DELAYED. Player bag (0..4) and bank (5..10) updates work normally — the 95% case.
Globals
CLASSIC_API_VERSION
Defined once FrameScript has booted. Addons can use this to detect that
the DLL is loaded and which version is in use. The value is
X*10000 + Y*100 + Z for a tag of vX.Y.Z passed to CMake at configure
time via -DCLASSICAPI_TAG=vX.Y.Z. Unset versions resolve to 0.
if CLASSIC_API_VERSION and CLASSIC_API_VERSION >= 10200 then
-- ClassicAPI v1.2.0 or newer is loaded
end
LE_EXPANSION_*
The retail / Classic Era expansion-level enum, exposed as Lua globals
so addons backporting from later expansions don't have to gate on
if LE_EXPANSION_CLASSIC then (the constant being defined is itself
the version probe). Values match the modern Enum.ExpansionLevel
table.
| Constant | Value |
|---|---|
LE_EXPANSION_LEVEL_CURRENT |
0 (this is Classic) |
LE_EXPANSION_CLASSIC |
0 |
LE_EXPANSION_BURNING_CRUSADE |
1 |
LE_EXPANSION_WRATH_OF_THE_LICH_KING |
2 |
LE_EXPANSION_CATACLYSM |
3 |
LE_EXPANSION_MISTS_OF_PANDARIA |
4 |
LE_EXPANSION_WARLORDS_OF_DRAENOR |
5 |
LE_EXPANSION_LEGION |
6 |
LE_EXPANSION_BATTLE_FOR_AZEROTH |
7 |
LE_EXPANSION_SHADOWLANDS |
8 |
LE_EXPANSION_DRAGONFLIGHT |
9 |
LE_EXPANSION_WAR_WITHIN |
10 |
LE_EXPANSION_MIDNIGHT |
11 |
-- Classic version check using modern idiom
if LE_EXPANSION_LEVEL_CURRENT < LE_EXPANSION_BURNING_CRUSADE then
-- pure-1.x (vanilla / Classic Era) code path
end
-- Probe for ClassicAPI presence
if LE_EXPANSION_LEVEL_CURRENT then
-- the constants are defined → ClassicAPI is loaded
end
LE_ITEM_QUALITY_*
The item-quality enum (modern Enum.ItemQuality), exposed as Lua
globals so addons backporting modern code can do
if quality >= LE_ITEM_QUALITY_RARE then ... against the integer
quality returned by GetItemInfo / C_Item.GetItemInfoInstant.
| Constant | Value | Color in tooltip |
|---|---|---|
LE_ITEM_QUALITY_POOR |
0 |
gray (junk) |
LE_ITEM_QUALITY_COMMON |
1 |
white |
LE_ITEM_QUALITY_UNCOMMON |
2 |
green |
LE_ITEM_QUALITY_RARE |
3 |
blue |
LE_ITEM_QUALITY_EPIC |
4 |
purple |
LE_ITEM_QUALITY_LEGENDARY |
5 |
orange |
LE_ITEM_QUALITY_ARTIFACT |
6 |
gold (TBC+ only) |
LE_ITEM_QUALITY_HEIRLOOM |
7 |
light blue (WotLK+ only) |
LE_ITEM_QUALITY_WOWTOKEN |
8 |
orange (WoD+ only) |
Values 0..5 (POOR..LEGENDARY) correspond to actual qualities present
in vanilla 1.12. Higher values are exposed for source compatibility
with modern addons — vanilla items will never carry those quality
values, so a comparison like quality == LE_ITEM_QUALITY_HEIRLOOM
trivially never matches and the rest of the code path is unreachable.
local _, _, quality = GetItemInfo(itemID)
if quality and quality >= LE_ITEM_QUALITY_RARE then
-- highlight in UI
end
LE_UNIT_STAT_*
The primary-stat enum (modern Enum.UnitStat), exposed as Lua globals
so addons can index UnitStat(unit, statIndex) symbolically:
| Constant | Value | Stat |
|---|---|---|
LE_UNIT_STAT_STRENGTH |
1 |
Strength |
LE_UNIT_STAT_AGILITY |
2 |
Agility |
LE_UNIT_STAT_STAMINA |
3 |
Stamina |
LE_UNIT_STAT_INTELLECT |
4 |
Intellect |
LE_UNIT_STAT_SPIRIT |
5 |
Spirit |
Values are stable across every WoW expansion — UnitStat("player", 1)
has always returned strength.
local _, effective = UnitStat("player", LE_UNIT_STAT_AGILITY)