mirror of
https://github.com/brues-code/ClassicAPI.git
synced 2026-11-15 23:50:38 +00:00
1001 lines
40 KiB
Markdown
1001 lines
40 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)
|
|
- [`C_Container.GetContainerItemID(bagIndex, slotIndex)`](#c_containergetcontaineritemidbagindex-slotindex)
|
|
- [`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)
|
|
- [Unit](#unit)
|
|
- [`UnitGUID(unit)`](#unitguidunit)
|
|
- [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: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)
|
|
```
|
|
|
|
### `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
|
|
```
|
|
|
|
### `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)
|
|
```
|
|
|
|
## 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.
|
|
|
|
## 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
|
|
```
|