From 084cc81ca8dcf6fe705b7011c14c96ffc5da7fb9 Mon Sep 17 00:00:00 2001 From: Brues <5278969+brues-code@users.noreply.github.com> Date: Mon, 18 May 2026 14:29:47 -0500 Subject: [PATCH] Sort docs/API.md sections alphabetically MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Reorders all 30 top-level sections (and the matching Contents TOC groups) by case-insensitive name. Done via a one-shot Python script that sliced the file by ## headers and reassembled in sorted order — no content edits, every per-section sub-bullet and prose block preserved verbatim. Also adds the Hooks TOC group that was missing entirely. The Hooks section existed in the body but had no TOC bullet pointing at it. Sub-bullet count is unchanged before/after (188 ### subsections), confirming nothing was dropped during the reshuffle. --- docs/API.md | 6589 ++++++++++++++++++++++++++------------------------- 1 file changed, 3310 insertions(+), 3279 deletions(-) diff --git a/docs/API.md b/docs/API.md index 05dafe58..72bc3abe 100644 --- a/docs/API.md +++ b/docs/API.md @@ -6,52 +6,68 @@ 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) - - [`IsUsableSpell(spell)` / `IsUsableSpell(slot, bookType)`](#isusablespellspell--isusablespellslot-booktype) - - [`C_Spell.IsSpellUsable(spellID)`](#c_spellisspellusablespellid) - - [`IsHarmfulSpell(spell)` / `IsHelpfulSpell(spell)`](#isharmfulspellspell--ishelpfulspellspell) - - [`C_Spell.IsSpellHarmful(spellID)` / `C_Spell.IsSpellHelpful(spellID)`](#c_spellisspellharmfulspellid--c_spellisspellhelpfulspellid) - - [`C_SpellBook.GetSpellLevelLearned(spellID)`](#c_spellbookgetspelllevellearnedspellid) - - [`C_SpellBook.GetCurrentLevelSpells([level])`](#c_spellbookgetcurrentlevelspellslevel) - - [`C_SpellBook.GetSpellSkillLine(spellID)`](#c_spellbookgetspellskilllinespellid) - - [`GetSpellSchool(spellID)`](#getspellschoolspellid) - - [`CastSpellNoToggle(name | spellID)`](#castspellnotogglename--spellid) -- [Macros](#macros) - - [Numeric spellIDs in `/cast` and `CastSpellByName`](#numeric-spellids-in-cast-and-castspellbyname) - - [`CastSpellNoToggle` as a macro cast line](#castspellnotoggle-as-a-macro-cast-line) -- [GameTooltip](#gametooltip) - - [`GameTooltip:SetSpellByID(spellID)`](#gametooltipsetspellbyidspellid) - - [`GameTooltip:SetTalentByID(talentID)`](#gametooltipsettalentbyidtalentid) - - [`GameTooltip:SetInventoryItemByID(itemID)`](#gametooltipsetinventoryitembyiditemid) - - [`GameTooltip:GetItem()`](#gametooltipgetitem) - - [`GameTooltip:GetSpell()`](#gametooltipgetspell) - - [`GameTooltip:HasItem()` / `GameTooltip:HasSpell()`](#gametooltiphasitem--gametooltiphasspell) -- [Quest](#quest) - - [`C_QuestLog.GetQuestIDFromLogIndex(index)`](#c_questloggetquestidfromlogindexindex) - - [`C_QuestLog.RequestLoadQuestByID(questID)`](#c_questlogrequestloadquestbyidquestid) - - [`C_QuestLog.GetTitleForQuestID(questID)`](#c_questloggettitleforquestidquestid) -- [Gossip](#gossip) - - [`C_GossipInfo.GetText()`](#c_gossipinfogettext) - - [`C_GossipInfo.GetOptions()`](#c_gossipinfogetoptions) - - [`C_GossipInfo.GetAvailableQuests()`](#c_gossipinfogetavailablequests) - - [`C_GossipInfo.GetActiveQuests()`](#c_gossipinfogetactivequests) - - [`C_GossipInfo.GetNumOptions()` / `GetNumAvailableQuests()` / `GetNumActiveQuests()`](#c_gossipinfogetnumoptions--getnumavailablequests--getnumactivequests) - - [`C_GossipInfo.SelectOption(gossipOptionID)` / `SelectOptionByIndex(orderIndex)`](#c_gossipinfoselectoptiongossipoptionid--selectoptionbyindexorderindex) - - [`C_GossipInfo.SelectAvailableQuest(questID)`](#c_gossipinfoselectavailablequestquestid) - - [`C_GossipInfo.SelectActiveQuest(questID)`](#c_gossipinfoselectactivequestquestid) - - [`C_GossipInfo.CloseGossip()`](#c_gossipinfoclosegossip) +- [Action](#action) + - [`GetActionInfo(slot)`](#getactioninfoslot) + +- [AddOns](#addons) + - [`C_AddOns.GetAddOnName(indexOrName)`](#c_addonsgetaddonnameindexorname) + - [`C_AddOns.GetAddOnTitle(indexOrName)`](#c_addonsgetaddontitleindexorname) + - [`C_AddOns.GetAddOnNotes(indexOrName)`](#c_addonsgetaddonnotesindexorname) + - [`C_AddOns.IsAddOnLoadable(indexOrName)`](#c_addonsisaddonloadableindexorname) + - [`C_AddOns.GetAddOnSecurity(indexOrName)`](#c_addonsgetaddonsecurityindexorname) + - [`C_AddOns.DoesAddOnExist(indexOrName)`](#c_addonsdoesaddonexistindexorname) + +- [CharacterList](#characterlist) + - [`GetSavedCharacterOrder(realm)` / `SetSavedCharacterOrder(realm, order)` — GlueXML only](#getsavedcharacterorderrealm--setsavedcharacterorderrealm-order--gluexml-only) + +- [Chat](#chat) + - [`GetCurrentChatGUID()`](#getcurrentchatguid) + +- [Class](#class) + - [`FillLocalizedClassList(table [, isFemale])`](#filllocalizedclasslisttable-isfemale) + +- [Combat](#combat) + - [`InCombatLockdown()`](#incombatlockdown) + +- [Container](#container) + - [`C_Container.GetContainerItemID(bagIndex, slotIndex)`](#c_containergetcontaineritemidbagindex-slotindex) + - [`C_Container.GetContainerItemDurability(containerIndex, slotIndex)`](#c_containergetcontaineritemdurabilitycontainerindex-slotindex) + - [`C_Container.GetContainerItemRepairCost(containerIndex, slotIndex)`](#c_containergetcontaineritemrepaircostcontainerindex-slotindex) + - [`C_Container.GetContainerNumFreeSlots(bagID)`](#c_containergetcontainernumfreeslotsbagid) + - [`C_Container.PlayerHasHearthstone()`](#c_containerplayerhashearthstone) + - [`C_Container.UseHearthstone()`](#c_containerusehearthstone) + - [`C_Item.UseItemByName(itemInfo)`](#c_itemuseitembynameiteminfo) + +- [CVar](#cvar) + - [`C_CVar.GetCVarBool(cvar)`](#c_cvargetcvarboolcvar) + +- [EquipmentSet](#equipmentset) + - [Overview & file format](#overview--file-format) + - [`C_EquipmentSet.CanUseEquipmentSets()`](#c_equipmentsetcanuseequipmentsets) + - [`C_EquipmentSet.GetNumEquipmentSets()`](#c_equipmentsetgetnumequipmentsets) + - [`C_EquipmentSet.GetEquipmentSetIDs()`](#c_equipmentsetgetequipmentsetids) + - [`C_EquipmentSet.GetEquipmentSetID(name)`](#c_equipmentsetgetequipmentsetidname) + - [`C_EquipmentSet.GetEquipmentSetInfo(setID)`](#c_equipmentsetgetequipmentsetinfosetid) + - [`C_EquipmentSet.GetIgnoredSlots(setID)`](#c_equipmentsetgetignoredslotssetid) + - [`C_EquipmentSet.GetItemIDs(setID)`](#c_equipmentsetgetitemidssetid) + - [`C_EquipmentSet.GetItemLocations(setID)`](#c_equipmentsetgetitemlocationssetid) + - [`C_EquipmentSet.CreateEquipmentSet(name [, icon])`](#c_equipmentsetcreateequipmentsetname--icon) + - [`C_EquipmentSet.SaveEquipmentSet(setID [, icon])`](#c_equipmentsetsaveequipmentsetsetid--icon) + - [`C_EquipmentSet.ModifyEquipmentSet(setID, newName)`](#c_equipmentsetmodifyequipmentsetsetid-newname) + - [`C_EquipmentSet.DeleteEquipmentSet(setID)`](#c_equipmentsetdeleteequipmentsetsetid) + - [`C_EquipmentSet.IgnoreSlotForSave(slot)` / `UnignoreSlotForSave` / `IsSlotIgnoredForSave` / `ClearIgnoredSlotsForSave`](#c_equipmentsetignoreslotforsaveslot--unignoreslotforsave--isslotignoredforsave--clearignoredslotsforsave) + - [`C_EquipmentSet.EquipmentSetContainsLockedItems(setID)`](#c_equipmentsetequipmentsetcontainslockeditemssetid) + - [`C_EquipmentSet.UseEquipmentSet(setID)`](#c_equipmentsetuseequipmentsetsetid) + - [`EQUIPMENT_SETS_CHANGED` event](#equipment_sets_changed-event) + - [`EQUIPMENT_SWAP_PENDING` event](#equipment_swap_pending-event) + - [`EQUIPMENT_SWAP_FINISHED` event](#equipment_swap_finished-event) + +- [Events](#events) + - [`C_EventUtils.IsEventValid(eventName)`](#c_eventutilsiseventvalideventname) + - [`BAG_UPDATE_DELAYED` event](#bag_update_delayed-event) + - [Player input-state events (`PLAYER_STARTED_MOVING` / `LOOKING` / `TURNING` + `STOPPED_*`)](#player-input-state-events) + - [`GLOBAL_MOUSE_DOWN` / `GLOBAL_MOUSE_UP` events](#global_mouse_down--global_mouse_up-events) + - [Faction](#faction) - [`GetFactionIDByIndex(factionIndex)`](#getfactionidbyindexfactionindex) - [`GetFactionInfoByID(factionID)`](#getfactioninfobyidfactionid) @@ -62,9 +78,47 @@ build instructions. - [`C_Reputation.SetWatchedFactionByID(factionID)`](#c_reputationsetwatchedfactionbyidfactionid) - [`C_Reputation.GetLastStandingChange()`](#c_reputationgetlaststandingchange) - [`FACTION_STANDING_CHANGED` event](#faction_standing_changed-event) + - [FriendList](#friendlist) - [`C_FriendList.SendWhoQueryByName(name)`](#c_friendlistsendwhoquerybynamename) - [`C_FriendList.IsWhoQueryPending()`](#c_friendlistiswhoquerypending) + +- [GameTooltip](#gametooltip) + - [`GameTooltip:SetSpellByID(spellID)`](#gametooltipsetspellbyidspellid) + - [`GameTooltip:SetTalentByID(talentID)`](#gametooltipsettalentbyidtalentid) + - [`GameTooltip:SetInventoryItemByID(itemID)`](#gametooltipsetinventoryitembyiditemid) + - [`GameTooltip:GetItem()`](#gametooltipgetitem) + - [`GameTooltip:GetSpell()`](#gametooltipgetspell) + - [`GameTooltip:HasItem()` / `GameTooltip:HasSpell()`](#gametooltiphasitem--gametooltiphasspell) + +- [Globals](#globals) + - [`CLASSIC_API_VERSION`](#classic_api_version) + - [`LE_EXPANSION_*`](#le_expansion_) + - [`LE_ITEM_QUALITY_*`](#le_item_quality_) + - [`LE_UNIT_STAT_*`](#le_unit_stat_) + - [`Enum.AddOnSecurityStatus`](#enumaddonsecuritystatus) + +- [Gossip](#gossip) + - [`C_GossipInfo.GetText()`](#c_gossipinfogettext) + - [`C_GossipInfo.GetOptions()`](#c_gossipinfogetoptions) + - [`C_GossipInfo.GetAvailableQuests()`](#c_gossipinfogetavailablequests) + - [`C_GossipInfo.GetActiveQuests()`](#c_gossipinfogetactivequests) + - [`C_GossipInfo.GetNumOptions()` / `GetNumAvailableQuests()` / `GetNumActiveQuests()`](#c_gossipinfogetnumoptions--getnumavailablequests--getnumactivequests) + - [`C_GossipInfo.SelectOption(gossipOptionID)` / `SelectOptionByIndex(orderIndex)`](#c_gossipinfoselectoptiongossipoptionid--selectoptionbyindexorderindex) + - [`C_GossipInfo.SelectAvailableQuest(questID)`](#c_gossipinfoselectavailablequestquestid) + - [`C_GossipInfo.SelectActiveQuest(questID)`](#c_gossipinfoselectactivequestquestid) + - [`C_GossipInfo.CloseGossip()`](#c_gossipinfoclosegossip) + +- [Hooks](#hooks) + - [`hooksecurefunc(name, callback)` / `hooksecurefunc(table, name, callback)`](#hooksecurefuncname-callback--hooksecurefunctable-name-callback) + +- [Input](#input) + - [`IsLeftShiftKeyDown()` / `IsRightShiftKeyDown()`](#isleftshiftkeydown--isrightshiftkeydown) + - [`IsLeftControlKeyDown()` / `IsRightControlKeyDown()`](#isleftcontrolkeydown--isrightcontrolkeydown) + - [`IsLeftAltKeyDown()` / `IsRightAltKeyDown()`](#isleftaltkeydown--isrightaltkeydown) + - [`IsModifierKeyDown()`](#ismodifierkeydown) + - [`MODIFIER_STATE_CHANGED` event](#modifier_state_changed-event) + - [Item](#item) - [`C_Item.IsBound(itemLocation)`](#c_itemisbounditemlocation) - [`C_Item.GetItemID(itemLocation)`](#c_itemgetitemiditemlocation) @@ -94,16 +148,11 @@ build instructions. - [`C_Item.GetItemGUID(itemLocation)`](#c_itemgetitemguiditemlocation) - [`C_Item.GetItemLocation(itemGUID)`](#c_itemgetitemlocationitemguid) - [`Get*ItemID` — companions to the engine's `Get*ItemLink` family](#getitemid--companions-to-the-engines-getitemlink-family) -- [Container](#container) - - [`C_Container.GetContainerItemID(bagIndex, slotIndex)`](#c_containergetcontaineritemidbagindex-slotindex) - - [`C_Container.GetContainerItemDurability(containerIndex, slotIndex)`](#c_containergetcontaineritemdurabilitycontainerindex-slotindex) - - [`C_Container.GetContainerItemRepairCost(containerIndex, slotIndex)`](#c_containergetcontaineritemrepaircostcontainerindex-slotindex) - - [`C_Container.GetContainerNumFreeSlots(bagID)`](#c_containergetcontainernumfreeslotsbagid) - - [`C_Container.PlayerHasHearthstone()`](#c_containerplayerhashearthstone) - - [`C_Container.UseHearthstone()`](#c_containerusehearthstone) - - [`C_Item.UseItemByName(itemInfo)`](#c_itemuseitembynameiteminfo) -- [Action](#action) - - [`GetActionInfo(slot)`](#getactioninfoslot) + +- [Macros](#macros) + - [Numeric spellIDs in `/cast` and `CastSpellByName`](#numeric-spellids-in-cast-and-castspellbyname) + - [`CastSpellNoToggle` as a macro cast line](#castspellnotoggle-as-a-macro-cast-line) + - [MerchantFrame](#merchantframe) - [`C_MerchantFrame.GetItemInfo(slot)`](#c_merchantframegetiteminfoslot) - [`C_MerchantFrame.GetBuybackItemID(slot)`](#c_merchantframegetbuybackitemidslot) @@ -111,45 +160,7 @@ build instructions. - [`C_MerchantFrame.SellAllJunkItems()`](#c_merchantframesellalljunkitems) - [`C_MerchantFrame.IsMerchantItemRefundable(slot)`](#c_merchantframeismerchantitemrefundableslot) - [`C_MerchantFrame.IsSellAllJunkEnabled()`](#c_merchantframeissellalljunkenabled) -- [EquipmentSet](#equipmentset) - - [Overview & file format](#overview--file-format) - - [`C_EquipmentSet.CanUseEquipmentSets()`](#c_equipmentsetcanuseequipmentsets) - - [`C_EquipmentSet.GetNumEquipmentSets()`](#c_equipmentsetgetnumequipmentsets) - - [`C_EquipmentSet.GetEquipmentSetIDs()`](#c_equipmentsetgetequipmentsetids) - - [`C_EquipmentSet.GetEquipmentSetID(name)`](#c_equipmentsetgetequipmentsetidname) - - [`C_EquipmentSet.GetEquipmentSetInfo(setID)`](#c_equipmentsetgetequipmentsetinfosetid) - - [`C_EquipmentSet.GetIgnoredSlots(setID)`](#c_equipmentsetgetignoredslotssetid) - - [`C_EquipmentSet.GetItemIDs(setID)`](#c_equipmentsetgetitemidssetid) - - [`C_EquipmentSet.GetItemLocations(setID)`](#c_equipmentsetgetitemlocationssetid) - - [`C_EquipmentSet.CreateEquipmentSet(name [, icon])`](#c_equipmentsetcreateequipmentsetname--icon) - - [`C_EquipmentSet.SaveEquipmentSet(setID [, icon])`](#c_equipmentsetsaveequipmentsetsetid--icon) - - [`C_EquipmentSet.ModifyEquipmentSet(setID, newName)`](#c_equipmentsetmodifyequipmentsetsetid-newname) - - [`C_EquipmentSet.DeleteEquipmentSet(setID)`](#c_equipmentsetdeleteequipmentsetsetid) - - [`C_EquipmentSet.IgnoreSlotForSave(slot)` / `UnignoreSlotForSave` / `IsSlotIgnoredForSave` / `ClearIgnoredSlotsForSave`](#c_equipmentsetignoreslotforsaveslot--unignoreslotforsave--isslotignoredforsave--clearignoredslotsforsave) - - [`C_EquipmentSet.EquipmentSetContainsLockedItems(setID)`](#c_equipmentsetequipmentsetcontainslockeditemssetid) - - [`C_EquipmentSet.UseEquipmentSet(setID)`](#c_equipmentsetuseequipmentsetsetid) - - [`EQUIPMENT_SETS_CHANGED` event](#equipment_sets_changed-event) - - [`EQUIPMENT_SWAP_PENDING` event](#equipment_swap_pending-event) - - [`EQUIPMENT_SWAP_FINISHED` event](#equipment_swap_finished-event) -- [Class](#class) - - [`FillLocalizedClassList(table [, isFemale])`](#filllocalizedclasslisttable-isfemale) -- [Unit](#unit) - - [`UnitGUID(unit)`](#unitguidunit) - - [`GetUnitSpeed(unit)`](#getunitspeedunit) - - [`UnitClassBase(unit)`](#unitclassbaseunit) - - [`UnitIsAFK(unit)`](#unitisafkunit) - - [`UnitIsDND(unit)`](#unitisdndunit) - - [`UnitIsFeignDeath(unit)`](#unitisfeigndeathunit) - - [`UnitIsInMyGuild(unitOrName)`](#unitisinmyguildunitorname) - - [`UnitIsPossessed(unit)`](#unitispossessedunit) - - [`UnitStandState(unit)`](#unitstandstateunit) -- [UnitAuras](#unitauras) - - [`C_UnitAuras.GetAuraDataByIndex(unit, index [, filter])`](#c_unitaurasgetauradatabyindexunit-index--filter) - - [`C_UnitAuras.GetBuffDataByIndex(unit, index)` / `GetDebuffDataByIndex(unit, index)`](#c_unitaurasgetbuffdatabyindexunit-index--getdebuffdatabyindexunit-index) - - [`C_UnitAuras.GetUnitAuraBySpellID(unit, spellID [, filter])`](#c_unitaurasgetunitaurabyspellidunit-spellid--filter) - - [`C_UnitAuras.GetPlayerAuraBySpellID(spellID)`](#c_unitaurasgetplayeraurabyspellidspellid) - - [`C_UnitAuras.GetUnitAuras(unit [, filter])`](#c_unitaurasgetunitaurasunit--filter) - - [`C_UnitAuras.GetAuraDispelTypeColor(dispelName)`](#c_unitaurasgetauradispeltypecolordispelname) + - [NameCache](#namecache) - [`GetPlayerInfoByGUID(guid)`](#getplayerinfobyguidguid) - [`C_PlayerCache.GetPlayerInfoByName(name)`](#c_playercachegetplayerinfobynamename) @@ -160,38 +171,49 @@ build instructions. - [`C_PlayerCache.IsEnabled()`](#c_playercacheisenabled) - [`C_PlayerCache.SetScanEnabled(enabled)`](#c_playercachesetscanenabledenabled) - [`C_PlayerCache.IsScanEnabled()`](#c_playercacheisscanenabled) + +- [Quest](#quest) + - [`C_QuestLog.GetQuestIDFromLogIndex(index)`](#c_questloggetquestidfromlogindexindex) + - [`C_QuestLog.RequestLoadQuestByID(questID)`](#c_questlogrequestloadquestbyidquestid) + - [`C_QuestLog.GetTitleForQuestID(questID)`](#c_questloggettitleforquestidquestid) + +- [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) + - [`IsUsableSpell(spell)` / `IsUsableSpell(slot, bookType)`](#isusablespellspell--isusablespellslot-booktype) + - [`C_Spell.IsSpellUsable(spellID)`](#c_spellisspellusablespellid) + - [`IsHarmfulSpell(spell)` / `IsHelpfulSpell(spell)`](#isharmfulspellspell--ishelpfulspellspell) + - [`C_Spell.IsSpellHarmful(spellID)` / `C_Spell.IsSpellHelpful(spellID)`](#c_spellisspellharmfulspellid--c_spellisspellhelpfulspellid) + - [`C_SpellBook.GetSpellLevelLearned(spellID)`](#c_spellbookgetspelllevellearnedspellid) + - [`C_SpellBook.GetCurrentLevelSpells([level])`](#c_spellbookgetcurrentlevelspellslevel) + - [`C_SpellBook.GetSpellSkillLine(spellID)`](#c_spellbookgetspellskilllinespellid) + - [`GetSpellSchool(spellID)`](#getspellschoolspellid) + - [`CastSpellNoToggle(name | spellID)`](#castspellnotogglename--spellid) + - [State](#state) - [`IsMounted()`](#ismounted) - [`IsStealthed()`](#isstealthed) - [`IsFalling()`](#isfalling) - [`IsSwimming()`](#isswimming) - [`IsAssistingRitual()`](#isassistingritual) -- [CharacterList](#characterlist) - - [`GetSavedCharacterOrder(realm)` / `SetSavedCharacterOrder(realm, order)` — GlueXML only](#getsavedcharacterorderrealm--setsavedcharacterorderrealm-order--gluexml-only) -- [Chat](#chat) - - [`GetCurrentChatGUID()`](#getcurrentchatguid) -- [AddOns](#addons) - - [`C_AddOns.GetAddOnName(indexOrName)`](#c_addonsgetaddonnameindexorname) - - [`C_AddOns.GetAddOnTitle(indexOrName)`](#c_addonsgetaddontitleindexorname) - - [`C_AddOns.GetAddOnNotes(indexOrName)`](#c_addonsgetaddonnotesindexorname) - - [`C_AddOns.IsAddOnLoadable(indexOrName)`](#c_addonsisaddonloadableindexorname) - - [`C_AddOns.GetAddOnSecurity(indexOrName)`](#c_addonsgetaddonsecurityindexorname) - - [`C_AddOns.DoesAddOnExist(indexOrName)`](#c_addonsdoesaddonexistindexorname) -- [Combat](#combat) - - [`InCombatLockdown()`](#incombatlockdown) -- [CVar](#cvar) - - [`C_CVar.GetCVarBool(cvar)`](#c_cvargetcvarboolcvar) + - [Table](#table) - [`table.wipe(t)`](#tablewipet) -- [Input](#input) - - [`IsLeftShiftKeyDown()` / `IsRightShiftKeyDown()`](#isleftshiftkeydown--isrightshiftkeydown) - - [`IsLeftControlKeyDown()` / `IsRightControlKeyDown()`](#isleftcontrolkeydown--isrightcontrolkeydown) - - [`IsLeftAltKeyDown()` / `IsRightAltKeyDown()`](#isleftaltkeydown--isrightaltkeydown) - - [`IsModifierKeyDown()`](#ismodifierkeydown) - - [`MODIFIER_STATE_CHANGED` event](#modifier_state_changed-event) + - [Talent](#talent) - [`GetTalentSpellID(tabIndex, talentIndex, [rank])`](#gettalentspellidtabindex-talentindex-rank) - [`GetTalentIDByIndex(tabIndex, talentIndex)`](#gettalentidbyindextabindex-talentindex) + - [Time](#time) - [`GetServerTime()`](#getservertime) - [`C_Timer.After(seconds, callback)`](#c_timeraftersseconds-callback) @@ -204,1257 +226,1043 @@ build instructions. - [`C_DateAndTime.CompareCalendarTime(lhs, rhs)`](#c_dateandtimecomparecalendartimelhs-rhs) - [`C_DateAndTime.GetServerTimeLocal()`](#c_dateandtimegetservertimelocal) - [`C_DateAndTime.GetSecondsUntilDailyReset()`](#c_dateandtimegetsecondsuntildailyreset) + - [UIColor](#uicolor) - [`C_UIColor.GetColors()`](#c_uicolorgetcolors) -- [Events](#events) - - [`C_EventUtils.IsEventValid(eventName)`](#c_eventutilsiseventvalideventname) - - [`BAG_UPDATE_DELAYED` event](#bag_update_delayed-event) - - [Player input-state events (`PLAYER_STARTED_MOVING` / `LOOKING` / `TURNING` + `STOPPED_*`)](#player-input-state-events) - - [`GLOBAL_MOUSE_DOWN` / `GLOBAL_MOUSE_UP` events](#global_mouse_down--global_mouse_up-events) -- [Globals](#globals) - - [`CLASSIC_API_VERSION`](#classic_api_version) - - [`LE_EXPANSION_*`](#le_expansion_) - - [`LE_ITEM_QUALITY_*`](#le_item_quality_) - - [`LE_UNIT_STAT_*`](#le_unit_stat_) - - [`Enum.AddOnSecurityStatus`](#enumaddonsecuritystatus) -## Spell +- [Unit](#unit) + - [`UnitGUID(unit)`](#unitguidunit) + - [`GetUnitSpeed(unit)`](#getunitspeedunit) + - [`UnitClassBase(unit)`](#unitclassbaseunit) + - [`UnitIsAFK(unit)`](#unitisafkunit) + - [`UnitIsDND(unit)`](#unitisdndunit) + - [`UnitIsFeignDeath(unit)`](#unitisfeigndeathunit) + - [`UnitIsInMyGuild(unitOrName)`](#unitisinmyguildunitorname) + - [`UnitIsPossessed(unit)`](#unitispossessedunit) + - [`UnitStandState(unit)`](#unitstandstateunit) -### `GetSpellInfo(spellID)` / `GetSpellInfo(slot, bookType)` +- [UnitAuras](#unitauras) + - [`C_UnitAuras.GetAuraDataByIndex(unit, index [, filter])`](#c_unitaurasgetauradatabyindexunit-index--filter) + - [`C_UnitAuras.GetBuffDataByIndex(unit, index)` / `GetDebuffDataByIndex(unit, index)`](#c_unitaurasgetbuffdatabyindexunit-index--getdebuffdatabyindexunit-index) + - [`C_UnitAuras.GetUnitAuraBySpellID(unit, spellID [, filter])`](#c_unitaurasgetunitaurabyspellidunit-spellid--filter) + - [`C_UnitAuras.GetPlayerAuraBySpellID(spellID)`](#c_unitaurasgetplayeraurabyspellidspellid) + - [`C_UnitAuras.GetUnitAuras(unit [, filter])`](#c_unitaurasgetunitaurasunit--filter) + - [`C_UnitAuras.GetAuraDispelTypeColor(dispelName)`](#c_unitaurasgetauradispeltypecolordispelname) -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. +## Action -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. +### `GetActionInfo(slot)` -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. +Returns the action descriptor for a 1-based action-bar slot, in the +shape `actionType, id, subType`. Returns `nil` for empty 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 +local actionType, id, subType = GetActionInfo(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. +| Slot contents | Returns | +|---------------------------|------------------------------------| +| empty | `nil` | +| spell | `"spell", spellID, "spell"` | +| macro | `"macro", macroSlot` | +| item (by-itemID) | `"item", itemID` | +| item (by bag-instance) | `"item", nil` | -### `C_Spell.GetSpellInfo(spellID)` +The 120-slot action table at `0x00BC6980` packs each entry as a +`uint32` where the top 4 bits are the type tag: -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. +- **`0x0` — spell action.** Entry is the spellID. The third return is + always `"spell"` for entries on this table; the engine helper + hardcodes pet flag to 0 here. Pet-bar actions live in a separate + table — use `PetHasActionBar` + the pet-action helpers for pet + slots. +- **`0x4` — macro or bag-item.** Ambiguous tag, disambiguated by + walking the 36-entry macro-slot map at `0x00BDCC60` and checking + whether `entry & 0xBFFFFFFF` matches any of those macro IDs. On a + hit, the slot is a macro and the matching index becomes the + 1-based `macroSlot` return. On a miss, the slot is a bag-item + reference; we surface the type as `"item"` but return `nil` for + the `id` — extracting the itemID from the bag-action hash struct + needs more reversing than we've done. +- **`0x8` — item by itemID.** `entry & 0x7FFFFFFF` is the itemID. -Table fields: +This is the same discrimination [SuperWoWhook][superwowhook] uses in +its replacement of `GetActionText` (which returns `name, type, id`). +Without SuperWoWhook the engine's stock `GetActionText` only handles +items in bags; ClassicAPI's `GetActionInfo` provides the modern-WoW +shape independently of any other DLL patches. -| 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 | +Equivalent to the function of the same name in retail. Subtype is +always `"spell"` for spell entries (no pet differentiation on this +table) and the bag-item itemID path is currently incomplete — see +the comment in [src/action/Info.cpp](../src/action/Info.cpp). + +[superwowhook]: https://github.com/balakethelock/SuperWoW + +## AddOns + +Six modern `C_AddOns.*` getters that splat the legacy +`GetAddOnInfo(arg)` 7-tuple `(name, title, notes, enabled, +loadable, reason, security)` into single-field accessors. Most +bypass `GetAddOnInfo` entirely and call the engine's per-field +helpers directly. + +All accept either a 1-based index (`1..GetNumAddOns()`) or an +addon directory name string. + +### `C_AddOns.GetAddOnName(indexOrName)` + +Returns the addon's directory name as the engine sees it (the +folder name on disk). For numeric input, returns the engine's +canonical casing; for string input, echoes the input verbatim +once existence is confirmed. Returns `nil` for missing addons. ```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. +C_AddOns.GetAddOnName(1) -- "Atlas-TW" +C_AddOns.GetAddOnName("DebugTools") -- "DebugTools" +C_AddOns.GetAddOnName("garbage") -- nil ``` -> **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. +### `C_AddOns.GetAddOnTitle(indexOrName)` -> **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. +Returns the `## Title:` from the addon's `.toc` file, with WoW +color-code escapes applied. `nil` for missing addons or addons +without a title field. ```lua -local name = C_Spell.GetSpellName(133) -- "Fireball" +C_AddOns.GetAddOnTitle("DebugTools") -- "UI Debug Tools" ``` -Equivalent to the function of the same name introduced in 10.0. +### `C_AddOns.GetAddOnNotes(indexOrName)` -### `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(...)`. +Returns the `## Notes:` from the `.toc`. `nil` for missing +addons or addons without notes. ```lua -local path = C_Spell.GetSpellTexture(133) --- path = "Interface\\Icons\\Spell_Fire_FlameBolt" +C_AddOns.GetAddOnNotes("DebugTools") +-- "Tools for developing addons (backport of Blizzard_DebugTools 3.3.5 to 1.12.1 / Lua 5.0)" ``` -Equivalent to the function of the same name introduced in 10.0. +### `C_AddOns.IsAddOnLoadable(indexOrName)` -### `FindSpellBookSlotByID(spellID)` +Returns `loadable, reason` — a real boolean and a status string +(or `nil`). -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. +`reason` comes from a small status table the engine consults when +populating `GetAddOnInfo`'s 6th return: `"DISABLED"`, `"BANNED"`, +`"CORRUPT"`, `"INSECURE"`, `"NOT_DEMAND_LOADED"`, +`"INTERFACE_VERSION"`, `"MISSING"`. `nil` when the addon is +loadable. The full modern signature accepts optional `character` +and `demandLoaded` arguments — those are ignored here since vanilla +1.12 has no per-character addon enable state. ```lua -local slot, book = FindSpellBookSlotByID(133) -if slot then - GameTooltip:SetSpell(slot, book) -- shows full caster-scaled tooltip +C_AddOns.IsAddOnLoadable("DebugTools") -- true, nil +C_AddOns.IsAddOnLoadable("HardcoreTooltips") -- false, "DISABLED" +C_AddOns.IsAddOnLoadable("garbage") -- false, nil +``` + +### `C_AddOns.GetAddOnSecurity(indexOrName)` + +Returns an `Enum.AddOnSecurityStatus` integer (not a string — modern +shape): + +| Value | `Enum.AddOnSecurityStatus.*` | When | +|------:|------------------------------|------| +| `0` | `Secure` | Blizzard-signed addons (`Blizzard_*`). | +| `1` | `Insecure` | Every user addon loaded from `Interface/AddOns/`. The default for any registered addon not in the secure or banned override sets. | +| `2` | `Banned` | Entries the engine has explicitly disqualified — set by server addon-banlist responses, rare in practice. | +| `3` | `NotAvailable` | No addon by that name / index exists. | + +```lua +C_AddOns.GetAddOnSecurity("Blizzard_TalentUI") -- 0 (Secure) +C_AddOns.GetAddOnSecurity("DebugTools") -- 1 (Insecure) +C_AddOns.GetAddOnSecurity("Nonexistent") -- 3 (NotAvailable) + +if status == Enum.AddOnSecurityStatus.Secure then ... +``` + +### `C_AddOns.DoesAddOnExist(indexOrName)` + +Returns `true` iff the engine's addon registry has a matching +entry, `false` otherwise. Cheap existence probe used by addons +doing soft-dependency checks. + +The implementation goes through the registry directly rather than +dispatching to `GetAddOnInfo` — the engine echoes its input name +back as ret1 unconditionally (before the lookup), so a +`GetAddOnInfo("garbage") ~= nil` heuristic returns true for any +string. This wrapper avoids that. + +```lua +C_AddOns.DoesAddOnExist("DebugTools") -- true +C_AddOns.DoesAddOnExist("garbage") -- false +``` + +## CharacterList + +### `GetSavedCharacterOrder(realm)` / `SetSavedCharacterOrder(realm, order)` — GlueXML only + +> **GlueXML scope.** These globals are registered on the **glue** +> Lua state (the engine that runs login / realm-select / +> character-select), not the in-world FrameScript engine. In-world +> addons can't see them — `/script GetSavedCharacterOrder("X")` +> from inside the world will error on a nil global. They exist +> specifically to support GlueXML patches that reorder the +> character-select list and need to persist that order across +> sessions; 1.12 glue ships no general-purpose persistence API +> (just `GetSavedAccountName`/`SetSavedAccountName`, which is +> saturated by the autologin system). + +- `GetSavedCharacterOrder(realm) -> string` — returns the saved + order string for `realm`, or `""` if none. Never returns `nil`. +- `SetSavedCharacterOrder(realm, order)` — writes the order + string. Calling with `order == ""` clears the realm's entry. + +Both args are opaque UTF-8 strings. The caller picks the encoding +for `order`; the DLL stores it verbatim. The expected pattern +(matching the anniversary-client reorder UI) is a pipe-delimited +list of character names: `"Thrall|Jaina|Sylvanas"`. + +Persistence: `WTF\Account\\ClassicAPI.txt`, one +`CharacterOrder.=` line per realm. Account scope is +implicit via the file path (so switching autologin accounts on the +glue screen automatically isolates per-account orderings); realm +scope is explicit via the line key. The same file is shared with +the persistent name cache settings — see [`Settings::Account` +in the source](../src/settings/Account.h) — no file-level +coordination needed at the call site. + +```lua +-- GlueXML, e.g. CharacterSelect.lua: persist the user's drag-reordered list +local realm = GetServerName() or "" +local names = {} +for i = 1, GetNumCharacters() do + table.insert(names, (GetCharacterInfo(translationTable[i]))) +end +SetSavedCharacterOrder(realm, table.concat(names, "|")) + +-- On the next CHARACTER_LIST_UPDATE: read the saved order back +local saved = GetSavedCharacterOrder(realm) +if saved ~= "" then + for name in string.gfind(saved, "([^|]+)") do + -- reconcile against the current GetCharacterInfo names + end end ``` -Equivalent to the legacy function of the same name introduced in 3.0 -(later renamed to `FindSpellBookSlotBySpellID` in 5.x). +> **How it works.** ClassicAPI hooks `FUN_0046ABB0` — the engine's +> master glue-init function, which runs once per glue boot (initial +> launch and every world→glue return on logout). After the engine +> registers its own 109 glue functions, our hook adds these two on +> the same Lua state via the engine's own +> `FrameScript_RegisterFunction`. The glue Lua state is torn down +> and recreated on every world transition; we re-register each +> cycle automatically. -### `GetSpellLink(spellID)` / `GetSpellLink(slot, bookType)` +## Chat -Returns the chat-style spell hyperlink and the spellID: +### `GetCurrentChatGUID()` -``` -link, spellID = GetSpellLink(spellID) - = GetSpellLink(slot, bookType) -``` +Returns the sender's GUID for whichever `CHAT_MSG_*` event is +currently being dispatched, or `nil` if called outside a chat +event or for a synthetic chat with no real sender (e.g. +`CHAT_MSG_SYSTEM`). -Format 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. +Format matches `UnitGUID`: `"0xHHHHHHHHLLLLLLLL"` (16 hex digits, +hi dword first). ```lua -local link = GetSpellLink(133) -DEFAULT_CHAT_FRAME:AddMessage("Cast " .. link .. "!") +local f = CreateFrame("Frame") +f:RegisterEvent("CHAT_MSG_CHANNEL") +f:RegisterEvent("CHAT_MSG_SAY") +f:RegisterEvent("CHAT_MSG_WHISPER") +f:SetScript("OnEvent", function() + local guid = GetCurrentChatGUID() + if guid then + local _, class, _, race = GetPlayerInfoByGUID(guid) + DEFAULT_CHAT_FRAME:AddMessage(string.format( + "%s: %s [%s %s]", arg2, arg1, class or "?", race or "?")) + end +end) +``` --- 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 +Vanilla 1.12's `CHAT_MSG_*` events don't include the sender GUID +in their payload — that was added in 3.0+ as `arg12`. Addons that +need to identify chatters reliably (rather than by sender name, +which is locale-fragile and ambiguous across realms) currently +strcmp against an addon-maintained name cache. This function lets +them skip that work. + +**Implementation**: hooks the engine's chat dispatcher at +`FUN_CHAT_DISPATCH` (`0x0049A870`), which receives the sender +GUID as args 11/12 of a 12-arg `__fastcall`. The hook stashes the +GUID into a static global before forwarding to the original +function; the engine then fires the appropriate `CHAT_MSG_*` +event synchronously inside that window, so `GetCurrentChatGUID()` +called from the addon's OnEvent sees the right GUID. The global +is restored to its prior value (not cleared) on hook return, so +nested chat dispatch (e.g. an addon calling `SendChatMessage` +from its handler) doesn't lose the outer context's GUID. + +The function returns `nil` rather than `"0x0000000000000000"` +for synthetic chat (system messages, login banners, etc.) where +the GUID args are zero — matches the idiomatic +`if GetCurrentChatGUID() then` check. + +## Class + +### `FillLocalizedClassList(table [, isFemale])` + +Fills the passed-in table with `[classToken] = localizedClassName` +pairs for every class in `ChrClasses.dbc`, and returns the same +table for chaining. + +The table is mutated in place. Existing keys are overwritten; +unrelated keys are preserved. + +```lua +local classes = FillLocalizedClassList({}) +-- classes.WARRIOR = "Warrior" +-- classes.MAGE = "Mage" +-- classes.PRIEST = "Priest" +-- ... +``` + +Modern API supports an optional `isFemale` boolean to fetch female- +form names. Vanilla 1.12 has no separate female-name array in +`ChrClasses.dbc` — `Name[9]` (one localized string per locale) +sits exactly between offsets `+0x14` and `+0x38`, with the class +token immediately after, leaving no room. The arg is accepted for +signature parity but ignored; the same names are returned either way. +Most locales (English included) wouldn't differentiate the two +anyway, so callers won't typically notice. + +Sparse class IDs (vanilla skips classID 6 — Death Knight didn't +exist yet — and a few others) have NULL records and are silently +skipped. + +Equivalent to the function of the same name introduced in 3.0. + +## 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. + +## 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.GetContainerItemRepairCost(containerIndex, slotIndex)` + +Bag/bank variant of +[`GetInventoryItemRepairCost`](#getinventoryitemrepaircostinvslot). +Same `copperCost` single-int return and the same "0 for nothing to +repair" semantics. + +``` +copperCost = C_Container.GetContainerItemRepairCost(containerIndex, slotIndex) +``` + +`containerIndex` accepts the same values as +[`C_Container.GetContainerItemDurability`](#c_containergetcontaineritemdurabilitycontainerindex-slotindex) +(`0` = backpack, `1..4` = equipped bags, `-1`/`5..11` = bank, etc.). + +```lua +for slot = 1, GetContainerNumSlots(0) do + local cost = C_Container.GetContainerItemRepairCost(0, slot) + if cost > 0 then + -- broken/damaged item sitting in the backpack + end +end +``` + +Useful for "repair only items above N copper" smart-repair logic +without scanning tooltips. ClassicAPI addition; modern WoW has no +direct equivalent. + +### `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 ``` -### `C_Spell.GetSpellLink(spellID)` +> **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. -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. +> **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. -```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). +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. -### `IsUsableSpell(spell)` / `IsUsableSpell(slot, bookType)` +### `C_Container.PlayerHasHearthstone()` -Returns `(usable, noMana)` for a spell, matching the modern -3.0+ signature. Returns `(1, nil)` when the spell is castable, -`(nil, 1)` when only mana is preventing it, `(nil, nil)` for any -other reason (unknown spell, dead, etc.). Matches the `1`/`nil` -return convention of the existing `Script_IsUsableAction`. - -Two arg shapes accepted: - -- **`IsUsableSpell(spellID)`** — direct spellID lookup. -- **`IsUsableSpell(slot, bookType)`** — `bookType` is `"spell"` - (player) or `"pet"`. Resolves to a spellID via the same engine - spellbook arrays `GetSpellInfo`/`GetSpellLink` walk. - -```lua -IsUsableSpell(133) -- Fireball: 1, nil if you have mana, nil, 1 if not -IsUsableSpell(1, "spell") -- player spellbook slot 1 -``` - -> **What this function checks:** -> -> 1. Player knows the spell (engine's spell-knowledge bitmap — -> covers trained class abilities, talent passives, racials, -> profession recipes). -> 2. Player is alive (HEALTH > 0). -> 3. Spell is not on cooldown (engine's per-spell cooldown helper). -> 4. Player has enough of the spell's power type for the base cost -> (mana / rage / focus / energy / happiness) — *only* this -> failure sets `noMana=true`. -> 5. Player has all required reagents in bags (Spell.dbc -> Reagent[8] / ReagentCount[8]). -> -> **What this function doesn't check** (different concerns or -> post-vanilla concepts): silence, GCD, stance/form, range, target -> type, line-of-sight, casting state. -> -> Verified empirically on Turtle WoW for the mana branch: Renew rank -> 3 (cost 105) is reported usable at 144 mana and unusable at 39 -> mana, transitioning at exactly the cost boundary. Cooldown and -> reagent checks ship in the same implementation but haven't been -> exercised in-game; if you find an inconsistency, the reagent -> offsets (+0x110 / +0x130) and cooldown helper (`0x006E2EA0`) are -> the components to verify. - -Equivalent to the function of the same name introduced in 3.0. - -### `C_Spell.IsSpellUsable(spellID)` - -Modern table-namespace form. Same logic as -[`IsUsableSpell(spellID)`](#isusablespellspell--isusablespellslot-booktype) -but returns proper booleans (`isUsable`, `insufficientPower`) per -the `C_Spell.*` convention rather than `1`/`nil` pairs. - -```lua -local usable, noMana = C_Spell.IsSpellUsable(133) --- usable=true, noMana=false → cast it --- usable=false, noMana=true → drink up --- usable=false, noMana=false → unknown spell, dead, or other block -``` - -Equivalent to the function of the same name introduced in 10.x. - -### `C_Item.GetWeaponEnchantInfo()` - -Returns the modern 12-tuple matching WotLK+'s extended -`GetWeaponEnchantInfo` signature, including the **temp-enchant IDs** -that vanilla 1.12's 8-return global omits. +Returns the itemID of the hearthstone if one is in the player's bags, +or `nil` otherwise. ``` -hasMain, mainExpire, mainCharges, mainEnchantID, -hasOff, offExpire, offCharges, offEnchantID, -hasRanged, rangedExpire, rangedCharges, rangedEnchantID - = C_Item.GetWeaponEnchantInfo() +itemID = C_Container.PlayerHasHearthstone() ``` ```lua --- Apply Brilliant Mana Oil to mainhand, then: -local has, expireMs, charges, enchantID = C_Item.GetWeaponEnchantInfo() --- has = true, expireMs ≈ 1800000, charges = 5, enchantID = -``` - -Reads the **temporary** enchant slot (`ITEM_FIELD_ENCHANTMENT` -slot 1 at descriptor `+0x4C`) — the same slot oils, sharpening -stones, and poisons populate and the engine drains as they expire. -This is what modern's `GetWeaponEnchantInfo` measures. - -The permanent enchant (Crusader, Mongoose, etc., in slot 0 at -`+0x40`) is **not** reported here — that's a separate field and -modern's `GetWeaponEnchantInfo` doesn't expose it either. Get the -permanent enchant ID by parsing `GetInventoryItemLink("player", -slot)` (the link includes it as the 2nd numeric field). - -Vanilla 1.12's global `GetWeaponEnchantInfo` is unchanged — old -addons reading positions 4..8 by index still work. - -Equivalent to the extension of `GetWeaponEnchantInfo` introduced -in 3.x. - -### `IsHarmfulSpell(spell)` / `IsHelpfulSpell(spell)` - -Classify a spell as offensive (`IsHarmfulSpell`) or non-offensive -(`IsHelpfulSpell`) without parsing its tooltip. Accept either form -the spellbook-aware globals use: - -```lua -IsHarmfulSpell(spellID) -- by ID -IsHarmfulSpell(slot, "spell") -- player spellbook slot -IsHarmfulSpell(slot, "pet") -- pet spellbook slot --- same calling shapes for IsHelpfulSpell -``` - -Examples: - -```lua -IsHarmfulSpell(133) -- true (Fireball) -IsHarmfulSpell(118) -- true (Polymorph) -IsHelpfulSpell(2061) -- true (Flash Heal) -IsHelpfulSpell(1243) -- true (Power Word: Fortitude) -IsHarmfulSpell(2061) -- false -``` - -Reads `Spell.dbc.AttributesEx` (record `+0x1C`) bit `0x80` — the -same `SPELL_ATTR_EX_NEGATIVE` bit CMaNGOS uses to mark spells as -debuffs server-side. `IsHarmfulSpell` is true iff that bit is set; -`IsHelpfulSpell` is true iff the spell exists and the bit is NOT -set. Both return `false` for invalid spellIDs. - -> Vanilla 1.12 doesn't have a dedicated "positive" flag, so the -> helpful side is the rough complement of harmful. For utility -> spells with no clear orientation (Aspect of the Cheetah, -> Stealth, ground-targeted AOEs), modern WoW sometimes returns -> false for both; we return `true` for helpful as a safer default -> for addons gating on "is this castable on me?" logic. Compute -> precise modern semantics by also inspecting effect implicit -> targets if you need them. - -Equivalent to the functions of the same name introduced in 3.x -(when WoW first exposed them as globals). - -### `C_Spell.IsSpellHarmful(spellID)` / `C_Spell.IsSpellHelpful(spellID)` - -Same classification logic as the globals above, but exposed in the -modern `C_Spell` namespace. Both take a numeric `spellID` only — -no `(slot, bookType)` form. - -```lua -C_Spell.IsSpellHarmful(133) -- true (Fireball) -C_Spell.IsSpellHelpful(2061) -- true (Flash Heal) -``` - -Equivalent to `C_Spell.IsSpellHarmful` / `C_Spell.IsSpellHelpful` -introduced in 11.x. - -### `C_SpellBook.GetSpellLevelLearned(spellID)` - -Returns the level at which a spell becomes available — the -`BaseLevel` field in `Spell.dbc` (record `+0x70`). Direct read off -the cached record; no class/race filtering. - -```lua -C_SpellBook.GetSpellLevelLearned(133) -- Fireball rank 1 → 4 -C_SpellBook.GetSpellLevelLearned(25306) -- Fireball rank 12 → 60 -C_SpellBook.GetSpellLevelLearned(2061) -- Flash Heal rank 1 → 20 -``` - -Returns `0` for invalid spellIDs, spells with no level requirement -(most non-class utility spells), or records the engine hasn't -cached. Matches modern semantics — unknown / utility spells -return 0 rather than nil. - -### `C_SpellBook.GetCurrentLevelSpells([level])` - -Returns a 1-based table of spellIDs the player's class/race can -learn at the given level. Without arguments, defaults to the -player's current level. - -```lua -C_SpellBook.GetCurrentLevelSpells() -- spells trainable at your level -C_SpellBook.GetCurrentLevelSpells(20) -- preview what's available at 20 -C_SpellBook.GetCurrentLevelSpells(60) -- preview at 60 -``` - -Walks `SkillLineAbility.dbc` filtering by the player's class bit -(`1 << (classID - 1)`) and race bit, respecting both the include -masks (entries with mask = 0 are "all classes"/"all races", which -also pass) and the exclude masks. For each surviving entry, looks -up the spell's `BaseLevel` and includes it if it matches the -queried level. - -> **Vanilla is trainer-driven.** Modern `GetCurrentLevelSpells` -> (added in 5.x when trainers were removed) returns *auto-learned* -> spells. Vanilla 1.12 requires visiting a trainer to actually -> learn most class spells. We return the closest available analog: -> **what's *trainable* at this level**. Useful for "what's new -> this level" UI panels and level-preview tooling ported from MoP+. - -Class/race come from the local player — there's no -`(class, race, level)` form because vanilla doesn't expose a -clean class-string→classID lookup. Returns an empty table at -character select / pre-login (no CGPlayer yet) and for levels -where no class/race spells match. - -### `C_SpellBook.GetSpellSkillLine(spellID)` - -Returns `(name, skillID)` — the SkillLine.dbc row that the given spell -belongs to. The name is the user-facing skill/tab string in the engine's -current locale: spellbook tab names for class spells (`"Protection"`, -`"Fire"`, `"Holy"`), profession headers (`"Tailoring"`, `"Engineering"`), -weapon-skill rows (`"Swords"`, `"Bows"`), etc. - -```lua -C_SpellBook.GetSpellSkillLine(1671) -- "Protection", 26 (Shield Bash) -C_SpellBook.GetSpellSkillLine(133) -- "Fire", 8 (Fireball) -C_SpellBook.GetSpellSkillLine(2050) -- "Holy", 56 (Lesser Heal) -C_SpellBook.GetSpellSkillLine(2480) -- "Bows", 45 (Shoot Bow) -C_SpellBook.GetSpellSkillLine(3273) -- "First Aid", 129 (Anesthetic) -``` - -Walks `SkillLineAbility.dbc` for any row whose `spellID` matches, then -reads the localized `Name[locale]` field at offset `+0x0C` of the -referenced `SkillLine.dbc` record. For spells with multiple SLA rows -(race-locked variants, Turtle WoW's faction-specific entries) the -lookup prefers a row whose class/race masks match the local player — -so the result reflects "what tab is this spell in *for me*" when one -exists. Falls back to the first matching row otherwise, so the -function still answers for spells the local player can't actually use -(inspecting other classes, parsing combat-log entries from unfamiliar -specs). - -Returns `(nil, nil)` for: -- non-numeric or non-positive input -- spellIDs with no `SkillLineAbility.dbc` row (most temporary auras, - proc-only spells, item-on-use effects, GM-debug spells) -- rows whose `skillID` doesn't resolve in `SkillLine.dbc` - -Vanilla's `GetSpellTabInfo(tabIndex)` enumerates spellbook tabs by -1-based index — it can't answer "what tab is *this spellID* in". -Addons that need a spellID→tab mapping have historically had to walk -every tab's slot range and string-match against `GetSpellName`. This -function reads it directly off the DBC for any spellID, including -spells the player hasn't learned. - -### `GetSpellSchool(spellID)` - -Returns `(schoolID, schoolName)` for any spell — known to the player -or not. `schoolID` is 1-based; `schoolName` is the locale-independent -English name. - -| schoolID | schoolName | -|---------:|------------| -| 1 | `"Physical"` | -| 2 | `"Holy"` | -| 3 | `"Fire"` | -| 4 | `"Nature"` | -| 5 | `"Frost"` | -| 6 | `"Shadow"` | -| 7 | `"Arcane"` | - -Reads directly from `Spell.dbc` record `+0x04`. Vanilla 1.12 stores -School as a single 0-based integer (no multi-school `SchoolMask` -combinations — that's a TBC+ thing), so a spell belongs to exactly -one school. - -Returns `nil` for invalid spellIDs (out of range or unpopulated -`Spell.dbc` slot). - -```lua -local id, name = GetSpellSchool(133) -- 3, "Fire" (Fireball) -local id, name = GetSpellSchool(116) -- 5, "Frost" (Frostbolt) -local id, name = GetSpellSchool(635) -- 2, "Holy" (Holy Light) -``` - -Useful for combat-log breakdown addons, dispel-eligibility checks, -resistance-aware aura libraries, and damage-meter school tagging. -Previously addons either maintained hardcoded `spellID → school` -tables or scanned tooltips for the first-line color tag. - -### `CastSpellNoToggle(name | spellID)` - -Spam-safe variant of `CastSpellByName` that won't toggle off an -already-active spell. Covers both kinds of vanilla-toggle abilities: - -- **Auto-repeat** — Shoot, Auto-Shot, Wand. Tracked via the engine's - active-auto-repeat global. -- **Self-aura toggles** — shapeshift (Cat/Bear/Travel/Moonkin/ - Shadowform), stance (Battle/Defensive/Berserker), aspect (Hunter), - seal (Paladin), blessing-on-self, etc. Tracked via the unit - descriptor's aura array. - -If either toggle is already on for the requested spell, the call is -a no-op — exactly what `/cast !SpellName` does in 2.3.2+ clients, -but expressed as a vanilla Lua call. - -| Engine state | Behavior | Return | -|-------------------------------|---------------------|---------| -| Nothing toggled | Starts the cast | `true` if the spell is now active, else `false` | -| This spell already auto-repeating | No-op | `true` | -| This spell's aura already on (form / stance / aspect) | No-op | `true` | -| A *different* auto-repeat is active | No-op | `false` (don't disrupt the other auto-repeat) | - -Replaces both the action-bar scan-and-skip pattern and the -form-already-active check: - -```lua --- Before (auto-repeat case) -for i = 1, 120 do - if IsAutoRepeatAction(i) then return end -end -CastSpellByName("Shoot") - --- Before (shapeshift case) -if not (UnitBuff("player", "Cat Form") or GetShapeshiftFormID() == CAT_FORM) then - CastSpellByName("Cat Form") -end - --- After (both cases) -CastSpellNoToggle("Shoot") -CastSpellNoToggle("Cat Form") -``` - -Accepts either a name string or a spellID number: - -```lua -CastSpellNoToggle("Shoot") -- by name (matches what CastSpellByName accepts) -CastSpellNoToggle(75) -- by spellID (Auto Shot rank 1) -CastSpellNoToggle("Aspect of the Hawk") -CastSpellNoToggle("Battle Stance") -``` - -String input matches case-insensitively and tolerates a trailing -`(Rank N)` suffix the same way `CastSpellByName` itself does — -`"Shoot"` and `"Shoot(Rank 1)"` both compare equal to a Shoot that's -already auto-repeating. - -Reads `[VAR_ACTIVE_AUTO_REPEAT_SPELL]` (`0x00CEAC30`) for the auto- -repeat check, and the engine's `FUN_SPELL_IS_TOGGLE_AURA_ACTIVE` -(`0x004B36F0`) for the aura-active check. Delegates to -`Script_CastSpellByName` (`0x004B4AB0`) for the actual cast — same -resolution semantics (rank picking, target rules, etc.) as the -engine's own global. - -Using this from inside a macro action slot? See -[`CastSpellNoToggle` as a macro cast line](#castspellnotoggle-as-a-macro-cast-line) below for the additional -parser support that makes the slot tag correctly for action-bar UIs. - -## Macros - -Engine-level extensions to how macros are parsed and dispatched. These -don't add new Lua functions — they teach the engine to recognize input -forms it didn't accept in stock 1.12. Macro authors get them for free -once `ClassicAPI.dll` is loaded. - -Vanilla 1.12 doesn't support `[target=...]`-style macro conditionals -natively; we don't add those. If you have a separate DLL/addon that -does (nampower's conditional macros, SuperWoWhook, etc.), the -extensions below compose with it — that layer strips the bracket -clause and forwards the cleaned tail to `CastSpellByName`, which then -flows through our additions. - -### Numeric spellIDs in `/cast` and `CastSpellByName` - -Pure-numeric input is now accepted anywhere a spell name would be: - -``` -/cast 5019 -- in a macro line; casts Shoot if known -CastSpellByName("5019") -- same effect from Lua / /run / chat -``` - -The spellID is resolved through `Spell.dbc` to the locale-resolved -name, then handed to the engine's existing name resolver — so all the -normal downstream behavior applies: the spellbook lookup gates on -"player knows this spell," action-bar UI sees the cast as if it had -been named, macros containing `/cast 5019` get tagged with the right -spellID in the engine's spell-state cache (so `IsCurrentAction(slot)` -and `IsAutoRepeatAction(slot)` work for the macro slot). - -| Input | Outcome | -|--------------|--------------------------------------------------------| -| `/cast 5019` | Casts Shoot if you know it (any rank, highest known) | -| `/cast 1234` | Falls through as "unknown spell," same as `/cast Foo` | -| `/cast Shoot`| Unchanged from vanilla — names still work | -| `/cast 5019(Rank 1)` | Falls through — rank suffix with a numeric stem isn't supported (use the name form if you need a specific rank) | - -Implemented as a single hook on the engine's name → spellbook-slot -resolver at `0x004B3950` — covers `/cast`, `/castsequence` aliases, -`CastSpellByName`, the macro parser's tagging path, and anywhere -else the engine resolves a spell name. Numeric input with garbage -trailing characters falls through unchanged. - -### `CastSpellNoToggle` as a macro cast line - -Putting `CastSpellNoToggle("Shoot")` in a macro body now tags the -macro with Shoot's spellID the same way `/cast Shoot` or -`CastSpellByName("Shoot")` would. Without this, the macro casts -correctly but vanilla's macro parser doesn't know to associate the -slot with any spell — so action-bar UIs that call -`IsCurrentAction(slot)` / `IsAutoRepeatAction(slot)` (pfUI's -actionbar, ShaguTweaks, etc.) never light up the slot. - -Recognized forms in a macro body: - -``` -CastSpellNoToggle("Shoot") -- by name (string) -CastSpellNoToggle("Cat Form") -- shapeshift / aspect / stance all tag the same way -CastSpellNoToggle(5019) -- not yet — macro parser only recognizes the string form -``` - -The numeric form **works for the cast itself** (via the function's -runtime resolution), but the macro parser only scans for the string -form when tagging. To get the slot to highlight when using the -spellID, write `CastSpellNoToggle("Shoot")` instead. - -The engine's first-match-wins rule still applies — if your macro is: - -``` -/cast Wand -CastSpellNoToggle("Shoot") -``` - -…the macro is tagged with Wand (the engine recognized `/cast Wand` -on line 1; our additional pattern is only consulted when the engine -didn't find any of its own patterns). - -Macro tagging happens at macro edit/save time. Existing macros need -to be opened in the Macro UI and re-saved once after dropping in the -new DLL to pick up the new parser behavior. - -## GameTooltip - -### `GameTooltip:SetItemByID(itemID)` - -Modern method that renders an item tooltip from just an itemID. The -1.12 workaround was constructing an item hyperlink and calling -`SetHyperlink` — `tooltip:SetHyperlink("item:" .. id .. ":0:0:0:0:0:0:0")` -— which works but forces every caller to know the hyperlink format. - -```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. - -### `GameTooltip:GetItem()` - -Returns `(name, link, itemID)` for whichever item the tooltip is -currently displaying, or nothing if it isn't showing an item. Modern -WoW returns only `(name, link)`; we extend with `itemID` as a third -return so callers don't have to gsub-extract it from the link. - -The engine stashes two fields per Set* item call: -- `tooltip+0x398` ← itemID (always populated) -- `tooltip+0x380/+0x384` ← item GUID (only when there's a real - CGItem — `SetBagItem`, `SetInventoryItem`, `SetLootItem`, - `SetMerchantItem`, etc. Zero for `SetItemByID` / `SetHyperlink` - which have no instance.) - -Both fields are zeroed by the per-tooltip Clear on Hide / before the -next Set*. - -```lua -GameTooltip:SetOwner(UIParent, "ANCHOR_CURSOR") - --- SetItemByID — no per-instance data, basic link returned -GameTooltip:SetItemByID(6948) -local name, link, id = GameTooltip:GetItem() --- name = "Hearthstone" --- link = "|cffffffff|Hitem:6948:0:0:0:0:0:0:0|h[Hearthstone]|h|r" --- id = 6948 - --- SetInventoryItem — full dressed link with enchant + random suffix -GameTooltip:SetInventoryItem("player", INVSLOT_BACK) -local name, link, id = GameTooltip:GetItem() --- name = "Superior Cloak" --- link = "|cff1eff00|Hitem:9805:247:843:0|h[Superior Cloak of the Eagle]|h|r" --- id = 9805 -``` - -Two link paths: - -| Set* path | Link form | Dressing | -|---|---|---| -| `SetBagItem`, `SetInventoryItem`, `SetLootItem`, `SetMerchantItem`, … | Full dressed link via the engine's own builder at `0x0052AE00` | Enchant ID, random-suffix factor, unique ID, suffix-decorated name | -| `SetItemByID`, `SetHyperlink` (item:N with no instance data) | Basic colored link | itemID + cached quality + cached name only | - -The dressed-link path works for items not in player inventory -(merchant, loot, mailbox, trade window, etc.) — the engine's -resolver finds any CGItem the client has loaded. - -Returns nothing for: non-item tooltip, uncached itemID on the -no-GUID path (fires a background cache warmup), or empty name. - -Equivalent to the function of the same name introduced in 3.0, -with the added `itemID` third return. - -### `GameTooltip:GetSpell()` - -Returns `(name, rank, spellID)` for whichever spell the tooltip is -currently displaying, or nothing if it isn't showing a spell. The -engine stashes the spellID on the tooltip frame at `+0x39C` whenever -any `SetX` spell path runs (`SetSpell`, `SetSpellByID`, -`SetUnitBuff`/`SetUnitDebuff`, `SetTalent`, etc.) and zeroes it on -the next `Clear` / `Hide`. - -```lua -GameTooltip:SetOwner(UIParent, "ANCHOR_CURSOR") -GameTooltip:SetSpellByID(25306) -local name, rank, spellID = GameTooltip:GetSpell() --- name = "Fireball" --- rank = "Rank 12" --- spellID = 25306 -``` - -`rank` is the empty string (not nil) for spells whose Spell.dbc rank -slot is blank — most racials, talent passives, and proc-triggered -spells. This matches the modern semantics where the rank position is -always populated. - -Equivalent to the function of the same name introduced in 3.0. - -### `GameTooltip:HasItem()` / `GameTooltip:HasSpell()` - -Boolean companions to `GetItem` / `GetSpell`. Return `true` if the -tooltip is currently displaying an item / spell, `false` otherwise. -Cheaper than `GetItem` / `GetSpell` when all you need is the -predicate — single `uint32` read against `OFF_TOOLTIP_ITEM_ID` / -`OFF_TOOLTIP_SPELL_ID`, no DBC lookup or link-build. - -```lua -if GameTooltip:HasItem() then - local _, link = GameTooltip:GetItem() - -- only do the GetItem work when we actually need it +if C_Container.PlayerHasHearthstone() then + -- player can hearth end ``` -Equivalent to the functions of the same name introduced in 3.0 -(`HasItem`) and 6.0 (`HasSpell`). +**Match logic.** An item counts as a hearthstone if **either**: +1. Its itemID is `6948` (the vanilla Hearthstone — fast path, no + cache lookup needed), **or** +2. Its on-use spell is spell `8690` (the "Hearthstone" cast itself). -### `GameTooltip:SetTalentByID(talentID)` +Rule 2 lets custom servers (Turtle WoW, etc.) ship reskinned +hearthstone items with different itemIDs and still have them +recognized — as long as their on-use is the Hearthstone spell. +The return is the **actual matched itemID**, not a hardcoded +constant, so code that wants to do something with the found id +(`SetItemRef` for chat-linking, `GetItemInfo` for the item's +name, etc.) gets the right value for any variant. -Renders a tooltip for the talent identified by `Talent.dbc` primary -key — the natural pair to -[`GetTalentIDByIndex`](#gettalentidbyindextabindex-talentindex). -Works for any class's talents, not just the player's. +> **Cache dependency for rule 2.** The on-use-spell check requires +> the item's `ItemStats_C` record to be in the local cache. Items +> currently in the player's bags are always cached (the engine +> pre-fills the cache during bag sync), so the check is reliable +> for this code path. The fallback to rule 1 (vanilla itemID +> equality) covers the moment-of-login window before the cache is +> fully populated. -Two-tier resolution: +Walks bags 0..4 via the same chain +[`C_Container.GetContainerItemID`](#c_containergetcontaineritemidbagindex-slotindex) +uses internally. Stops on first match. -| Tier | When it applies | Tooltip rendered | -|------|-----------------|------------------| -| Player class (rich) | `talentID` belongs to one of the player's loaded tabs | Full talent tooltip — name, "Rank N/M", description, prereqs, "click to learn" prompts | -| Cross-class (fallback) | `talentID` is from another class | Spell tooltip for the talent's rank-1 spellID — name, cast time, range, mana cost, description | +Equivalent to the function of the same name introduced in 9.0. -The fallback exists because vanilla 1.12 only loads the local -player's class talent data into the engine's per-player TabInfo -arrays. For other classes, we look up the talent in `Talent.dbc` -directly and dispatch the rank-1 spell tooltip — functionally -"what does this talent do?" without the rank counter. Modern WoW -adds talent name and "Rank 0/N" decorations on top of the spell -description for cross-class; we don't replicate that here yet. +### `C_Container.UseHearthstone()` -Silent no-op (no tooltip change) when: +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. -- `talentID` doesn't match any record in `Talent.dbc` -- `talentID` is `nil`, non-numeric, or non-positive - -```lua --- Player's own class — rich tooltip -local talentID = GetTalentIDByIndex(1, 9) -- player's tab 1, talent 9 -GameTooltip:SetOwner(UIParent, "ANCHOR_CURSOR") -GameTooltip:SetTalentByID(talentID) -GameTooltip:Show() - --- Other class — spell tooltip for the talent's primary ability -GameTooltip:SetTalentByID(2065) -- works regardless of player class -GameTooltip:Show() +``` +used = C_Container.UseHearthstone() ``` -Equivalent to the function of the same name introduced in 5.0. - -### `GameTooltip:SetInventoryItemByID(itemID)` - -Renders the tooltip for the **equipped instance** of `itemID` — -walks character-pane slots 1..19, finds the matching item, and -shows it with its actual enchants, random-suffix stats, and -broken/locked state. Distinct from -[`SetItemByID`](#gametooltipsetitembyiditemid), which shows the -clean ItemSparse data with no instance-specific decorations. - -For example, on a pair of boots with a run-speed enchant equipped: - -| Method | Renders | -|--------|---------| -| `SetItemByID()` | Base boots tooltip — name, armor, durability, level req. **No enchant.** | -| `SetInventoryItemByID()` | Same plus `Enchanted: Minor Speed` and any random-suffix lines. | - -Silent no-op if the item isn't currently equipped — fall back to -`SetItemByID` for unworn items, or check via -[`C_Item.IsEquippedItem`](#c_itemisequippeditemitem) first. - -When the player has duplicates of the same itemID equipped -(matched MH/OH weapons, identical rings, identical trinkets), the -**lower-numbered slot wins** — MAINHAND before OFFHAND, FINGER1 -before FINGER2, TRINKET1 before TRINKET2. Matches modern client -behavior (verified empirically). - ```lua -local _, _, _, _, _, _, _, _, _, _, _, _, _, link = GetItemInfo(itemID) -GameTooltip:SetOwner(UIParent, "ANCHOR_CURSOR") -if C_Item.IsEquippedItem(itemID) then - GameTooltip:SetInventoryItemByID(itemID) -- shows enchants/suffix -else - GameTooltip:SetItemByID(itemID) -- shows base stats -end -GameTooltip:Show() -``` - -Equivalent to the function of the same name introduced in 8.0. - -## Quest - -### `C_QuestLog.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 = C_QuestLog.GetQuestIDFromLogIndex(i) -- 0 for headers - -- ... +if not C_Container.UseHearthstone() then + print("No hearthstone in bags!") end ``` -### `C_QuestLog.RequestLoadQuestByID(questID)` +> **`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`). -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. +Internally locates the hearthstone with the same walk +`PlayerHasHearthstone` uses and hands the resulting `CGItem *` pointer +to the engine's by-pointer use primitive at `0x005D8D00` — the same +fallback path `Script_UseContainerItem` ends up at after every special +cursor-mode branch (repair vendor, spell-cast targeting, drop-on-bag) +is skipped. Bypassing the dispatcher avoids the Lua-stack roundtrip +of pushing `(bag, slot)` only for `Script_UseContainerItem` to re-parse +and re-resolve the same item. -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. +Equivalent to the function of the same name introduced in 9.0. -> **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 ...`. +### `C_Item.UseItemByName(itemInfo)` -> **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). +Finds the first item in the player's bags matching `itemInfo` and +uses it. Returns nothing; silently no-ops when: + +- the input is `nil`, an empty string, or otherwise unparseable +- no matching item is in bags +- the engine refuses the use — cooldown, locked item, level + requirement, etc. + +`itemInfo` accepts the same shapes as +[`C_Item.EquipItemByName`](#c_itemequipitembynameiteminfo--dstslot) — +itemID number, bare `"item:N"` string, full chat link, or a localized +item name. Name matches are case-insensitive against the cached +`m_name[0]`. + +```lua +C_Item.UseItemByName("Hearthstone") -- hearth home +C_Item.UseItemByName(6948) -- same thing, by ID +C_Item.UseItemByName("Major Healing Potion") +``` + +Mirrors 3.3.5's `Script_UseItemByName` structure: locate the item +directly, then hand the `CGItem *` to the engine's by-pointer use +primitive at `0x005D8D00`. That primitive dispatches internally based +on item type (food, potion, on-use spell, scroll, quiver, ...) so a +single call covers every item category. We skip +`Script_UseContainerItem` entirely — its branches for repair vendor, +spell-cast targeting, and drop-on-bag cursor modes don't apply to an +addon-issued call from a clean cursor. + +For target-required items (scrolls, traps), the engine reads +cursor-target state at call time, which a Lua-side caller can pre-set +with `TargetUnit("...")`. For self-use items (hearthstone, potions, +food) the engine substitutes the player even if a different target is +present, so no pre-setup is needed. + +Equivalent to the function of the same name introduced in 3.x. + +## CVar + +### `C_CVar.GetCVarBool(cvar)` + +Returns the cvar's value coerced to a boolean, or `nil` if no cvar +by that name is registered. The `C_CVar` namespace was added in +10.x; vanilla 1.12 only has `GetCVar` which returns a string. + +```lua +C_CVar.GetCVarBool("gxMaximize") -- true if the window is set fullscreen +C_CVar.GetCVarBool("CombatDamage") -- false if floating damage text is off +C_CVar.GetCVarBool("doesNotExist") -- nil — distinguishable from false +``` + +Coercion rules (only applied when the cvar exists): + +| Cvar string value | Result | +|---|---| +| `"1"` or any non-zero numeric (`"42"`, `"-3"`, …) | `true` | +| `"true"` (case-insensitive) | `true` | +| `"0"` or empty | `false` | +| Non-numeric, non-`"true"` (`"on"`, `"yes"`) | `false` | +| Cvar name not registered | `nil` | + +Implementation reads the cvar registry directly (engine's +`FUN_FIND_CVAR` at `0x0063DEC0`), bypassing `GetCVar`'s Lua-error +path for unknown cvars. The `nil` return lets callers distinguish +"the cvar exists and is falsy" from "no such cvar." + +#### Glue-state availability + +`C_CVar.GetCVarBool` is also registered on the glue Lua state, and +the engine's stock `GetCVar` / `SetCVar` / `RegisterCVar` / +`GetCVarDefault` — which vanilla 1.12 only exposes in-game — are +mirrored onto glue too. GlueXML patches at the login / realm / +char-select screens can now read and write CVars directly. CVar +storage is process-global, so writes on either state are +immediately visible on the other (a `SetCVar("foo", "1")` from a +GlueXML script will read back as `"1"` on the in-world side, and +vice versa). + +## EquipmentSet + +Backports the modern `C_EquipmentSet.*` namespace on top of a +client-side persistent store. Vanilla 1.12 had no equipment-set +functionality at all (Blizzard introduced it in 3.1.2 as +`SaveEquipmentSet` etc., then namespaced it into `C_EquipmentSet` in +Legion) — and even when it shipped natively, the data lived +server-side, synced via `SMSG_EQUIPMENT_SET_LIST`. Vanilla servers +don't speak that opcode and won't ever, so each character's sets are +kept in a per-character file under `WTF\Account\...`. The format +matches what `VanillaMinimapTracking` does for its tracking config. + +### Overview & file format + +Sets are stored in +`WTF\Account\\\\ClassicAPI_EquipmentSets.txt` +in a line-oriented, human-readable format: + +``` +# ClassicAPI Equipment Sets v1 +set 1 + name=Tanking + icon=INV_Shield_06 + slot 1 guid=0x0000000040000123 + slot 2 ignored + slot 5 guid=0x0000000040000789 +set 2 + name=Healing + icon=Spell_Holy_HolyBolt + ... +``` + +Identity is by **item GUID**, snapshotted at `CreateEquipmentSet` / +`SaveEquipmentSet` time. `UseEquipmentSet` searches every player-owned +container for those GUIDs and dispatches pickup→equip pairs for items +that aren't already where they belong. The search reads the +underlying GUID arrays directly (same trick `C_Item.GetItemCount` +uses for its `includeBank=true` path), so bank items resolve **even +without the bank window being open** — the bank gate at +`VAR_BANK_GATE_GUID` only suppresses `GetItemBySlot`, not the +underlying data. + +One limitation worth knowing about: + +- **Equipping from the bank** is not supported by vanilla's protocol + — `UseEquipmentSet` skips bank items rather than try and fail. + Retrieve the items first, then re-run. + +Modern's signatures take a numeric `iconFileID`; we accept icon path +strings (e.g. `"INV_Shield_06"`) since vanilla has no fileDataID +system. Same string-or-default fallback semantic as 4.3.4 native. + +Cap is **10 sets per character**, matching 4.3.4. The full list re- +serializes on every mutation; a corrupted file is harmless (parse +errors leave the in-memory list empty and the next save rewrites the +file from scratch). + +> Note: this is a **fresh client-side namespace**, not a polyfill of +> some specific Blizzard build's behavior. The shape mirrors Classic +> Era 1.15.x's `C_EquipmentSet.*` where it can, but anything that +> requires server-side state (cross-character sharing, the +> "Equipment Manager" specialization tab) isn't supported. + +### `C_EquipmentSet.CanUseEquipmentSets()` + +Returns `true` unconditionally. Vanilla has no banker/feature gate +on equipment-set storage; we ship the feature for every character. +Equivalent to Classic Era's behavior. + +### `C_EquipmentSet.GetNumEquipmentSets()` + +Returns the count of sets stored for the current character. Loads +the file on first call after login. + +### `C_EquipmentSet.GetEquipmentSetIDs()` + +Returns a numeric-keyed table of every setID in storage order +(insertion-order; not alphabetical). Empty table when nothing's +saved. + +### `C_EquipmentSet.GetEquipmentSetID(name)` + +Returns the numeric setID for a set with the given name, or `nil` if +no set by that name exists. Names are exact (case-sensitive, no +trimming). + +### `C_EquipmentSet.GetEquipmentSetInfo(setID)` + +Returns the nine values modern ships: + +``` +name, icon, setID, isEquipped, +numItems, numEquipped, numInInventory, numMissing, numIgnored +``` + +`isEquipped` is `true` when every resolvable item in the set is in +its target slot (missing items don't disqualify — useful so a set +that includes a bank-stored cloak still shows as equipped after you +swap in the rest). `numItems` excludes ignored slots; `numIgnored` +counts them separately. Returns nothing for an unknown setID. + +### `C_EquipmentSet.GetIgnoredSlots(setID)` + +Returns a numeric-keyed table of slot indices (1..19) that the set +has flagged ignored. Empty table when no slots are ignored. Ignored +slots are recorded **per-set at save time**, by reading the global +`IgnoreSlotForSave` state — not retroactively editable on a saved set. + +### `C_EquipmentSet.GetItemIDs(setID)` + +Returns a hash table `{ [slot] = itemID }` for every set slot whose +item is currently resolvable. Missing items (GUID stored but client +can't find a CGItem) are omitted because vanilla doesn't keep an +itemID separate from the live CGItem record. + +### `C_EquipmentSet.GetItemLocations(setID)` + +Returns a hash table `{ [slot] = locationCode }`. Location codes use +the same bit-packed encoding Blizzard's FrameXML +`EquipmentManager_UnpackLocation` decodes (constants in +`Blizzard_FrameXMLBase/Classic/Constants.lua`): + +| Bit/field | Meaning | +|-----------|---------| +| `0x00100000` (PLAYER) | Item is in a player slot (equipped or in a player bag) | +| `0x00200000` (BAGS) | Item is inside a bag (player or bank) | +| `0x00400000` (BANK) | Item is in the bank (main or bank bag) | +| bits 0..7 | Slot (1-based) within the container | +| bits 8..15 | Bag index — present only when BAGS bit is set | + +PLAYER and BANK are **mutually exclusive** in the encoding (the +unpack uses `if player elseif bank`). Bank bags subtract 4 from the +bagID before storing so the field fits cleanly; unpack reverses this +to give back bag IDs 5..10. Composition: + +| Location | Bits | Example | +|----------|------|---------| +| Equipped (paperdoll slot 1..19) | `PLAYER | slot` | `0x100007` = legs (slot 7) | +| Backpack / player bag 1..4 | `PLAYER | BAGS | (bag<<8) | slot` | `0x300205` = bag 2 slot 5 | +| Main bank slot 1..28 | `BANK | slot` | `0x400003` = bank slot 3 | +| Bank bag 5..10 | `BANK | BAGS | ((bag-4)<<8) | slot` | `0x600101` = bank bag 5 slot 1 | + +Special values returned in the table entry: +- `1` — slot is ignored (`GetIgnoredSlots` lists these) +- `-1` — item is missing (was in the set, can't find now) + +The packed codes pass cleanly through Blizzard's +`EquipmentManager_UnpackLocation` if you want to use the +shared-FrameXML helpers in your addon UI. + +### `C_EquipmentSet.CreateEquipmentSet(name [, icon])` + +Snapshots the player's currently-equipped items into a new set and +returns its setID. Honors `IgnoreSlotForSave` — slots flagged ignored +at call time get the ignored marker instead of the equipped item's +GUID. + +Returns the new setID on success. Returns nothing if: +- the name is empty or already in use +- the cap of 10 sets is reached + +`icon` defaults to `"INV_Misc_QuestionMark"` if omitted. + +### `C_EquipmentSet.SaveEquipmentSet(setID [, icon])` + +Overwrites an existing set's contents with the player's currently- +equipped items. Same ignored-slot handling as `CreateEquipmentSet`. +If `icon` is provided it replaces the set's previous icon; otherwise +the icon is left unchanged. + +### `C_EquipmentSet.ModifyEquipmentSet(setID, newName)` + +Renames an existing set. Fails silently if the new name is empty, +already in use by a different set, or the setID doesn't exist. + +### `C_EquipmentSet.DeleteEquipmentSet(setID)` + +Removes the set. SetIDs are not reused — the next `Create` call +allocates one higher than any seen. + +### `C_EquipmentSet.IgnoreSlotForSave(slot)` / `UnignoreSlotForSave` / `IsSlotIgnoredForSave` / `ClearIgnoredSlotsForSave` + +Global "skip this slot the next time `CreateEquipmentSet` or +`SaveEquipmentSet` runs" state, indexed by 1-based slot (1..19). +Persists for the rest of the session; not written to the WTF file. +Use it when building a set that should leave (say) the tabard slot +free — set the ignore flag, then call `CreateEquipmentSet`, then +optionally `ClearIgnoredSlotsForSave()` afterward. + +### `C_EquipmentSet.EquipmentSetContainsLockedItems(setID)` + +Returns `true` if any item in the set is currently flagged "locked" +by the engine — a pending pickup or use is in flight that +`UseEquipmentSet` would race with. Reads bit 2 (`0x04`) of +`ITEM_FIELD_FLAGS` for each resolvable item in the set. + +### `C_EquipmentSet.UseEquipmentSet(setID)` + +Walks the set and dispatches one **atomic server-side swap** per item +that isn't already in its target slot. Items in the bank are skipped +silently (vanilla can't equip from bank). Missing items are skipped +silently. Returns `true` if the call ran (the set existed), `false` +otherwise. + +Implementation uses the same `FUN_INVENTORY_SWAP` primitive +[`C_Item.EquipItemByName`](#c_itemequipitembynameiteminfo--dstslot) +uses for its explicit-slot path. Each swap is a single +CMSG_SWAP_INV_ITEM (or CMSG_AUTOEQUIP_ITEM) packet that the server +applies atomically — the two-cycle "ring A in slot 11, ring B in +slot 12, set swaps them" case resolves in one packet because the +opcode swaps both slots in a single server transaction. The cursor +is never touched; an item held on the cursor when +`UseEquipmentSet` is called stays on the cursor. + +Longer dependency chains (3+ items rotating) are rare with 1.12's +slot set — the realistic conflicts are paired slots (rings 11/12, +trinkets 13/14, weapons 16/17), all 2-cycles. + +> **`CURSOR_UPDATE` fires per item moved.** The engine's swap +> primitive (`FUN_005E0C40`) runs a generic cursor-state cleanup at +> the end of each call, which fires `CURSOR_UPDATE` regardless of +> whether the cursor was actually touched. So one +> `UseEquipmentSet` call that moves N items will fire N +> `CURSOR_UPDATE` events in quick succession. Addons that react to +> `CURSOR_UPDATE` (cursor-attached tooltips, drag-state tracking) +> should debounce — or check `CursorHasItem()` before doing work — +> since most of those fires won't reflect a real cursor change. +> This is engine behavior, not a bug in the implementation; the +> old cursor-based path actually fired more (one per pickup, one +> per equip, one per cursor-clear). + +### `EQUIPMENT_SETS_CHANGED` event + +Fires (with no payload) after any mutation: `Create`, `Save`, +`Modify`, `Delete`, and the four `*IgnoredSlot*` calls. Addon UI +should re-read its set list / button state when this fires. + +### `EQUIPMENT_SWAP_PENDING` event + +Fires with a single payload arg — `setID` — at the **start** of +`UseEquipmentSet`, right after the set-exists check passes and +before any pickup/equip work begins. Modern addons use this to +gate "swap in progress" UI state (grey out the set button, show +a spinner, etc.) until `EQUIPMENT_SWAP_FINISHED` arrives. + +Doesn't fire if `UseEquipmentSet` is called with an unknown +setID — in that case only `EQUIPMENT_SWAP_FINISHED(false, setID)` +fires. + +### `EQUIPMENT_SWAP_FINISHED` event + +Fires at the end of every `UseEquipmentSet` call with two payload +args: `success` (1 if the set existed and we dispatched the swap, 0 +if the setID was unknown) and `setID`. Note this is "we ran the +dispatch" success — not "every item ended up in its target slot." +Items that were in the bank or that couldn't complete a swap cycle +in one pass still report success=1. Listen for this if you want to +re-paint the character pane / refresh tooltips after a swap. + +## 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. + +### `BAG_UPDATE_DELAYED` event + +Fires (with no payload) once per frame in which any `BAG_UPDATE` +fired. Matches modern WoW's coalescing semantic exactly — register +for `BAG_UPDATE_DELAYED` instead of `BAG_UPDATE` and rescan once +per frame regardless of how many updates fired. ```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) +f:RegisterEvent("BAG_UPDATE_DELAYED") +f:SetScript("OnEvent", function() RescanMyInventory() end) ``` -### `C_QuestLog.GetTitleForQuestID(questID)` +A trade with 6 stacks (12 `BAG_UPDATE`s, all processed in one +frame) produces exactly 1 `BAG_UPDATE_DELAYED` at the end of the +frame — matches Classic Era 1.15.x's observed behavior. -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`. +Implemented by three hooks, none in regions other DLLs touch: +- `FUN_004F91A0` / `FUN_004F9370` (bag subsystem at `0x004F9xxx`) + — each just sets a `g_pending` flag, no fire +- `FUN_0066FD50` (engine's per-frame world-subsystem update at + `0x0066xxxx`, deep in the rendering pipeline, only one caller in + the entire binary) — drains the flag at the tail of the world + tick -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: +The world-tick hook is a tail hook (run original first, then fire +DELAYED), so the fire happens after every other per-frame world +work completes. Addon callbacks see DELAYED after their normal +event handlers. + +> **Coverage limitation.** The keyring `BAG_UPDATE(-2)` path goes +> through a separate function (`FUN_004F8DB0`) that uses +> `__thiscall` with an awkward register-arg shape. Keyring updates +> currently won't trigger `BAG_UPDATE_DELAYED`. Player bag (0..4) +> and bank (5..10) updates work normally — the 95% case. + +### Player input-state events + +Three pairs of zero-payload events fired from a single per-frame +`Tick::WorldTick` callback that reads input state once and edge- +detects each pair. + +| Event | Fires on | Source | +|-------|----------|--------| +| `PLAYER_STARTED_MOVING` / `PLAYER_STOPPED_MOVING` | WASD or autorun toggle | UI-input controller flags at `*0x00BE1148 + 0x04` (`0x10` W \| `0x20` S \| `0x40` A \| `0x80` D \| `0x1000` autorun) | +| `PLAYER_STARTED_TURNING` / `PLAYER_STOPPED_TURNING` | Mouselook bit held AND character body yaw is changing | Mouselook bit `0x01` + per-frame delta on `CGPlayer + 0x9C4` (body yaw, radians) | +| `PLAYER_STARTED_LOOKING` / `PLAYER_STOPPED_LOOKING` | Free-look bit held AND camera-relative yaw is changing | Free-look bit `0x02` + per-frame delta on `[*0x00B4B2BC + 0x65B8] + 0xF0` (camera yaw, radians) | ```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. - -## Gossip - -Retail-shaped wrappers around vanilla's flat `GetGossipText` / -`GetGossipOptions` / `GetGossipAvailableQuests` / `GetGossipActiveQuests` -/ `SelectGossipOption` / `SelectGossipAvailableQuest` / -`SelectGossipActiveQuest` / `CloseGossip` surface. The data is the -same — these calls just read the engine's two gossip-state arrays -(`0x00BBBE90` for options, `0x00BB74C0` for quests, both filled by the -SMSG_GOSSIP_MESSAGE handler at `0x004E26E0`) and shape it into the -modern struct-tables that addons ported from retail expect. - -**Fields the 1.12 server simply doesn't send** — and therefore aren't -in any of the returned tables — include `rewards` and `spellID` (added -after the post-vanilla quest/spell system rework), per-option -`status` (Available / Unavailable / Locked / AlreadyComplete — vanilla -servers don't compute this), and modern UX hints like `overrideIconID` -and `selectOptionWhenOnlyOption`. - -The `icon` field is the raw icon-type byte from SMSG_GOSSIP_MESSAGE -(server-extensible — pservers can add custom NPC types past the -Blizzard 0..10 range). Default Blizzard types resolve to -`Interface\GossipFrame\GossipIcon`: - -| Value | Type | Value | Type | -|------:|:-----|------:|:-----| -| `0` | Gossip | `6` | Banker | -| `1` | Vendor | `7` | Petition | -| `2` | Taxi | `8` | Tabard | -| `3` | Trainer | `9` | BattleMaster | -| `4` | Healer | `10` | Auctioneer | -| `5` | Binder (innkeeper) | | | - -### `C_GossipInfo.GetText()` - -Returns the gossip greeting string the engine resolved from the NPC's -referenced `NPC_TEXT.dbc` row. Same value `GetGossipText()` returns; -provided so addons that prefer the `C_GossipInfo` namespace don't have -to mix the two surfaces. - -```lua -print(C_GossipInfo.GetText()) -``` - -### `C_GossipInfo.GetOptions()` - -Returns an array of gossip-option tables in display order. Each entry -contains: - -| Field | Type | Notes | -|------------------|---------|-------| -| `gossipOptionID` | number | Vanilla `optionIndex`. The same value `C_GossipInfo.SelectOption` expects; arbitrary integer assigned by the server. | -| `name` | string | Option text (locale-applied by the server). | -| `icon` | number | Raw icon-type byte from SMSG_GOSSIP_MESSAGE — passed through unmapped so pserver-added types (anything past the default `0..10` range) survive. See the type table above for the default Blizzard categories and the `Interface\GossipFrame\GossipIcon` path each one resolves to. | -| `flags` | number | Bit 0 set = `boxCoded` (the option asks for confirmation text — `Are you sure?` boxes). | -| `orderIndex` | number | 1-based position in the emitted list. Matches the index `SelectGossipOption` (legacy) expects. | - -```lua -for _, opt in ipairs(C_GossipInfo.GetOptions()) do - print(opt.gossipOptionID, opt.name, "icon", opt.icon) +for _, ev in ipairs({ + "PLAYER_STARTED_MOVING", "PLAYER_STOPPED_MOVING", + "PLAYER_STARTED_LOOKING", "PLAYER_STOPPED_LOOKING", + "PLAYER_STARTED_TURNING", "PLAYER_STOPPED_TURNING", +}) do + f:RegisterEvent(ev) end +f:SetScript("OnEvent", function(_, event) print(event) end) ``` -### `C_GossipInfo.GetAvailableQuests()` +**Key-state semantics for MOVING**: `STOPPED_MOVING` fires the +instant the movement keys release, even if the character is still +airborne from a jump. Matches retail (verified empirically). For +an "is the character actually displacing this frame" signal, use +`GetUnitSpeed("player")` and watch the first return. -Returns an array of deliverable-quest tables (quests the giver is -offering to start), in display order. Filter mirrors vanilla's -`GetGossipAvailableQuests` — status field at `+0x008` not in `{3, 4}`. +**Latched semantics for TURNING and LOOKING**: each pair fires +exactly once per RMB / LMB hold. STARTED waits until both the +mouse-button bit is held AND the relevant yaw has actually +changed (matches retail's "camera has moved" semantics — clicking +without dragging doesn't fire). STOPPED fires when the button bit +clears (RMB / LMB release). The latch stays on through any drag- +stop-drag motion within a single hold; no spurious flapping. -| Field | Type | Notes | -|--------------|--------|-------| -| `questID` | number | Quest.dbc row ID. | -| `title` | string | Localized quest title. | -| `questLevel` | number | Quest level. | +The camera-relative yaw at `[camera + 0xF0]` stays at 0 during +RMB-mouselook (camera rotates *with* the character, so its offset +from the character doesn't change), so TURNING and LOOKING are +cleanly separable: RMB only fires TURNING, LMB only fires LOOKING. -### `C_GossipInfo.GetActiveQuests()` +Implementation: single subscriber on the shared `Tick::WorldTick` +registry (same `MinHook` on `FUN_0066FD50` shared with +`BAG_UPDATE_DELAYED`). When any of the input controller / player / +camera pointers is null (pre-login, loading screen, character +select), all states reset so the next valid tick doesn't fire +spurious STOPPED transitions. -Returns an array of active-quest tables (quests the giver wants you -to turn in, in-progress or complete). Status field at `+0x008` in -`{3, 4}`. +### `GLOBAL_MOUSE_DOWN` / `GLOBAL_MOUSE_UP` events -| Field | Type | Notes | -|--------------|---------|-------| -| `questID` | number | Quest.dbc row ID. | -| `title` | string | Localized quest title. | -| `questLevel` | number | Quest level. | -| `isComplete` | boolean | `true` when the engine's status byte is `4` (ready to turn in); `false` when it's `3` (still in progress). | +Fires on every raw mouse-button press or release while WoW has +focus. Payload is the button identifier string — matches modern +WoW's signature exactly. -### `C_GossipInfo.GetNumOptions()` / `GetNumAvailableQuests()` / `GetNumActiveQuests()` +```lua +local f = CreateFrame("Frame") +f:RegisterEvent("GLOBAL_MOUSE_DOWN") +f:RegisterEvent("GLOBAL_MOUSE_UP") +f:SetScript("OnEvent", function(_, event, button) + print(event, button) -- "GLOBAL_MOUSE_DOWN", "LeftButton" +end) +``` -Convenience counters — return the length of each of the three lists -above without building the table. +| Payload | Source | +|---------|--------| +| `"LeftButton"` | `VK_LBUTTON` | +| `"RightButton"` | `VK_RBUTTON` | +| `"MiddleButton"` | `VK_MBUTTON` | +| `"Button4"` | `VK_XBUTTON1` | +| `"Button5"` | `VK_XBUTTON2` | -### `C_GossipInfo.SelectOption(gossipOptionID)` / `SelectOptionByIndex(orderIndex)` +Distinct from per-frame `OnMouseDown` scripts — these fire even +when the click misses every UI frame (clicks in the world / on +nothing). Distinct from `PLAYER_STARTED_LOOKING` / +`PLAYER_STARTED_TURNING` — those are camera-rotation events; +these are raw input events. -Picks a gossip option. `SelectOption` resolves the modern -`gossipOptionID` to vanilla's 1-based slot, then tail-calls the -engine's native `SelectGossipOption`. `SelectOptionByIndex` is a thin -passthrough for callers that already have the slot index (e.g. from -`opt.orderIndex` on a `GetOptions()` entry, or from a UI button bound -directly to the slot). - -Both end in the same CMSG; the option-ID variant exists so addons can -drive selections off the modern `gossipOptionID` key without keeping -their own slot mapping. Returns nothing. - -Vanilla's `SelectGossipOption` doesn't accept a confirmation-text -argument, so for `boxCoded` options the engine's own confirm dialog -runs as usual — there is no way to send the password from the script. - -### `C_GossipInfo.SelectAvailableQuest(questID)` - -Picks a deliverable quest by `questID`. Walks the active-vs-available -filter the same way `GetAvailableQuests` does, locates the matching -1-based slot, and tail-calls the engine's `SelectGossipAvailableQuest`. -Returns nothing. - -### `C_GossipInfo.SelectActiveQuest(questID)` - -Picks an in-progress quest by `questID`. Same shape as -`SelectAvailableQuest` but walks the active filter and tail-calls -`SelectGossipActiveQuest`. Returns nothing. - -### `C_GossipInfo.CloseGossip()` - -Closes the gossip window. Direct passthrough to the engine's -`CloseGossip`. Returns nothing. +**Focus-gated.** Polls Win32 `GetAsyncKeyState` per frame on the +shared `Tick::WorldTick` registry. DOWN transitions are only +honored when WoW is the foreground window — clicking in another +app while alt-tabbed doesn't fire. UP transitions always fire, +even if the user alt-tabbed mid-click, so an addon never gets +left in a "button is held" state. ## Faction @@ -1857,6 +1665,613 @@ contribute to the same pending window. This is acceptable for the addons that need per-call tracking should manage their own ticket state on top. +## 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. + +### `GameTooltip:GetItem()` + +Returns `(name, link, itemID)` for whichever item the tooltip is +currently displaying, or nothing if it isn't showing an item. Modern +WoW returns only `(name, link)`; we extend with `itemID` as a third +return so callers don't have to gsub-extract it from the link. + +The engine stashes two fields per Set* item call: +- `tooltip+0x398` ← itemID (always populated) +- `tooltip+0x380/+0x384` ← item GUID (only when there's a real + CGItem — `SetBagItem`, `SetInventoryItem`, `SetLootItem`, + `SetMerchantItem`, etc. Zero for `SetItemByID` / `SetHyperlink` + which have no instance.) + +Both fields are zeroed by the per-tooltip Clear on Hide / before the +next Set*. + +```lua +GameTooltip:SetOwner(UIParent, "ANCHOR_CURSOR") + +-- SetItemByID — no per-instance data, basic link returned +GameTooltip:SetItemByID(6948) +local name, link, id = GameTooltip:GetItem() +-- name = "Hearthstone" +-- link = "|cffffffff|Hitem:6948:0:0:0:0:0:0:0|h[Hearthstone]|h|r" +-- id = 6948 + +-- SetInventoryItem — full dressed link with enchant + random suffix +GameTooltip:SetInventoryItem("player", INVSLOT_BACK) +local name, link, id = GameTooltip:GetItem() +-- name = "Superior Cloak" +-- link = "|cff1eff00|Hitem:9805:247:843:0|h[Superior Cloak of the Eagle]|h|r" +-- id = 9805 +``` + +Two link paths: + +| Set* path | Link form | Dressing | +|---|---|---| +| `SetBagItem`, `SetInventoryItem`, `SetLootItem`, `SetMerchantItem`, … | Full dressed link via the engine's own builder at `0x0052AE00` | Enchant ID, random-suffix factor, unique ID, suffix-decorated name | +| `SetItemByID`, `SetHyperlink` (item:N with no instance data) | Basic colored link | itemID + cached quality + cached name only | + +The dressed-link path works for items not in player inventory +(merchant, loot, mailbox, trade window, etc.) — the engine's +resolver finds any CGItem the client has loaded. + +Returns nothing for: non-item tooltip, uncached itemID on the +no-GUID path (fires a background cache warmup), or empty name. + +Equivalent to the function of the same name introduced in 3.0, +with the added `itemID` third return. + +### `GameTooltip:GetSpell()` + +Returns `(name, rank, spellID)` for whichever spell the tooltip is +currently displaying, or nothing if it isn't showing a spell. The +engine stashes the spellID on the tooltip frame at `+0x39C` whenever +any `SetX` spell path runs (`SetSpell`, `SetSpellByID`, +`SetUnitBuff`/`SetUnitDebuff`, `SetTalent`, etc.) and zeroes it on +the next `Clear` / `Hide`. + +```lua +GameTooltip:SetOwner(UIParent, "ANCHOR_CURSOR") +GameTooltip:SetSpellByID(25306) +local name, rank, spellID = GameTooltip:GetSpell() +-- name = "Fireball" +-- rank = "Rank 12" +-- spellID = 25306 +``` + +`rank` is the empty string (not nil) for spells whose Spell.dbc rank +slot is blank — most racials, talent passives, and proc-triggered +spells. This matches the modern semantics where the rank position is +always populated. + +Equivalent to the function of the same name introduced in 3.0. + +### `GameTooltip:HasItem()` / `GameTooltip:HasSpell()` + +Boolean companions to `GetItem` / `GetSpell`. Return `true` if the +tooltip is currently displaying an item / spell, `false` otherwise. +Cheaper than `GetItem` / `GetSpell` when all you need is the +predicate — single `uint32` read against `OFF_TOOLTIP_ITEM_ID` / +`OFF_TOOLTIP_SPELL_ID`, no DBC lookup or link-build. + +```lua +if GameTooltip:HasItem() then + local _, link = GameTooltip:GetItem() + -- only do the GetItem work when we actually need it +end +``` + +Equivalent to the functions of the same name introduced in 3.0 +(`HasItem`) and 6.0 (`HasSpell`). + +### `GameTooltip:SetTalentByID(talentID)` + +Renders a tooltip for the talent identified by `Talent.dbc` primary +key — the natural pair to +[`GetTalentIDByIndex`](#gettalentidbyindextabindex-talentindex). +Works for any class's talents, not just the player's. + +Two-tier resolution: + +| Tier | When it applies | Tooltip rendered | +|------|-----------------|------------------| +| Player class (rich) | `talentID` belongs to one of the player's loaded tabs | Full talent tooltip — name, "Rank N/M", description, prereqs, "click to learn" prompts | +| Cross-class (fallback) | `talentID` is from another class | Spell tooltip for the talent's rank-1 spellID — name, cast time, range, mana cost, description | + +The fallback exists because vanilla 1.12 only loads the local +player's class talent data into the engine's per-player TabInfo +arrays. For other classes, we look up the talent in `Talent.dbc` +directly and dispatch the rank-1 spell tooltip — functionally +"what does this talent do?" without the rank counter. Modern WoW +adds talent name and "Rank 0/N" decorations on top of the spell +description for cross-class; we don't replicate that here yet. + +Silent no-op (no tooltip change) when: + +- `talentID` doesn't match any record in `Talent.dbc` +- `talentID` is `nil`, non-numeric, or non-positive + +```lua +-- Player's own class — rich tooltip +local talentID = GetTalentIDByIndex(1, 9) -- player's tab 1, talent 9 +GameTooltip:SetOwner(UIParent, "ANCHOR_CURSOR") +GameTooltip:SetTalentByID(talentID) +GameTooltip:Show() + +-- Other class — spell tooltip for the talent's primary ability +GameTooltip:SetTalentByID(2065) -- works regardless of player class +GameTooltip:Show() +``` + +Equivalent to the function of the same name introduced in 5.0. + +### `GameTooltip:SetInventoryItemByID(itemID)` + +Renders the tooltip for the **equipped instance** of `itemID` — +walks character-pane slots 1..19, finds the matching item, and +shows it with its actual enchants, random-suffix stats, and +broken/locked state. Distinct from +[`SetItemByID`](#gametooltipsetitembyiditemid), which shows the +clean ItemSparse data with no instance-specific decorations. + +For example, on a pair of boots with a run-speed enchant equipped: + +| Method | Renders | +|--------|---------| +| `SetItemByID()` | Base boots tooltip — name, armor, durability, level req. **No enchant.** | +| `SetInventoryItemByID()` | Same plus `Enchanted: Minor Speed` and any random-suffix lines. | + +Silent no-op if the item isn't currently equipped — fall back to +`SetItemByID` for unworn items, or check via +[`C_Item.IsEquippedItem`](#c_itemisequippeditemitem) first. + +When the player has duplicates of the same itemID equipped +(matched MH/OH weapons, identical rings, identical trinkets), the +**lower-numbered slot wins** — MAINHAND before OFFHAND, FINGER1 +before FINGER2, TRINKET1 before TRINKET2. Matches modern client +behavior (verified empirically). + +```lua +local _, _, _, _, _, _, _, _, _, _, _, _, _, link = GetItemInfo(itemID) +GameTooltip:SetOwner(UIParent, "ANCHOR_CURSOR") +if C_Item.IsEquippedItem(itemID) then + GameTooltip:SetInventoryItemByID(itemID) -- shows enchants/suffix +else + GameTooltip:SetItemByID(itemID) -- shows base stats +end +GameTooltip:Show() +``` + +Equivalent to the function of the same name introduced in 8.0. + +## 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 +``` + +### `LE_EXPANSION_*` + +The retail / Classic Era expansion-level enum, exposed as Lua globals +so addons backporting from later expansions don't have to gate on +`if LE_EXPANSION_CLASSIC then` (the constant being defined is itself +the version probe). Values match the modern `Enum.ExpansionLevel` +table. + +| Constant | Value | +|---------------------------------------|------:| +| `LE_EXPANSION_LEVEL_CURRENT` | `0` *(this is Classic)* | +| `LE_EXPANSION_CLASSIC` | `0` | +| `LE_EXPANSION_BURNING_CRUSADE` | `1` | +| `LE_EXPANSION_WRATH_OF_THE_LICH_KING` | `2` | +| `LE_EXPANSION_CATACLYSM` | `3` | +| `LE_EXPANSION_MISTS_OF_PANDARIA` | `4` | +| `LE_EXPANSION_WARLORDS_OF_DRAENOR` | `5` | +| `LE_EXPANSION_LEGION` | `6` | +| `LE_EXPANSION_BATTLE_FOR_AZEROTH` | `7` | +| `LE_EXPANSION_SHADOWLANDS` | `8` | +| `LE_EXPANSION_DRAGONFLIGHT` | `9` | +| `LE_EXPANSION_WAR_WITHIN` | `10` | +| `LE_EXPANSION_MIDNIGHT` | `11` | + +```lua +-- Classic version check using modern idiom +if LE_EXPANSION_LEVEL_CURRENT < LE_EXPANSION_BURNING_CRUSADE then + -- pure-1.x (vanilla / Classic Era) code path +end + +-- Probe for ClassicAPI presence +if LE_EXPANSION_LEVEL_CURRENT then + -- the constants are defined → ClassicAPI is loaded +end +``` + +### `LE_ITEM_QUALITY_*` + +The item-quality enum (modern `Enum.ItemQuality`), exposed as Lua +globals so addons backporting modern code can do +`if quality >= LE_ITEM_QUALITY_RARE then ...` against the integer +quality returned by `GetItemInfo` / `C_Item.GetItemInfoInstant`. + +| Constant | Value | Color in tooltip | +|--------------------------------|------:|------------------| +| `LE_ITEM_QUALITY_POOR` | `0` | gray (junk) | +| `LE_ITEM_QUALITY_COMMON` | `1` | white | +| `LE_ITEM_QUALITY_UNCOMMON` | `2` | green | +| `LE_ITEM_QUALITY_RARE` | `3` | blue | +| `LE_ITEM_QUALITY_EPIC` | `4` | purple | +| `LE_ITEM_QUALITY_LEGENDARY` | `5` | orange | +| `LE_ITEM_QUALITY_ARTIFACT` | `6` | gold *(TBC+ only)* | +| `LE_ITEM_QUALITY_HEIRLOOM` | `7` | light blue *(WotLK+ only)* | +| `LE_ITEM_QUALITY_WOWTOKEN` | `8` | orange *(WoD+ only)* | + +Values 0..5 (POOR..LEGENDARY) correspond to actual qualities present +in vanilla 1.12. Higher values are exposed for source compatibility +with modern addons — vanilla items will never carry those quality +values, so a comparison like `quality == LE_ITEM_QUALITY_HEIRLOOM` +trivially never matches and the rest of the code path is unreachable. + +```lua +local _, _, quality = GetItemInfo(itemID) +if quality and quality >= LE_ITEM_QUALITY_RARE then + -- highlight in UI +end +``` + +### `LE_UNIT_STAT_*` + +The primary-stat enum (modern `Enum.UnitStat`), exposed as Lua globals +so addons can index `UnitStat(unit, statIndex)` symbolically: + +| Constant | Value | Stat | +|-------------------------|------:|------| +| `LE_UNIT_STAT_STRENGTH` | `1` | Strength | +| `LE_UNIT_STAT_AGILITY` | `2` | Agility | +| `LE_UNIT_STAT_STAMINA` | `3` | Stamina | +| `LE_UNIT_STAT_INTELLECT` | `4` | Intellect | +| `LE_UNIT_STAT_SPIRIT` | `5` | Spirit | + +Values are stable across every WoW expansion — `UnitStat("player", 1)` +has always returned strength. + +```lua +local _, effective = UnitStat("player", LE_UNIT_STAT_AGILITY) +``` + +### `Enum.AddOnSecurityStatus` + +The integer enum `C_AddOns.GetAddOnSecurity` returns. Matches +Blizzard's `Enum.AddOnSecurityStatus`: + +| Value | Field | Notes | +|------:|----------------|-------| +| `0` | `Secure` | Blizzard-signed addons. | +| `1` | `Insecure` | User addons; default for any registered addon. | +| `2` | `Banned` | Server-disqualified entries. | +| `3` | `NotAvailable` | No addon by that name / index. | + +```lua +if C_AddOns.GetAddOnSecurity(name) == Enum.AddOnSecurityStatus.Secure then + -- it's a Blizzard_* addon +end +``` + +## Gossip + +Retail-shaped wrappers around vanilla's flat `GetGossipText` / +`GetGossipOptions` / `GetGossipAvailableQuests` / `GetGossipActiveQuests` +/ `SelectGossipOption` / `SelectGossipAvailableQuest` / +`SelectGossipActiveQuest` / `CloseGossip` surface. The data is the +same — these calls just read the engine's two gossip-state arrays +(`0x00BBBE90` for options, `0x00BB74C0` for quests, both filled by the +SMSG_GOSSIP_MESSAGE handler at `0x004E26E0`) and shape it into the +modern struct-tables that addons ported from retail expect. + +**Fields the 1.12 server simply doesn't send** — and therefore aren't +in any of the returned tables — include `rewards` and `spellID` (added +after the post-vanilla quest/spell system rework), per-option +`status` (Available / Unavailable / Locked / AlreadyComplete — vanilla +servers don't compute this), and modern UX hints like `overrideIconID` +and `selectOptionWhenOnlyOption`. + +The `icon` field is the raw icon-type byte from SMSG_GOSSIP_MESSAGE +(server-extensible — pservers can add custom NPC types past the +Blizzard 0..10 range). Default Blizzard types resolve to +`Interface\GossipFrame\GossipIcon`: + +| Value | Type | Value | Type | +|------:|:-----|------:|:-----| +| `0` | Gossip | `6` | Banker | +| `1` | Vendor | `7` | Petition | +| `2` | Taxi | `8` | Tabard | +| `3` | Trainer | `9` | BattleMaster | +| `4` | Healer | `10` | Auctioneer | +| `5` | Binder (innkeeper) | | | + +### `C_GossipInfo.GetText()` + +Returns the gossip greeting string the engine resolved from the NPC's +referenced `NPC_TEXT.dbc` row. Same value `GetGossipText()` returns; +provided so addons that prefer the `C_GossipInfo` namespace don't have +to mix the two surfaces. + +```lua +print(C_GossipInfo.GetText()) +``` + +### `C_GossipInfo.GetOptions()` + +Returns an array of gossip-option tables in display order. Each entry +contains: + +| Field | Type | Notes | +|------------------|---------|-------| +| `gossipOptionID` | number | Vanilla `optionIndex`. The same value `C_GossipInfo.SelectOption` expects; arbitrary integer assigned by the server. | +| `name` | string | Option text (locale-applied by the server). | +| `icon` | number | Raw icon-type byte from SMSG_GOSSIP_MESSAGE — passed through unmapped so pserver-added types (anything past the default `0..10` range) survive. See the type table above for the default Blizzard categories and the `Interface\GossipFrame\GossipIcon` path each one resolves to. | +| `flags` | number | Bit 0 set = `boxCoded` (the option asks for confirmation text — `Are you sure?` boxes). | +| `orderIndex` | number | 1-based position in the emitted list. Matches the index `SelectGossipOption` (legacy) expects. | + +```lua +for _, opt in ipairs(C_GossipInfo.GetOptions()) do + print(opt.gossipOptionID, opt.name, "icon", opt.icon) +end +``` + +### `C_GossipInfo.GetAvailableQuests()` + +Returns an array of deliverable-quest tables (quests the giver is +offering to start), in display order. Filter mirrors vanilla's +`GetGossipAvailableQuests` — status field at `+0x008` not in `{3, 4}`. + +| Field | Type | Notes | +|--------------|--------|-------| +| `questID` | number | Quest.dbc row ID. | +| `title` | string | Localized quest title. | +| `questLevel` | number | Quest level. | + +### `C_GossipInfo.GetActiveQuests()` + +Returns an array of active-quest tables (quests the giver wants you +to turn in, in-progress or complete). Status field at `+0x008` in +`{3, 4}`. + +| Field | Type | Notes | +|--------------|---------|-------| +| `questID` | number | Quest.dbc row ID. | +| `title` | string | Localized quest title. | +| `questLevel` | number | Quest level. | +| `isComplete` | boolean | `true` when the engine's status byte is `4` (ready to turn in); `false` when it's `3` (still in progress). | + +### `C_GossipInfo.GetNumOptions()` / `GetNumAvailableQuests()` / `GetNumActiveQuests()` + +Convenience counters — return the length of each of the three lists +above without building the table. + +### `C_GossipInfo.SelectOption(gossipOptionID)` / `SelectOptionByIndex(orderIndex)` + +Picks a gossip option. `SelectOption` resolves the modern +`gossipOptionID` to vanilla's 1-based slot, then tail-calls the +engine's native `SelectGossipOption`. `SelectOptionByIndex` is a thin +passthrough for callers that already have the slot index (e.g. from +`opt.orderIndex` on a `GetOptions()` entry, or from a UI button bound +directly to the slot). + +Both end in the same CMSG; the option-ID variant exists so addons can +drive selections off the modern `gossipOptionID` key without keeping +their own slot mapping. Returns nothing. + +Vanilla's `SelectGossipOption` doesn't accept a confirmation-text +argument, so for `boxCoded` options the engine's own confirm dialog +runs as usual — there is no way to send the password from the script. + +### `C_GossipInfo.SelectAvailableQuest(questID)` + +Picks a deliverable quest by `questID`. Walks the active-vs-available +filter the same way `GetAvailableQuests` does, locates the matching +1-based slot, and tail-calls the engine's `SelectGossipAvailableQuest`. +Returns nothing. + +### `C_GossipInfo.SelectActiveQuest(questID)` + +Picks an in-progress quest by `questID`. Same shape as +`SelectAvailableQuest` but walks the active filter and tail-calls +`SelectGossipActiveQuest`. Returns nothing. + +### `C_GossipInfo.CloseGossip()` + +Closes the gossip window. Direct passthrough to the engine's +`CloseGossip`. Returns nothing. + +## Hooks + +### `hooksecurefunc(name, callback)` / `hooksecurefunc(table, name, callback)` + +Modern post-call hook: the original function runs first, then +`callback` runs with the same args (return values discarded). The +original's return values propagate to the caller. + +```lua +hooksecurefunc("GetSpellInfo", function(spellID) + print("GetSpellInfo called with " .. tostring(spellID)) +end) + +hooksecurefunc(GameTooltip, "SetInventoryItem", function(self, unit, slot) + -- runs after the engine fills the tooltip + print("inventory tooltip:", unit, slot) +end) +``` + +The "secure" label refers to taint-propagation behavior introduced in +3.0 for protected-frame manipulation. Vanilla 1.12 has no taint +system, so the function is functionally equivalent to a plain +"after-hook" — just preserves modern API parity for addons being +backported from later expansions. + +Implemented in pure C: builds a Lua C closure with `(orig, callback)` +as upvalues; the wrapper calls orig with `LUA_MULTRET`, then callback, +then returns orig's full result list. No return-count cap — works +correctly for functions returning any number of values. + +Errors via `lua_error` on: +- Non-string `name` +- Non-function `callback` +- `target[name]` not resolvable to a function (covers typos and + hooking unknown frame methods) + +## Input + +1.12 ships `IsShiftKeyDown` / `IsControlKeyDown` / `IsAltKeyDown` but +they only report "any shift/ctrl/alt" — there's no built-in way to tell +left from right. These seven functions add the missing distinction +plus an `IsModifierKeyDown()` rollup. + +### `IsLeftShiftKeyDown()` / `IsRightShiftKeyDown()` +### `IsLeftControlKeyDown()` / `IsRightControlKeyDown()` +### `IsLeftAltKeyDown()` / `IsRightAltKeyDown()` + +Each returns `1` when the corresponding key is physically down, `nil` +otherwise — matching the convention 1.12's own `IsShiftKeyDown` etc. +use. + +```lua +if IsLeftShiftKeyDown() and not IsRightShiftKeyDown() then + -- left-shift-only binding +end +``` + +### `IsModifierKeyDown()` + +Returns `1` if **any** of the six modifier keys is down, `nil` +otherwise. Equivalent to +`IsShiftKeyDown() or IsControlKeyDown() or IsAltKeyDown()` but in one +call. + +### `MODIFIER_STATE_CHANGED` event + +Fires on every modifier-key press and release with `(key, down)`: + +| arg1 (`key`) | `LSHIFT`, `RSHIFT`, `LCTRL`, `RCTRL`, `LALT`, `RALT` | +| arg2 (`down`) | `1` on press, `0` on release | + +Only transitions fire — key autorepeat does not. Matches 2.4.3+ +semantics. + +```lua +local f = CreateFrame("Frame") +f:RegisterEvent("MODIFIER_STATE_CHANGED") +f:SetScript("OnEvent", function() + -- in vanilla 1.12 OnEvent receives no args; engine sets `event` and + -- `arg1..argN` as globals before invoking the handler. + if event == "MODIFIER_STATE_CHANGED" and arg1 == "LSHIFT" then + print("left shift", arg2 == 1 and "down" or "up") + end +end) +``` + +**Implementation notes** + +L/R modifier distinction doesn't exist anywhere in the 1.12 engine's +own state — its `IsShiftKeyDown` chain bottoms out at +`GetKeyState(VK_SHIFT)` (the merged virtual key, `0x10`), never the +L/R-aware `VK_LSHIFT` / `VK_RSHIFT`. The OS-level keystate *does* have +the distinction; we capture it by installing a `WH_GETMESSAGE` Win32 +thread hook on the engine's message-pump thread, decoding each +`WM_KEY{,SYS}{DOWN,UP}` message (using `MapVirtualKeyA(scancode, +MAPVK_VSC_TO_VK_EX)` to resolve `VK_SHIFT` to L/R and the `KF_EXTENDED` +bit in `lParam` for `VK_CONTROL` / `VK_MENU`), and maintaining a +6-bit cached bitmap that the seven query functions read. + +The thread-message hook is per-thread, not per-`HWND` — it survives +renderer-state changes that recreate WoW's main window (e.g. toggling +vertical sync), where an `SetWindowLongPtr`-style `WNDPROC` subclass +would be left dangling. + ## Item > ### `itemLocation` argument shapes @@ -2763,310 +3178,87 @@ end > itemID; `GetCraftSpellID` returns the recipe spellID — because > there's no produced item to point at. -## Container +## Macros -### `C_Container.GetContainerItemID(bagIndex, slotIndex)` +Engine-level extensions to how macros are parsed and dispatched. These +don't add new Lua functions — they teach the engine to recognize input +forms it didn't accept in stock 1.12. Macro authors get them for free +once `ClassicAPI.dll` is loaded. -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. +Vanilla 1.12 doesn't support `[target=...]`-style macro conditionals +natively; we don't add those. If you have a separate DLL/addon that +does (nampower's conditional macros, SuperWoWhook, etc.), the +extensions below compose with it — that layer strips the bracket +clause and forwards the cleaned tail to `CastSpellByName`, which then +flows through our additions. -- `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). +### Numeric spellIDs in `/cast` and `CastSpellByName` -```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. +Pure-numeric input is now accepted anywhere a spell name would be: ``` -current, maximum = C_Container.GetContainerItemDurability(containerIndex, slotIndex) +/cast 5019 -- in a macro line; casts Shoot if known +CastSpellByName("5019") -- same effect from Lua / /run / chat ``` -- `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. +The spellID is resolved through `Spell.dbc` to the locale-resolved +name, then handed to the engine's existing name resolver — so all the +normal downstream behavior applies: the spellbook lookup gates on +"player knows this spell," action-bar UI sees the cast as if it had +been named, macros containing `/cast 5019` get tagged with the right +spellID in the engine's spell-state cache (so `IsCurrentAction(slot)` +and `IsAutoRepeatAction(slot)` work for the macro slot). -```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 -``` +| Input | Outcome | +|--------------|--------------------------------------------------------| +| `/cast 5019` | Casts Shoot if you know it (any rank, highest known) | +| `/cast 1234` | Falls through as "unknown spell," same as `/cast Foo` | +| `/cast Shoot`| Unchanged from vanilla — names still work | +| `/cast 5019(Rank 1)` | Falls through — rank suffix with a numeric stem isn't supported (use the name form if you need a specific rank) | -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. +Implemented as a single hook on the engine's name → spellbook-slot +resolver at `0x004B3950` — covers `/cast`, `/castsequence` aliases, +`CastSpellByName`, the macro parser's tagging path, and anywhere +else the engine resolves a spell name. Numeric input with garbage +trailing characters falls through unchanged. -Equivalent to the function of the same name introduced in 10.0. +### `CastSpellNoToggle` as a macro cast line -### `C_Container.GetContainerItemRepairCost(containerIndex, slotIndex)` +Putting `CastSpellNoToggle("Shoot")` in a macro body now tags the +macro with Shoot's spellID the same way `/cast Shoot` or +`CastSpellByName("Shoot")` would. Without this, the macro casts +correctly but vanilla's macro parser doesn't know to associate the +slot with any spell — so action-bar UIs that call +`IsCurrentAction(slot)` / `IsAutoRepeatAction(slot)` (pfUI's +actionbar, ShaguTweaks, etc.) never light up the slot. -Bag/bank variant of -[`GetInventoryItemRepairCost`](#getinventoryitemrepaircostinvslot). -Same `copperCost` single-int return and the same "0 for nothing to -repair" semantics. +Recognized forms in a macro body: ``` -copperCost = C_Container.GetContainerItemRepairCost(containerIndex, slotIndex) +CastSpellNoToggle("Shoot") -- by name (string) +CastSpellNoToggle("Cat Form") -- shapeshift / aspect / stance all tag the same way +CastSpellNoToggle(5019) -- not yet — macro parser only recognizes the string form ``` -`containerIndex` accepts the same values as -[`C_Container.GetContainerItemDurability`](#c_containergetcontaineritemdurabilitycontainerindex-slotindex) -(`0` = backpack, `1..4` = equipped bags, `-1`/`5..11` = bank, etc.). +The numeric form **works for the cast itself** (via the function's +runtime resolution), but the macro parser only scans for the string +form when tagging. To get the slot to highlight when using the +spellID, write `CastSpellNoToggle("Shoot")` instead. -```lua -for slot = 1, GetContainerNumSlots(0) do - local cost = C_Container.GetContainerItemRepairCost(0, slot) - if cost > 0 then - -- broken/damaged item sitting in the backpack - end -end -``` - -Useful for "repair only items above N copper" smart-repair logic -without scanning tooltips. ClassicAPI addition; modern WoW has no -direct equivalent. - -### `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). +The engine's first-match-wins rule still applies — if your macro is: ``` -numberOfFreeSlots, bagType = C_Container.GetContainerNumFreeSlots(bagID) +/cast Wand +CastSpellNoToggle("Shoot") ``` -- `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. +…the macro is tagged with Wand (the engine recognized `/cast Wand` +on line 1; our additional pattern is only consulted when the engine +didn't find any of its own patterns). -```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. - -``` -itemID = C_Container.PlayerHasHearthstone() -``` - -```lua -if C_Container.PlayerHasHearthstone() then - -- player can hearth -end -``` - -**Match logic.** An item counts as a hearthstone if **either**: -1. Its itemID is `6948` (the vanilla Hearthstone — fast path, no - cache lookup needed), **or** -2. Its on-use spell is spell `8690` (the "Hearthstone" cast itself). - -Rule 2 lets custom servers (Turtle WoW, etc.) ship reskinned -hearthstone items with different itemIDs and still have them -recognized — as long as their on-use is the Hearthstone spell. -The return is the **actual matched itemID**, not a hardcoded -constant, so code that wants to do something with the found id -(`SetItemRef` for chat-linking, `GetItemInfo` for the item's -name, etc.) gets the right value for any variant. - -> **Cache dependency for rule 2.** The on-use-spell check requires -> the item's `ItemStats_C` record to be in the local cache. Items -> currently in the player's bags are always cached (the engine -> pre-fills the cache during bag sync), so the check is reliable -> for this code path. The fallback to rule 1 (vanilla itemID -> equality) covers the moment-of-login window before the cache is -> fully populated. - -Walks bags 0..4 via the same chain -[`C_Container.GetContainerItemID`](#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 and hands the resulting `CGItem *` pointer -to the engine's by-pointer use primitive at `0x005D8D00` — the same -fallback path `Script_UseContainerItem` ends up at after every special -cursor-mode branch (repair vendor, spell-cast targeting, drop-on-bag) -is skipped. Bypassing the dispatcher avoids the Lua-stack roundtrip -of pushing `(bag, slot)` only for `Script_UseContainerItem` to re-parse -and re-resolve the same item. - -Equivalent to the function of the same name introduced in 9.0. - -### `C_Item.UseItemByName(itemInfo)` - -Finds the first item in the player's bags matching `itemInfo` and -uses it. Returns nothing; silently no-ops when: - -- the input is `nil`, an empty string, or otherwise unparseable -- no matching item is in bags -- the engine refuses the use — cooldown, locked item, level - requirement, etc. - -`itemInfo` accepts the same shapes as -[`C_Item.EquipItemByName`](#c_itemequipitembynameiteminfo--dstslot) — -itemID number, bare `"item:N"` string, full chat link, or a localized -item name. Name matches are case-insensitive against the cached -`m_name[0]`. - -```lua -C_Item.UseItemByName("Hearthstone") -- hearth home -C_Item.UseItemByName(6948) -- same thing, by ID -C_Item.UseItemByName("Major Healing Potion") -``` - -Mirrors 3.3.5's `Script_UseItemByName` structure: locate the item -directly, then hand the `CGItem *` to the engine's by-pointer use -primitive at `0x005D8D00`. That primitive dispatches internally based -on item type (food, potion, on-use spell, scroll, quiver, ...) so a -single call covers every item category. We skip -`Script_UseContainerItem` entirely — its branches for repair vendor, -spell-cast targeting, and drop-on-bag cursor modes don't apply to an -addon-issued call from a clean cursor. - -For target-required items (scrolls, traps), the engine reads -cursor-target state at call time, which a Lua-side caller can pre-set -with `TargetUnit("...")`. For self-use items (hearthstone, potions, -food) the engine substitutes the player even if a different target is -present, so no pre-setup is needed. - -Equivalent to the function of the same name introduced in 3.x. - -## Action - -### `GetActionInfo(slot)` - -Returns the action descriptor for a 1-based action-bar slot, in the -shape `actionType, id, subType`. Returns `nil` for empty slots. - -```lua -local actionType, id, subType = GetActionInfo(1) -``` - -| Slot contents | Returns | -|---------------------------|------------------------------------| -| empty | `nil` | -| spell | `"spell", spellID, "spell"` | -| macro | `"macro", macroSlot` | -| item (by-itemID) | `"item", itemID` | -| item (by bag-instance) | `"item", nil` | - -The 120-slot action table at `0x00BC6980` packs each entry as a -`uint32` where the top 4 bits are the type tag: - -- **`0x0` — spell action.** Entry is the spellID. The third return is - always `"spell"` for entries on this table; the engine helper - hardcodes pet flag to 0 here. Pet-bar actions live in a separate - table — use `PetHasActionBar` + the pet-action helpers for pet - slots. -- **`0x4` — macro or bag-item.** Ambiguous tag, disambiguated by - walking the 36-entry macro-slot map at `0x00BDCC60` and checking - whether `entry & 0xBFFFFFFF` matches any of those macro IDs. On a - hit, the slot is a macro and the matching index becomes the - 1-based `macroSlot` return. On a miss, the slot is a bag-item - reference; we surface the type as `"item"` but return `nil` for - the `id` — extracting the itemID from the bag-action hash struct - needs more reversing than we've done. -- **`0x8` — item by itemID.** `entry & 0x7FFFFFFF` is the itemID. - -This is the same discrimination [SuperWoWhook][superwowhook] uses in -its replacement of `GetActionText` (which returns `name, type, id`). -Without SuperWoWhook the engine's stock `GetActionText` only handles -items in bags; ClassicAPI's `GetActionInfo` provides the modern-WoW -shape independently of any other DLL patches. - -Equivalent to the function of the same name in retail. Subtype is -always `"spell"` for spell entries (no pet differentiation on this -table) and the bag-item itemID path is currently incomplete — see -the comment in [src/action/Info.cpp](../src/action/Info.cpp). - -[superwowhook]: https://github.com/balakethelock/SuperWoW +Macro tagging happens at macro edit/save time. Existing macros need +to be opened in the Macro UI and re-saved once after dropping in the +new DLL to pick up the new parser behavior. ## MerchantFrame @@ -3214,299 +3406,1593 @@ disable the sell-all-junk button; vanilla has no such setting, so the feature is always on. Function exists so retail addons that gate `SellAllJunkItems` on this don't no-op silently. -## EquipmentSet +## NameCache -Backports the modern `C_EquipmentSet.*` namespace on top of a -client-side persistent store. Vanilla 1.12 had no equipment-set -functionality at all (Blizzard introduced it in 3.1.2 as -`SaveEquipmentSet` etc., then namespaced it into `C_EquipmentSet` in -Legion) — and even when it shipped natively, the data lived -server-side, synced via `SMSG_EQUIPMENT_SET_LIST`. Vanilla servers -don't speak that opcode and won't ever, so each character's sets are -kept in a per-character file under `WTF\Account\...`. The format -matches what `VanillaMinimapTracking` does for its tracking config. +GUID-keyed cache of player names and classes. The engine itself +maintains an in-memory `NameCache` at `0x00C0E228`, populated by +`SMSG_NAME_QUERY_RESPONSE` — but vanilla doesn't expose it to Lua, +and it doesn't survive `/reload`. This module surfaces it as +`GetPlayerInfoByGUID`, adds an opt-in **persistent** layer that +survives `/reload` and full client restarts, and (separately +toggleable) sweeps the engine's visible-object list to populate +entries the SMSG path would never reach on its own. -### Overview & file format +Two toggles, each independent: -Sets are stored in -`WTF\Account\\\\ClassicAPI_EquipmentSets.txt` -in a line-oriented, human-readable format: +- **`C_PlayerCache.SetEnabled`** — turn on the on-disk cache. + Off by default. Without this, the module is read-only against + the engine's transient in-memory cache. +- **`C_PlayerCache.SetScanEnabled`** — turn on the visible-object + sweep. Off by default. Requires the on-disk cache to be enabled + to have any effect. -``` -# ClassicAPI Equipment Sets v1 -set 1 - name=Tanking - icon=INV_Shield_06 - slot 1 guid=0x0000000040000123 - slot 2 ignored - slot 5 guid=0x0000000040000789 -set 2 - name=Healing - icon=Spell_Holy_HolyBolt - ... -``` +Three population sources feed the cache when fully enabled: -Identity is by **item GUID**, snapshotted at `CreateEquipmentSet` / -`SaveEquipmentSet` time. `UseEquipmentSet` searches every player-owned -container for those GUIDs and dispatches pickup→equip pairs for items -that aren't already where they belong. The search reads the -underlying GUID arrays directly (same trick `C_Item.GetItemCount` -uses for its `includeBank=true` path), so bank items resolve **even -without the bank window being open** — the bank gate at -`VAR_BANK_GATE_GUID` only suppresses `GetItemBySlot`, not the -underlying data. +1. **`SMSG_NAME_QUERY_RESPONSE` hook** (always active when the + on-disk cache is on). Every name-query response the engine + processes is mirrored to disk. Covers chat, group/raid sync, + guild updates, visible-object resolution — anything the engine + itself issues a name query for. +2. **`C_PlayerCache.RememberPlayer`** (always available, no-op + when the cache is off). Lets addons feed in sources the engine + never sees: `/who` results, etc. +3. **Visible-object sweep** (active when both toggles are on). + Walks the engine's live visible-object list every ~10 seconds + on the `Frame::RegisterEvent` hook, resolving each player and + feeding name + class. Picks up nearby players whether or not + the engine ever queried them. -One limitation worth knowing about: +Storage: -- **Equipping from the bank** is not supported by vanilla's protocol - — `UseEquipmentSet` skips bank items rather than try and fail. - Retrieve the items first, then re-run. +- `WTF\Account\\ClassicAPI.txt` — account-level settings + (`PersistentNameCacheEnabled`, `NameCacheScanEnabled`). +- `WTF\Account\\\ClassicAPI_NameCache.txt` — + per-realm cache. Tab-separated text, ~30 bytes/entry, + hand-editable. Shared across all characters on the same + account+realm (a 50-character bank alt's chat scraping doesn't + double the storage cost). -Modern's signatures take a numeric `iconFileID`; we accept icon path -strings (e.g. `"INV_Shield_06"`) since vanilla has no fileDataID -system. Same string-or-default fallback semantic as 4.3.4 native. +### `GetPlayerInfoByGUID(guid)` -Cap is **10 sets per character**, matching 4.3.4. The full list re- -serializes on every mutation; a corrupted file is harmless (parse -errors leave the in-memory list empty and the next save rewrites the -file from scratch). - -> Note: this is a **fresh client-side namespace**, not a polyfill of -> some specific Blizzard build's behavior. The shape mirrors Classic -> Era 1.15.x's `C_EquipmentSet.*` where it can, but anything that -> requires server-side state (cross-character sharing, the -> "Equipment Manager" specialization tab) isn't supported. - -### `C_EquipmentSet.CanUseEquipmentSets()` - -Returns `true` unconditionally. Vanilla has no banker/feature gate -on equipment-set storage; we ship the feature for every character. -Equivalent to Classic Era's behavior. - -### `C_EquipmentSet.GetNumEquipmentSets()` - -Returns the count of sets stored for the current character. Loads -the file on first call after login. - -### `C_EquipmentSet.GetEquipmentSetIDs()` - -Returns a numeric-keyed table of every setID in storage order -(insertion-order; not alphabetical). Empty table when nothing's -saved. - -### `C_EquipmentSet.GetEquipmentSetID(name)` - -Returns the numeric setID for a set with the given name, or `nil` if -no set by that name exists. Names are exact (case-sensitive, no -trimming). - -### `C_EquipmentSet.GetEquipmentSetInfo(setID)` - -Returns the nine values modern ships: - -``` -name, icon, setID, isEquipped, -numItems, numEquipped, numInInventory, numMissing, numIgnored -``` - -`isEquipped` is `true` when every resolvable item in the set is in -its target slot (missing items don't disqualify — useful so a set -that includes a bank-stored cloak still shows as equipped after you -swap in the rest). `numItems` excludes ignored slots; `numIgnored` -counts them separately. Returns nothing for an unknown setID. - -### `C_EquipmentSet.GetIgnoredSlots(setID)` - -Returns a numeric-keyed table of slot indices (1..19) that the set -has flagged ignored. Empty table when no slots are ignored. Ignored -slots are recorded **per-set at save time**, by reading the global -`IgnoreSlotForSave` state — not retroactively editable on a saved set. - -### `C_EquipmentSet.GetItemIDs(setID)` - -Returns a hash table `{ [slot] = itemID }` for every set slot whose -item is currently resolvable. Missing items (GUID stored but client -can't find a CGItem) are omitted because vanilla doesn't keep an -itemID separate from the live CGItem record. - -### `C_EquipmentSet.GetItemLocations(setID)` - -Returns a hash table `{ [slot] = locationCode }`. Location codes use -the same bit-packed encoding Blizzard's FrameXML -`EquipmentManager_UnpackLocation` decodes (constants in -`Blizzard_FrameXMLBase/Classic/Constants.lua`): - -| Bit/field | Meaning | -|-----------|---------| -| `0x00100000` (PLAYER) | Item is in a player slot (equipped or in a player bag) | -| `0x00200000` (BAGS) | Item is inside a bag (player or bank) | -| `0x00400000` (BANK) | Item is in the bank (main or bank bag) | -| bits 0..7 | Slot (1-based) within the container | -| bits 8..15 | Bag index — present only when BAGS bit is set | - -PLAYER and BANK are **mutually exclusive** in the encoding (the -unpack uses `if player elseif bank`). Bank bags subtract 4 from the -bagID before storing so the field fits cleanly; unpack reverses this -to give back bag IDs 5..10. Composition: - -| Location | Bits | Example | -|----------|------|---------| -| Equipped (paperdoll slot 1..19) | `PLAYER | slot` | `0x100007` = legs (slot 7) | -| Backpack / player bag 1..4 | `PLAYER | BAGS | (bag<<8) | slot` | `0x300205` = bag 2 slot 5 | -| Main bank slot 1..28 | `BANK | slot` | `0x400003` = bank slot 3 | -| Bank bag 5..10 | `BANK | BAGS | ((bag-4)<<8) | slot` | `0x600101` = bank bag 5 slot 1 | - -Special values returned in the table entry: -- `1` — slot is ignored (`GetIgnoredSlots` lists these) -- `-1` — item is missing (was in the set, can't find now) - -The packed codes pass cleanly through Blizzard's -`EquipmentManager_UnpackLocation` if you want to use the -shared-FrameXML helpers in your addon UI. - -### `C_EquipmentSet.CreateEquipmentSet(name [, icon])` - -Snapshots the player's currently-equipped items into a new set and -returns its setID. Honors `IgnoreSlotForSave` — slots flagged ignored -at call time get the ignored marker instead of the equipped item's -GUID. - -Returns the new setID on success. Returns nothing if: -- the name is empty or already in use -- the cap of 10 sets is reached - -`icon` defaults to `"INV_Misc_QuestionMark"` if omitted. - -### `C_EquipmentSet.SaveEquipmentSet(setID [, icon])` - -Overwrites an existing set's contents with the player's currently- -equipped items. Same ignored-slot handling as `CreateEquipmentSet`. -If `icon` is provided it replaces the set's previous icon; otherwise -the icon is left unchanged. - -### `C_EquipmentSet.ModifyEquipmentSet(setID, newName)` - -Renames an existing set. Fails silently if the new name is empty, -already in use by a different set, or the setID doesn't exist. - -### `C_EquipmentSet.DeleteEquipmentSet(setID)` - -Removes the set. SetIDs are not reused — the next `Create` call -allocates one higher than any seen. - -### `C_EquipmentSet.IgnoreSlotForSave(slot)` / `UnignoreSlotForSave` / `IsSlotIgnoredForSave` / `ClearIgnoredSlotsForSave` - -Global "skip this slot the next time `CreateEquipmentSet` or -`SaveEquipmentSet` runs" state, indexed by 1-based slot (1..19). -Persists for the rest of the session; not written to the WTF file. -Use it when building a set that should leave (say) the tabard slot -free — set the ignore flag, then call `CreateEquipmentSet`, then -optionally `ClearIgnoredSlotsForSave()` afterward. - -### `C_EquipmentSet.EquipmentSetContainsLockedItems(setID)` - -Returns `true` if any item in the set is currently flagged "locked" -by the engine — a pending pickup or use is in flight that -`UseEquipmentSet` would race with. Reads bit 2 (`0x04`) of -`ITEM_FIELD_FLAGS` for each resolvable item in the set. - -### `C_EquipmentSet.UseEquipmentSet(setID)` - -Walks the set and dispatches one **atomic server-side swap** per item -that isn't already in its target slot. Items in the bank are skipped -silently (vanilla can't equip from bank). Missing items are skipped -silently. Returns `true` if the call ran (the set existed), `false` -otherwise. - -Implementation uses the same `FUN_INVENTORY_SWAP` primitive -[`C_Item.EquipItemByName`](#c_itemequipitembynameiteminfo--dstslot) -uses for its explicit-slot path. Each swap is a single -CMSG_SWAP_INV_ITEM (or CMSG_AUTOEQUIP_ITEM) packet that the server -applies atomically — the two-cycle "ring A in slot 11, ring B in -slot 12, set swaps them" case resolves in one packet because the -opcode swaps both slots in a single server transaction. The cursor -is never touched; an item held on the cursor when -`UseEquipmentSet` is called stays on the cursor. - -Longer dependency chains (3+ items rotating) are rare with 1.12's -slot set — the realistic conflicts are paired slots (rings 11/12, -trinkets 13/14, weapons 16/17), all 2-cycles. - -> **`CURSOR_UPDATE` fires per item moved.** The engine's swap -> primitive (`FUN_005E0C40`) runs a generic cursor-state cleanup at -> the end of each call, which fires `CURSOR_UPDATE` regardless of -> whether the cursor was actually touched. So one -> `UseEquipmentSet` call that moves N items will fire N -> `CURSOR_UPDATE` events in quick succession. Addons that react to -> `CURSOR_UPDATE` (cursor-attached tooltips, drag-state tracking) -> should debounce — or check `CursorHasItem()` before doing work — -> since most of those fires won't reflect a real cursor change. -> This is engine behavior, not a bug in the implementation; the -> old cursor-based path actually fired more (one per pickup, one -> per equip, one per cursor-clear). - -### `EQUIPMENT_SETS_CHANGED` event - -Fires (with no payload) after any mutation: `Create`, `Save`, -`Modify`, `Delete`, and the four `*IgnoredSlot*` calls. Addon UI -should re-read its set list / button state when this fires. - -### `EQUIPMENT_SWAP_PENDING` event - -Fires with a single payload arg — `setID` — at the **start** of -`UseEquipmentSet`, right after the set-exists check passes and -before any pickup/equip work begins. Modern addons use this to -gate "swap in progress" UI state (grey out the set button, show -a spinner, etc.) until `EQUIPMENT_SWAP_FINISHED` arrives. - -Doesn't fire if `UseEquipmentSet` is called with an unknown -setID — in that case only `EQUIPMENT_SWAP_FINISHED(false, setID)` -fires. - -### `EQUIPMENT_SWAP_FINISHED` event - -Fires at the end of every `UseEquipmentSet` call with two payload -args: `success` (1 if the set existed and we dispatched the swap, 0 -if the setID was unknown) and `setID`. Note this is "we ran the -dispatch" success — not "every item ended up in its target slot." -Items that were in the bank or that couldn't complete a swap cycle -in one pass still report success=1. Listen for this if you want to -re-paint the character pane / refresh tooltips after a swap. - -## Class - -### `FillLocalizedClassList(table [, isFemale])` - -Fills the passed-in table with `[classToken] = localizedClassName` -pairs for every class in `ChrClasses.dbc`, and returns the same -table for chaining. - -The table is mutated in place. Existing keys are overwritten; -unrelated keys are preserved. +Returns +`localizedClass, englishClass, localizedRace, englishRace, sex, name, realm` +for a player GUID the engine has cached, or `nil` on a cache miss. ```lua -local classes = FillLocalizedClassList({}) --- classes.WARRIOR = "Warrior" --- classes.MAGE = "Mage" --- classes.PRIEST = "Priest" --- ... +local _, class, _, race, sex, name = GetPlayerInfoByGUID(UnitGUID("target")) +-- e.g. "WARRIOR", "NightElf", 2, "Sylphir" + +GetPlayerInfoByGUID("0x0000000000000777") -- same shape for a literal GUID ``` -Modern API supports an optional `isFemale` boolean to fetch female- -form names. Vanilla 1.12 has no separate female-name array in -`ChrClasses.dbc` — `Name[9]` (one localized string per locale) -sits exactly between offsets `+0x14` and `+0x38`, with the class -token immediately after, leaving no room. The arg is accepted for -signature parity but ignored; the same names are returned either way. -Most locales (English included) wouldn't differentiate the two -anyway, so callers won't typically notice. +`guid` is the `"0xHHHHHHHHLLLLLLLL"` string returned by `UnitGUID`. +Bare 8-hex `"0xLLLLLLLL"` (hi-dword zero) is also accepted. -Sparse class IDs (vanilla skips classID 6 — Death Knight didn't -exist yet — and a few others) have NULL records and are silently -skipped. +Returns: + +| 1 `localizedClass` | `"Warrior"` / `"Krieger"` etc. — from `ChrClasses.dbc` indexed by locale. | +| 2 `englishClass` | `"WARRIOR"` (uppercase tag, same value `UnitClass` returns as 2nd return on modern clients) — `ChrClasses.dbc` filename field. | +| 3 `localizedRace` | `"Human"` / `"Mensch"` / `"Humain"` etc. — from `ChrRaces.dbc` indexed by locale. | +| 4 `englishRace` | `"Human"`, `"Orc"`, `"Dwarf"`, `"NightElf"`, `"Scourge"` (vanilla's filename for what addons call Undead), `"Tauren"`, `"Gnome"`, `"Troll"` — from `ChrRaces.dbc` filename field. | +| 5 `sex` | `2` = male, `3` = female. Matches `UnitSex` convention (the cache stores `0`/`1`; we add `2`). | +| 6 `name` | Character name. | +| 7 `realm` | Realm name. Single-realm in vanilla, so usually the local realm. | + +**Cache coverage**: the engine populates entries from +`SMSG_NAME_QUERY_RESPONSE`. Anything the client has already seen +populates the cache: chat (whispers, says, party chat), raid/group +events, guild updates, visible objects (target, party, raid in +zone). Names of offline friends never seen in chat are *not* +cached — `GetPlayerInfoByGUID` returns `nil` for them until the +client does something that triggers a name query. This module +deliberately does not trigger queries from a passive getter; a +future `C_PlayerInfo.RequestLoadPlayerByID` would do that +explicitly and fire a load-result event. + +**Persistent fallback**: when +[`C_PlayerCache.SetEnabled(true)`](#c_playercachesetenabledenabled) +has been opted into, a per-realm on-disk cache extends coverage +across sessions. On engine cache miss, `GetPlayerInfoByGUID` falls +back to the persistent cache and returns `name`, `class`, `race`, +and `sex` from storage (`realm` comes back as `""` since vanilla +is single-realm and we don't carry per-player realm names). +Returns `nil` only when both the engine and persistent caches miss. + +**Implementation**: calls the engine's get-or-fetch primitive at +`0x0055F080` with a NULL callback (pure cache read). The cache +instance lives at `0x00C0E228`; entry layout (name, realm, race, +sex, class) was reverse-engineered from the +`SMSG_NAME_QUERY_RESPONSE` write path at `0x0055F310`. + +### `C_PlayerCache.GetPlayerInfoByName(name)` + +Returns +`localizedClass, englishClass, localizedRace, englishRace, sex, name, realm, guid` +for a player in the persistent NameCache, or `nil` if the name +isn't cached. Companion to `GetPlayerInfoByGUID` for the case where +an addon has a player's name but not their GUID — e.g., when +`GetCurrentChatGUID()` returns nil for a chat event the engine +didn't tag with the sender GUID (system notifications, some channel +messages, etc.). + +```lua +local _, class, _, race, _, _, _, guid = C_PlayerCache.GetPlayerInfoByName("Gedwyr") +-- "MAGE", "Human", "0x000000003B9ADAA7" + +C_PlayerCache.GetPlayerInfoByName("NeverSeen") -- nil (not cached) +``` + +Match is **case-sensitive, exact** — vanilla server-stored names +are case-stable (`"Gedwyr"` won't match `"gedwyr"`). + +Returns (vs. `GetPlayerInfoByGUID`): + +| Slot | Value | Notes | +|------|-------|-------| +| 1–7 | same as `GetPlayerInfoByGUID` | see above | +| 8 | `guid` | `"0xHHHHHHHHLLLLLLLL"` — the cached player's full GUID, so name-based callers can chain into GUID-keyed APIs. Absent from `GetPlayerInfoByGUID` since the caller already has it. | + +Only reads from the **persistent NameCache** — does *not* hit the +engine's in-memory NAME_QUERY cache (that's keyed by GUID and has +no name index). So this requires `C_PlayerCache.SetEnabled(true)` +to have been opted into; entries get there via the engine's +NAME_QUERY response hook, the visible-object scan, and +`C_PlayerCache.RememberPlayer`. + +**Implementation**: O(1) lookup via a `name → guid` index map +maintained in lockstep with the GUID-keyed entry map. Eviction +keeps the index consistent: when a name's character is deleted and +the name is recycled to a different GUID, the prior entry is +removed from both maps. + +### `C_PlayerCache.RememberPlayer(guid, name, classToken)` + +Adds a `(guid → name, classID, raceID, sex)` entry to the persistent +name cache. For the engine-driven coverage (chat / group / guild / +visible objects), no addon-side feeding is needed — those flow into +the cache automatically through the engine's +`SMSG_NAME_QUERY_RESPONSE` write path. This call exists for the +*other* sources libunitscan-style addons harvest from but the engine +NameCache doesn't see directly: `/who` results, mouseover, target +snapshots, etc. + +``` +C_PlayerCache.RememberPlayer(guid, name, classToken [, raceToken [, sex]]) +``` + +Returns `true` on success, `false` if the persistent cache isn't +enabled or the required args are malformed. + +- `guid` — `"0xHHHHHHHHLLLLLLLL"` string (same format `UnitGUID` + returns). 8-hex `"0xLLLLLLLL"` is also accepted (hi-dword zero). +- `name` — 1–12 ASCII chars (vanilla character-name range). Tabs, + newlines, and high bytes are stripped. +- `classToken` — uppercase token like `"WARRIOR"`, `"MAGE"`. Looked + up against `ChrClasses.dbc` filename field, case-insensitive. + Passing an unknown token keeps the entry's prior class (so a + name-only sighting doesn't erase good class data). +- `raceToken` *(optional)* — uppercase token like `"NIGHTELF"`, + `"SCOURGE"` (vanilla's filename for Undead). Same resolution as + classToken, against `ChrRaces.dbc`. Omitted/unknown → leaves + prior race alone. +- `sex` *(optional)* — `0` (male) or `1` (female), matching the + wire-format convention the engine cache stores. Modern WoW's + `UnitSex` uses `2`/`3`; pass `UnitSex - 2` if you're forwarding + that value. Omitted/`0` → leaves prior sex alone (so this call + can't be used to flip a stored value back to male; the + `SMSG_NAME_QUERY_RESPONSE` hook handles direct assignment). + +```lua +-- Harvest /who results into the persistent cache +local function OnWhoUpdate() + for i = 1, GetNumWhoResults() do + local name, _, _, _, class, _, _, _, _, _, _, sex = GetWhoInfo(i) + -- class/race come back localized from GetWhoInfo; the + -- locale-token tables in pfUI/AceLocale handle the + -- inverse mapping. RememberPlayer expects engine tokens + -- ("WARRIOR" etc.). + end +end +``` + +Each non-zero field is updated on the existing entry; zeros are +treated as "caller doesn't know" and preserve prior real data. A +`name`-only update (classToken passed but unknown) refreshes the +name without erasing class. + +The "deleted character recreated with same name, different class" +collision case that name-keyed caches suffer from doesn't apply +here: GUIDs are permanent for the life of a vanilla character, so +the new character has a different GUID and gets a different cache +entry. + +### `C_PlayerInfo.GUIDIsPlayer(guid)` / `GUIDIsCreature` / `GUIDIsPet` / `GUIDIsGameObject` + +Type checks on the raw 1.12 GUID format. Vanilla GUIDs encode the +entity type in the high 16 bits of the qword — players have +`0x0000` (low dword = player ID), creatures `0xF130xxxx`, pets +`0xF140xxxx`, game objects (herbs / chests / etc.) `0xF110xxxx`, +items `0x4000xxxx`. Each function returns `true` only for its +specific prefix; the `"0x0000000000000000"` sentinel returns +`false` from all four. + +```lua +if C_PlayerInfo.GUIDIsPlayer(UnitGUID("target")) then + -- target is a player +end + +-- Combat-log row triage: was that a player kill or a mob kill? +local function OnCombatLogEvent(_, _, eventType, srcGUID, ...) + if eventType == "PARTY_KILL" then + if C_PlayerInfo.GUIDIsPlayer(srcGUID) then ... end + end +end +``` + +`GUIDIsPlayer` matches modern WoW's signature exactly; the other +three are companions for the most common type-distinction needs. +For other types (corpse, dynamic object, transport, item) the +underlying classifier exists internally — let us know if you need +one exposed. + +Accepts either the 16-digit `"0xHHHHHHHHLLLLLLLL"` form or the +8-digit `"0xLLLLLLLL"` shortcut (high dword implicitly zero). +Malformed input returns `false` rather than raising — matching +modern's tolerance for stale GUIDs from addon-side caches. + +### `C_CreatureInfo.GetCreatureID(guid)` + +Extracts the creature template / NPC ID from a unit GUID. Vanilla +1.12 packs the entry ID directly into bits 24-47 of the 64-bit +GUID for the types that carry one; this function does the shift +and mask so addons don't have to. + +```lua +C_CreatureInfo.GetCreatureID(UnitGUID("target")) -- 1842 for Hogger +C_CreatureInfo.GetCreatureID(UnitGUID("pet")) -- pet's creature template ID +C_CreatureInfo.GetCreatureID(UnitGUID("player")) -- nil (no entry on players) +``` + +Accepts creature GUIDs (`0xF130xxxx…`) and pet GUIDs +(`0xF140xxxx…`). Returns `nil` for: +- non-string input or malformed GUIDs +- player GUIDs — the low 32 bits hold a player ID, not a template +- game-object / dynamic-object / corpse / item GUIDs — modern's + `C_CreatureInfo` doesn't surface entry IDs for these even though + the bits are in the same range; addons that need them can shift + the raw GUID themselves (`(guid >> 24) & 0xFFFFFF`) +- entry IDs of 0 — the engine never assigns 0; treated as "no info" + +The standard 16-digit (`"0xHHHHHHHHLLLLLLLL"`) and 8-digit +(`"0xLLLLLLLL"`) GUID-string forms are both accepted, same as +`C_PlayerInfo.GUIDIs*` above. + +### `C_PlayerCache.SetEnabled(enabled)` + +Opts into (or out of) the persistent name cache. `enabled` is a +boolean (numeric `0`/`1` also accepted). Persists to +`WTF\Account\\ClassicAPI.txt` as +`PersistentNameCacheEnabled=1`/`0`, so the choice survives +client restarts. + +When enabled: + +- Every `SMSG_NAME_QUERY_RESPONSE` the engine processes is also + written to `WTF\Account\\\ClassicAPI_NameCache.txt`. +- Lua-side `C_PlayerCache.RememberPlayer` calls become effective + (they're no-ops when the cache is disabled). +- `GetPlayerInfoByGUID` gains the cross-session fallback path + documented above. +- [`SetScanEnabled`](#c_playercachesetscanenabledenabled) + becomes effective if also turned on. + +When disabled, the on-disk file is left in place (re-enabling later +restores the prior contents); future writes are simply suppressed. + +```lua +C_PlayerCache.SetEnabled(true) +``` + +Returns nothing. + +### `C_PlayerCache.IsEnabled()` + +Returns the current state of the persistent name cache as a +boolean. `false` until +[`SetEnabled`](#c_playercachesetenabledenabled) +has been called (or its prior call survived in the on-disk settings +file). + +```lua +if C_PlayerCache.IsEnabled() then + -- persistent fallback is active for GetPlayerInfoByGUID +end +``` + +### `C_PlayerCache.SetScanEnabled(enabled)` + +Opts into the **visible-object sweep**: an opportunistic walk of +the engine's live visible-object list that feeds every player in +render range (whose object is currently loaded by the client) into +the persistent name cache. Throttled to once per ~10 seconds, on +the existing `Frame::RegisterEvent` hook — no per-frame overhead, +no extra hooks installed. + +`enabled` is a boolean (numeric `0`/`1` also accepted). Persists to +`WTF\Account\\ClassicAPI.txt` as +`NameCacheScanEnabled=1`/`0`. + +```lua +C_PlayerCache.SetEnabled(true) -- prerequisite +C_PlayerCache.SetScanEnabled(true) +-- Now: standing in Stormwind for a minute pre-populates the cache +-- with every visible player's name and class. +``` + +**Independent of the cache toggle.** Turning this on alone has no +effect — the sweep relies on `Remember()` which silently no-ops +when the on-disk cache is disabled. Turning the cache off (without +also turning the scan off) preserves the scan setting for the next +time you re-enable the cache. + +**Players only.** NPCs and pets aren't cached — their GUIDs are +ephemeral and can get reused across sessions, so caching them is +worse than useless. + +**Implementation**: walks `ClntObjMgrEnumVisibleObjects` +(`0x00468380`) — the same engine iterator +[VanillaMinimapTracking](https://github.com/Brues/VanillaMinimapTracking) +uses for blip rendering — filtering each GUID through +`ClntObjMgrObjectPtr` (`0x00468460`) with `TYPEMASK_PLAYER`. Name +comes from the CGObject vftable's `GetName` slot; class is the +byte at `[m_objectFields + 0x79]` (UNIT_FIELD_BYTES_0 byte 1, same +field `Script_UnitClass` reads). + +### `C_PlayerCache.IsScanEnabled()` + +Returns the current visible-object scan setting as a boolean. +Independent of the cache toggle — this only reflects the scan- +specific setting, not whether the scan is *effectively* running +(which also requires the cache to be on). + +```lua +if C_PlayerCache.IsScanEnabled() + and C_PlayerCache.IsEnabled() then + -- visible-object sweeps are running every ~10s +end +``` + +## Quest + +### `C_QuestLog.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 = C_QuestLog.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. + +## 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. +### `IsUsableSpell(spell)` / `IsUsableSpell(slot, bookType)` + +Returns `(usable, noMana)` for a spell, matching the modern +3.0+ signature. Returns `(1, nil)` when the spell is castable, +`(nil, 1)` when only mana is preventing it, `(nil, nil)` for any +other reason (unknown spell, dead, etc.). Matches the `1`/`nil` +return convention of the existing `Script_IsUsableAction`. + +Two arg shapes accepted: + +- **`IsUsableSpell(spellID)`** — direct spellID lookup. +- **`IsUsableSpell(slot, bookType)`** — `bookType` is `"spell"` + (player) or `"pet"`. Resolves to a spellID via the same engine + spellbook arrays `GetSpellInfo`/`GetSpellLink` walk. + +```lua +IsUsableSpell(133) -- Fireball: 1, nil if you have mana, nil, 1 if not +IsUsableSpell(1, "spell") -- player spellbook slot 1 +``` + +> **What this function checks:** +> +> 1. Player knows the spell (engine's spell-knowledge bitmap — +> covers trained class abilities, talent passives, racials, +> profession recipes). +> 2. Player is alive (HEALTH > 0). +> 3. Spell is not on cooldown (engine's per-spell cooldown helper). +> 4. Player has enough of the spell's power type for the base cost +> (mana / rage / focus / energy / happiness) — *only* this +> failure sets `noMana=true`. +> 5. Player has all required reagents in bags (Spell.dbc +> Reagent[8] / ReagentCount[8]). +> +> **What this function doesn't check** (different concerns or +> post-vanilla concepts): silence, GCD, stance/form, range, target +> type, line-of-sight, casting state. +> +> Verified empirically on Turtle WoW for the mana branch: Renew rank +> 3 (cost 105) is reported usable at 144 mana and unusable at 39 +> mana, transitioning at exactly the cost boundary. Cooldown and +> reagent checks ship in the same implementation but haven't been +> exercised in-game; if you find an inconsistency, the reagent +> offsets (+0x110 / +0x130) and cooldown helper (`0x006E2EA0`) are +> the components to verify. + +Equivalent to the function of the same name introduced in 3.0. + +### `C_Spell.IsSpellUsable(spellID)` + +Modern table-namespace form. Same logic as +[`IsUsableSpell(spellID)`](#isusablespellspell--isusablespellslot-booktype) +but returns proper booleans (`isUsable`, `insufficientPower`) per +the `C_Spell.*` convention rather than `1`/`nil` pairs. + +```lua +local usable, noMana = C_Spell.IsSpellUsable(133) +-- usable=true, noMana=false → cast it +-- usable=false, noMana=true → drink up +-- usable=false, noMana=false → unknown spell, dead, or other block +``` + +Equivalent to the function of the same name introduced in 10.x. + +### `C_Item.GetWeaponEnchantInfo()` + +Returns the modern 12-tuple matching WotLK+'s extended +`GetWeaponEnchantInfo` signature, including the **temp-enchant IDs** +that vanilla 1.12's 8-return global omits. + +``` +hasMain, mainExpire, mainCharges, mainEnchantID, +hasOff, offExpire, offCharges, offEnchantID, +hasRanged, rangedExpire, rangedCharges, rangedEnchantID + = C_Item.GetWeaponEnchantInfo() +``` + +```lua +-- Apply Brilliant Mana Oil to mainhand, then: +local has, expireMs, charges, enchantID = C_Item.GetWeaponEnchantInfo() +-- has = true, expireMs ≈ 1800000, charges = 5, enchantID = +``` + +Reads the **temporary** enchant slot (`ITEM_FIELD_ENCHANTMENT` +slot 1 at descriptor `+0x4C`) — the same slot oils, sharpening +stones, and poisons populate and the engine drains as they expire. +This is what modern's `GetWeaponEnchantInfo` measures. + +The permanent enchant (Crusader, Mongoose, etc., in slot 0 at +`+0x40`) is **not** reported here — that's a separate field and +modern's `GetWeaponEnchantInfo` doesn't expose it either. Get the +permanent enchant ID by parsing `GetInventoryItemLink("player", +slot)` (the link includes it as the 2nd numeric field). + +Vanilla 1.12's global `GetWeaponEnchantInfo` is unchanged — old +addons reading positions 4..8 by index still work. + +Equivalent to the extension of `GetWeaponEnchantInfo` introduced +in 3.x. + +### `IsHarmfulSpell(spell)` / `IsHelpfulSpell(spell)` + +Classify a spell as offensive (`IsHarmfulSpell`) or non-offensive +(`IsHelpfulSpell`) without parsing its tooltip. Accept either form +the spellbook-aware globals use: + +```lua +IsHarmfulSpell(spellID) -- by ID +IsHarmfulSpell(slot, "spell") -- player spellbook slot +IsHarmfulSpell(slot, "pet") -- pet spellbook slot +-- same calling shapes for IsHelpfulSpell +``` + +Examples: + +```lua +IsHarmfulSpell(133) -- true (Fireball) +IsHarmfulSpell(118) -- true (Polymorph) +IsHelpfulSpell(2061) -- true (Flash Heal) +IsHelpfulSpell(1243) -- true (Power Word: Fortitude) +IsHarmfulSpell(2061) -- false +``` + +Reads `Spell.dbc.AttributesEx` (record `+0x1C`) bit `0x80` — the +same `SPELL_ATTR_EX_NEGATIVE` bit CMaNGOS uses to mark spells as +debuffs server-side. `IsHarmfulSpell` is true iff that bit is set; +`IsHelpfulSpell` is true iff the spell exists and the bit is NOT +set. Both return `false` for invalid spellIDs. + +> Vanilla 1.12 doesn't have a dedicated "positive" flag, so the +> helpful side is the rough complement of harmful. For utility +> spells with no clear orientation (Aspect of the Cheetah, +> Stealth, ground-targeted AOEs), modern WoW sometimes returns +> false for both; we return `true` for helpful as a safer default +> for addons gating on "is this castable on me?" logic. Compute +> precise modern semantics by also inspecting effect implicit +> targets if you need them. + +Equivalent to the functions of the same name introduced in 3.x +(when WoW first exposed them as globals). + +### `C_Spell.IsSpellHarmful(spellID)` / `C_Spell.IsSpellHelpful(spellID)` + +Same classification logic as the globals above, but exposed in the +modern `C_Spell` namespace. Both take a numeric `spellID` only — +no `(slot, bookType)` form. + +```lua +C_Spell.IsSpellHarmful(133) -- true (Fireball) +C_Spell.IsSpellHelpful(2061) -- true (Flash Heal) +``` + +Equivalent to `C_Spell.IsSpellHarmful` / `C_Spell.IsSpellHelpful` +introduced in 11.x. + +### `C_SpellBook.GetSpellLevelLearned(spellID)` + +Returns the level at which a spell becomes available — the +`BaseLevel` field in `Spell.dbc` (record `+0x70`). Direct read off +the cached record; no class/race filtering. + +```lua +C_SpellBook.GetSpellLevelLearned(133) -- Fireball rank 1 → 4 +C_SpellBook.GetSpellLevelLearned(25306) -- Fireball rank 12 → 60 +C_SpellBook.GetSpellLevelLearned(2061) -- Flash Heal rank 1 → 20 +``` + +Returns `0` for invalid spellIDs, spells with no level requirement +(most non-class utility spells), or records the engine hasn't +cached. Matches modern semantics — unknown / utility spells +return 0 rather than nil. + +### `C_SpellBook.GetCurrentLevelSpells([level])` + +Returns a 1-based table of spellIDs the player's class/race can +learn at the given level. Without arguments, defaults to the +player's current level. + +```lua +C_SpellBook.GetCurrentLevelSpells() -- spells trainable at your level +C_SpellBook.GetCurrentLevelSpells(20) -- preview what's available at 20 +C_SpellBook.GetCurrentLevelSpells(60) -- preview at 60 +``` + +Walks `SkillLineAbility.dbc` filtering by the player's class bit +(`1 << (classID - 1)`) and race bit, respecting both the include +masks (entries with mask = 0 are "all classes"/"all races", which +also pass) and the exclude masks. For each surviving entry, looks +up the spell's `BaseLevel` and includes it if it matches the +queried level. + +> **Vanilla is trainer-driven.** Modern `GetCurrentLevelSpells` +> (added in 5.x when trainers were removed) returns *auto-learned* +> spells. Vanilla 1.12 requires visiting a trainer to actually +> learn most class spells. We return the closest available analog: +> **what's *trainable* at this level**. Useful for "what's new +> this level" UI panels and level-preview tooling ported from MoP+. + +Class/race come from the local player — there's no +`(class, race, level)` form because vanilla doesn't expose a +clean class-string→classID lookup. Returns an empty table at +character select / pre-login (no CGPlayer yet) and for levels +where no class/race spells match. + +### `C_SpellBook.GetSpellSkillLine(spellID)` + +Returns `(name, skillID)` — the SkillLine.dbc row that the given spell +belongs to. The name is the user-facing skill/tab string in the engine's +current locale: spellbook tab names for class spells (`"Protection"`, +`"Fire"`, `"Holy"`), profession headers (`"Tailoring"`, `"Engineering"`), +weapon-skill rows (`"Swords"`, `"Bows"`), etc. + +```lua +C_SpellBook.GetSpellSkillLine(1671) -- "Protection", 26 (Shield Bash) +C_SpellBook.GetSpellSkillLine(133) -- "Fire", 8 (Fireball) +C_SpellBook.GetSpellSkillLine(2050) -- "Holy", 56 (Lesser Heal) +C_SpellBook.GetSpellSkillLine(2480) -- "Bows", 45 (Shoot Bow) +C_SpellBook.GetSpellSkillLine(3273) -- "First Aid", 129 (Anesthetic) +``` + +Walks `SkillLineAbility.dbc` for any row whose `spellID` matches, then +reads the localized `Name[locale]` field at offset `+0x0C` of the +referenced `SkillLine.dbc` record. For spells with multiple SLA rows +(race-locked variants, Turtle WoW's faction-specific entries) the +lookup prefers a row whose class/race masks match the local player — +so the result reflects "what tab is this spell in *for me*" when one +exists. Falls back to the first matching row otherwise, so the +function still answers for spells the local player can't actually use +(inspecting other classes, parsing combat-log entries from unfamiliar +specs). + +Returns `(nil, nil)` for: +- non-numeric or non-positive input +- spellIDs with no `SkillLineAbility.dbc` row (most temporary auras, + proc-only spells, item-on-use effects, GM-debug spells) +- rows whose `skillID` doesn't resolve in `SkillLine.dbc` + +Vanilla's `GetSpellTabInfo(tabIndex)` enumerates spellbook tabs by +1-based index — it can't answer "what tab is *this spellID* in". +Addons that need a spellID→tab mapping have historically had to walk +every tab's slot range and string-match against `GetSpellName`. This +function reads it directly off the DBC for any spellID, including +spells the player hasn't learned. + +### `GetSpellSchool(spellID)` + +Returns `(schoolID, schoolName)` for any spell — known to the player +or not. `schoolID` is 1-based; `schoolName` is the locale-independent +English name. + +| schoolID | schoolName | +|---------:|------------| +| 1 | `"Physical"` | +| 2 | `"Holy"` | +| 3 | `"Fire"` | +| 4 | `"Nature"` | +| 5 | `"Frost"` | +| 6 | `"Shadow"` | +| 7 | `"Arcane"` | + +Reads directly from `Spell.dbc` record `+0x04`. Vanilla 1.12 stores +School as a single 0-based integer (no multi-school `SchoolMask` +combinations — that's a TBC+ thing), so a spell belongs to exactly +one school. + +Returns `nil` for invalid spellIDs (out of range or unpopulated +`Spell.dbc` slot). + +```lua +local id, name = GetSpellSchool(133) -- 3, "Fire" (Fireball) +local id, name = GetSpellSchool(116) -- 5, "Frost" (Frostbolt) +local id, name = GetSpellSchool(635) -- 2, "Holy" (Holy Light) +``` + +Useful for combat-log breakdown addons, dispel-eligibility checks, +resistance-aware aura libraries, and damage-meter school tagging. +Previously addons either maintained hardcoded `spellID → school` +tables or scanned tooltips for the first-line color tag. + +### `CastSpellNoToggle(name | spellID)` + +Spam-safe variant of `CastSpellByName` that won't toggle off an +already-active spell. Covers both kinds of vanilla-toggle abilities: + +- **Auto-repeat** — Shoot, Auto-Shot, Wand. Tracked via the engine's + active-auto-repeat global. +- **Self-aura toggles** — shapeshift (Cat/Bear/Travel/Moonkin/ + Shadowform), stance (Battle/Defensive/Berserker), aspect (Hunter), + seal (Paladin), blessing-on-self, etc. Tracked via the unit + descriptor's aura array. + +If either toggle is already on for the requested spell, the call is +a no-op — exactly what `/cast !SpellName` does in 2.3.2+ clients, +but expressed as a vanilla Lua call. + +| Engine state | Behavior | Return | +|-------------------------------|---------------------|---------| +| Nothing toggled | Starts the cast | `true` if the spell is now active, else `false` | +| This spell already auto-repeating | No-op | `true` | +| This spell's aura already on (form / stance / aspect) | No-op | `true` | +| A *different* auto-repeat is active | No-op | `false` (don't disrupt the other auto-repeat) | + +Replaces both the action-bar scan-and-skip pattern and the +form-already-active check: + +```lua +-- Before (auto-repeat case) +for i = 1, 120 do + if IsAutoRepeatAction(i) then return end +end +CastSpellByName("Shoot") + +-- Before (shapeshift case) +if not (UnitBuff("player", "Cat Form") or GetShapeshiftFormID() == CAT_FORM) then + CastSpellByName("Cat Form") +end + +-- After (both cases) +CastSpellNoToggle("Shoot") +CastSpellNoToggle("Cat Form") +``` + +Accepts either a name string or a spellID number: + +```lua +CastSpellNoToggle("Shoot") -- by name (matches what CastSpellByName accepts) +CastSpellNoToggle(75) -- by spellID (Auto Shot rank 1) +CastSpellNoToggle("Aspect of the Hawk") +CastSpellNoToggle("Battle Stance") +``` + +String input matches case-insensitively and tolerates a trailing +`(Rank N)` suffix the same way `CastSpellByName` itself does — +`"Shoot"` and `"Shoot(Rank 1)"` both compare equal to a Shoot that's +already auto-repeating. + +Reads `[VAR_ACTIVE_AUTO_REPEAT_SPELL]` (`0x00CEAC30`) for the auto- +repeat check, and the engine's `FUN_SPELL_IS_TOGGLE_AURA_ACTIVE` +(`0x004B36F0`) for the aura-active check. Delegates to +`Script_CastSpellByName` (`0x004B4AB0`) for the actual cast — same +resolution semantics (rank picking, target rules, etc.) as the +engine's own global. + +Using this from inside a macro action slot? See +[`CastSpellNoToggle` as a macro cast line](#castspellnotoggle-as-a-macro-cast-line) below for the additional +parser support that makes the slot tag correctly for action-bar UIs. + +## State + +Player movement / visibility state queries that modern WoW exposes +as no-arg globals. 1.12 doesn't bind them to Lua despite the engine +tracking the underlying state — broadcast in UpdateFields for some +(mount, stealth visibility), local-only for others (falling, +swimming). + +### `IsMounted()` + +Returns `true` if the player is currently mounted, `false` otherwise. + +Reads `UNIT_FIELD_MOUNTDISPLAYID` from the player's broadcast +descriptor. The field holds a creature display ID (the model the +engine renders under the player) when mounted, and `0` otherwise. + +```lua +if not IsMounted() then + CastSpellByName("Summon Dreadsteed") +end +``` + +Equivalent to the function of the same name introduced in 1.10. + +### `IsStealthed()` + +Returns `true` if the player is currently in Stealth (Rogue) or +Prowl (Druid), `false` otherwise. + +Reads bit `0x02` of the player visibility byte at descriptor +`+0x17C` and AND-gates with `MountDisplayID == 0` to disambiguate +mount (which sets the same bit). Untested for Druid shapeshift +forms — if you find a false-positive there, file an issue and we'll +switch to walking the player's aura array for the actual stealth +spell. + +```lua +if IsStealthed() then + -- defer the spell that would break stealth +end +``` + +### `IsFalling()` + +Returns `true` if the player is currently mid-jump or falling, +`false` otherwise. + +Reads the local CGPlayer movement-flags word at `+0x9E8` and tests +`MOVEFLAG_FALLING | MOVEFLAG_FALLING_FAR` (`0x2000 | 0x4000`). This +is client-side state (outbound `MSG_MOVE_*` data, never visible for +remote units), so the function only meaningfully applies to the +local player. + +```lua +if not IsFalling() then + -- safe to bind ground-targeted spell +end +``` + +### `IsSwimming()` + +Returns `true` if the player is currently swimming (in liquid, with +the swim animation/movement set), `false` otherwise. + +Same movement-flags word as `IsFalling`, testing `MOVEFLAG_SWIMMING` +(`0x200000`). Local-player only. + +```lua +if IsSwimming() then + -- breath bar logic, mount-failure suppression, etc. +end +``` + +### `IsAssistingRitual()` + +Returns `true` if the local player is currently clicking a warlock +summoning portal (the channel-on-GameObject state with no castbar +UI, where movement breaks the channel), `false` otherwise. + +This is distinct from spell channeling: the function fires for +*participants* who clicked the portal, not the warlock who cast +Ritual of Summoning. Vanilla has no Lua surface for this state — +the engine's `SPELLCAST_CHANNEL_*` events don't fire and +`CastingInfo()` returns nothing — so addons that want to react to +the player being committed to a ritual (e.g. suppress autorun +toggles, hide nameplate clicks, warn before movement) have no other +way to detect it. + +Detection uses two state slots: + +- `UNIT_CHANNEL_SPELL` (descriptor `+0x228`) — the warlock's channel + spell ID (698) is mirrored onto every clicker for the duration + of the ritual. +- A CGPlayer-local pointer at `+0xB4` — the engine's "current spell + cast target GameObject" slot, set to the portal GO while the + clicker is engaged. + +Either signal alone is ambiguous (the warlock channeling matches +the first; mining and other GO-targeted casts match the second); +the conjunction is portal-clicker-specific. + +The engine fires `SPELLCAST_CHANNEL_START` / `SPELLCAST_CHANNEL_STOP` +on the portal click, even though there's no castbar — Blizzard's +vanilla castbar UI filters out spell ID 698 (Ritual of Summoning), +but the events themselves fire normally. Combine them with this +function for ritual-specific triggers: + +```lua +local frame = CreateFrame("Frame") +frame:RegisterEvent("SPELLCAST_CHANNEL_START") +frame:RegisterEvent("SPELLCAST_CHANNEL_STOP") +frame:SetScript("OnEvent", function() + if event == "SPELLCAST_CHANNEL_START" and IsAssistingRitual() then + -- player just committed to a ritual portal + elseif event == "SPELLCAST_CHANNEL_STOP" then + -- channel ended; was it a ritual? + end +end) +``` + +Local-player only — the `+0xB4` pointer lives on the CGPlayer +object, not in the broadcast descriptor, so the function can't +report state for `target` / `party*` / etc. Returns `false` when +called before the player object is initialized (login screen). + +## Table + +### `table.wipe(t)` + +Removes every key from `t`, leaving it empty but preserving its +internal hash and array capacity. Returns `t` for chaining. + +```lua +local cache = {} +-- ... fill it up ... +table.wipe(cache) -- cache is now {} +local also_t = table.wipe(t2) -- also_t === t2 after wipe +``` + +Port of Blizzard's 3.3.5 implementation at VA `0x00852180` — same +pattern, just using 1.12's Lua 5.0 entry points instead of 5.1's. +Both Lua versions' `lua_next` walks the hash node array linearly, +so the canonical `lua_next` + `rawset(k, nil)` "during-iteration +removal" pattern works in practice even though it's technically +undefined per the Lua reference manual. + +Errors on non-table input. + +## 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. + +### `C_Timer.After(seconds, callback)` + +Schedules `callback` to fire once after `seconds`. Returns nothing. +Backports modern WoW's `C_Timer.After` as an engine binding (retail +12.0.5 ships this as a `Script_*` C function, not Lua — we mirror +that shape so addons relying on the modern semantics get +identical behavior). + +```lua +C_Timer.After(0.5, function() print("half a second later") end) +C_Timer.After(0, function() print("next frame") end) +``` + +Errors in the callback are caught (via `lua_pcall`) and silently +swallowed — same as modern's behavior. One broken timer doesn't +poison other timers on the same tick. + +### `C_Timer.NewTimer(seconds, callback)` + +Like `After`, but returns a cancel-handle table: + +```lua +local handle = C_Timer.NewTimer(10, function() print("never if I cancel") end) +handle:Cancel() -- prevents the callback from firing +print(handle:IsCancelled()) -- true +``` + +`Cancel()` is idempotent; calling it on a timer that already fired +or was previously cancelled is a no-op. `IsCancelled()` returns +`true` after `Cancel()`, after natural expiry, or for an unknown +timer ID. Both methods take no arguments other than `self`. + +### `C_Timer.NewTicker(seconds, callback, [iterations])` + +Recurring variant. `callback` fires every `seconds` until cancelled +or until `iterations` fires have happened. `iterations` is optional; +omitted or non-numeric means forever. + +```lua +local h = C_Timer.NewTicker(1, function() print("each second") end) +-- ...later +h:Cancel() + +-- bounded: +C_Timer.NewTicker(0.25, function() ... end, 8) -- fires 8 times, every 250ms +``` + +Minimum period is clamped to `0.0001` to prevent tight loops. +Returns the same kind of cancel handle as `NewTimer`. The handle +auto-cancels itself when the iteration count exhausts. + +Implementation notes (apply to all three functions): + +- One unified timer queue walked once per frame from + `FUN_WORLD_TICK`'s subscription. Same hook the + `BAG_UPDATE_DELAYED` flusher uses, so there's no per-feature hook + overhead. +- Resolution is one frame (~16ms at 60fps). A timer scheduled for + `0.001` seconds will fire on the next tick, same as one + scheduled for `0`. +- The timer queue uses a monotonic clock (`QueryPerformanceCounter`), + so timers don't drift if the system clock changes mid-session. +- Callbacks are pinned in the Lua registry under per-timer string + keys so they survive GC between scheduling and firing. + +### `C_DateAndTime` overview + +Backport of the modern `C_DateAndTime` namespace — calendar-style +date math built on top of `GetServerTime()`. All seven functions +exchange `CalendarTime` tables with these fields (matching +Blizzard's `TimeDocumentation.lua`): + +| Field | Range | Notes | +|-------|-------|-------| +| `year` | full year, e.g. 2026 | | +| `month` | 1..12 | luaIndex (1-based) | +| `monthDay` | 1..31 | luaIndex (1-based) | +| `weekday` | 1..7 | luaIndex; 1 = Sunday | +| `hour` | 0..23 | | +| `minute` | 0..59 | | + +> **Daily reset semantics.** `GetSecondsUntilDailyReset` treats reset +> as midnight in server wall-clock time. This is exactly what +> `GetServerTime() % 86400 == 0` gives you — the engine's gametime +> components are converted to an epoch by treating them as UTC, so +> day boundaries in epoch math align with server-clock midnight. +> +> **Weekly reset not implemented.** Vanilla has no server-broadcast +> weekly reset schedule, and Turtle WoW realm schedules vary, so +> `C_DateAndTime.GetSecondsUntilWeeklyReset` would have to hardcode a +> weekday/hour that's wrong on some realms. Addons that need it can +> compute their own value from the daily reset + a CVAR. + +### `C_DateAndTime.GetCurrentCalendarTime()` + +Returns the server clock as a CalendarTime table, or nothing before +login. Equivalent to `GetCalendarTimeFromEpoch(GetServerTime())`. + +```lua +local t = C_DateAndTime.GetCurrentCalendarTime() +-- t = { year=2026, month=5, monthDay=11, weekday=2, hour=14, minute=30 } +``` + +### `C_DateAndTime.GetCalendarTimeFromEpoch(epoch)` + +Converts a Unix epoch (seconds since 1970-01-01 UTC) to a +CalendarTime table. Pure `gmtime`; no engine state touched. + +### `C_DateAndTime.AdjustTimeByDays(date, days)` / `AdjustTimeByMinutes(date, minutes)` + +Returns a new CalendarTime offset from the input by the given number +of days (or minutes). Negative deltas walk backwards. Out-of-range +inputs (`month=13`, `monthDay=32`) normalize via the underlying +`_mkgmtime` / `gmtime` round-trip. + +```lua +local today = C_DateAndTime.GetCurrentCalendarTime() +local tomorrow = C_DateAndTime.AdjustTimeByDays(today, 1) +local yesterday = C_DateAndTime.AdjustTimeByDays(today, -1) +``` + +### `C_DateAndTime.CompareCalendarTime(lhs, rhs)` + +Returns `-1` if `lhs < rhs`, `0` if equal, `1` if `lhs > rhs`. +Compares by epoch conversion so denormalized inputs sort +consistently. + +### `C_DateAndTime.GetServerTimeLocal()` + +Returns the server's wall clock re-interpreted as a Unix epoch in +the **player's** local timezone. Useful when you want to feed a +server-clock value into Lua's `date(format, epoch)` and have the +formatted string show the server's apparent hour/minute. If the +server reports 14:30 and the player is in UTC-5, this returns the +epoch that corresponds to 14:30 in UTC-5 (which is 19:30 UTC). + +### `C_DateAndTime.GetSecondsUntilDailyReset()` + +Returns seconds until the next server midnight (00:00:00 in server +wall-clock time). Returns 0 if called before login. + +> See the overview's "Daily reset semantics" note — this uses server +> midnight, not UTC midnight (though they happen to coincide for +> Turtle WoW since the server reports UTC-aligned components). + +## UIColor + +### `C_UIColor.GetColors()` + +Returns an array of rows, each shaped +`{ baseTag = "FOO_COLOR", color = ColorMixin }`, mirroring the modern +function of the same name. The `color` field is a real `ColorMixin` +instance (carries `GetRGB`, `GenerateHexColorMarkup`, etc.) — the DLL +calls back into Lua's `CreateColor(r,g,b,a)` per row to construct it, +so `ColorMixin` and `CreateColor` must already be defined when +`GetColors` is called. + +The companion addon `!!!ClassicAPI/Util/Color.lua` does both: it +defines `ColorMixin`/`CreateColor` first, then loops the result the +same way `Blizzard_SharedXMLBase/Color.lua` does on modern WoW — +assigning each row as a global under its `baseTag` plus a `_CODE` +variant holding the `|c`-prefixed hex markup: + +```lua +for _, dbColor in ipairs(C_UIColor.GetColors()) do + local color = CreateColor(dbColor.color.r, dbColor.color.g, dbColor.color.b, dbColor.color.a) + _G[dbColor.baseTag] = color + _G[dbColor.baseTag.."_CODE"] = color:GenerateHexColorMarkup() +end +``` + +After that runs, addons can use the standard modern color globals +directly: + +```lua +/dump ACHIEVEMENT_COLOR:GetRGB() -- 1, 1, 0 +/dump ITEM_EPIC_COLOR:GenerateHexColor() +ITEM_EPIC_COLOR_CODE .. "Legendary" .. "|r" +``` + +The data comes from a snapshot of `GlobalColor.dbc` taken from BC +Classic 2.5.5 (build 67323) — vanilla 1.12 has no `GlobalColor.dbc`, +so the rows are embedded in the DLL (see [`src/ui/ColorData.h`](../src/ui/ColorData.h)). +Duplicate `baseTag`s in the source DBC (`PURE_RED_COLOR`, +`INVASION_*`, etc.) are deduplicated keeping the higher-ID entry, +matching what `ipairs(DBColors)` ends up assigning on modern. Colors +introduced after BC (Death Knight runes, Mythic+ medals, healing +absorbs, glyphs, objective tracker) aren't in the snapshot and so +aren't surfaced — none have a use case in 1.12 anyway. + +If `CreateColor` happens not to be defined when `GetColors` is called +(e.g. another DLL or addon manages to call us before `!!!ClassicAPI` +loads), each `color` field falls back to a plain `{r,g,b,a}` table. +The loop above tolerates both shapes — `dbColor.color.r` reads the +same way either way — so consumers shouldn't notice. + ## Unit ### `UnitGUID(unit)` @@ -3875,1458 +5361,3 @@ builds. So the returned value carries the mixin methods `.r/.g/.b/.a` fields. Falls back to a plain `{r,g,b,a}` table if `CreateColor` isn't loaded yet (shouldn't happen — `!!!ClassicAPI` loads first thanks to the triple-`!` prefix). - -## NameCache - -GUID-keyed cache of player names and classes. The engine itself -maintains an in-memory `NameCache` at `0x00C0E228`, populated by -`SMSG_NAME_QUERY_RESPONSE` — but vanilla doesn't expose it to Lua, -and it doesn't survive `/reload`. This module surfaces it as -`GetPlayerInfoByGUID`, adds an opt-in **persistent** layer that -survives `/reload` and full client restarts, and (separately -toggleable) sweeps the engine's visible-object list to populate -entries the SMSG path would never reach on its own. - -Two toggles, each independent: - -- **`C_PlayerCache.SetEnabled`** — turn on the on-disk cache. - Off by default. Without this, the module is read-only against - the engine's transient in-memory cache. -- **`C_PlayerCache.SetScanEnabled`** — turn on the visible-object - sweep. Off by default. Requires the on-disk cache to be enabled - to have any effect. - -Three population sources feed the cache when fully enabled: - -1. **`SMSG_NAME_QUERY_RESPONSE` hook** (always active when the - on-disk cache is on). Every name-query response the engine - processes is mirrored to disk. Covers chat, group/raid sync, - guild updates, visible-object resolution — anything the engine - itself issues a name query for. -2. **`C_PlayerCache.RememberPlayer`** (always available, no-op - when the cache is off). Lets addons feed in sources the engine - never sees: `/who` results, etc. -3. **Visible-object sweep** (active when both toggles are on). - Walks the engine's live visible-object list every ~10 seconds - on the `Frame::RegisterEvent` hook, resolving each player and - feeding name + class. Picks up nearby players whether or not - the engine ever queried them. - -Storage: - -- `WTF\Account\\ClassicAPI.txt` — account-level settings - (`PersistentNameCacheEnabled`, `NameCacheScanEnabled`). -- `WTF\Account\\\ClassicAPI_NameCache.txt` — - per-realm cache. Tab-separated text, ~30 bytes/entry, - hand-editable. Shared across all characters on the same - account+realm (a 50-character bank alt's chat scraping doesn't - double the storage cost). - -### `GetPlayerInfoByGUID(guid)` - -Returns -`localizedClass, englishClass, localizedRace, englishRace, sex, name, realm` -for a player GUID the engine has cached, or `nil` on a cache miss. - -```lua -local _, class, _, race, sex, name = GetPlayerInfoByGUID(UnitGUID("target")) --- e.g. "WARRIOR", "NightElf", 2, "Sylphir" - -GetPlayerInfoByGUID("0x0000000000000777") -- same shape for a literal GUID -``` - -`guid` is the `"0xHHHHHHHHLLLLLLLL"` string returned by `UnitGUID`. -Bare 8-hex `"0xLLLLLLLL"` (hi-dword zero) is also accepted. - -Returns: - -| 1 `localizedClass` | `"Warrior"` / `"Krieger"` etc. — from `ChrClasses.dbc` indexed by locale. | -| 2 `englishClass` | `"WARRIOR"` (uppercase tag, same value `UnitClass` returns as 2nd return on modern clients) — `ChrClasses.dbc` filename field. | -| 3 `localizedRace` | `"Human"` / `"Mensch"` / `"Humain"` etc. — from `ChrRaces.dbc` indexed by locale. | -| 4 `englishRace` | `"Human"`, `"Orc"`, `"Dwarf"`, `"NightElf"`, `"Scourge"` (vanilla's filename for what addons call Undead), `"Tauren"`, `"Gnome"`, `"Troll"` — from `ChrRaces.dbc` filename field. | -| 5 `sex` | `2` = male, `3` = female. Matches `UnitSex` convention (the cache stores `0`/`1`; we add `2`). | -| 6 `name` | Character name. | -| 7 `realm` | Realm name. Single-realm in vanilla, so usually the local realm. | - -**Cache coverage**: the engine populates entries from -`SMSG_NAME_QUERY_RESPONSE`. Anything the client has already seen -populates the cache: chat (whispers, says, party chat), raid/group -events, guild updates, visible objects (target, party, raid in -zone). Names of offline friends never seen in chat are *not* -cached — `GetPlayerInfoByGUID` returns `nil` for them until the -client does something that triggers a name query. This module -deliberately does not trigger queries from a passive getter; a -future `C_PlayerInfo.RequestLoadPlayerByID` would do that -explicitly and fire a load-result event. - -**Persistent fallback**: when -[`C_PlayerCache.SetEnabled(true)`](#c_playercachesetenabledenabled) -has been opted into, a per-realm on-disk cache extends coverage -across sessions. On engine cache miss, `GetPlayerInfoByGUID` falls -back to the persistent cache and returns `name`, `class`, `race`, -and `sex` from storage (`realm` comes back as `""` since vanilla -is single-realm and we don't carry per-player realm names). -Returns `nil` only when both the engine and persistent caches miss. - -**Implementation**: calls the engine's get-or-fetch primitive at -`0x0055F080` with a NULL callback (pure cache read). The cache -instance lives at `0x00C0E228`; entry layout (name, realm, race, -sex, class) was reverse-engineered from the -`SMSG_NAME_QUERY_RESPONSE` write path at `0x0055F310`. - -### `C_PlayerCache.GetPlayerInfoByName(name)` - -Returns -`localizedClass, englishClass, localizedRace, englishRace, sex, name, realm, guid` -for a player in the persistent NameCache, or `nil` if the name -isn't cached. Companion to `GetPlayerInfoByGUID` for the case where -an addon has a player's name but not their GUID — e.g., when -`GetCurrentChatGUID()` returns nil for a chat event the engine -didn't tag with the sender GUID (system notifications, some channel -messages, etc.). - -```lua -local _, class, _, race, _, _, _, guid = C_PlayerCache.GetPlayerInfoByName("Gedwyr") --- "MAGE", "Human", "0x000000003B9ADAA7" - -C_PlayerCache.GetPlayerInfoByName("NeverSeen") -- nil (not cached) -``` - -Match is **case-sensitive, exact** — vanilla server-stored names -are case-stable (`"Gedwyr"` won't match `"gedwyr"`). - -Returns (vs. `GetPlayerInfoByGUID`): - -| Slot | Value | Notes | -|------|-------|-------| -| 1–7 | same as `GetPlayerInfoByGUID` | see above | -| 8 | `guid` | `"0xHHHHHHHHLLLLLLLL"` — the cached player's full GUID, so name-based callers can chain into GUID-keyed APIs. Absent from `GetPlayerInfoByGUID` since the caller already has it. | - -Only reads from the **persistent NameCache** — does *not* hit the -engine's in-memory NAME_QUERY cache (that's keyed by GUID and has -no name index). So this requires `C_PlayerCache.SetEnabled(true)` -to have been opted into; entries get there via the engine's -NAME_QUERY response hook, the visible-object scan, and -`C_PlayerCache.RememberPlayer`. - -**Implementation**: O(1) lookup via a `name → guid` index map -maintained in lockstep with the GUID-keyed entry map. Eviction -keeps the index consistent: when a name's character is deleted and -the name is recycled to a different GUID, the prior entry is -removed from both maps. - -### `C_PlayerCache.RememberPlayer(guid, name, classToken)` - -Adds a `(guid → name, classID, raceID, sex)` entry to the persistent -name cache. For the engine-driven coverage (chat / group / guild / -visible objects), no addon-side feeding is needed — those flow into -the cache automatically through the engine's -`SMSG_NAME_QUERY_RESPONSE` write path. This call exists for the -*other* sources libunitscan-style addons harvest from but the engine -NameCache doesn't see directly: `/who` results, mouseover, target -snapshots, etc. - -``` -C_PlayerCache.RememberPlayer(guid, name, classToken [, raceToken [, sex]]) -``` - -Returns `true` on success, `false` if the persistent cache isn't -enabled or the required args are malformed. - -- `guid` — `"0xHHHHHHHHLLLLLLLL"` string (same format `UnitGUID` - returns). 8-hex `"0xLLLLLLLL"` is also accepted (hi-dword zero). -- `name` — 1–12 ASCII chars (vanilla character-name range). Tabs, - newlines, and high bytes are stripped. -- `classToken` — uppercase token like `"WARRIOR"`, `"MAGE"`. Looked - up against `ChrClasses.dbc` filename field, case-insensitive. - Passing an unknown token keeps the entry's prior class (so a - name-only sighting doesn't erase good class data). -- `raceToken` *(optional)* — uppercase token like `"NIGHTELF"`, - `"SCOURGE"` (vanilla's filename for Undead). Same resolution as - classToken, against `ChrRaces.dbc`. Omitted/unknown → leaves - prior race alone. -- `sex` *(optional)* — `0` (male) or `1` (female), matching the - wire-format convention the engine cache stores. Modern WoW's - `UnitSex` uses `2`/`3`; pass `UnitSex - 2` if you're forwarding - that value. Omitted/`0` → leaves prior sex alone (so this call - can't be used to flip a stored value back to male; the - `SMSG_NAME_QUERY_RESPONSE` hook handles direct assignment). - -```lua --- Harvest /who results into the persistent cache -local function OnWhoUpdate() - for i = 1, GetNumWhoResults() do - local name, _, _, _, class, _, _, _, _, _, _, sex = GetWhoInfo(i) - -- class/race come back localized from GetWhoInfo; the - -- locale-token tables in pfUI/AceLocale handle the - -- inverse mapping. RememberPlayer expects engine tokens - -- ("WARRIOR" etc.). - end -end -``` - -Each non-zero field is updated on the existing entry; zeros are -treated as "caller doesn't know" and preserve prior real data. A -`name`-only update (classToken passed but unknown) refreshes the -name without erasing class. - -The "deleted character recreated with same name, different class" -collision case that name-keyed caches suffer from doesn't apply -here: GUIDs are permanent for the life of a vanilla character, so -the new character has a different GUID and gets a different cache -entry. - -### `C_PlayerInfo.GUIDIsPlayer(guid)` / `GUIDIsCreature` / `GUIDIsPet` / `GUIDIsGameObject` - -Type checks on the raw 1.12 GUID format. Vanilla GUIDs encode the -entity type in the high 16 bits of the qword — players have -`0x0000` (low dword = player ID), creatures `0xF130xxxx`, pets -`0xF140xxxx`, game objects (herbs / chests / etc.) `0xF110xxxx`, -items `0x4000xxxx`. Each function returns `true` only for its -specific prefix; the `"0x0000000000000000"` sentinel returns -`false` from all four. - -```lua -if C_PlayerInfo.GUIDIsPlayer(UnitGUID("target")) then - -- target is a player -end - --- Combat-log row triage: was that a player kill or a mob kill? -local function OnCombatLogEvent(_, _, eventType, srcGUID, ...) - if eventType == "PARTY_KILL" then - if C_PlayerInfo.GUIDIsPlayer(srcGUID) then ... end - end -end -``` - -`GUIDIsPlayer` matches modern WoW's signature exactly; the other -three are companions for the most common type-distinction needs. -For other types (corpse, dynamic object, transport, item) the -underlying classifier exists internally — let us know if you need -one exposed. - -Accepts either the 16-digit `"0xHHHHHHHHLLLLLLLL"` form or the -8-digit `"0xLLLLLLLL"` shortcut (high dword implicitly zero). -Malformed input returns `false` rather than raising — matching -modern's tolerance for stale GUIDs from addon-side caches. - -### `C_CreatureInfo.GetCreatureID(guid)` - -Extracts the creature template / NPC ID from a unit GUID. Vanilla -1.12 packs the entry ID directly into bits 24-47 of the 64-bit -GUID for the types that carry one; this function does the shift -and mask so addons don't have to. - -```lua -C_CreatureInfo.GetCreatureID(UnitGUID("target")) -- 1842 for Hogger -C_CreatureInfo.GetCreatureID(UnitGUID("pet")) -- pet's creature template ID -C_CreatureInfo.GetCreatureID(UnitGUID("player")) -- nil (no entry on players) -``` - -Accepts creature GUIDs (`0xF130xxxx…`) and pet GUIDs -(`0xF140xxxx…`). Returns `nil` for: -- non-string input or malformed GUIDs -- player GUIDs — the low 32 bits hold a player ID, not a template -- game-object / dynamic-object / corpse / item GUIDs — modern's - `C_CreatureInfo` doesn't surface entry IDs for these even though - the bits are in the same range; addons that need them can shift - the raw GUID themselves (`(guid >> 24) & 0xFFFFFF`) -- entry IDs of 0 — the engine never assigns 0; treated as "no info" - -The standard 16-digit (`"0xHHHHHHHHLLLLLLLL"`) and 8-digit -(`"0xLLLLLLLL"`) GUID-string forms are both accepted, same as -`C_PlayerInfo.GUIDIs*` above. - -### `C_PlayerCache.SetEnabled(enabled)` - -Opts into (or out of) the persistent name cache. `enabled` is a -boolean (numeric `0`/`1` also accepted). Persists to -`WTF\Account\\ClassicAPI.txt` as -`PersistentNameCacheEnabled=1`/`0`, so the choice survives -client restarts. - -When enabled: - -- Every `SMSG_NAME_QUERY_RESPONSE` the engine processes is also - written to `WTF\Account\\\ClassicAPI_NameCache.txt`. -- Lua-side `C_PlayerCache.RememberPlayer` calls become effective - (they're no-ops when the cache is disabled). -- `GetPlayerInfoByGUID` gains the cross-session fallback path - documented above. -- [`SetScanEnabled`](#c_playercachesetscanenabledenabled) - becomes effective if also turned on. - -When disabled, the on-disk file is left in place (re-enabling later -restores the prior contents); future writes are simply suppressed. - -```lua -C_PlayerCache.SetEnabled(true) -``` - -Returns nothing. - -### `C_PlayerCache.IsEnabled()` - -Returns the current state of the persistent name cache as a -boolean. `false` until -[`SetEnabled`](#c_playercachesetenabledenabled) -has been called (or its prior call survived in the on-disk settings -file). - -```lua -if C_PlayerCache.IsEnabled() then - -- persistent fallback is active for GetPlayerInfoByGUID -end -``` - -### `C_PlayerCache.SetScanEnabled(enabled)` - -Opts into the **visible-object sweep**: an opportunistic walk of -the engine's live visible-object list that feeds every player in -render range (whose object is currently loaded by the client) into -the persistent name cache. Throttled to once per ~10 seconds, on -the existing `Frame::RegisterEvent` hook — no per-frame overhead, -no extra hooks installed. - -`enabled` is a boolean (numeric `0`/`1` also accepted). Persists to -`WTF\Account\\ClassicAPI.txt` as -`NameCacheScanEnabled=1`/`0`. - -```lua -C_PlayerCache.SetEnabled(true) -- prerequisite -C_PlayerCache.SetScanEnabled(true) --- Now: standing in Stormwind for a minute pre-populates the cache --- with every visible player's name and class. -``` - -**Independent of the cache toggle.** Turning this on alone has no -effect — the sweep relies on `Remember()` which silently no-ops -when the on-disk cache is disabled. Turning the cache off (without -also turning the scan off) preserves the scan setting for the next -time you re-enable the cache. - -**Players only.** NPCs and pets aren't cached — their GUIDs are -ephemeral and can get reused across sessions, so caching them is -worse than useless. - -**Implementation**: walks `ClntObjMgrEnumVisibleObjects` -(`0x00468380`) — the same engine iterator -[VanillaMinimapTracking](https://github.com/Brues/VanillaMinimapTracking) -uses for blip rendering — filtering each GUID through -`ClntObjMgrObjectPtr` (`0x00468460`) with `TYPEMASK_PLAYER`. Name -comes from the CGObject vftable's `GetName` slot; class is the -byte at `[m_objectFields + 0x79]` (UNIT_FIELD_BYTES_0 byte 1, same -field `Script_UnitClass` reads). - -### `C_PlayerCache.IsScanEnabled()` - -Returns the current visible-object scan setting as a boolean. -Independent of the cache toggle — this only reflects the scan- -specific setting, not whether the scan is *effectively* running -(which also requires the cache to be on). - -```lua -if C_PlayerCache.IsScanEnabled() - and C_PlayerCache.IsEnabled() then - -- visible-object sweeps are running every ~10s -end -``` - -## State - -Player movement / visibility state queries that modern WoW exposes -as no-arg globals. 1.12 doesn't bind them to Lua despite the engine -tracking the underlying state — broadcast in UpdateFields for some -(mount, stealth visibility), local-only for others (falling, -swimming). - -### `IsMounted()` - -Returns `true` if the player is currently mounted, `false` otherwise. - -Reads `UNIT_FIELD_MOUNTDISPLAYID` from the player's broadcast -descriptor. The field holds a creature display ID (the model the -engine renders under the player) when mounted, and `0` otherwise. - -```lua -if not IsMounted() then - CastSpellByName("Summon Dreadsteed") -end -``` - -Equivalent to the function of the same name introduced in 1.10. - -### `IsStealthed()` - -Returns `true` if the player is currently in Stealth (Rogue) or -Prowl (Druid), `false` otherwise. - -Reads bit `0x02` of the player visibility byte at descriptor -`+0x17C` and AND-gates with `MountDisplayID == 0` to disambiguate -mount (which sets the same bit). Untested for Druid shapeshift -forms — if you find a false-positive there, file an issue and we'll -switch to walking the player's aura array for the actual stealth -spell. - -```lua -if IsStealthed() then - -- defer the spell that would break stealth -end -``` - -### `IsFalling()` - -Returns `true` if the player is currently mid-jump or falling, -`false` otherwise. - -Reads the local CGPlayer movement-flags word at `+0x9E8` and tests -`MOVEFLAG_FALLING | MOVEFLAG_FALLING_FAR` (`0x2000 | 0x4000`). This -is client-side state (outbound `MSG_MOVE_*` data, never visible for -remote units), so the function only meaningfully applies to the -local player. - -```lua -if not IsFalling() then - -- safe to bind ground-targeted spell -end -``` - -### `IsSwimming()` - -Returns `true` if the player is currently swimming (in liquid, with -the swim animation/movement set), `false` otherwise. - -Same movement-flags word as `IsFalling`, testing `MOVEFLAG_SWIMMING` -(`0x200000`). Local-player only. - -```lua -if IsSwimming() then - -- breath bar logic, mount-failure suppression, etc. -end -``` - -### `IsAssistingRitual()` - -Returns `true` if the local player is currently clicking a warlock -summoning portal (the channel-on-GameObject state with no castbar -UI, where movement breaks the channel), `false` otherwise. - -This is distinct from spell channeling: the function fires for -*participants* who clicked the portal, not the warlock who cast -Ritual of Summoning. Vanilla has no Lua surface for this state — -the engine's `SPELLCAST_CHANNEL_*` events don't fire and -`CastingInfo()` returns nothing — so addons that want to react to -the player being committed to a ritual (e.g. suppress autorun -toggles, hide nameplate clicks, warn before movement) have no other -way to detect it. - -Detection uses two state slots: - -- `UNIT_CHANNEL_SPELL` (descriptor `+0x228`) — the warlock's channel - spell ID (698) is mirrored onto every clicker for the duration - of the ritual. -- A CGPlayer-local pointer at `+0xB4` — the engine's "current spell - cast target GameObject" slot, set to the portal GO while the - clicker is engaged. - -Either signal alone is ambiguous (the warlock channeling matches -the first; mining and other GO-targeted casts match the second); -the conjunction is portal-clicker-specific. - -The engine fires `SPELLCAST_CHANNEL_START` / `SPELLCAST_CHANNEL_STOP` -on the portal click, even though there's no castbar — Blizzard's -vanilla castbar UI filters out spell ID 698 (Ritual of Summoning), -but the events themselves fire normally. Combine them with this -function for ritual-specific triggers: - -```lua -local frame = CreateFrame("Frame") -frame:RegisterEvent("SPELLCAST_CHANNEL_START") -frame:RegisterEvent("SPELLCAST_CHANNEL_STOP") -frame:SetScript("OnEvent", function() - if event == "SPELLCAST_CHANNEL_START" and IsAssistingRitual() then - -- player just committed to a ritual portal - elseif event == "SPELLCAST_CHANNEL_STOP" then - -- channel ended; was it a ritual? - end -end) -``` - -Local-player only — the `+0xB4` pointer lives on the CGPlayer -object, not in the broadcast descriptor, so the function can't -report state for `target` / `party*` / etc. Returns `false` when -called before the player object is initialized (login screen). - -## CharacterList - -### `GetSavedCharacterOrder(realm)` / `SetSavedCharacterOrder(realm, order)` — GlueXML only - -> **GlueXML scope.** These globals are registered on the **glue** -> Lua state (the engine that runs login / realm-select / -> character-select), not the in-world FrameScript engine. In-world -> addons can't see them — `/script GetSavedCharacterOrder("X")` -> from inside the world will error on a nil global. They exist -> specifically to support GlueXML patches that reorder the -> character-select list and need to persist that order across -> sessions; 1.12 glue ships no general-purpose persistence API -> (just `GetSavedAccountName`/`SetSavedAccountName`, which is -> saturated by the autologin system). - -- `GetSavedCharacterOrder(realm) -> string` — returns the saved - order string for `realm`, or `""` if none. Never returns `nil`. -- `SetSavedCharacterOrder(realm, order)` — writes the order - string. Calling with `order == ""` clears the realm's entry. - -Both args are opaque UTF-8 strings. The caller picks the encoding -for `order`; the DLL stores it verbatim. The expected pattern -(matching the anniversary-client reorder UI) is a pipe-delimited -list of character names: `"Thrall|Jaina|Sylvanas"`. - -Persistence: `WTF\Account\\ClassicAPI.txt`, one -`CharacterOrder.=` line per realm. Account scope is -implicit via the file path (so switching autologin accounts on the -glue screen automatically isolates per-account orderings); realm -scope is explicit via the line key. The same file is shared with -the persistent name cache settings — see [`Settings::Account` -in the source](../src/settings/Account.h) — no file-level -coordination needed at the call site. - -```lua --- GlueXML, e.g. CharacterSelect.lua: persist the user's drag-reordered list -local realm = GetServerName() or "" -local names = {} -for i = 1, GetNumCharacters() do - table.insert(names, (GetCharacterInfo(translationTable[i]))) -end -SetSavedCharacterOrder(realm, table.concat(names, "|")) - --- On the next CHARACTER_LIST_UPDATE: read the saved order back -local saved = GetSavedCharacterOrder(realm) -if saved ~= "" then - for name in string.gfind(saved, "([^|]+)") do - -- reconcile against the current GetCharacterInfo names - end -end -``` - -> **How it works.** ClassicAPI hooks `FUN_0046ABB0` — the engine's -> master glue-init function, which runs once per glue boot (initial -> launch and every world→glue return on logout). After the engine -> registers its own 109 glue functions, our hook adds these two on -> the same Lua state via the engine's own -> `FrameScript_RegisterFunction`. The glue Lua state is torn down -> and recreated on every world transition; we re-register each -> cycle automatically. - -## Chat - -### `GetCurrentChatGUID()` - -Returns the sender's GUID for whichever `CHAT_MSG_*` event is -currently being dispatched, or `nil` if called outside a chat -event or for a synthetic chat with no real sender (e.g. -`CHAT_MSG_SYSTEM`). - -Format matches `UnitGUID`: `"0xHHHHHHHHLLLLLLLL"` (16 hex digits, -hi dword first). - -```lua -local f = CreateFrame("Frame") -f:RegisterEvent("CHAT_MSG_CHANNEL") -f:RegisterEvent("CHAT_MSG_SAY") -f:RegisterEvent("CHAT_MSG_WHISPER") -f:SetScript("OnEvent", function() - local guid = GetCurrentChatGUID() - if guid then - local _, class, _, race = GetPlayerInfoByGUID(guid) - DEFAULT_CHAT_FRAME:AddMessage(string.format( - "%s: %s [%s %s]", arg2, arg1, class or "?", race or "?")) - end -end) -``` - -Vanilla 1.12's `CHAT_MSG_*` events don't include the sender GUID -in their payload — that was added in 3.0+ as `arg12`. Addons that -need to identify chatters reliably (rather than by sender name, -which is locale-fragile and ambiguous across realms) currently -strcmp against an addon-maintained name cache. This function lets -them skip that work. - -**Implementation**: hooks the engine's chat dispatcher at -`FUN_CHAT_DISPATCH` (`0x0049A870`), which receives the sender -GUID as args 11/12 of a 12-arg `__fastcall`. The hook stashes the -GUID into a static global before forwarding to the original -function; the engine then fires the appropriate `CHAT_MSG_*` -event synchronously inside that window, so `GetCurrentChatGUID()` -called from the addon's OnEvent sees the right GUID. The global -is restored to its prior value (not cleared) on hook return, so -nested chat dispatch (e.g. an addon calling `SendChatMessage` -from its handler) doesn't lose the outer context's GUID. - -The function returns `nil` rather than `"0x0000000000000000"` -for synthetic chat (system messages, login banners, etc.) where -the GUID args are zero — matches the idiomatic -`if GetCurrentChatGUID() then` check. - -## AddOns - -Six modern `C_AddOns.*` getters that splat the legacy -`GetAddOnInfo(arg)` 7-tuple `(name, title, notes, enabled, -loadable, reason, security)` into single-field accessors. Most -bypass `GetAddOnInfo` entirely and call the engine's per-field -helpers directly. - -All accept either a 1-based index (`1..GetNumAddOns()`) or an -addon directory name string. - -### `C_AddOns.GetAddOnName(indexOrName)` - -Returns the addon's directory name as the engine sees it (the -folder name on disk). For numeric input, returns the engine's -canonical casing; for string input, echoes the input verbatim -once existence is confirmed. Returns `nil` for missing addons. - -```lua -C_AddOns.GetAddOnName(1) -- "Atlas-TW" -C_AddOns.GetAddOnName("DebugTools") -- "DebugTools" -C_AddOns.GetAddOnName("garbage") -- nil -``` - -### `C_AddOns.GetAddOnTitle(indexOrName)` - -Returns the `## Title:` from the addon's `.toc` file, with WoW -color-code escapes applied. `nil` for missing addons or addons -without a title field. - -```lua -C_AddOns.GetAddOnTitle("DebugTools") -- "UI Debug Tools" -``` - -### `C_AddOns.GetAddOnNotes(indexOrName)` - -Returns the `## Notes:` from the `.toc`. `nil` for missing -addons or addons without notes. - -```lua -C_AddOns.GetAddOnNotes("DebugTools") --- "Tools for developing addons (backport of Blizzard_DebugTools 3.3.5 to 1.12.1 / Lua 5.0)" -``` - -### `C_AddOns.IsAddOnLoadable(indexOrName)` - -Returns `loadable, reason` — a real boolean and a status string -(or `nil`). - -`reason` comes from a small status table the engine consults when -populating `GetAddOnInfo`'s 6th return: `"DISABLED"`, `"BANNED"`, -`"CORRUPT"`, `"INSECURE"`, `"NOT_DEMAND_LOADED"`, -`"INTERFACE_VERSION"`, `"MISSING"`. `nil` when the addon is -loadable. The full modern signature accepts optional `character` -and `demandLoaded` arguments — those are ignored here since vanilla -1.12 has no per-character addon enable state. - -```lua -C_AddOns.IsAddOnLoadable("DebugTools") -- true, nil -C_AddOns.IsAddOnLoadable("HardcoreTooltips") -- false, "DISABLED" -C_AddOns.IsAddOnLoadable("garbage") -- false, nil -``` - -### `C_AddOns.GetAddOnSecurity(indexOrName)` - -Returns an `Enum.AddOnSecurityStatus` integer (not a string — modern -shape): - -| Value | `Enum.AddOnSecurityStatus.*` | When | -|------:|------------------------------|------| -| `0` | `Secure` | Blizzard-signed addons (`Blizzard_*`). | -| `1` | `Insecure` | Every user addon loaded from `Interface/AddOns/`. The default for any registered addon not in the secure or banned override sets. | -| `2` | `Banned` | Entries the engine has explicitly disqualified — set by server addon-banlist responses, rare in practice. | -| `3` | `NotAvailable` | No addon by that name / index exists. | - -```lua -C_AddOns.GetAddOnSecurity("Blizzard_TalentUI") -- 0 (Secure) -C_AddOns.GetAddOnSecurity("DebugTools") -- 1 (Insecure) -C_AddOns.GetAddOnSecurity("Nonexistent") -- 3 (NotAvailable) - -if status == Enum.AddOnSecurityStatus.Secure then ... -``` - -### `C_AddOns.DoesAddOnExist(indexOrName)` - -Returns `true` iff the engine's addon registry has a matching -entry, `false` otherwise. Cheap existence probe used by addons -doing soft-dependency checks. - -The implementation goes through the registry directly rather than -dispatching to `GetAddOnInfo` — the engine echoes its input name -back as ret1 unconditionally (before the lookup), so a -`GetAddOnInfo("garbage") ~= nil` heuristic returns true for any -string. This wrapper avoids that. - -```lua -C_AddOns.DoesAddOnExist("DebugTools") -- true -C_AddOns.DoesAddOnExist("garbage") -- false -``` - -## Combat - -### `InCombatLockdown()` - -Returns `true` if the local player is currently in combat, `false` -otherwise. Modern WoW gates secure-frame UI manipulation on this; 1.12 -has no secure-frame system, so the function reduces to a plain -"is the player in combat" check. Useful for addons backporting modern -code that does e.g. `if not InCombatLockdown() then SetBindingClick(...) end`. - -```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. - -## Hooks - -### `hooksecurefunc(name, callback)` / `hooksecurefunc(table, name, callback)` - -Modern post-call hook: the original function runs first, then -`callback` runs with the same args (return values discarded). The -original's return values propagate to the caller. - -```lua -hooksecurefunc("GetSpellInfo", function(spellID) - print("GetSpellInfo called with " .. tostring(spellID)) -end) - -hooksecurefunc(GameTooltip, "SetInventoryItem", function(self, unit, slot) - -- runs after the engine fills the tooltip - print("inventory tooltip:", unit, slot) -end) -``` - -The "secure" label refers to taint-propagation behavior introduced in -3.0 for protected-frame manipulation. Vanilla 1.12 has no taint -system, so the function is functionally equivalent to a plain -"after-hook" — just preserves modern API parity for addons being -backported from later expansions. - -Implemented in pure C: builds a Lua C closure with `(orig, callback)` -as upvalues; the wrapper calls orig with `LUA_MULTRET`, then callback, -then returns orig's full result list. No return-count cap — works -correctly for functions returning any number of values. - -Errors via `lua_error` on: -- Non-string `name` -- Non-function `callback` -- `target[name]` not resolvable to a function (covers typos and - hooking unknown frame methods) - -## CVar - -### `C_CVar.GetCVarBool(cvar)` - -Returns the cvar's value coerced to a boolean, or `nil` if no cvar -by that name is registered. The `C_CVar` namespace was added in -10.x; vanilla 1.12 only has `GetCVar` which returns a string. - -```lua -C_CVar.GetCVarBool("gxMaximize") -- true if the window is set fullscreen -C_CVar.GetCVarBool("CombatDamage") -- false if floating damage text is off -C_CVar.GetCVarBool("doesNotExist") -- nil — distinguishable from false -``` - -Coercion rules (only applied when the cvar exists): - -| Cvar string value | Result | -|---|---| -| `"1"` or any non-zero numeric (`"42"`, `"-3"`, …) | `true` | -| `"true"` (case-insensitive) | `true` | -| `"0"` or empty | `false` | -| Non-numeric, non-`"true"` (`"on"`, `"yes"`) | `false` | -| Cvar name not registered | `nil` | - -Implementation reads the cvar registry directly (engine's -`FUN_FIND_CVAR` at `0x0063DEC0`), bypassing `GetCVar`'s Lua-error -path for unknown cvars. The `nil` return lets callers distinguish -"the cvar exists and is falsy" from "no such cvar." - -#### Glue-state availability - -`C_CVar.GetCVarBool` is also registered on the glue Lua state, and -the engine's stock `GetCVar` / `SetCVar` / `RegisterCVar` / -`GetCVarDefault` — which vanilla 1.12 only exposes in-game — are -mirrored onto glue too. GlueXML patches at the login / realm / -char-select screens can now read and write CVars directly. CVar -storage is process-global, so writes on either state are -immediately visible on the other (a `SetCVar("foo", "1")` from a -GlueXML script will read back as `"1"` on the in-world side, and -vice versa). - -## Table - -### `table.wipe(t)` - -Removes every key from `t`, leaving it empty but preserving its -internal hash and array capacity. Returns `t` for chaining. - -```lua -local cache = {} --- ... fill it up ... -table.wipe(cache) -- cache is now {} -local also_t = table.wipe(t2) -- also_t === t2 after wipe -``` - -Port of Blizzard's 3.3.5 implementation at VA `0x00852180` — same -pattern, just using 1.12's Lua 5.0 entry points instead of 5.1's. -Both Lua versions' `lua_next` walks the hash node array linearly, -so the canonical `lua_next` + `rawset(k, nil)` "during-iteration -removal" pattern works in practice even though it's technically -undefined per the Lua reference manual. - -Errors on non-table input. - -## Input - -1.12 ships `IsShiftKeyDown` / `IsControlKeyDown` / `IsAltKeyDown` but -they only report "any shift/ctrl/alt" — there's no built-in way to tell -left from right. These seven functions add the missing distinction -plus an `IsModifierKeyDown()` rollup. - -### `IsLeftShiftKeyDown()` / `IsRightShiftKeyDown()` -### `IsLeftControlKeyDown()` / `IsRightControlKeyDown()` -### `IsLeftAltKeyDown()` / `IsRightAltKeyDown()` - -Each returns `1` when the corresponding key is physically down, `nil` -otherwise — matching the convention 1.12's own `IsShiftKeyDown` etc. -use. - -```lua -if IsLeftShiftKeyDown() and not IsRightShiftKeyDown() then - -- left-shift-only binding -end -``` - -### `IsModifierKeyDown()` - -Returns `1` if **any** of the six modifier keys is down, `nil` -otherwise. Equivalent to -`IsShiftKeyDown() or IsControlKeyDown() or IsAltKeyDown()` but in one -call. - -### `MODIFIER_STATE_CHANGED` event - -Fires on every modifier-key press and release with `(key, down)`: - -| arg1 (`key`) | `LSHIFT`, `RSHIFT`, `LCTRL`, `RCTRL`, `LALT`, `RALT` | -| arg2 (`down`) | `1` on press, `0` on release | - -Only transitions fire — key autorepeat does not. Matches 2.4.3+ -semantics. - -```lua -local f = CreateFrame("Frame") -f:RegisterEvent("MODIFIER_STATE_CHANGED") -f:SetScript("OnEvent", function() - -- in vanilla 1.12 OnEvent receives no args; engine sets `event` and - -- `arg1..argN` as globals before invoking the handler. - if event == "MODIFIER_STATE_CHANGED" and arg1 == "LSHIFT" then - print("left shift", arg2 == 1 and "down" or "up") - end -end) -``` - -**Implementation notes** - -L/R modifier distinction doesn't exist anywhere in the 1.12 engine's -own state — its `IsShiftKeyDown` chain bottoms out at -`GetKeyState(VK_SHIFT)` (the merged virtual key, `0x10`), never the -L/R-aware `VK_LSHIFT` / `VK_RSHIFT`. The OS-level keystate *does* have -the distinction; we capture it by installing a `WH_GETMESSAGE` Win32 -thread hook on the engine's message-pump thread, decoding each -`WM_KEY{,SYS}{DOWN,UP}` message (using `MapVirtualKeyA(scancode, -MAPVK_VSC_TO_VK_EX)` to resolve `VK_SHIFT` to L/R and the `KF_EXTENDED` -bit in `lParam` for `VK_CONTROL` / `VK_MENU`), and maintaining a -6-bit cached bitmap that the seven query functions read. - -The thread-message hook is per-thread, not per-`HWND` — it survives -renderer-state changes that recreate WoW's main window (e.g. toggling -vertical sync), where an `SetWindowLongPtr`-style `WNDPROC` subclass -would be left dangling. - -## Talent - -### `GetTalentSpellID(tabIndex, talentIndex, [rank])` - -Returns the spellID for the talent at the given `(tabIndex, talentIndex)` -and rank, or `nil` if the talent index is out of range or the rank slot -is empty. 1.12's `GetTalentInfo` returns `(name, icon, tier, column, -currentRank, maxRank, ...)` with no spellID; this fills the gap so -addons can chain into the spell APIs without maintaining their own -`(class, tab, idx) → spellID` lookup tables. - -```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. - -### `C_Timer.After(seconds, callback)` - -Schedules `callback` to fire once after `seconds`. Returns nothing. -Backports modern WoW's `C_Timer.After` as an engine binding (retail -12.0.5 ships this as a `Script_*` C function, not Lua — we mirror -that shape so addons relying on the modern semantics get -identical behavior). - -```lua -C_Timer.After(0.5, function() print("half a second later") end) -C_Timer.After(0, function() print("next frame") end) -``` - -Errors in the callback are caught (via `lua_pcall`) and silently -swallowed — same as modern's behavior. One broken timer doesn't -poison other timers on the same tick. - -### `C_Timer.NewTimer(seconds, callback)` - -Like `After`, but returns a cancel-handle table: - -```lua -local handle = C_Timer.NewTimer(10, function() print("never if I cancel") end) -handle:Cancel() -- prevents the callback from firing -print(handle:IsCancelled()) -- true -``` - -`Cancel()` is idempotent; calling it on a timer that already fired -or was previously cancelled is a no-op. `IsCancelled()` returns -`true` after `Cancel()`, after natural expiry, or for an unknown -timer ID. Both methods take no arguments other than `self`. - -### `C_Timer.NewTicker(seconds, callback, [iterations])` - -Recurring variant. `callback` fires every `seconds` until cancelled -or until `iterations` fires have happened. `iterations` is optional; -omitted or non-numeric means forever. - -```lua -local h = C_Timer.NewTicker(1, function() print("each second") end) --- ...later -h:Cancel() - --- bounded: -C_Timer.NewTicker(0.25, function() ... end, 8) -- fires 8 times, every 250ms -``` - -Minimum period is clamped to `0.0001` to prevent tight loops. -Returns the same kind of cancel handle as `NewTimer`. The handle -auto-cancels itself when the iteration count exhausts. - -Implementation notes (apply to all three functions): - -- One unified timer queue walked once per frame from - `FUN_WORLD_TICK`'s subscription. Same hook the - `BAG_UPDATE_DELAYED` flusher uses, so there's no per-feature hook - overhead. -- Resolution is one frame (~16ms at 60fps). A timer scheduled for - `0.001` seconds will fire on the next tick, same as one - scheduled for `0`. -- The timer queue uses a monotonic clock (`QueryPerformanceCounter`), - so timers don't drift if the system clock changes mid-session. -- Callbacks are pinned in the Lua registry under per-timer string - keys so they survive GC between scheduling and firing. - -### `C_DateAndTime` overview - -Backport of the modern `C_DateAndTime` namespace — calendar-style -date math built on top of `GetServerTime()`. All seven functions -exchange `CalendarTime` tables with these fields (matching -Blizzard's `TimeDocumentation.lua`): - -| Field | Range | Notes | -|-------|-------|-------| -| `year` | full year, e.g. 2026 | | -| `month` | 1..12 | luaIndex (1-based) | -| `monthDay` | 1..31 | luaIndex (1-based) | -| `weekday` | 1..7 | luaIndex; 1 = Sunday | -| `hour` | 0..23 | | -| `minute` | 0..59 | | - -> **Daily reset semantics.** `GetSecondsUntilDailyReset` treats reset -> as midnight in server wall-clock time. This is exactly what -> `GetServerTime() % 86400 == 0` gives you — the engine's gametime -> components are converted to an epoch by treating them as UTC, so -> day boundaries in epoch math align with server-clock midnight. -> -> **Weekly reset not implemented.** Vanilla has no server-broadcast -> weekly reset schedule, and Turtle WoW realm schedules vary, so -> `C_DateAndTime.GetSecondsUntilWeeklyReset` would have to hardcode a -> weekday/hour that's wrong on some realms. Addons that need it can -> compute their own value from the daily reset + a CVAR. - -### `C_DateAndTime.GetCurrentCalendarTime()` - -Returns the server clock as a CalendarTime table, or nothing before -login. Equivalent to `GetCalendarTimeFromEpoch(GetServerTime())`. - -```lua -local t = C_DateAndTime.GetCurrentCalendarTime() --- t = { year=2026, month=5, monthDay=11, weekday=2, hour=14, minute=30 } -``` - -### `C_DateAndTime.GetCalendarTimeFromEpoch(epoch)` - -Converts a Unix epoch (seconds since 1970-01-01 UTC) to a -CalendarTime table. Pure `gmtime`; no engine state touched. - -### `C_DateAndTime.AdjustTimeByDays(date, days)` / `AdjustTimeByMinutes(date, minutes)` - -Returns a new CalendarTime offset from the input by the given number -of days (or minutes). Negative deltas walk backwards. Out-of-range -inputs (`month=13`, `monthDay=32`) normalize via the underlying -`_mkgmtime` / `gmtime` round-trip. - -```lua -local today = C_DateAndTime.GetCurrentCalendarTime() -local tomorrow = C_DateAndTime.AdjustTimeByDays(today, 1) -local yesterday = C_DateAndTime.AdjustTimeByDays(today, -1) -``` - -### `C_DateAndTime.CompareCalendarTime(lhs, rhs)` - -Returns `-1` if `lhs < rhs`, `0` if equal, `1` if `lhs > rhs`. -Compares by epoch conversion so denormalized inputs sort -consistently. - -### `C_DateAndTime.GetServerTimeLocal()` - -Returns the server's wall clock re-interpreted as a Unix epoch in -the **player's** local timezone. Useful when you want to feed a -server-clock value into Lua's `date(format, epoch)` and have the -formatted string show the server's apparent hour/minute. If the -server reports 14:30 and the player is in UTC-5, this returns the -epoch that corresponds to 14:30 in UTC-5 (which is 19:30 UTC). - -### `C_DateAndTime.GetSecondsUntilDailyReset()` - -Returns seconds until the next server midnight (00:00:00 in server -wall-clock time). Returns 0 if called before login. - -> See the overview's "Daily reset semantics" note — this uses server -> midnight, not UTC midnight (though they happen to coincide for -> Turtle WoW since the server reports UTC-aligned components). - -## UIColor - -### `C_UIColor.GetColors()` - -Returns an array of rows, each shaped -`{ baseTag = "FOO_COLOR", color = ColorMixin }`, mirroring the modern -function of the same name. The `color` field is a real `ColorMixin` -instance (carries `GetRGB`, `GenerateHexColorMarkup`, etc.) — the DLL -calls back into Lua's `CreateColor(r,g,b,a)` per row to construct it, -so `ColorMixin` and `CreateColor` must already be defined when -`GetColors` is called. - -The companion addon `!!!ClassicAPI/Util/Color.lua` does both: it -defines `ColorMixin`/`CreateColor` first, then loops the result the -same way `Blizzard_SharedXMLBase/Color.lua` does on modern WoW — -assigning each row as a global under its `baseTag` plus a `_CODE` -variant holding the `|c`-prefixed hex markup: - -```lua -for _, dbColor in ipairs(C_UIColor.GetColors()) do - local color = CreateColor(dbColor.color.r, dbColor.color.g, dbColor.color.b, dbColor.color.a) - _G[dbColor.baseTag] = color - _G[dbColor.baseTag.."_CODE"] = color:GenerateHexColorMarkup() -end -``` - -After that runs, addons can use the standard modern color globals -directly: - -```lua -/dump ACHIEVEMENT_COLOR:GetRGB() -- 1, 1, 0 -/dump ITEM_EPIC_COLOR:GenerateHexColor() -ITEM_EPIC_COLOR_CODE .. "Legendary" .. "|r" -``` - -The data comes from a snapshot of `GlobalColor.dbc` taken from BC -Classic 2.5.5 (build 67323) — vanilla 1.12 has no `GlobalColor.dbc`, -so the rows are embedded in the DLL (see [`src/ui/ColorData.h`](../src/ui/ColorData.h)). -Duplicate `baseTag`s in the source DBC (`PURE_RED_COLOR`, -`INVASION_*`, etc.) are deduplicated keeping the higher-ID entry, -matching what `ipairs(DBColors)` ends up assigning on modern. Colors -introduced after BC (Death Knight runes, Mythic+ medals, healing -absorbs, glyphs, objective tracker) aren't in the snapshot and so -aren't surfaced — none have a use case in 1.12 anyway. - -If `CreateColor` happens not to be defined when `GetColors` is called -(e.g. another DLL or addon manages to call us before `!!!ClassicAPI` -loads), each `color` field falls back to a plain `{r,g,b,a}` table. -The loop above tolerates both shapes — `dbColor.color.r` reads the -same way either way — so consumers shouldn't notice. - -## 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. - -### `BAG_UPDATE_DELAYED` event - -Fires (with no payload) once per frame in which any `BAG_UPDATE` -fired. Matches modern WoW's coalescing semantic exactly — register -for `BAG_UPDATE_DELAYED` instead of `BAG_UPDATE` and rescan once -per frame regardless of how many updates fired. - -```lua -local f = CreateFrame("Frame") -f:RegisterEvent("BAG_UPDATE_DELAYED") -f:SetScript("OnEvent", function() RescanMyInventory() end) -``` - -A trade with 6 stacks (12 `BAG_UPDATE`s, all processed in one -frame) produces exactly 1 `BAG_UPDATE_DELAYED` at the end of the -frame — matches Classic Era 1.15.x's observed behavior. - -Implemented by three hooks, none in regions other DLLs touch: -- `FUN_004F91A0` / `FUN_004F9370` (bag subsystem at `0x004F9xxx`) - — each just sets a `g_pending` flag, no fire -- `FUN_0066FD50` (engine's per-frame world-subsystem update at - `0x0066xxxx`, deep in the rendering pipeline, only one caller in - the entire binary) — drains the flag at the tail of the world - tick - -The world-tick hook is a tail hook (run original first, then fire -DELAYED), so the fire happens after every other per-frame world -work completes. Addon callbacks see DELAYED after their normal -event handlers. - -> **Coverage limitation.** The keyring `BAG_UPDATE(-2)` path goes -> through a separate function (`FUN_004F8DB0`) that uses -> `__thiscall` with an awkward register-arg shape. Keyring updates -> currently won't trigger `BAG_UPDATE_DELAYED`. Player bag (0..4) -> and bank (5..10) updates work normally — the 95% case. - -### Player input-state events - -Three pairs of zero-payload events fired from a single per-frame -`Tick::WorldTick` callback that reads input state once and edge- -detects each pair. - -| Event | Fires on | Source | -|-------|----------|--------| -| `PLAYER_STARTED_MOVING` / `PLAYER_STOPPED_MOVING` | WASD or autorun toggle | UI-input controller flags at `*0x00BE1148 + 0x04` (`0x10` W \| `0x20` S \| `0x40` A \| `0x80` D \| `0x1000` autorun) | -| `PLAYER_STARTED_TURNING` / `PLAYER_STOPPED_TURNING` | Mouselook bit held AND character body yaw is changing | Mouselook bit `0x01` + per-frame delta on `CGPlayer + 0x9C4` (body yaw, radians) | -| `PLAYER_STARTED_LOOKING` / `PLAYER_STOPPED_LOOKING` | Free-look bit held AND camera-relative yaw is changing | Free-look bit `0x02` + per-frame delta on `[*0x00B4B2BC + 0x65B8] + 0xF0` (camera yaw, radians) | - -```lua -local f = CreateFrame("Frame") -for _, ev in ipairs({ - "PLAYER_STARTED_MOVING", "PLAYER_STOPPED_MOVING", - "PLAYER_STARTED_LOOKING", "PLAYER_STOPPED_LOOKING", - "PLAYER_STARTED_TURNING", "PLAYER_STOPPED_TURNING", -}) do - f:RegisterEvent(ev) -end -f:SetScript("OnEvent", function(_, event) print(event) end) -``` - -**Key-state semantics for MOVING**: `STOPPED_MOVING` fires the -instant the movement keys release, even if the character is still -airborne from a jump. Matches retail (verified empirically). For -an "is the character actually displacing this frame" signal, use -`GetUnitSpeed("player")` and watch the first return. - -**Latched semantics for TURNING and LOOKING**: each pair fires -exactly once per RMB / LMB hold. STARTED waits until both the -mouse-button bit is held AND the relevant yaw has actually -changed (matches retail's "camera has moved" semantics — clicking -without dragging doesn't fire). STOPPED fires when the button bit -clears (RMB / LMB release). The latch stays on through any drag- -stop-drag motion within a single hold; no spurious flapping. - -The camera-relative yaw at `[camera + 0xF0]` stays at 0 during -RMB-mouselook (camera rotates *with* the character, so its offset -from the character doesn't change), so TURNING and LOOKING are -cleanly separable: RMB only fires TURNING, LMB only fires LOOKING. - -Implementation: single subscriber on the shared `Tick::WorldTick` -registry (same `MinHook` on `FUN_0066FD50` shared with -`BAG_UPDATE_DELAYED`). When any of the input controller / player / -camera pointers is null (pre-login, loading screen, character -select), all states reset so the next valid tick doesn't fire -spurious STOPPED transitions. - -### `GLOBAL_MOUSE_DOWN` / `GLOBAL_MOUSE_UP` events - -Fires on every raw mouse-button press or release while WoW has -focus. Payload is the button identifier string — matches modern -WoW's signature exactly. - -```lua -local f = CreateFrame("Frame") -f:RegisterEvent("GLOBAL_MOUSE_DOWN") -f:RegisterEvent("GLOBAL_MOUSE_UP") -f:SetScript("OnEvent", function(_, event, button) - print(event, button) -- "GLOBAL_MOUSE_DOWN", "LeftButton" -end) -``` - -| Payload | Source | -|---------|--------| -| `"LeftButton"` | `VK_LBUTTON` | -| `"RightButton"` | `VK_RBUTTON` | -| `"MiddleButton"` | `VK_MBUTTON` | -| `"Button4"` | `VK_XBUTTON1` | -| `"Button5"` | `VK_XBUTTON2` | - -Distinct from per-frame `OnMouseDown` scripts — these fire even -when the click misses every UI frame (clicks in the world / on -nothing). Distinct from `PLAYER_STARTED_LOOKING` / -`PLAYER_STARTED_TURNING` — those are camera-rotation events; -these are raw input events. - -**Focus-gated.** Polls Win32 `GetAsyncKeyState` per frame on the -shared `Tick::WorldTick` registry. DOWN transitions are only -honored when WoW is the foreground window — clicking in another -app while alt-tabbed doesn't fire. UP transitions always fire, -even if the user alt-tabbed mid-click, so an addon never gets -left in a "button is held" state. - -## 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 -``` - -### `LE_EXPANSION_*` - -The retail / Classic Era expansion-level enum, exposed as Lua globals -so addons backporting from later expansions don't have to gate on -`if LE_EXPANSION_CLASSIC then` (the constant being defined is itself -the version probe). Values match the modern `Enum.ExpansionLevel` -table. - -| Constant | Value | -|---------------------------------------|------:| -| `LE_EXPANSION_LEVEL_CURRENT` | `0` *(this is Classic)* | -| `LE_EXPANSION_CLASSIC` | `0` | -| `LE_EXPANSION_BURNING_CRUSADE` | `1` | -| `LE_EXPANSION_WRATH_OF_THE_LICH_KING` | `2` | -| `LE_EXPANSION_CATACLYSM` | `3` | -| `LE_EXPANSION_MISTS_OF_PANDARIA` | `4` | -| `LE_EXPANSION_WARLORDS_OF_DRAENOR` | `5` | -| `LE_EXPANSION_LEGION` | `6` | -| `LE_EXPANSION_BATTLE_FOR_AZEROTH` | `7` | -| `LE_EXPANSION_SHADOWLANDS` | `8` | -| `LE_EXPANSION_DRAGONFLIGHT` | `9` | -| `LE_EXPANSION_WAR_WITHIN` | `10` | -| `LE_EXPANSION_MIDNIGHT` | `11` | - -```lua --- Classic version check using modern idiom -if LE_EXPANSION_LEVEL_CURRENT < LE_EXPANSION_BURNING_CRUSADE then - -- pure-1.x (vanilla / Classic Era) code path -end - --- Probe for ClassicAPI presence -if LE_EXPANSION_LEVEL_CURRENT then - -- the constants are defined → ClassicAPI is loaded -end -``` - -### `LE_ITEM_QUALITY_*` - -The item-quality enum (modern `Enum.ItemQuality`), exposed as Lua -globals so addons backporting modern code can do -`if quality >= LE_ITEM_QUALITY_RARE then ...` against the integer -quality returned by `GetItemInfo` / `C_Item.GetItemInfoInstant`. - -| Constant | Value | Color in tooltip | -|--------------------------------|------:|------------------| -| `LE_ITEM_QUALITY_POOR` | `0` | gray (junk) | -| `LE_ITEM_QUALITY_COMMON` | `1` | white | -| `LE_ITEM_QUALITY_UNCOMMON` | `2` | green | -| `LE_ITEM_QUALITY_RARE` | `3` | blue | -| `LE_ITEM_QUALITY_EPIC` | `4` | purple | -| `LE_ITEM_QUALITY_LEGENDARY` | `5` | orange | -| `LE_ITEM_QUALITY_ARTIFACT` | `6` | gold *(TBC+ only)* | -| `LE_ITEM_QUALITY_HEIRLOOM` | `7` | light blue *(WotLK+ only)* | -| `LE_ITEM_QUALITY_WOWTOKEN` | `8` | orange *(WoD+ only)* | - -Values 0..5 (POOR..LEGENDARY) correspond to actual qualities present -in vanilla 1.12. Higher values are exposed for source compatibility -with modern addons — vanilla items will never carry those quality -values, so a comparison like `quality == LE_ITEM_QUALITY_HEIRLOOM` -trivially never matches and the rest of the code path is unreachable. - -```lua -local _, _, quality = GetItemInfo(itemID) -if quality and quality >= LE_ITEM_QUALITY_RARE then - -- highlight in UI -end -``` - -### `LE_UNIT_STAT_*` - -The primary-stat enum (modern `Enum.UnitStat`), exposed as Lua globals -so addons can index `UnitStat(unit, statIndex)` symbolically: - -| Constant | Value | Stat | -|-------------------------|------:|------| -| `LE_UNIT_STAT_STRENGTH` | `1` | Strength | -| `LE_UNIT_STAT_AGILITY` | `2` | Agility | -| `LE_UNIT_STAT_STAMINA` | `3` | Stamina | -| `LE_UNIT_STAT_INTELLECT` | `4` | Intellect | -| `LE_UNIT_STAT_SPIRIT` | `5` | Spirit | - -Values are stable across every WoW expansion — `UnitStat("player", 1)` -has always returned strength. - -```lua -local _, effective = UnitStat("player", LE_UNIT_STAT_AGILITY) -``` - -### `Enum.AddOnSecurityStatus` - -The integer enum `C_AddOns.GetAddOnSecurity` returns. Matches -Blizzard's `Enum.AddOnSecurityStatus`: - -| Value | Field | Notes | -|------:|----------------|-------| -| `0` | `Secure` | Blizzard-signed addons. | -| `1` | `Insecure` | User addons; default for any registered addon. | -| `2` | `Banned` | Server-disqualified entries. | -| `3` | `NotAvailable` | No addon by that name / index. | - -```lua -if C_AddOns.GetAddOnSecurity(name) == Enum.AddOnSecurityStatus.Secure then - -- it's a Blizzard_* addon -end -```