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 -```