mirror of
https://github.com/brues-code/ClassicAPI.git
synced 2026-11-16 16:10:36 +00:00
1449 lines
58 KiB
Markdown
1449 lines
58 KiB
Markdown
# ClassicAPI — Lua Reference
|
||
|
||
Per-function reference for the calls ClassicAPI adds to the WoW 1.12.1 Lua
|
||
environment. See the [project README](../README.md) for installation and
|
||
build instructions.
|
||
|
||
## Contents
|
||
|
||
- [Spell](#spell)
|
||
- [`GetSpellInfo(spellID)` / `GetSpellInfo(slot, bookType)`](#getspellinfospellid--getspellinfoslot-booktype)
|
||
- [`C_Spell.GetSpellInfo(spellID)`](#c_spellgetspellinfospellid)
|
||
- [`C_Spell.GetSpellName(spellID)`](#c_spellgetspellnamespellid)
|
||
- [`C_Spell.GetSpellTexture(spellID)`](#c_spellgetspelltexturespellid)
|
||
- [`FindSpellBookSlotByID(spellID)`](#findspellbookslotbyidspellid)
|
||
- [`GetSpellLink(spellID)` / `GetSpellLink(slot, bookType)`](#getspelllinkspellid--getspelllinkslot-booktype)
|
||
- [`C_Spell.GetSpellLink(spellID)`](#c_spellgetspelllinkspellid)
|
||
- [`C_Spell.GetSpellDescription(spellID)`](#c_spellgetspelldescriptionspellid)
|
||
- [`IsPassiveSpell(spellID)` / `IsPassiveSpell(slot, bookType)`](#ispassivespellspellid--ispassivespellslot-booktype)
|
||
- [`C_Spell.IsSpellPassive(spellID)`](#c_spellisspellpassivespellid)
|
||
- [`IsPlayerSpell(spellID)`](#isplayerspellspellid)
|
||
- [`IsSpellKnown(spellID, [isPet])`](#isspellknownspellid-ispet)
|
||
- [GameTooltip](#gametooltip)
|
||
- [`GameTooltip:SetSpellByID(spellID)`](#gametooltipsetspellbyidspellid)
|
||
- [Quest](#quest)
|
||
- [`GetQuestIDFromLogIndex(index)`](#getquestidfromlogindexindex)
|
||
- [`C_QuestLog.RequestLoadQuestByID(questID)`](#c_questlogrequestloadquestbyidquestid)
|
||
- [`C_QuestLog.GetTitleForQuestID(questID)`](#c_questloggettitleforquestidquestid)
|
||
- [Faction](#faction)
|
||
- [`GetFactionIDByIndex(factionIndex)`](#getfactionidbyindexfactionindex)
|
||
- [`GetFactionInfoByID(factionID)`](#getfactioninfobyidfactionid)
|
||
- [`GetFactionParentID(factionID)`](#getfactionparentidfactionid)
|
||
- [Item](#item)
|
||
- [`C_Item.IsBound(itemLocation)`](#c_itemisbounditemlocation)
|
||
- [`C_Item.GetItemID(itemLocation)`](#c_itemgetitemiditemlocation)
|
||
- [`GetInventoryItemID(unit, slot)`](#getinventoryitemidunit-slot)
|
||
- [`GetInventoryItemDurability(invSlot)`](#getinventoryitemdurabilityinvslot)
|
||
- [`C_Item.GetItemFamily(item)`](#c_itemgetitemfamilyitem)
|
||
- [`C_Item.GetItemCount(itemInfo, [includeBank], [includeUses])`](#c_itemgetitemcountiteminfo-includebank-includeuses)
|
||
- [`GetItemIcon(itemID)` / `C_Item.GetItemIcon(itemLocation)` / `C_Item.GetItemIconByID(item)`](#getitemiconitemid--c_itemgetitemiconitemlocation--c_itemgetitemiconbyiditem)
|
||
- [`C_Item.GetItemInfoInstant(item)`](#c_itemgetiteminfoinstantitem)
|
||
- [`C_Item.IsItemDataCachedByID(item)` / `C_Item.IsItemDataCached(itemLocation)`](#c_itemisitemdatacachedbyiditem--c_itemisitemdatacacheditemlocation)
|
||
- [`C_Item.RequestLoadItemDataByID(item)` / `C_Item.RequestLoadItemData(itemLocation)`](#c_itemrequestloaditemdatabyiditem--c_itemrequestloaditemdataitemlocation)
|
||
- [Container](#container)
|
||
- [`C_Container.GetContainerItemID(bagIndex, slotIndex)`](#c_containergetcontaineritemidbagindex-slotindex)
|
||
- [`C_Container.GetContainerItemDurability(containerIndex, slotIndex)`](#c_containergetcontaineritemdurabilitycontainerindex-slotindex)
|
||
- [`C_Container.GetContainerNumFreeSlots(bagID)`](#c_containergetcontainernumfreeslotsbagid)
|
||
- [`C_Container.PlayerHasHearthstone()`](#c_containerplayerhashearthstone)
|
||
- [`C_Container.UseHearthstone()`](#c_containerusehearthstone)
|
||
- [Unit](#unit)
|
||
- [`UnitGUID(unit)`](#unitguidunit)
|
||
- [`UnitIsAFK(unit)`](#unitisafkunit)
|
||
- [`UnitIsDND(unit)`](#unitisdndunit)
|
||
- [`UnitIsFeignDeath(unit)`](#unitisfeigndeathunit)
|
||
- [Combat](#combat)
|
||
- [`InCombatLockdown()`](#incombatlockdown)
|
||
- [Talent](#talent)
|
||
- [`GetTalentSpellID(tabIndex, talentIndex, [rank])`](#gettalentspellidtabindex-talentindex-rank)
|
||
- [`GetTalentIDByIndex(tabIndex, talentIndex)`](#gettalentidbyindextabindex-talentindex)
|
||
- [Time](#time)
|
||
- [`GetServerTime()`](#getservertime)
|
||
- [Events](#events)
|
||
- [`C_EventUtils.IsEventValid(eventName)`](#c_eventutilsiseventvalideventname)
|
||
- [Globals](#globals)
|
||
- [`CLASSIC_API_VERSION`](#classic_api_version)
|
||
|
||
## 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's
|
||
`GetSpellName(slot, bookType)`. `slot` is 1-based, `bookType` is
|
||
`"spell"` (player) or `"pet"`. The slot is resolved to a spellID via
|
||
the engine's spellbook array, then the same DBC reads run. Returns
|
||
`nil` for empty / out-of-range slots.
|
||
|
||
```lua
|
||
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 `spellID` at 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 |
|
||
|
||
```lua
|
||
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 `iconID` as a
|
||
> `fileID: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 with `texture: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 in `Spell.dbc` and the previous-generation `GetSpellInfo` exposed
|
||
> 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`](#c_spellgetspellinfospellid)
|
||
when that's all you need — single field read, no DBC indirection beyond
|
||
the locale lookup.
|
||
|
||
```lua
|
||
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 on [`C_Spell.GetSpellInfo`](#c_spellgetspellinfospellid)'s
|
||
> `iconID` field. Pass directly to `texture:SetTexture(...)`.
|
||
|
||
```lua
|
||
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 `nil` if 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.
|
||
|
||
```lua
|
||
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`](#getspellinfospellid--getspellinfoslot-booktype):
|
||
|
||
- `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.
|
||
|
||
```lua
|
||
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)`](#getspelllinkspellid--getspelllinkslot-booktype),
|
||
but returns only the link — no spellID echo since the caller already
|
||
had it on hand to make the call.
|
||
|
||
```lua
|
||
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.
|
||
|
||
```lua
|
||
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:SetSpellByID` and 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.
|
||
|
||
```lua
|
||
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)`](#c_spellisspellpassivespellid)
|
||
(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`](#ispassivespellspellid--ispassivespellslot-booktype).
|
||
Same return semantics, but takes a spellID only — `C_Spell.*` calls
|
||
don't accept the older spellbook slot + bookType shape.
|
||
|
||
```lua
|
||
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"
|
||
|
||
```lua
|
||
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 return `false` even though the player
|
||
> conceptually "has" them. Matches the same semantic Classic Era 1.15.x
|
||
> uses: a player with 5/5 Unbreakable Will sees `IsPlayerSpell(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`.
|
||
|
||
```lua
|
||
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: `IsSpellKnown` is the strict "in the spellbook UI" check,
|
||
> `IsPlayerSpell` is the broad "any kind of known" query. The split
|
||
> matters because:
|
||
>
|
||
> | Spell type | `IsPlayerSpell` | `IsSpellKnown` |
|
||
> |---|---|---|
|
||
> | Trained class ability (Fireball) | `true` | `true` |
|
||
> | Active talent grant (Mortal Strike) | `true` | `true` |
|
||
> | Passive talent (Wand Spec, Imp Fireball) | `true` | **`false`** |
|
||
> | Profession recipe (Bolt of Linen) | `true` | **`false`** |
|
||
>
|
||
> Use `IsPlayerSpell` for "do I have access to this effect at all";
|
||
> use `IsSpellKnown` for "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.
|
||
|
||
## 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.
|
||
|
||
```lua
|
||
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 by
|
||
> `SMSG_ITEM_QUERY_SINGLE_RESPONSE` only 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:
|
||
>
|
||
> ```lua
|
||
> 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
|
||
> end
|
||
> ```
|
||
>
|
||
> This caching behavior matches what `C_Item.GetItemInfoInstant`
|
||
> documents — same underlying cache. Modern WoW (5.0+) has the same
|
||
> caveat, just with `C_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.
|
||
|
||
```lua
|
||
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.
|
||
|
||
```lua
|
||
GameTooltip:SetOwner(UIParent, "ANCHOR_CURSOR")
|
||
GameTooltip:SetSpellByID(133) -- Fireball
|
||
GameTooltip:Show()
|
||
```
|
||
|
||
Equivalent to the function of the same name introduced in 3.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 `0` for header rows (zone / category dividers).
|
||
- Returns `nil` if the index is out of range.
|
||
|
||
```lua
|
||
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 — `success`
|
||
> arrives as `1`/`0` (number), not `true`/`false`, just like
|
||
> `ITEM_DATA_LOAD_RESULT`. Idiomatic check is `if 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_RESULT` doesn't fire with `success=0`
|
||
> either. Modern Classic Era servers explicitly respond with an error
|
||
> for invalid IDs, which is why modern `RequestLoadQuestByID` reliably
|
||
> fires `success=false`; vanilla doesn't. Addons that need to handle
|
||
> "request timed out" should use their own timer (the Lua polyfill at
|
||
> `!!!ClassicAPI/Util/QuestUtil.lua` uses a 180-second wait).
|
||
|
||
```lua
|
||
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:
|
||
|
||
```lua
|
||
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 `0` for header / category rows (`"Other"`, `"Inactive"`, etc.) —
|
||
matching the modern Classic Era client, which puts `0` in
|
||
`GetFactionInfo`'s `factionID` slot for those rows.
|
||
- Returns `nil` if 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.
|
||
|
||
```lua
|
||
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 flags `nil`. Matches what 3.3.5's
|
||
`GetFactionInfoByID` returns for unencountered factions.
|
||
- **Invalid factionID** (out of range or empty DBC slot) — `nil`.
|
||
|
||
```lua
|
||
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.
|
||
|
||
```lua
|
||
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`).
|
||
|
||
## 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):
|
||
|
||
```lua
|
||
{ equipmentSlotIndex = N } -- 1-based, character pane
|
||
{ bagID = B, slotIndex = S } -- both required
|
||
```
|
||
|
||
```lua
|
||
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`:
|
||
|
||
```lua
|
||
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 range `GetItemBySlot` accepts 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
|
||
on `UnitPlayerControlled` to avoid the engine crash that
|
||
`GetInventoryItemLink` itself would trigger on the same input.
|
||
|
||
```lua
|
||
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)
|
||
```
|
||
|
||
```lua
|
||
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+ `GetInventoryItemDurability`
|
||
> takes 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 — `max` is the discriminator,
|
||
> matching the engine's own `GetInventoryItemBroken` logic.
|
||
|
||
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`](#c_itemisbounditemlocation) 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_itemgetiteminfoinstantitem).
|
||
|
||
```lua
|
||
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 via `bitmask = 1 << (rawID - 1)`, so
|
||
> callers backporting from modern see the encoding they expect — addons
|
||
> can `band(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.GetItemFamily` works 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's `subClass` via
|
||
> [`C_Item.GetItemInfoInstant`](#c_itemgetiteminfoinstantitem)
|
||
> instead. The Quiver class is fully populated; everything else needs
|
||
> the subClass fallback.
|
||
|
||
> **`nil` vs `0`.** Modern WoW returns `0` for items the cache lookup
|
||
> fails on; we return `nil` so callers can distinguish "item not
|
||
> cached, retry after the event lands" from "item exists but has no
|
||
> family preference." Both are safe to treat as `0` for routing-logic
|
||
> purposes; the distinction helps debugging.
|
||
|
||
> **Auto-warmup on cache miss.** First call for an uncached item
|
||
> returns `nil` AND triggers the engine's cache fill in the
|
||
> background. Listen for `GET_ITEM_INFO_RECEIVED(itemID, success)` and
|
||
> retry once the matching `itemID` arrives. 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's `GetItemFamily` doesn't fire
|
||
> any event when the cache lands (silent fill), whereas we fire
|
||
> `GET_ITEM_INFO_RECEIVED` to 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` — numeric `itemID` or 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 `-1` for the main bank, bags `5..10` for bank-bag slots).
|
||
- `includeUses` *(optional, default false)* — **accepted but
|
||
currently ignored.** Returns the same value as `false` regardless.
|
||
See note below.
|
||
|
||
```lua
|
||
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
|
||
```
|
||
|
||
> **`includeUses` not yet supported.** Modern semantics: when `true`,
|
||
> multiplies each match by the item's spell-charges count (a stack
|
||
> of 5 wands × 50 charges each → 250). Implementing this needs the
|
||
> `ITEM_FIELD_SPELL_CHARGES` descriptor offset, which hasn't been
|
||
> verified empirically yet. The arg is accepted for API parity so
|
||
> backported code doesn't break, but currently both `true` and
|
||
> `false` produce 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 `GetItemBySlot` gates 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 path `GetItemBySlot` would 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`](#c_containergetcontaineritemidbagindex-slotindex)
|
||
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(...)`.
|
||
|
||
```lua
|
||
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 a
|
||
> `fileID:number` (specifically `iconFileID` in Classic Era 1.15.x). 1.12
|
||
> has no fileID system — same situation as
|
||
> [`C_Spell.GetSpellTexture`](#c_spellgetspelltexturespellid) and
|
||
> [`C_Spell.GetSpellInfo`](#c_spellgetspellinfospellid)'s `iconID` field.
|
||
> 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` / `itemSubType` are the localized class / subclass names
|
||
(e.g. `"Weapon"` / `"One-Handed Swords"`), read from `ItemClass.dbc` and
|
||
`ItemSubClass.dbc`.
|
||
- `itemEquipLoc` is the `"INVTYPE_*"` constant (e.g. `"INVTYPE_HEAD"`), or
|
||
`""` for non-equippable items.
|
||
- `icon` is 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` / `subClassID` are the raw enum integers (e.g. `2`, `7` for
|
||
one-handed swords).
|
||
|
||
```lua
|
||
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.
|
||
|
||
```lua
|
||
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 — `success`
|
||
> arrives as `1`/`0` (number), not `true`/`false`. Idiomatic check is
|
||
> `if success == 1 then ...`.
|
||
|
||
```lua
|
||
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)
|
||
```
|
||
|
||
## 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's `PackBagSlot` rejects out-of-range slots and returns nil
|
||
cleanly).
|
||
|
||
```lua
|
||
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`](#getinventoryitemdurabilityinvslot).
|
||
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.
|
||
|
||
```lua
|
||
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`](#c_containergetcontaineritemidbagindex-slotindex)
|
||
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 cached `ItemStats_C` record —
|
||
`m_containerSlots` and `m_bagFamily` respectively. If no bag is
|
||
equipped (or the item somehow isn't cached): `(0, 0)`.
|
||
- Other `bagID` values (bank, keyring, out-of-range): `(0, 0)`. Always
|
||
returns two values, never nil.
|
||
|
||
```lua
|
||
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 `bagType` is 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)`
|
||
> from [`C_Item.GetItemInfoInstant`](#c_itemgetiteminfoinstantitem).
|
||
> The same field on **individual loot items** (arrows, bullets,
|
||
> shards, herbs) IS populated reliably — use
|
||
> [`C_Item.GetItemFamily`](#c_itemgetitemfamilyitem) for routing
|
||
> decisions.
|
||
|
||
> **The bitmask encoding matches modern.** `bagType` is the bit
|
||
> position (`1 << (familyID - 1)`), not the raw 1.12-stored familyID,
|
||
> so callers can bitwise-AND with itemFamily values from
|
||
> [`C_Item.GetItemFamily`](#c_itemgetitemfamilyitem) directly. We
|
||
> convert internally — see that function's notes for the
|
||
> encoding-shift story.
|
||
|
||
Implementation walks the bag using
|
||
[`Item::Location::ResolveBag`](#c_containergetcontaineritemidbagindex-slotindex)
|
||
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. Vanilla 1.12 only has a single hearthstone item
|
||
(itemID `6948`), so the return is always either `6948` or `nil`.
|
||
|
||
```
|
||
itemID = C_Container.PlayerHasHearthstone()
|
||
```
|
||
|
||
```lua
|
||
if C_Container.PlayerHasHearthstone() then
|
||
-- player can hearth
|
||
end
|
||
```
|
||
|
||
> **Modern WoW returns the actual itemID found.** Modern clients
|
||
> recognize a list of hearthstone-equivalent toys (Garrison
|
||
> Hearthstone, Dalaran Hearthstone, etc.); whichever is found in bags
|
||
> is returned. None of those items exist in 1.12, so the original
|
||
> Hearthstone (`6948`) is the only possible result here. Code
|
||
> backporting from modern that does
|
||
> `local id = C_Container.PlayerHasHearthstone()` works without
|
||
> modification — `id` is just always `6948` when truthy.
|
||
|
||
Walks bags 0..4 via the same chain
|
||
[`C_Container.GetContainerItemID`](#c_containergetcontaineritemidbagindex-slotindex)
|
||
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()
|
||
```
|
||
|
||
```lua
|
||
if not C_Container.UseHearthstone() then
|
||
print("No hearthstone in bags!")
|
||
end
|
||
```
|
||
|
||
> **`true` doesn't guarantee the cast started.** The return reflects
|
||
> "we had a hearthstone to try with and called the engine's
|
||
> `UseContainerItem` on it." Whether the cast actually starts depends
|
||
> on cooldown, combat, movement, etc. — same downstream rules as
|
||
> calling `UseContainerItem(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.
|
||
|
||
## 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 (NULL pointer or all zeroes).
|
||
|
||
```lua
|
||
local guid = UnitGUID("player") -- "0x0000000000000777" (low IDs are local-realm characters)
|
||
local guid = UnitGUID("target") -- "0xF13000059A002553" (the F130... prefix tags creatures)
|
||
```
|
||
|
||
> **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.
|
||
|
||
### `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`.
|
||
|
||
```lua
|
||
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.
|
||
|
||
```lua
|
||
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.
|
||
|
||
```lua
|
||
UnitIsFeignDeath("target") -- true if a feigning hunter
|
||
```
|
||
|
||
> **Untested.** The flag-bit value is the standard vanilla emulator
|
||
> constant; the function compiles and won't crash, but we haven't
|
||
> confirmed the bit position against live data (no Hunter on hand).
|
||
> If a Hunter happens to be nearby and using FD,
|
||
> `/dump UnitIsFeignDeath("target")` is the diagnostic.
|
||
|
||
Equivalent to the function of the same name introduced in 3.0.
|
||
|
||
## 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`.
|
||
|
||
```lua
|
||
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.
|
||
|
||
## 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.
|
||
|
||
```lua
|
||
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`
|
||
- `tabIndex` or `talentIndex` out of range for the player's class
|
||
- explicit `rank` exceeding 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.
|
||
|
||
```lua
|
||
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).
|
||
|
||
```lua
|
||
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) / 1000`
|
||
> seconds for subsequent calls in that minute.
|
||
>
|
||
> The very first call after login lands at second `:00` of 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.
|
||
|
||
## 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).
|
||
|
||
```lua
|
||
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.
|
||
|
||
## 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`.
|
||
|
||
```lua
|
||
if CLASSIC_API_VERSION and CLASSIC_API_VERSION >= 10200 then
|
||
-- ClassicAPI v1.2.0 or newer is loaded
|
||
end
|
||
```
|