brues-code 1da06d4a73 frame: attribute backport, modern script args, and SMSG hook consolidation (#13)
* frame: backport Frame:SetAttribute/GetAttribute + unit-frame mouseover/click

Adds native SetAttribute / SetAttributeNoHandler / GetAttribute on the base
Frame registry: a per-frame, case-insensitive value store with the 3.3.5
prefix/name/suffix getter precedence, stored on the frame's own Lua table.

A `unit` attribute makes the frame a mouseover source. A WorldTick poll of the
engine's mouse-focus frame (GetMouseFocus's global) calls the real mouseover
setter (FUN_00492890) for its unit -- 1:1 with hovering the 3D model: model
highlight, mouseover tooltip, UPDATE_MOUSEOVER_UNIT, and the native GUID slot.
Stomp-proof (the engine's 3D-hover setter is event-driven) and independent of
the frame's scripts, so an addon setting its own OnEnter can't break it.

A `type1`/`type2`/`type` attribute installs a chained OnClick on that frame only
(PCall-guarded, Button-only) that dispatches target / assist / focus on the
unit at click time, then runs any prior handler.

No global hooks: mouseover reads the mouse-focus global; clicks use the frame's
own OnClick. Deliberately does NOT MinHook the button-click dispatcher
(FUN_00779540) -- SuperWoW's click-casting owns that prologue and a second
inline hook corrupts the trampoline (ERROR #132).

* frame: extend attribute backport (one-verb click dispatcher + OnAttributeChanged)

The `type*` click path now mirrors retail's SecureActionButton_OnClick:
resolve ONE verb per click from the modifier/button-qualified `type`
attribute and perform it, instead of a fixed `type1=target`.

- Modifier/button resolution: `[alt-/ctrl-/shift-]type[1..5]` with
  prefix..name..suffix -> name..suffix -> name precedence, read from the
  live key state and the click's button.
- Verbs: target (with the engine's default-interaction precedence -
  cast a pending spell / drop a cursor item on the unit instead of
  switching target), assist, focus, spell, stopcasting, macro, and menu.
- Own-the-click: when a verb resolves we perform it and do NOT chain the
  frame's previous OnClick, so a configured `type1` no longer double-
  dispatches alongside an addon's own conditional click handler.
- Self-healing wire: addons that re-SetScript OnClick (pfUI on every raid
  relayout) clobber our closure; WireOnClick re-wraps a clobbered Lua
  handler but skips its own C closure, so re-setting `type*` recovers
  without double-chaining.

Dispatch goes straight to C++ where we own the code - no Lua round-trip
through the global table: spell -> Spell::AtUnit::CastByName (a native
unit-targeted cast; the unit's GUID is fed to the engine's dispatcher so
there's no target juggling, and ground-target spells land at the unit's
feet), focus -> Unit::Focus::Set, and the target verb's predicates ->
Spell::AtCursor::IsPlacementActive / Cursor::Info::HasItem. Only genuine
engine entries (TargetUnit/AssistUnit/SpellTargetUnit/DropItemOnUnit/
SpellStopCasting) and addon-provided functions still go through Lua
globals. Spell::AtUnit gains a C++ header sharing its CastCore with the
C_Spell.CastAtUnit Lua entry.

macro verb: takes the content from the `macrotext`/`macro` attribute and
prefers an addon-provided RunMacro (SuperCleveRoidMacros etc. - handles
named macros and extended macro text), falling back to running the text
natively when no RunMacro global is present. The native path runs each
line through the stock FrameXML ChatEdit_ParseText via a throwaway
edit-box (GetText closure + no-op __index), so it needs no addon.

menu/togglemenu verb: pops the standard unit dropdown at the cursor via
the new ClassicAPI_ToggleUnitMenu (Util/SecureUnitMenu.lua), resolving
the unit -> menu type with Blizzard's own generic resolver
(self->SELF, pet->PET, grouped player->PARTY, other player->PLAYER,
NPC->RAID_TARGET_ICON). Keeps the FrameXML dropdown logic in Lua with
the C side as a thin call.

OnAttributeChanged is now a real SetScript/GetScript/HookScript-able
frame script on every frame: SetAttribute fires it, SetAttributeNoHandler
suppresses it. Made settable by co-hooking the base-frame script-name
resolver FUN_0076a0d0 (the one every frame type delegates through) and
handing back an external per-frame {handler, context} cell for that name -
frames are immortal in 1.12, so the cell never goes stale. One hook does
it (vs the tooltip OnTooltipSet* work's five) because we already own the
firing side. 1.12 convention: the handler reads this = frame, arg1 = name,
arg2 = value. Recursion-guarded so a handler may itself SetAttribute.

* frame: add Frame:ClearAttribute (retail 11.2.0)

`cleared = frame:ClearAttribute(name)` removes an attribute and returns
whether it was set. Registered on the base Frame method registry next to
SetAttribute/GetAttribute, so every frame has it.

Routes through DoSet's nil-value path (removes the stored key, drops a
`unit` mouseover binding) but does NOT fire OnAttributeChanged — verified
against a live retail 11.2 client: SetAttribute fires the handler,
ClearAttribute fires nothing, and the return is true for a set attribute /
false when there was nothing to clear.

* frame: store attributes in the Lua registry, hidden from Lua

Attributes were kept as a subtable on the frame's own Lua table under a
control-char key ("\1ClassicAPIAttributes"). That key, while collision-
safe, is still enumerable via pairs(frame) and readable/writable from Lua.

Move the store to registry[frame] in the Lua registry (LUA_REGISTRYINDEX),
which has no _G path — so the attribute map is invisible to pairs(frame)
and can't be read or tampered with from script, matching how retail keeps
attributes C-side. Only PushSub changed (create/fetch now key the registry
by the frame table); GetAttribute/DoSet/CopyAttr sit on top unchanged.
1.12 frames are immortal, so the strong registry key never leaks. The dead
kAttrKey constant is removed.

Verified in-game: SetAttribute/GetAttribute still round-trip, and a
pairs(frame) scan no longer finds any ClassicAPI key.

* frame: add the `item` click verb (SecureActionButton item action)

type*="item" uses the modifier-qualified `item` attribute:
- a "bag slot" string (e.g. "0 1") -> UseContainerItem(bag, slot);
- otherwise an item name / itemID / link -> C_Item.UseItemByName(item, unit),
  passing the unit as the use target (self-use items ignore it, targeted
  ones like scrolls/bandages apply to it);
- the deprecated `bag` + `slot` attributes are honored when `item` is unset.

Both bag paths go through lua_call (new CallTableFunc2Str / CallGlobalNum2)
rather than a direct C++ call: the item-use bag walk does SetTop(L, 0), so
it needs its own Lua stack frame — a direct call would wipe the dispatcher's
stack. (spell stays direct because Spell::AtUnit is stack-free; the helper
comment records the distinction.) Retail's "bag slot" string is the
preferred form; the deprecated per-attribute form is supported too.

* docs: format the attribute click verbs as a table

The verbs were one long paragraph of nested parentheticals - hard to scan.
Replace it with a Verb | Extra attributes | Action table so each verb's
inputs and behavior are legible at a glance. Content-equivalent; no API change.

* frame: clear target on the `target` verb when unit is "none"

Retail's SecureActionButton target action treats a "none" unit as "clear
target". Match it: the `target` verb calls ClearTarget() when the resolved
`unit` is "none" (case-insensitive), before the normal cursor/spell
precedence. Mouseover already handles "none" implicitly (it resolves to
GUID 0 = no unit). Docs' target-verb row updated.

* frame: pass modern positional args to script handlers

Vanilla always invokes frame-script handlers with zero Lua args; the
handler reads this/arg1/event as globals. Modern addon ports write
SetScript("OnMouseWheel", function(self, delta) ...) and get nothing.

Co-hook both script runners -- FUN_FRAME_INVOKE_SCRIPT (no-arg scripts)
and FUN_FRAME_RUN_SCRIPT_ARGS (scripts with values) -- and reimplement
their pcall tail: keep the engine's exact this/argN global save-set-
restore and message-handler errfunc, but additionally push self +
arg1..argN as real positional arguments and pcall with nargs = 1+N.
Purely additive: a zero-param vanilla handler ignores the extras and
reads globals; a modern (self, delta) handler binds them.

OnEvent gets (self, event, arg1..argN), detected structurally by
matching the invoked handler ref against the frame OnEvent slot
(frame+0x0C) -- exact, since each SetScript makes a distinct ref.

Runtime switch SetModernScriptArgs()/GetModernScriptArgs(), default on;
when off both detours are a straight passthrough to the original runner,
which matters because FUN_FRAME_RUN_SCRIPT_ARGS is the hottest Lua path
in the engine (every OnUpdate frame). Verified in-game across
OnMouseWheel/OnClick/OnValueChanged/OnUpdate/OnEnter/OnLeave/OnEvent.

* net: consolidate spell SMSG hooks onto one dispatch funnel

The spell subsystem's per-opcode SMSG handlers (SpellGo, SpellStart,
SpellDelayed, ChannelStart/Update, SpellFailure, SpellFailedOther,
SpellCooldown) were each co-hooked directly -- and nampower (hadesmem)
plus SuperWoW detour the same prologues. Two inline hookers on one
prologue is the documented MinHook collision risk, and a whole-protocol
bisect fingered exactly this cluster as the crash-suspect surface.

Add Net::PacketDispatch: a receive-side mirror of Net::SendObserver that
co-hooks the single incoming-SMSG dispatch funnel FUN_NET_MESSAGE_DISPATCH
(0x00537AA0) -- a chokepoint nampower does NOT hook (it detours the leaf
handlers) -- and fans each packet out to opcode subscribers with the
cursor at the body and centralized save/restore.

Migrate all eight handlers to subscribers: aura/Source (SpellGo, which
re-decodes the packed guids + spellId the leaf handler used to hand it
pre-decoded), spell/Cast (Start/Delayed/Channel*/Failure*), and
lossofcontrol (Cooldown). The parse bodies are unchanged; only the hook
site moved. Subscribers run before the engine's leaf handler instead of
after a co-hook's original -- verified order-independent for all eight
(self-contained cache/state updates; SpellGo's aura-application handoff
rides a separate SMSG_UPDATE_OBJECT).

Cuts the ClassicAPI-nampower shared spell prologues from 10 to 3 (the
OnAura* method hooks, which have no packet chokepoint to relocate to).
One hook on an uncontended function replaces eight on contended ones.

Verified in-game: cast bars, channels (incl. Mind Control cast-then-
channel), pushback, remote-cast interrupt eviction, and C_LossOfControl
school lockouts all intact.

* ScriptArgs is back to opt-in

* frame: fix ScriptArgs comments to match opt-in default

* frame/net: dedupe packet observers, reuse Lua/token helpers, fix attr edge cases

Post-review cleanup of the attribute + SMSG-consolidation work.

- net: extract the shared packet-observer plumbing (PacketObserver.h) — the
  intrusive subscriber list, Subscribe(), and the read-opcode / reset-cursor /
  fan-out / restore loop — so Net::PacketDispatch (SMSG, u16) and
  Net::SendObserver (CMSG, u32) each reduce to a one-line hook thunk over
  FanOutByOpcode<OpcodeT>. Drops the dead per-namespace Callback aliases
  rather than keeping them as compat shims.

- Game::Lua: promote PushGlobalFunction / CallGlobal / CallGlobalString into
  the shared Lua helpers (a pattern several modules open-code); Frame
  attributes use them instead of private copies.

- frame/Attributes: resolve unit tokens through Unit::Identity::GuidForToken
  (engine resolver + player fast-path) instead of a duplicate raw-cast wrapper.

- frame/Attributes: wire the chained OnClick for every "type" action attribute
  the click resolver reads (IsTypeAttr: modifier prefixes + type1..type5), not
  just type/type1/type2 — a middle-click or modifier-only binding now installs.

- frame/Attributes: FireAttributeChanged snapshots and restores the caller's
  arg1/arg2 around the fire, so calling SetAttribute from inside a running
  script handler no longer clobbers its globals.
2026-08-03 00:37:36 -05:00
2026-05-15 23:12:16 -05:00
2026-05-15 23:12:16 -05:00
2026-07-15 01:22:14 -05:00

ClassicAPI

A small DLL for World of Warcraft 1.12.1 (Vanilla / Turtle WoW) that adds a collection of Lua API calls Blizzard never exposed in 1.12 but which make addon authoring noticeably less painful — primarily for backporting addons written against later API versions (3.3.5+) where these calls do exist.

The DLL hooks the FrameScript engine after WoW boots and registers its extensions through the same in-engine mechanisms WoW uses for its own Lua functions. No companion addon is required.

What's added

Full per-function reference: docs/API.md.

Calls

Namespace Calls
Action GetActionInfo
AddOns C_AddOns.DoesAddOnExist, C_AddOns.GetAddOnName, C_AddOns.GetAddOnNotes, C_AddOns.GetAddOnOptionalDependencies, C_AddOns.GetAddOnSecurity, C_AddOns.GetAddOnTitle, C_AddOns.IsAddOnLoadable, C_AddOns.IsAddOnLoaded
AuctionHouse C_AuctionHouse.PostItem
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
CVar C_CVar.GetCVarBool
Cursor GetCursorInfo
Container 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.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
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.GetFactionDataByIndex, C_Reputation.GetFactionStandings, C_Reputation.GetLastStandingChange, C_Reputation.GetWatchedFactionData, C_Reputation.SetWatchedFactionByID, GetFactionIDByIndex, GetFactionInfoByID, GetFactionParentID
Focus ClearFocus, FocusUnit
Frame region:SetPoint("point") (one-arg form), region:SetSize, region:GetSize, region:IsMouseOver, region:GetRect, region:IsDragging, frame:SetShown, frame:SetResizeBounds, frame:HookScript, frame:IsEventRegistered, frame:GetEffectiveAlpha
FriendList C_FriendList.IsWhoQueryPending, C_FriendList.SendWhoQueryByName
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 coroutine.create, coroutine.resume, coroutine.status, coroutine.wrap, coroutine.yield, CreateFromMixins, math.fmod, math.huge, math.modf, Mixin, select, string.gmatch, string.match, string.reverse, strjoin, strreplace, strrev, strsplit, strtrim, table.count, table.wipe
Macros GetLooseMacroIcons, GetLooseMacroItemIcons, GetMacroIcons, GetMacroItemIcons, GetMacroSpell
Mail GetInboxItemLink, GetSendMailItemLink
Map C_Map.GetAreaInfo, C_Map.GetAreas, C_Map.GetAreaTriggerInfo, C_Map.GetAreaTriggers, C_Map.GetBestMapForUnit, C_Map.GetMapAreaIDs, C_Map.GetMapOverlays, C_Map.GetMapWorldSize
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.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.IsRangedAutoAttackSpell, C_Spell.IsSelfBuff, C_Spell.IsSpellHarmful, C_Spell.IsSpellHelpful, C_Spell.IsSpellInRange, C_Spell.IsSpellPassive, C_Spell.IsSpellUsable, 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.GetSpellLevelLearned, C_SpellBook.GetSpellSkillLine, C_SpellBook.IsAutoAttackSpellBookItem, C_SpellBook.IsRangedAutoAttackSpellBookItem, FindSpellBookSlotByID
State CancelShapeshiftForm, Dismount, GetMirrorTimerInfo, GetMirrorTimerProgress, GetShapeshiftFormID, 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
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
TradeSkillUI C_TradeSkillUI.GetTradeSkillListLink, C_TradeSkillUI.GetCraftListLink, C_TradeSkillUI.GetTradeSkillListRecipes
UIColor C_UIColor.GetColors
Unit ClosestUnitPosition, GetUnitSpeed, UnitClassBase, UnitCreatureFamilyID, UnitCreatureTypeID, UnitDistanceSquared, UnitGUID, UnitHealthMissing, UnitInLineOfSight, UnitInRange, UnitIsAFK, UnitIsDND, UnitIsFeignDeath, UnitIsInMyGuild, UnitIsMinion, UnitIsOtherPlayersPet, UnitIsPet, UnitIsPossessed, UnitOwnerGUID, UnitPosition, UnitPower, UnitPowerMax, UnitPowerMissing, UnitPowerType, UnitRaceBase, UnitSpellHaste, UnitStandState, UnitSubName, UnitTokenFromGUID
UnitAuras C_UnitAuras.GetAuraDataByIndex, C_UnitAuras.GetAuraDataBySpellName, C_UnitAuras.GetAuraDispelTypeColor, C_UnitAuras.GetBuffDataByIndex, C_UnitAuras.GetDebuffDataByIndex, C_UnitAuras.GetPlayerAuraBySpellID, C_UnitAuras.GetUnitAuraBySpellID, C_UnitAuras.GetUnitAuras, C_UnitAuras.RegisterAuraDurationModifier, C_UnitAuras.RegisterAuraDurationModifierByTrigger, C_UnitAuras.RegisterComboDuration
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

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, since vanilla 1.12 glue ships no general-purpose persistence API beyond GetSavedAccountName/SetSavedAccountName (saturated by autologin). 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 extensions to macro parsing and dispatch — no new Lua functions, just behavior the stock 1.12 engine didn't have. 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

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

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

Group Constants
Version CLASSIC_API_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)

Unit tokens

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

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 Focus / Bindings for the implementation note.

Behaviors

Transparent engine tweaks — no API to call, they just fix a vanilla limitation:

Tweak Effect
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.

Installation

Download the prebuilt ClassicAPI.dll from the latest release (or build it yourself). It's loaded with VanillaFixes:

  1. Install VanillaFixes if it isn't already.
  2. Copy ClassicAPI.dll into your game directory.
  3. Add ClassicAPI.dll to dlls.txt.
  4. 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 (originally shipped with the 3.0 client) 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 3.3.5 helpers that don't exist in 1.12):

Global Purpose
print(...) Backport of the 3.3.5 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.

S
Description
No description provided
Readme GPL-3.0
18 MiB
2026-09-30 20:01:20 +00:00
Languages
C++ 72.5%
Lua 17.3%
C 9.9%
CMake 0.2%