Two phases, because every item move is a server round trip and the second phase reads slot contents the first changed. Phase one packs partial stacks; phase two runs on the next Bag::UpdateDelayed, plans the whole layout, and fires the swaps as one batch, tracking each item's live position rather than re-reading a layout it is mutating. The ordering is ours, since retail computes it in code we cannot read and its categories have no counterpart here: hearthstone, gear by descending quality, consumables, reagents, trade goods, quest items, everything else by quality, junk last and filled from the far end. Then class, subclass, name, fuller stacks first - a real tuple comparator, so there is no zero-padding to overflow and no placeholder name to wedge an unnamed item among real ones. An item whose data has not arrived is pinned in place with its slot withheld, rather than ranked by guesswork. Neither phase may touch the Lua stack, since phase two runs from a bag update callback. Hence Lua-free ContainersFrom / AutoStoreFrom / MoveCountFrom, with the Lua-taking forms reduced to resolving the source pointer and delegating, plus a direct invMgr walk instead of ResolveBag. Five things had to be found the hard way, every one of them the client's local state disagreeing with the server's: - Never plan a swap between two stacks of the same item. Player::SwapItem tries a MERGE before it considers swapping and returns if that succeeds, collapsing two slots into one or redistributing counts and leaving both in place. Neither is a swap, so a single collision invalidated the bookkeeping for every move after it in the batch. One collision in a 55-item bag turned one pass into three. - Entry marked "unplaced" with destBag = -1, safe while bag IDs were 0..4 and wrong the moment the main bank joined as bagID -1: every item bound for the main bank read as unplaced and had its move dropped, so nothing could move into the main bank at all. The sentinel is destSlot now, which cannot collide because slots are 1-based. - FUN_INVENTORY_SWAP's last argument gates a pre-send confirmation check. With 0, a Bind-on-Equip item the character could wear is stashed behind the bind dialog and NO PACKET IS SENT - silently, since the builder returns void. Now passes 1, which is what the engine itself does when re-issuing a swap after the dialog is accepted, and is correct here because both endpoints are always bag content slots where nothing binds. - CMSG_AUTOSTORE_BAG_ITEM cannot merge across bags. Its destination byte can only be INVENTORY_SLOT_BAG_0 (255) for the player, and server-side that is the specific-container branch: keyring and backpack only. The search-every-bag path is NULL_BAG (0), which the builder cannot emit. Both sets now use one explicit two-pointer merge that addresses both endpoints and works everywhere. It costs a packet per transfer rather than per emptied source, which is the price of being correct. - The merge loop must choose split-versus-swap from its own model, not the item's live stack count. The batch goes out in one frame with no replies, so descriptors still hold pre-batch counts; a move the model knew was the last of a stack went out as a split, and the server rejects a split that would empty its source. Consolidation packs fully rather than stopping once a slot is freed: 9 and 2 with a cap of 10 become 10 and 1. It settles in one pass and sends nothing on the next call, because a packed group has every stack full except the last, so the first step walks straight to the end. Bank specifics: ViewForBag gains the main bank (bagID -1, inside the player's own invMgr) and bank bags (5..10, each with its own), which can themselves be specialty bags. Bank bags resolve only once the bank window has been opened, which is the right gate rather than an accident - the server refuses bank moves without it, so a bank sort with the bank closed finds no cells and does nothing instead of dispatching a batch that would be rejected wholesale. _classicapi_SortBagsStats() and _classicapi_SortBagsBags() report the last pass and the per-bag view. Both earned their keep: the stats ruled out our side of the swap divergence by showing a complete plan fully dispatched with zero local failures, and the per-bag dump ended the sentinel hunt by eliminating the entire area three successive guesses had been aimed at.
ClassicAPI
ClassicAPI is a DLL for World of Warcraft 1.12.1 (Vanilla / Turtle WoW). It backports a large part of the modern WoW API — 550+ functions and 50+ events, plus much of Lua 5.1 — into the 1.12 client, so addons written for later versions (3.3.5+ or Classic Era) run with little or no change.
It hooks the engine after WoW boots and registers everything the same way WoW registers its own Lua functions. Nothing else to install — the DLL is self-contained.
Highlights
The headline features. Each one takes effect as soon as the DLL loads, so your existing addons benefit without any code changes. The complete per-function reference is in docs/API.md.
Lua 5.1 compatibility
The flagship feature: run modern Lua 5.1 addon code on 1.12's Lua 5.0 VM.
| Feature | Effect |
|---|---|
| Syntax | Compiles the Lua 5.1 length (#), modulo (%), ...-expression, 0x hex-literal, and leveled long bracket ([=[ ]=]) syntax that vanilla's Lua 5.0 rejects, by rewriting addon source before it compiles. Each addon file also receives its (name, table) through ... (local name, tbl = ...). |
| Upvalue limit | A function can use up to 60 upvalues, the outer locals it refers to, matching Lua 5.1. Lua 5.0 stops at 32 and rejects the whole file, so a large handler that reads many file-level locals can be valid 5.1 and still fail to load here. Nothing changes for a function within 32. |
| String methods | Every string value accepts method calls — ("asd"):upper(), ("%d gold"):format(n), msg:match("^!(%w+)") — resolving through the string table, the way Lua 5.1 works. Works on literals and variables, in-world and on the login screen, and inside coroutines. |
| Script-handler arguments | Frame-script handlers receive their values as positional arguments — OnMouseWheel(self, delta), OnClick(self, button), OnEvent(self, event, ...), etc. — so modern addon ports work unmodified. The this / arg1 globals stay set. A handler that declares no parameters is unaffected. A handler that declared a parameter and expected nil now receives its real value. On by default. SetModernScriptArgs(false) restores exact vanilla dispatch. |
Modern client behaviors
| Feature | Effect |
|---|---|
| Inline textures | Draws inline texture markup (|T…|t) and atlas markup (|A…|a) as icons in FontStrings, chat, and tooltips. This covers item and spell icons, raid-target markers, and the coin icons in money strings. GetStringWidth and GetStringHeight count the icons, so measured width and text wrapping stay correct. Done in pure C++ by hooking the engine's text pipeline — no addon. |
| Tooltip line cap | Lifts GameTooltip's hard 30-line limit to 60 for every GameTooltipTemplate frame (GameTooltip, ShoppingTooltip1/2, ItemRefTooltip, AtlasLoot, …). Stat-heavy tooltips and comparison blocks (e.g. pfUI's eqcompare) no longer have their extra lines silently dropped. Done in pure C++ by growing the engine's FontString pool at tooltip-creation time. |
| Event-driven nameplates | The modern C_NamePlate API, driven by real events. NAME_PLATE_UNIT_ADDED / NAME_PLATE_UNIT_REMOVED fire as plates appear and vanish, nameplate1..nameplateN tokens resolve with every UnitX function (and fire UNIT_HEALTH, UNIT_AURA, … as arg1 == "nameplateN"), and C_NamePlate.GetNamePlateForUnit / GetNamePlates hand back the live frames. |
| Focus target | A sticky focus unit. FocusUnit("target") pins it and ClearFocus() drops it, with PLAYER_FOCUS_CHANGED on every change. The focus / focustarget tokens resolve with every UnitX function and fire unit events (UNIT_HEALTH, UNIT_AURA, … as arg1 == "focus"), and the predefined FOCUSTARGET / TARGETFOCUS keybinds are ready to set. |
Retail-like /reload |
/reload picks up addon changes made while the game runs. A new folder under Interface\AddOns\ registers and loads as a normal addon, new files added to an existing addon's TOC load, a newly installed addon's first SavedVariables save survives /reload, ## metadata edits (## SavedVariables:, ## Dependencies:, ## Title:, …) take effect, and a deleted addon folder drops from the addon list. |
| Multi-flavor & conditional TOC | Loads modern multi-flavor addons that ship one folder. Selects a version-specific TOC (<Name>_ClassicAPI.toc or <Name>_Turtle.toc) and the matching keybinding file (Bindings_ClassicAPI.xml / Bindings_Turtle.xml), accepts a comma-separated ## Interface: version list (compatible when it includes the client version 11200), and honors per-line [AllowLoadGameType] / [AllowLoadTextLocale] conditions and [Family] / [Game] / [TextLocale] path variables inside a TOC. |
| Launch switches | Options you add to the shortcut that starts the game. -config <name> reads and writes WTF\<name> in place of WTF\Config.wtf, so one install can hold several settings profiles. -gluescript and -gluescriptFile run Lua at the login and character-select screens, every time those screens appear. -gamescript and -gamescriptFile run it one time, after you enter the world. Each script runs after the interface has loaded, so it can call interface functions and use frames. |
| Any texture size | Textures load at any size and any shape. Width and height do not need to be powers of two, and there is no fixed upper limit. The only limit is the maximum texture size of your graphics card. This applies to every texture path: SetTexture, sprite sheets, inline textures, tooltips, and masks. The client allocates memory for a large texture only when an addon loads one, so small textures cost nothing extra. |
Full API reference
Everything ClassicAPI adds, in full. Each section is collapsed — click a heading to expand it. For signatures and return values, see the per-function reference in docs/API.md.
In-game Lua calls — 550+ functions across ~60 namespaces
| Namespace | Calls |
|---|---|
| Action | GetActionInfo |
| AddOns | C_AddOns.DoesAddOnExist, C_AddOns.GetAddOnLocalTable, C_AddOns.GetAddOnName, C_AddOns.GetAddOnNotes, C_AddOns.GetAddOnOptionalDependencies, C_AddOns.GetAddOnSecurity, C_AddOns.GetAddOnTitle, C_AddOns.IsAddOnLoadable, C_AddOns.IsAddOnLoaded, C_AddOns.LoadAddOn |
| AuctionHouse | C_AuctionHouse.PostItem |
| Bindings | SetBindingSpell, SetBindingItem, SetBindingMacro, SetBindingClick, SetOverrideBinding, SetOverrideBindingSpell, SetOverrideBindingItem, SetOverrideBindingMacro, SetOverrideBindingClick, ClearOverrideBindings |
| Chat | GetCurrentChatGUID |
| ChatBubbles | C_ChatBubbles.GetAllChatBubbles |
| Class | FillLocalizedClassList |
| ColorUtil | C_ColorUtil.ConvertRGBToHSV, C_ColorUtil.ConvertHSVToRGB, C_ColorUtil.ConvertHSVToHSL, C_ColorUtil.ConvertHSLToHSV, C_ColorUtil.ConvertHSLToRGB, C_ColorUtil.GenerateTextColorCode, C_ColorUtil.WrapTextInColor, C_ColorUtil.WrapTextInColorCode |
| Combat | InCombatLockdown, StartAttack, StopAttack |
| Console | CalculateStringEditDistance, ConsoleEcho, ConsoleExec, ConsoleGetAllCommands, ConsoleGetColorFromType, ConsoleGetFontHeight, ConsoleIsActive, ConsolePrintAllMatchingCommands, SetConsoleKey |
| CVar | C_CVar.AreCVarsLoaded, C_CVar.DoesCVarExist, C_CVar.GetCVarBitfield, C_CVar.GetCVarBool, C_CVar.GetCVarInfo, C_CVar.SetCVarBitfield |
| Cursor | GetCursorInfo |
| Container | C_Container.AutoStoreItem, C_Container.CalculateTotalNumberOfFreeBagSlots, C_Container.GetContainerItemCharges, C_Container.GetContainerItemDurability, C_Container.GetContainerItemID, C_Container.GetContainerItemInfo, C_Container.GetContainerItemRepairCost, C_Container.GetContainerNumFreeSlots, C_Container.GetItemCooldown, C_Container.HasContainerItem, C_Container.IsContainerItemOpenable, C_Container.MoveItem, C_Container.PlayerHasHearthstone, C_Container.SortBags, C_Container.SortBankBags, C_Container.SwapItems, C_Container.UseHearthstone, GetItemCooldown |
| Creature | C_CreatureInfo.GetCreatureID, C_CreatureInfo.GetCreatureInfoByID, C_CreatureInfo.RequestLoadCreatureByID, C_CreatureInfo.GetRaceInfo, C_CreatureInfo.GetClassInfo, C_CreatureInfo.GetCreatureFamilyInfo, C_CreatureInfo.GetCreatureFamilyIDs, C_CreatureInfo.GetFactionInfo, C_CreatureInfo.GetCreatureTypeInfo, C_CreatureInfo.GetCreatureTypeIDs |
| Currency | GetCoinTextureString, C_CurrencyInfo.GetCoinTextureString |
| EncodingUtil | C_EncodingUtil.CompressString, C_EncodingUtil.DecompressString, C_EncodingUtil.EncodeBase64, C_EncodingUtil.DecodeBase64, C_EncodingUtil.EncodeHex, C_EncodingUtil.DecodeHex, C_EncodingUtil.SerializeJSON, C_EncodingUtil.DeserializeJSON, C_EncodingUtil.SerializeCBOR, C_EncodingUtil.DeserializeCBOR |
| EquipmentSet | C_EquipmentSet.CanUseEquipmentSets, C_EquipmentSet.ClearIgnoredSlotsForSave, C_EquipmentSet.CreateEquipmentSet, C_EquipmentSet.DeleteEquipmentSet, C_EquipmentSet.EquipmentSetContainsLockedItems, C_EquipmentSet.GetEquipmentSetID, C_EquipmentSet.GetEquipmentSetIDs, C_EquipmentSet.GetEquipmentSetInfo, C_EquipmentSet.GetIgnoredSlots, C_EquipmentSet.GetItemIDs, C_EquipmentSet.GetItemLocations, C_EquipmentSet.GetNumEquipmentSets, C_EquipmentSet.IgnoreSlotForSave, C_EquipmentSet.IsSlotIgnoredForSave, C_EquipmentSet.ModifyEquipmentSet, C_EquipmentSet.SaveEquipmentSet, C_EquipmentSet.UnignoreSlotForSave, C_EquipmentSet.UseEquipmentSet |
| Events | C_EventUtils.IsEventValid, GetFramesRegisteredForEvent |
| Expansion | ClassicExpansionAtLeast, ClassicExpansionAtMost, GetClassicExpansionLevel |
| Faction | C_Reputation.GetFactionDataByID, C_Reputation.GetFactionDataByIndex, C_Reputation.GetFactionStandings, C_Reputation.GetLastStandingChange, C_Reputation.GetWatchedFactionData, C_Reputation.IsFactionActive, C_Reputation.IsFactionActiveByID, C_Reputation.IsFactionInactive, C_Reputation.SetFactionActive, C_Reputation.SetFactionActiveByID, C_Reputation.SetFactionInactive, C_Reputation.SetFactionInactiveByID, C_Reputation.SetSelectedFaction, C_Reputation.SetSelectedFactionByID, C_Reputation.SetWatchedFactionByID, C_Reputation.ToggleFactionAtWar, C_Reputation.ToggleFactionAtWarByID, GetFactionIDByIndex, GetFactionInfoByID, GetFactionParentID |
| Focus | ClearFocus, FocusUnit |
| Frame | region:SetPoint("point") (one-arg form), region:SetSize, region:GetSize, region:IsMouseOver, region:GetRect, region:IsDragging, GetMouseFoci, frame:SetShown, fontstring:GetStringHeight, fontstring:GetUnboundedStringWidth, fontstring:GetWrappedWidth, fontstring:GetNumLines, fontstring:GetLineHeight, fontstring:IsTruncated, fontstring:SetMaxLines, fontstring:GetMaxLines, fontstring:SetFormattedText, texture:SetRotation, texture:GetRotation, texture:SetVertexOffset, texture:GetVertexOffset, texture:SetColorTexture, texture:SetAtlas, texture:GetAtlas, texture:ResetTexCoord, texture:SetSpriteSheetCell, texture:SetMask, frame:CreateMaskTexture, texture:AddMaskTexture, texture:RemoveMaskTexture, texture:GetNumMaskTextures, texture:GetMaskTexture, fontstring:SetRotation, fontstring:GetRotation, editBox:SetCursorPosition, editBox:GetCursorPosition, editBox:GetUTF8CursorPosition, editBox:ClearHighlightText, editBox:HasFocus, editBox:HasText, editBox:SetHighlightColor, editBox:GetHighlightColor, editBox:ClearHistory, frame:SetResizeBounds, frame:HookScript, frame:IsEventRegistered, frame:GetEffectiveAlpha, frame:SetAttribute, frame:SetAttributeNoHandler, frame:ClearAttribute, frame:GetAttribute, OnAttributeChanged (script), SetModernScriptArgs, GetModernScriptArgs, PreClick (script), PostClick (script), GetClickFrame |
| FriendList | C_FriendList.GetFriendInfo, C_FriendList.GetFriendInfoByIndex, C_FriendList.GetNumFriends, C_FriendList.GetNumOnlineFriends, C_FriendList.GetNumWhoResults, C_FriendList.GetWhoInfo, C_FriendList.IsFriend, C_FriendList.IsIgnored, C_FriendList.IsIgnoredByGuid, C_FriendList.IsWhoQueryPending, C_FriendList.SendWhoQueryByName, C_FriendList.SetFriendNotes, C_FriendList.SetFriendNotesByIndex |
| GameObject | C_GameObjectInfo.GetGameObjectInfoByID, C_GameObjectInfo.RequestLoadGameObjectByID, ClosestGameObjectPosition |
| Glue | C_Glue.IsOnGlueScreen |
| Gossip | C_GossipInfo.CloseGossip, C_GossipInfo.GetActiveQuests, C_GossipInfo.GetAvailableQuests, C_GossipInfo.GetNumActiveQuests, C_GossipInfo.GetNumAvailableQuests, C_GossipInfo.GetNumOptions, C_GossipInfo.GetOptions, C_GossipInfo.GetText, C_GossipInfo.SelectActiveQuest, C_GossipInfo.SelectAvailableQuest, C_GossipInfo.SelectOption, C_GossipInfo.SelectOptionByIndex |
| GameTooltip | GameTooltip:AddSpellByID, GameTooltip:GetGameObject, GameTooltip:GetItem, GameTooltip:GetOwner, GameTooltip:GetSpell, GameTooltip:GetUnitGUID, GameTooltip:HasGameObject, GameTooltip:HasItem, GameTooltip:HasSpell, GameTooltip:HasUnit, GameTooltip:IsEquippedItem, GameTooltip:SetEquipmentSet, GameTooltip:SetHyperlinkCompareItem, GameTooltip:SetInventoryItemByID, GameTooltip:SetItemByGUID, GameTooltip:SetItemByID, GameTooltip:SetSpellByID, GameTooltip:SetTalentByID, GameTooltip:SetTotem, GameTooltip:SetUnitAura, OnTooltipSetItem, OnTooltipSetSpell, OnTooltipSetUnit, OnTooltipSetGameObject (scripts) |
| Hooks | hooksecurefunc |
| Input | GetMouseButtonClicked, IsLeftAltKeyDown, IsLeftControlKeyDown, IsLeftShiftKeyDown, IsModifierKeyDown, IsMouseButtonDown, IsRightAltKeyDown, IsRightControlKeyDown, IsRightShiftKeyDown |
| Instance | GetInstanceInfo |
| Item | C_Item.DoesItemExist, C_Item.DoesItemExistByID, C_Item.EquipItemByName, C_Item.GetCurrentItemLevel, C_Item.GetDetailedItemLevelInfo, C_Item.GetEnchantInfo, C_Item.GetItemCount, C_Item.GetItemFamily, C_Item.GetItemGUID, C_Item.GetItemIcon, C_Item.GetItemIconByID, C_Item.GetItemID, C_Item.GetItemInfo, C_Item.GetItemInfoInstant, C_Item.GetItemInventorySlotInfo, C_Item.GetItemInventorySlotKey, C_Item.GetItemInventoryType, C_Item.GetItemInventoryTypeByID, C_Item.GetItemLink, C_Item.GetItemLocation, C_Item.GetItemMaxStackSize, C_Item.GetItemMaxStackSizeByID, C_Item.GetItemName, C_Item.GetItemNameByID, C_Item.GetItemQuality, C_Item.GetItemQualityByID, C_Item.GetItemSellPrice, C_Item.GetItemSellPriceByID, C_Item.GetItemSetID, C_Item.GetItemSetIDByID, C_Item.GetItemSetInfo, C_Item.GetItemSpell, C_Item.GetItemStatDelta, C_Item.GetItemStats, C_Item.GetItemClassInfo, C_Item.GetItemSubClassInfo, C_Item.GetItemUniqueness, C_Item.GetItemUniquenessByID, C_Item.GetStackCount, C_Item.GetWeaponEnchantInfo, C_Item.IsBound, C_Item.IsConsumableItem, C_Item.IsEquippableItem, C_Item.IsEquippedItem, C_Item.IsItemDataCached, C_Item.IsItemDataCachedByID, C_Item.IsItemGUIDInInventory, C_Item.IsItemInRange, C_Item.IsItemOpenable, C_Item.IsLocked, C_Item.LockItem, C_Item.LockItemByGUID, C_Item.PickupItem, C_Item.UnlockAllItems, C_Item.UnlockItem, C_Item.RequestLoadItemData, C_Item.RequestLoadItemDataByID, C_Item.UseAtCursor, C_Item.UseAtUnit, C_Item.UseItemByName, GetAuctionItemID, GetAuctionSellItemID, GetAverageItemLevel, GetCraftReagentItemID, GetInboxItemID, GetInventoryItemDurability, GetInventoryItemID, GetInventoryItemsForSlot, GetInventoryItemRepairCost, GetItemClassInfo, GetItemIcon, GetItemSubClassInfo, GetLootRollItemID, GetLootSlotItemID, GetMerchantItemID, GetQuestItemID, GetQuestLogItemID, GetTradePlayerItemID, GetTradeSkillItemID, GetTradeSkillReagentItemID, GetTradeTargetItemID, OffhandHasWeapon |
| Loot | C_Loot.GetNearbyLootableUnits, C_Loot.GetLastScanResults, C_Loot.IsScanInProgress, C_Loot.LootAllCorpses, C_Loot.LootUnit, C_Loot.LootUnitItem, C_Loot.ScanNearbyLoot |
| LootHistory | C_LootHistory.GetNumItems, C_LootHistory.GetItem, C_LootHistory.GetPlayerInfo, C_LootHistory.Clear |
| LossOfControl | C_LossOfControl.GetActiveLossOfControlData, C_LossOfControl.GetActiveLossOfControlDataCount |
| Lua | collectgarbage (5.1 options), coroutine.create, coroutine.resume, coroutine.running, coroutine.status, coroutine.wrap, coroutine.yield, CreateFromMixins, math.fmod, math.huge, math.modf, Mixin, select, string.gmatch, string.gsub (table replacement), string.match, string.reverse, strjoin, strreplace, strrev, strsplit, strtrim, table.count, table.maxn, table.wipe, unpack (range args) |
| Macros | C_Macro.CreateMacro, C_Macro.EditMacro, GetLooseMacroIcons, GetLooseMacroItemIcons, GetMacroIcons, GetMacroItemIcons, GetMacroSpell |
GetInboxItemLink, GetSendMailItemLink |
|
| Map | C_Map.CanSetUserWaypointOnMap, C_Map.ClearUserWaypoint, C_Map.GetAreaInfo, C_Map.GetAreas, C_Map.GetAreaTriggerInfo, C_Map.GetAreaTriggers, C_Map.GetBestMapForUnit, C_Map.GetFallbackWorldMapID, C_Map.GetMapAreaIDs, C_Map.GetMapArtLayers, C_Map.GetMapArtLayerTextures, C_Map.GetMapChildrenInfo, C_Map.GetMapInfo, C_Map.GetMapInfoAtPosition, C_Map.GetMapOverlays, C_Map.GetMapPosFromWorldPos, C_Map.GetMapRectOnMap, C_Map.GetMapWorldSize, C_Map.GetPlayerMapPosition, C_Map.GetUserWaypoint, C_Map.GetUserWaypointFromHyperlink, C_Map.GetUserWaypointHyperlink, C_Map.GetUserWaypointPositionForMap, C_Map.GetWorldPosFromMapPos, C_Map.HasUserWaypoint, C_Map.MapHasArt, C_Map.SetUserWaypoint |
| MapExplorationInfo | C_MapExplorationInfo.GetExploredMapTextures, C_MapExplorationInfo.GetUnexploredMapTextures |
| MerchantFrame | C_MerchantFrame.GetBuybackItemID, C_MerchantFrame.GetItemInfo, C_MerchantFrame.GetNumJunkItems, C_MerchantFrame.IsMerchantItemRefundable, C_MerchantFrame.IsSellAllJunkEnabled, C_MerchantFrame.SellAllJunkItems |
| NamePlate | C_NamePlate.GetNamePlateForGUID, C_NamePlate.GetNamePlateForUnit, C_NamePlate.GetNamePlateGUIDs, C_NamePlate.GetNamePlates |
| NameCache | C_PlayerCache.GetPlayerInfoByName, C_PlayerCache.IsEnabled, C_PlayerCache.IsScanEnabled, C_PlayerCache.RememberPlayer, C_PlayerCache.SetEnabled, C_PlayerCache.SetScanEnabled, GetPlayerInfoByGUID, UnitNameFromGUID |
| NewItems | C_NewItems.ClearAll, C_NewItems.IsNewItem, C_NewItems.RemoveNewItem |
| PlayerInfo | C_PlayerInfo.CanUseItem, C_PlayerInfo.GetClass, C_PlayerInfo.GetName, C_PlayerInfo.GetRace, C_PlayerInfo.GetSex, C_PlayerInfo.GUIDIsCreature, C_PlayerInfo.GUIDIsGameObject, C_PlayerInfo.GUIDIsPet, C_PlayerInfo.GUIDIsPlayer, C_PlayerInfo.IsConnected |
| Quest | C_QuestLog.GetNumQuestObjectives, C_QuestLog.GetQuestDetails, C_QuestLog.GetHeaderIndexForQuest, C_QuestLog.GetLogIndexForQuestID, C_QuestLog.GetQuestIDForLogIndex, C_QuestLog.GetTitleForQuestID, C_QuestLog.IsOnQuest, C_QuestLog.IsQuestDataCachedByID, C_QuestLog.IsUnitOnQuest, C_QuestLog.RequestLoadQuestByID, GetQuestLogLeaderBoardID |
| Spell | C_Spell.CancelSpellByID, C_Spell.CastAtCursor, C_Spell.CastAtUnit, C_Spell.CastingInfo, C_Spell.ChannelInfo, C_Spell.DoesSpellExist, C_Spell.GetSchoolString, C_Spell.GetSpellCooldown, C_Spell.GetSpellDescription, C_Spell.GetSpellDispelType, C_Spell.GetSpellEffectMechanics, C_Spell.GetSpellInfo, C_Spell.GetSpellLevelInfo, C_Spell.GetSpellLink, C_Spell.GetSpellMechanicByID, C_Spell.GetSpellName, C_Spell.GetSpellPowerCost, C_Spell.GetSpellRadius, C_Spell.GetSpellReagents, C_Spell.GetSpellRequiredTargetLevel, C_Spell.GetSpellSubtext, C_Spell.GetSpellTexture, C_Spell.IsAutoAttackSpell, C_Spell.IsCurrentSpell, C_Spell.IsNextMeleeSpell, C_Spell.IsRangedAutoAttackSpell, C_Spell.IsSelfBuff, C_Spell.IsSpellHarmful, C_Spell.IsSpellHelpful, C_Spell.IsSpellInRange, C_Spell.IsSpellPassive, C_Spell.IsSpellUsable, C_Spell.ResetsMeleeSwing, C_Spell.SpellHasRange, C_Spell.UnitCastingInfo, C_Spell.UnitChannelInfo, CanDualWield, CancelSpellByName, CastSpellNoToggle, GetCraftSpellID, GetSpellBonusDamage, GetSpellBonusHealing, GetSpellInfo, GetSpellLink, GetSpellRadius, GetSpellRequiredTargetLevel, GetSpellSchool, IsHarmfulSpell, IsHelpfulSpell, IsPassiveSpell, IsPlayerSpell, IsSpellKnown, IsUsableSpell, SpellHasRange |
| SpellBook | C_SpellBook.GetCurrentLevelSpells, C_SpellBook.GetSkillLineName, C_SpellBook.GetSkillLineRank, C_SpellBook.GetSpellBookItemInfo, C_SpellBook.GetSpellLevelLearned, C_SpellBook.GetSpellSkillLine, C_SpellBook.IsAutoAttackSpellBookItem, C_SpellBook.IsRangedAutoAttackSpellBookItem, FindSpellBookSlotByID |
| State | CancelShapeshiftForm, Dismount, GetMirrorTimerInfo, GetMirrorTimerProgress, GetShapeshiftFormID, GetSheathState, IsAssistingRitual, IsFalling, IsIndoors, IsInGroup, IsInRaid, IsLoggedIn, IsMounted, IsOutdoors, IsStealthed, IsSwimming |
| System | CopyToClipboard, GetPhysicalScreenSize |
| Talent | GetTalentIDByIndex, GetTalentSpellID |
| Targeting | GetPlayerFacing, TargetDirectionEnemy, TargetDirectionFriend, TargetNearest, TargetNearestEnemyPlayer, TargetNearestFriendPlayer |
| TaxiMap | C_TaxiMap.GetTaxiNodesForMap, C_TaxiMap.GetAllTaxiNodes, C_TaxiMap.GetTaxiPaths, C_TaxiMap.GetTaxiPathWaypoints, C_TaxiMap.GetTaxiRoute |
| Texture | C_Texture.GetAtlasElementID, C_Texture.GetAtlasElements, C_Texture.GetAtlasExists, C_Texture.GetAtlasID, C_Texture.GetAtlasInfo, C_Texture.RegisterAtlas |
| Time | C_DateAndTime.AdjustTimeByDays, C_DateAndTime.AdjustTimeByMinutes, C_DateAndTime.CompareCalendarTime, C_DateAndTime.GetCalendarTimeFromEpoch, C_DateAndTime.GetCurrentCalendarTime, C_DateAndTime.GetSecondsUntilDailyReset, C_DateAndTime.GetServerTimeLocal, C_Timer.After, C_Timer.NewTicker, C_Timer.NewTimer, GetServerTime, GetTimeCached |
| Totem | GetTotemInfo, GetTotemTimeLeft, GetTotemDuration, TargetTotem |
| Tracking | GetNumTrackingTypes, GetTrackingInfo, SetTracking |
| TradeSkillUI | C_TradeSkillUI.GetTradeSkillListLink, C_TradeSkillUI.GetCraftListLink, C_TradeSkillUI.GetTradeSkillListRecipes |
| UIColor | C_UIColor.GetColors |
| Unit | ClosestUnitPosition, GetUnitSpeed, UnitClassBase, UnitCreatedBySpell, UnitCreatureFamilyID, UnitCreatureID, UnitCreatureTypeID, UnitDistanceSquared, UnitGUID, UnitHealthMissing, UnitInLineOfSight, UnitInRange, UnitIsAFK, UnitIsDND, UnitIsFeignDeath, UnitIsInMyGuild, UnitIsMinion, UnitIsOtherPlayersPet, UnitIsPet, UnitIsPossessed, UnitOwnerGUID, UnitPosition, UnitPower, UnitPowerMax, UnitPowerMissing, UnitPowerType, UnitRaceBase, UnitSpellHaste, UnitSpellTargetName, UnitStandState, UnitSubName, UnitTokenFromGUID |
| UnitAuras | C_UnitAuras.GetAuraDataByIndex, C_UnitAuras.GetAuraDataBySlot, C_UnitAuras.GetAuraDataBySpellName, C_UnitAuras.GetAuraDispelTypeColor, C_UnitAuras.GetAuraSlots, C_UnitAuras.GetBuffDataByIndex, C_UnitAuras.GetDebuffDataByIndex, C_UnitAuras.GetPlayerAuraBySpellID, C_UnitAuras.GetUnitAuraBySpellID, C_UnitAuras.GetUnitAuras, C_UnitAuras.RegisterAuraDurationModifierByTrigger, C_UnitAuras.RegisterComboDuration, C_UnitAuras.UnitAura, C_UnitAuras.UnitAuraBySlot, C_UnitAuras.UnitBuff, C_UnitAuras.UnitDebuff |
| VoiceChat | C_VoiceChat.GetTtsVoices, C_VoiceChat.GetRemoteTtsVoices, C_VoiceChat.SpeakText, C_VoiceChat.StopSpeakingText, C_TTSSettings.GetSpeechRate, C_TTSSettings.GetSpeechVolume, C_TTSSettings.GetSpeechVoiceID, C_TTSSettings.GetVoiceOptionName, C_TTSSettings.SetSpeechRate, C_TTSSettings.SetSpeechVolume, C_TTSSettings.SetVoiceOption, C_TTSSettings.SetVoiceOptionByName, C_TTSSettings.SetDefaultSettings, C_TTSSettings.RefreshVoices |
| XMLUtil | C_XMLUtil.DoesTemplateExist, C_XMLUtil.GetTemplateInfo, C_XMLUtil.GetTemplates |
GlueXML calls — login / realm-select / character-select screens
Registered on the glue Lua state (the engine that runs the login, realm-select, and character-select screens). The persistence entries in the first row are glue-only — they exist to support GlueXML patches that need a small persistence surface across sessions. The rest of the table is in-game calls that we also mirror onto the glue state because GlueXML had no way to reach them otherwise.
| Group | Calls |
|---|---|
| Account | SaveAccount, DeleteAccount, GetSavedAccounts, LoginWithSavedAccount (passwords encrypted in Windows Credential Manager, scoped per realmlist; plaintext never returned to Lua) |
| CharacterList | GetSavedCharacterOrder, SetSavedCharacterOrder (persist to WTF\Account\...\ClassicAPI.txt) |
| CVar | GetCVar, SetCVar, RegisterCVar, GetCVarDefault, C_CVar.GetCVarBool (storage is process-global — writes from glue are visible in-world and vice versa) |
| Glue | C_Glue.IsFirstLoadThisSession, C_Glue.IsOnGlueScreen |
| Script | RunScript (compile and run a Lua chunk in the glue state's globals — useful for slash-command-style helpers in GlueXML) |
| State | IsLoggedIn |
Macros — engine-level parsing extensions
Engine-level extensions to macro parsing and dispatch — no new Lua functions. See the Macros section in the Lua reference for details.
| Form | What it does |
|---|---|
/cast <spellID> |
/cast 5019 casts Shoot if known; macro slot tags correctly for action-bar UI |
CastSpellByName("<spellID>") |
Same — numeric strings resolve through the engine's name resolver |
CastSpellNoToggle("<name>") in a macro |
Engine's macro parser now recognizes it as a primary-spell line, so the macro slot in an addon like pfUI highlights when its spell is auto-repeating or its self-aura is active |
Console commands — developer console (-console)
Registered on the engine's developer console (the ~ console available
when launching with -console), not as Lua functions. See the
Console section in the Lua reference for details.
| Command | What it does |
|---|---|
ExportInterfaceFiles code |
Extracts Blizzard's UI source (.lua/.xml/.toc/.xsd) from the MPQs to BlizzardInterfaceCode\ |
ExportInterfaceFiles art |
Extracts Blizzard's UI art (.blp/.tga) from the MPQs to BlizzardInterfaceArt\ |
ExportDBCFiles |
Extracts the client's .dbc tables from the MPQs to DBFilesClient\ |
Events — new events fired to addons
| Event | Payload |
|---|---|
BAG_NEW_ITEMS_UPDATED |
(none) |
BAG_UPDATE_DELAYED |
(none) |
EQUIPMENT_SETS_CHANGED |
(none) |
EQUIPMENT_SWAP_PENDING |
setID |
EQUIPMENT_SWAP_FINISHED |
success, setID |
FACTION_STANDING_CHANGED |
factionID, newStanding, repGained |
GLOBAL_MOUSE_DOWN |
button |
GLOBAL_MOUSE_UP |
button |
HEARTHSTONE_BOUND |
(none) |
ITEM_DATA_LOAD_RESULT |
itemID, success |
LOOT_HISTORY_ROLL_CHANGED |
itemIndex, playerIndex |
LOOT_HISTORY_ROLL_COMPLETE |
itemIndex |
LOOT_SCAN_COMPLETED |
(none) |
LOSS_OF_CONTROL_ADDED |
eventIndex |
LOSS_OF_CONTROL_UPDATE |
unitToken (always "player") |
MODIFIER_STATE_CHANGED |
keyName, down |
NAME_PLATE_CREATED |
nameplateFrame |
NAME_PLATE_UNIT_ADDED |
unitToken ("nameplateN") |
NAME_PLATE_UNIT_REMOVED |
unitToken ("nameplateN") |
PLAYER_EQUIPMENT_CHANGED |
equipmentSlot, hasCurrent |
PLAYER_FOCUS_CHANGED |
(none) |
PLAYER_STARTED_LOOKING |
(none) |
PLAYER_STOPPED_LOOKING |
(none) |
PLAYER_STARTED_MOVING |
(none) |
PLAYER_STOPPED_MOVING |
(none) |
PLAYER_STARTED_TURNING |
(none) |
PLAYER_STOPPED_TURNING |
(none) |
PLAYER_TOTEM_UPDATE |
totemSlot |
QUEST_ACCEPTED |
questLogIndex, questID |
QUEST_DATA_LOAD_RESULT |
questID, success |
QUEST_REMOVED |
questID |
QUEST_TURNED_IN |
questID, xpReward, moneyReward |
UNIT_SPELLCAST_SENT |
"player", target, castGUID, spellID, spellName, rank |
UNIT_SPELLCAST_START |
unit, castGUID, spellID, spellName, rank |
UNIT_SPELLCAST_STOP |
unit, castGUID, spellID, spellName, rank |
UNIT_SPELLCAST_DELAYED |
"player", castGUID, spellID, spellName, rank |
UNIT_SPELLCAST_SUCCEEDED |
unit, castGUID, spellID, spellName, rank |
UNIT_SPELLCAST_INTERRUPTED |
unit, castGUID, spellID, spellName, rank |
UNIT_SPELLCAST_FAILED |
"player", castGUID, spellID, spellName, rank |
UNIT_SPELLCAST_FAILED_QUIET |
"player", castGUID, spellID, spellName, rank |
UNIT_SPELLCAST_CHANNEL_START |
unit, castGUID, spellID, spellName, rank |
UNIT_SPELLCAST_CHANNEL_UPDATE |
"player", castGUID, spellID, spellName, rank |
UNIT_SPELLCAST_CHANNEL_STOP |
unit, castGUID, spellID, spellName, rank |
UNIT_SPELLCAST_RETICLE_TARGET |
"player", "", spellID, spellName, rank |
UNIT_SPELLCAST_RETICLE_CLEAR |
"player", "", spellID, spellName, rank |
UPDATE_INVENTORY_DURABILITY |
(none) |
UPDATE_SHAPESHIFT_FORM |
(none) |
USER_WAYPOINT_UPDATED |
(none) |
VOICE_CHAT_TTS_PLAYBACK_STARTED |
numConsumers, utteranceID, durationMS, destination |
VOICE_CHAT_TTS_PLAYBACK_FINISHED |
numConsumers, utteranceID, destination |
VOICE_CHAT_TTS_PLAYBACK_FAILED |
status, utteranceID, destination |
VOICE_CHAT_TTS_VOICES_UPDATE |
(none) |
Globals & enums
| Group | Constants |
|---|---|
| Version | CLASSIC_API_VERSION, INTERFACE_VERSION |
| Expansion | LE_EXPANSION_LEVEL_CURRENT, LE_EXPANSION_CLASSIC … LE_EXPANSION_MIDNIGHT |
| Item quality | LE_ITEM_QUALITY_POOR … LE_ITEM_QUALITY_WOWTOKEN |
| Unit stat | LE_UNIT_STAT_STRENGTH … LE_UNIT_STAT_SPIRIT |
| Addon security | Enum.AddOnSecurityStatus.{Secure,Insecure,Banned,NotAvailable} |
| Power type | Enum.PowerType.{HealthCost,None,Mana,Rage,Focus,Energy,Happiness} |
| Inventory type | Enum.InventoryType.Index*Type (0–34, e.g. IndexHeadType=1 … IndexRelicType=28) |
| Item class | Enum.ItemClass.{Consumable,Container,Weapon,Gem,Armor,Reagent,Projectile,Tradegoods,ItemEnhancement,Recipe,Quiver,Questitem,Key,Miscellaneous,…} (0–19) |
| Item quality | Enum.ItemQuality.{Poor,Common,Uncommon,Rare,Epic,Legendary,Artifact} (0–6) |
| Spellbook bank | Enum.SpellBookSpellBank.{Player,Pet} (0–1) |
| Spellbook item type | Enum.SpellBookItemType.{None,Spell,FutureSpell,PetAction,Flyout} (0–4; 1.12 only yields Spell/PetAction) |
Unit tokens — nameplateN, focus, markN
| Token | Resolves to |
|---|---|
nameplate1..nameplateN |
Unit behind the Nth visible nameplate, in creation-order. Works with every UnitX function — UnitName, UnitGUID, UnitClass, UnitHealth, etc. Suffix chains (nameplate1target, nameplate1targettarget) compose. See NamePlate / Unit tokens. |
focus / focustarget |
Sticky target set via FocusUnit, cleared via ClearFocus. Same UnitX coverage as nameplateN. Fires PLAYER_FOCUS_CHANGED on transition. See Focus. |
mark1..mark8 |
Unit currently wearing the Nth raid-target marker (mark1 = star … mark8 = skull). Same UnitX coverage as nameplateN, and fires unit events (UNIT_HEALTH, UNIT_AURA, …) with arg1 == "markN". UnitExists("markN") is false when the marker is unset, out of range, or on a non-unit. Suffix chains (mark1target) compose. See Unit tokens (markN). |
Bindings — direct-action and override binding families
ClassicAPI backports the direct-action and temporary override
binding families. Permanent bindings use the standard SPELL, ITEM,
MACRO, and CLICK command strings and can be saved normally. Overrides are
session-only, frame-owned, and support the usual priority flag.
See the Bindings API reference for signatures, precedence, execution behavior, macro-text usage, and 1.12 compatibility notes.
Predefined focus bindings. Injected into the engine's Targeting Functions group at FrameXML Bindings.xml load time, so they appear in the keybind UI alongside native targeting bindings instead of orphaned at the bottom.
| Binding | Action |
|---|---|
FOCUSTARGET |
FocusUnit("target") — pin current target as focus |
TARGETFOCUS |
TargetUnit("focus") — switch target to the focus |
See Predefined focus bindings for the implementation note.
Installation
Download the prebuilt ClassicAPI.dll from the
latest release
(or build it yourself). It's loaded with
VanillaFixes:
- Install VanillaFixes if it isn't already.
- Copy
ClassicAPI.dllinto your game directory. - Add
ClassicAPI.dlltodlls.txt. - Launch the game with
VanillaFixes.exe.
The bundled !!!ClassicAPI addon ships inside the DLL — no separate
addon download or install step needed.
Bundled addon: !!!ClassicAPI
The Lua-side companion library lives in
AddOns/!!!ClassicAPI/. It's a 1.12.1 /
Lua 5.0 backport of the modern Blizzard helpers that aren't engine
functions but that consumer code still expects to find as globals —
CallbackRegistryMixin, EventRegistry, ColorMixin + CreateColor,
Item / ItemLocation, MathUtil(Lerp / Clamp / CreateCounter),
TableUtil (tCompare, MergeTable, SafePack, etc.), and EventUtil
(ContinueOnAddOnLoaded etc.).
You don't have to install the addon manually — the DLL embeds
the contents of AddOns/!!!ClassicAPI/ and
registers them with the engine as a synthetic addon on startup, so
the library is always available when the DLL is loaded. It fires
ADDON_LOADED, supports SavedVariables, and is resolvable by name —
IsAddOnLoaded("!!!ClassicAPI"), GetAddOnInfo("!!!ClassicAPI"), and
## Dependencies: !!!ClassicAPI all work as usual.
It is intentionally always-on and cannot be disabled. The library
provides FrameXML-compat fixes that other addons and the DLL's own
features rely on, so leaving it toggleable would let a user (or a
one-off character-select uncheck) silently break them. The DLL
therefore hides it from the character-select AddOns list and
force-enables it every login — so it never appears as a checkbox and
can't be switched off. Being hidden means it's omitted from the
index-based GetNumAddOns() / GetAddOnInfo(i) enumeration, but every
by-name lookup and dependency reference still resolves normally.
If you drop the folder into your Interface/AddOns/ directory, that
copy's files win — the DLL's embedded version only serves files when
the engine's normal scan doesn't already have a newer entry under that
name. Useful for editing the Lua locally without rebuilding the DLL.
The hidden + force-enabled treatment applies either way (it's keyed to
the addon name, not to which copy serves the files), so the local copy
is also absent from the AddOns list. The dispatch is transparent:
addons consuming Mixin, ColorMixin, TableUtil, etc. behave
identically in both cases.
Bundled addon: DebugTools
A 1.12.1 / Lua 5.0 backport of Blizzard's Blizzard_DebugTools addon
lives in AddOns/DebugTools/.
It's an independent addon — it doesn't use anything ClassicAPI adds, and
ClassicAPI works fine without it. It's bundled here because it's the
natural companion for testing and debugging anything written against the
1.12 Lua surface (with or without the ClassicAPI extensions).
Slash commands provided:
| Command | Purpose |
|---|---|
/dump <expr> |
Pretty-print any Lua value, including tables and multi-return tuples. The right tool for inspecting return values from GetSpellInfo, C_Item.GetItemInfoInstant, etc. |
/etrace |
Event tracer window. /etrace start, /etrace stop, /etrace add EVENT, etc. |
/framestack (or /fstack) |
Tooltip showing the frame hierarchy under the mouse cursor. |
/luaerrors (or /scripterrors) |
Lua error display window. |
Lua globals provided (backports of Blizzard helpers):
| Global | Purpose |
|---|---|
print(...) |
Backport of Blizzard's print — concats varargs with " " and pushes to DEFAULT_CHAT_FRAME. Routes through setprinthandler's handler; falls back via geterrorhandler if the handler errors. |
setprinthandler(func) / getprinthandler() |
Install / query a custom print handler. Useful for redirecting print output in tests. |
tostringall(...) |
Apply tostring() to every vararg, preserving the count. Lua 5.0-compatible (uses arg.n since select doesn't exist in 5.0). |
To install: copy AddOns/DebugTools/ into your
Interface/AddOns/ directory like any other addon.
Building
Requires CMake (3.10+) and an MSVC toolchain that can target 32-bit Windows. WoW.exe is x86, so the DLL must be built as Win32; an x64 build will not load.
git submodule update --init --recursive # fetches MinHook, picojson, tinycbor
cmake -B build -A Win32
cmake --build build --config Release
The output is build/Release/ClassicAPI.dll.
To stamp a version into CLASSIC_API_VERSION, pass -DCLASSICAPI_TAG=vX.Y.Z
at configure time; the value exposed to Lua will be X*10000 + Y*100 + Z.
License
GPL v3 or later. See the headers in src/ for the full notice.