Add FOCUSTARGET / TARGETFOCUS bindings under TARGETING

Splice into the engine's FrameXML Bindings.xml at load time via a file-read hook so the new bindings receive display indices from the same running counter as native bindings — landing visually inside the TARGETING block instead of orphaned at the bottom (where addon-side Bindings.xml entries always render, regardless of header="TARGETING").
sort Items category
2026-11-11 04:17:38 +00:00 · 2026-06-02 17:29:49 -05:00 · 2026-06-02 16:51:15 -05:00 · 2026-06-02 16:22:54 -05:00 · 2026-06-02 14:51:05 -05:00 · 2026-05-31 12:42:40 -05:00
27 changed files with 2422 additions and 931 deletions
@@ -1,7 +1,7 @@
 ## Interface: 11200
 ## Title: !!!ClassicAPI
 ## Notes: Library to emulate aspects of the modern WoW API on 1.12.1 / Lua 5.0.
-## Version: 1.3
+## Version: DEV
 ## Author: Brues

 GlobalStrings.lua
@@ -29,3 +29,4 @@ Util\PlayerUtil.lua
 Util\SlashCommandsRegistry.lua
 Util\LinkUtil.lua
 Util\IconDataProvider.lua
+Util\GameTooltip.lua
@@ -1,6 +1,10 @@
+BINDING_NAME_FOCUSTARGET = "Focus Target";
+BINDING_NAME_TARGETFOCUS = "Target Focus";
+FOCUSTARGET = "Focus Target";
 ITEMS_VARIABLE_QUANTITY = "%d |4Item:Items;";
 ITEMS_EQUIPPED = "%d |4item:items; equipped";
 ITEMS_IN_INVENTORY = "%d |4item:items; in inventory";
 ITEM_SLOTS_IGNORED = "%d |4slot:slots; ignored";
 ITEM_MISSING = "%s missing";
 ITEMS_NOT_IN_INVENTORY = "%d |4item:items; missing";
+TARGETFOCUS = "Target Focus";
@@ -83,12 +83,11 @@ function EventUtil.TriggerOnVariablesLoaded()
 end

 function EventUtil.ContinueOnAddOnLoaded(addOnName, callback)
-    -- 1.12's IsAddOnLoaded returns a single bool. 3.3.5 split that into
-    -- (isLoadedOrLoading, isLoaded); treat truthy as "ready to use".
-    if IsAddOnLoaded(addOnName) then
-        callback()
-        return
-    end
+	local isLoadedOrLoading, isLoaded = C_AddOns.IsAddOnLoaded(addOnName)
+	if isLoaded then
+		callback();
+		return;
+	end

    EventUtil.RegisterOnceFrameEventAndCallback("ADDON_LOADED", callback, addOnName)
 end
@@ -0,0 +1,3 @@
+function GameTooltip_Hide()
+	GameTooltip:Hide()
+end
@@ -18,7 +18,7 @@ Full per-function reference: **[docs/API.md](docs/API.md)**.
 | Namespace | Calls |
 |-----------|-------|
 | [Action](docs/API.md#action) | `GetActionInfo` |
-| [AddOns](docs/API.md#addons) | `C_AddOns.DoesAddOnExist`, `C_AddOns.GetAddOnName`, `C_AddOns.GetAddOnNotes`, `C_AddOns.GetAddOnSecurity`, `C_AddOns.GetAddOnTitle`, `C_AddOns.IsAddOnLoadable` |
+| [AddOns](docs/API.md#addons) | `C_AddOns.DoesAddOnExist`, `C_AddOns.GetAddOnName`, `C_AddOns.GetAddOnNotes`, `C_AddOns.GetAddOnSecurity`, `C_AddOns.GetAddOnTitle`, `C_AddOns.IsAddOnLoadable`, `C_AddOns.IsAddOnLoaded` |
 | [Chat](docs/API.md#chat) | `GetCurrentChatGUID` |
 | [Class](docs/API.md#class) | `FillLocalizedClassList` |
 | [Combat](docs/API.md#combat) | `InCombatLockdown` |
@@ -33,9 +33,9 @@ Full per-function reference: **[docs/API.md](docs/API.md)**.
 | [Focus](docs/API.md#focus) | `ClearFocus`, `FocusUnit` |
 | [FriendList](docs/API.md#friendlist) | `C_FriendList.IsWhoQueryPending`, `C_FriendList.SendWhoQueryByName` |
 | [Gossip](docs/API.md#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](docs/API.md#gametooltip) | `GameTooltip:GetGameObject`, `GameTooltip:GetItem`, `GameTooltip:GetOwner`, `GameTooltip:GetSpell`, `GameTooltip:GetUnitGUID`, `GameTooltip:HasGameObject`, `GameTooltip:HasItem`, `GameTooltip:HasSpell`, `GameTooltip:HasUnit`, `GameTooltip:SetEquipmentSet`, `GameTooltip:SetInventoryItemByID`, `GameTooltip:SetItemByID`, `GameTooltip:SetSpellByID`, `GameTooltip:SetTalentByID`, `GameTooltip:SetUnitAura` |
+| [GameTooltip](docs/API.md#gametooltip) | `GameTooltip:GetGameObject`, `GameTooltip:GetItem`, `GameTooltip:GetOwner`, `GameTooltip:GetSpell`, `GameTooltip:GetUnitGUID`, `GameTooltip:HasGameObject`, `GameTooltip:HasItem`, `GameTooltip:HasSpell`, `GameTooltip:HasUnit`, `GameTooltip:SetEquipmentSet`, `GameTooltip:SetInventoryItemByID`, `GameTooltip:SetItemByGUID`, `GameTooltip:SetItemByID`, `GameTooltip:SetSpellByID`, `GameTooltip:SetTalentByID`, `GameTooltip:SetUnitAura` |
 | [Hooks](docs/API.md#hooks) | `hooksecurefunc` |
-| [Input](docs/API.md#input) | `IsLeftAltKeyDown`, `IsLeftControlKeyDown`, `IsLeftShiftKeyDown`, `IsModifierKeyDown`, `IsRightAltKeyDown`, `IsRightControlKeyDown`, `IsRightShiftKeyDown` |
+| [Input](docs/API.md#input) | `IsLeftAltKeyDown`, `IsLeftControlKeyDown`, `IsLeftShiftKeyDown`, `IsModifierKeyDown`, `IsMouseButtonDown`, `IsRightAltKeyDown`, `IsRightControlKeyDown`, `IsRightShiftKeyDown` |
 | [Instance](docs/API.md#instance) | `GetInstanceInfo` |
 | [Item](docs/API.md#item) | `C_Item.DoesItemExist`, `C_Item.DoesItemExistByID`, `C_Item.EquipItemByName`, `C_Item.GetCurrentItemLevel`, `C_Item.GetDetailedItemLevelInfo`, `C_Item.GetItemCount`, `C_Item.GetItemFamily`, `C_Item.GetItemGUID`, `C_Item.GetItemIcon`, `C_Item.GetItemIconByID`, `C_Item.GetItemID`, `C_Item.GetItemInfoInstant`, `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.GetItemUniqueness`, `C_Item.GetItemUniquenessByID`, `C_Item.GetStackCount`, `C_Item.GetWeaponEnchantInfo`, `C_Item.IsBound`, `C_Item.IsEquippableItem`, `C_Item.IsEquippedItem`, `C_Item.IsItemDataCached`, `C_Item.IsItemDataCachedByID`, `C_Item.IsItemOpenable`, `C_Item.IsLocked`, `C_Item.LockItem`, `C_Item.LockItemByGUID`, `C_Item.UnlockAllItems`, `C_Item.UnlockItem`, `C_Item.RequestLoadItemData`, `C_Item.RequestLoadItemDataByID`, `C_Item.UseItemByName`, `GetAuctionItemID`, `GetAuctionSellItemID`, `GetAverageItemLevel`, `GetCraftReagentItemID`, `GetInboxItemID`, `GetInventoryItemDurability`, `GetInventoryItemID`, `GetInventoryItemsForSlot`, `GetInventoryItemRepairCost`, `GetItemIcon`, `GetLootRollItemID`, `GetLootSlotItemID`, `GetMerchantItemID`, `GetQuestItemID`, `GetQuestLogItemID`, `GetTradePlayerItemID`, `GetTradeSkillItemID`, `GetTradeSkillReagentItemID`, `GetTradeTargetItemID`, `OffhandHasWeapon` |
 | [Macros](docs/API.md#macros) | `GetLooseMacroIcons`, `GetLooseMacroItemIcons`, `GetMacroIcons`, `GetMacroItemIcons`, `GetMacroSpell` |
@@ -43,10 +43,10 @@ Full per-function reference: **[docs/API.md](docs/API.md)**.
 | [MerchantFrame](docs/API.md#merchantframe) | `C_MerchantFrame.GetBuybackItemID`, `C_MerchantFrame.GetItemInfo`, `C_MerchantFrame.GetNumJunkItems`, `C_MerchantFrame.IsMerchantItemRefundable`, `C_MerchantFrame.IsSellAllJunkEnabled`, `C_MerchantFrame.SellAllJunkItems` |
 | [NamePlate](docs/API.md#nameplate) | `C_NamePlate.GetNamePlateForGUID`, `C_NamePlate.GetNamePlateForUnit`, `C_NamePlate.GetNamePlateGUIDs`, `C_NamePlate.GetNamePlates` |
 | [NameCache](docs/API.md#namecache) | `C_CreatureInfo.GetCreatureID`, `C_PlayerCache.GetPlayerInfoByName`, `C_PlayerCache.IsEnabled`, `C_PlayerCache.IsScanEnabled`, `C_PlayerCache.RememberPlayer`, `C_PlayerCache.SetEnabled`, `C_PlayerCache.SetScanEnabled`, `C_PlayerInfo.GUIDIsCreature`, `C_PlayerInfo.GUIDIsGameObject`, `C_PlayerInfo.GUIDIsPet`, `C_PlayerInfo.GUIDIsPlayer`, `GetPlayerInfoByGUID` |
-| [Quest](docs/API.md#quest) | `C_QuestLog.GetQuestIDForLogIndex`, `C_QuestLog.GetTitleForQuestID`, `C_QuestLog.IsOnQuest`, `C_QuestLog.IsQuestDataCachedByID`, `C_QuestLog.IsUnitOnQuest`, `C_QuestLog.RequestLoadQuestByID`, `GetQuestLogLeaderBoardID` |
+| [Quest](docs/API.md#quest) | `C_QuestLog.GetQuestDetails`, `C_QuestLog.GetQuestIDForLogIndex`, `C_QuestLog.GetTitleForQuestID`, `C_QuestLog.IsOnQuest`, `C_QuestLog.IsQuestDataCachedByID`, `C_QuestLog.IsUnitOnQuest`, `C_QuestLog.RequestLoadQuestByID`, `GetQuestLogLeaderBoardID` |
 | [Spell](docs/API.md#spell) | `C_Spell.CancelSpellByID`, `C_Spell.DoesSpellExist`, `C_Spell.GetSchoolString`, `C_Spell.GetSpellCooldown`, `C_Spell.GetSpellDescription`, `C_Spell.GetSpellInfo`, `C_Spell.GetSpellLink`, `C_Spell.GetSpellName`, `C_Spell.GetSpellReagents`, `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.IsSpellPassive`, `C_Spell.IsSpellUsable`, `C_Spell.SpellHasRange`, `CancelSpellByName`, `CastSpellNoToggle`, `GetCraftSpellID`, `GetSpellInfo`, `GetSpellLink`, `GetSpellSchool`, `IsHarmfulSpell`, `IsHelpfulSpell`, `IsPassiveSpell`, `IsPlayerSpell`, `IsSpellKnown`, `IsUsableSpell`, `SpellHasRange` |
 | [SpellBook](docs/API.md#spellbook) | `C_SpellBook.GetCurrentLevelSpells`, `C_SpellBook.GetSpellLevelLearned`, `C_SpellBook.GetSpellSkillLine`, `C_SpellBook.IsAutoAttackSpellBookItem`, `C_SpellBook.IsRangedAutoAttackSpellBookItem`, `FindSpellBookSlotByID` |
-| [State](docs/API.md#state) | `CancelShapeshiftForm`, `Dismount`, `GetMirrorTimerInfo`, `GetMirrorTimerProgress`, `GetShapeshiftFormID`, `IsAssistingRitual`, `IsFalling`, `IsInGroup`, `IsInRaid`, `IsMounted`, `IsStealthed`, `IsSwimming` |
+| [State](docs/API.md#state) | `CancelShapeshiftForm`, `Dismount`, `GetMirrorTimerInfo`, `GetMirrorTimerProgress`, `GetShapeshiftFormID`, `IsAssistingRitual`, `IsFalling`, `IsInGroup`, `IsInRaid`, `IsLoggedIn`, `IsMounted`, `IsStealthed`, `IsSwimming` |
 | [Table](docs/API.md#table) | `table.wipe` |
 | [Talent](docs/API.md#talent) | `GetTalentIDByIndex`, `GetTalentSpellID` |
 | [Time](docs/API.md#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` |
@@ -71,6 +71,7 @@ the glue state because GlueXML had no way to reach them otherwise.
 | [CharacterList](docs/API.md#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) |
 | 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

@@ -186,17 +186,45 @@ void PushLocalizedString(void *L, const char *globalName, const char *fallback)
    }
 }

+// In-place `string.gsub(stack[-1], pattern, replacement)` — replaces
+// the string at the top of the stack with the substitution result.
+// Discards gsub's second return (the substitution count) by
+// requesting only one return from `Call`.
+static void GsubInPlace(void *L, const char *pattern, const char *replacement) {
+    PushString(L, "string");
+    GetTable(L, GLOBALS_INDEX);
+    PushString(L, "gsub");
+    GetTable(L, -2);             // [..., str, string, gsub]
+    Remove(L, -2);                // [..., str, gsub]
+    Insert(L, -2);                // [..., gsub, str]
+    PushString(L, pattern);
+    PushString(L, replacement);
+    Call(L, 3, 1);                // [..., result]
+}
+
 void PushLocalizedFormatInt(void *L, const char *globalName,
                            const char *fallback, int n) {
-    // Resolve `string.format` from _G. The engine ships it as both a
-    // global and as `string.format`; the global is faster (one
-    // gettable instead of two) and equally available across builds.
+    // Resolve `string.format` from _G.
    PushString(L, "format");
    GetTable(L, GLOBALS_INDEX);
-
    PushLocalizedString(L, globalName, fallback);
+
+    // Expand WoW's `|4singular:plural;` (and 3-form
+    // `|4nom:gen_sing:plural;`) pluralization template by piggybacking
+    // on Lua's `string.gsub`. The 2- vs 3-form distinction is locale
+    // grammar (Slavic counting has a separate genitive-singular form
+    // for 2..4); we collapse to nominative/plural since vanilla has
+    // no proper locale-aware counting rules. 3-form pattern runs
+    // first because it's more specific. Vanilla's `string.format`
+    // doesn't process `|4` natively, so without this the template
+    // would render literally.
+    const char *picker3 = (n == 1) ? "%1" : "%3";
+    const char *picker2 = (n == 1) ? "%1" : "%2";
+    GsubInPlace(L, "|4([^:;]+):([^:;]+):([^;]+);", picker3);
+    GsubInPlace(L, "|4([^:;]+):([^;]+);", picker2);
+
    PushNumber(L, static_cast<double>(n));
-    Call(L, 2, 1); // format(fmt, n) → string
+    Call(L, 2, 1);                // format(expandedFmt, n) → string
 }
 } // namespace Lua

@@ -1488,6 +1488,35 @@ enum Offsets {
    VAR_SKILL_LINE_COUNT = 0x00C0D930,
    OFF_SKILL_LINE_NAME = 0x0C,

+    // Player's known-skills table — separate from the DBC. Populated
+    // by the engine on login from server data; entries are pointers
+    // to per-skill records. Each record's `+0x00` is the
+    // `SkillLine.dbc` row (or `0` for header / category rows), and
+    // `+0x10` is the current skill rank (other rank/modifier fields
+    // follow). Source: `Script_GetSkillLineInfo` at `0x004D3610`,
+    // which walks this array indexed by the Lua arg.
+    VAR_PLAYER_SKILL_LIST = 0x00B7318C,
+    VAR_PLAYER_SKILL_COUNT = 0x00B731B8,
+    OFF_PLAYER_SKILL_LINE_ID = 0x00,
+    OFF_PLAYER_SKILL_RANK = 0x10,
+
+    // Per-itemClass proficiency bitmap maintained by the engine.
+    // 17 u32 entries (indexed by Item.dbc `m_class`, 0..16). Each
+    // entry is a bitmask where bit N is set if the player has
+    // proficiency in subclass N of that item class — i.e.
+    // `table[4] & (1 << 3)` = "can wear Mail" (armor=class 4,
+    // mail=subclass 3).
+    //
+    // Populated by SMSG_SET_PROFICIENCY's handler at
+    // `FUN_005E7B70`, which writes `table[itemClass] = mask`
+    // verbatim from the packet. Same source the engine itself uses
+    // for equip eligibility (the tooltip "Mail" red-text logic
+    // and the cursor-drop-on-paperdoll check both read this). Note:
+    // covers **weapons too** (class 2), making it strictly more
+    // general than walking the per-skill-line table for individual
+    // armor proficiencies.
+    VAR_PROFICIENCY_TABLE = 0x00C4D4A0,
+
    // Spell.dbc `BaseLevel` — the level a spell becomes available
    // (trainer offers it, quest reward grants it, etc.). Distinct
    // from `SpellLevel` at +0x74 which is the effective level used
@@ -2147,6 +2176,7 @@ enum Offsets {
    // `Script_IsInInstance`).
    VAR_CURRENT_MAP_ID = 0x00B4E378,

+
    // Local player's current AreaTable.dbc area ID (u32 storage; only
    // the low 16 bits are used — the value is broadcast over the wire
    // as a u16 in `SMSG_PARTY_MEMBER_STATS`). Written by the zone-change
@@ -2433,6 +2463,48 @@ enum Offsets {
    // registry before the load pass.
    FUN_ADDON_INIT = 0x0051C740,

+    // Generic intrusive-list insert/move helper used by `FUN_TOC_PARSER`
+    // to thread new addon entries into the registry's doubly-linked
+    // list. Signature (`__thiscall`):
+    //   `(ListCtrl *this, void *entry, int position, int anchor)`
+    // Where:
+    //   - `this`        — list-control struct (for the addon registry,
+    //                      this is `&VAR_ADDON_LIST_CTRL`).
+    //   - `entry`       — entry to insert. If already linked, the
+    //                      function removes it from its current
+    //                      position first.
+    //   - `position`    — `1` = insert at head, anything else (engine
+    //                      passes `2`) = insert at tail.
+    //   - `anchor`      — `0` = anchor against the list sentinel
+    //                      (default), nonzero = anchor relative to
+    //                      another entry's link field at that offset.
+    //
+    // Used by `Addons::Embedded` to move our injected `!!!ClassicAPI`
+    // entry from the tail (where `FUN_TOC_PARSER` puts it) to the head
+    // — vanilla's addon load pass at `FUN_0051F600` walks the linked
+    // list in insertion order, so without this fix our addon would
+    // load *last*, breaking dependent addons that expect our globals
+    // to be ready in their main chunk.
+    FUN_INTRUSIVE_LIST_INSERT = 0x00521AD0,
+
+    // Addon-registry intrusive-list control. Layout
+    // (`__thiscall`-friendly, generic across all intrusive lists in the
+    // binary):
+    //   +0x00 (= `0x00BE1B64`) — `int` next-pointer offset within each
+    //                              entry (= `0xC` at runtime; entries
+    //                              store their next-link at
+    //                              `entry+0xC..0x10`).
+    //   +0x04 (= `0x00BE1B68`) — sentinel `next` field
+    //                              (points back into &sentinel+1 when
+    //                              the list is empty).
+    //   +0x08 (= `0x00BE1B6C`) — list head (alias for sentinel `prev`
+    //                              when treated as circular).
+    //
+    // `VAR_ADDON_LIST_CTRL` is just the address of the control struct
+    // (i.e., `0x00BE1B64`). Pass `&VAR_ADDON_LIST_CTRL` as the `this`
+    // arg to `FUN_INTRUSIVE_LIST_INSERT`.
+    VAR_ADDON_LIST_CTRL = 0x00BE1B64,
+
    // `SStrDup(const char *src, const char *file, int line)`. `__stdcall`.
    // Storm's string-copy wrapper around `SMemAlloc` — used by the engine
    // itself to populate event entry names. We use it from `Event::Custom`
@@ -2567,9 +2639,11 @@ enum Offsets {
    // We dispatch to these directly so the wrappers don't need to
    // bounce through `Script_GetAddOnInfo` and unwind 7 returns.
    //
-    //   IS_LOAD_ON_DEMAND `__fastcall(entry) → byte`
-    //     Hash-table lookup in the addon registry. Non-zero ⇒
-    //     `## LoadOnDemand: 1` in the .toc.
+    //   IS_LOADED `__fastcall(entry) → byte`
+    //     Hash-table lookup in the addon registry. Returns the byte
+    //     at `entry+0x18`, which the addon loader (`FUN_0051F240`)
+    //     writes `1` to when the addon has finished loading. Non-zero
+    //     ⇒ the addon is loaded.
    //
    //   CAN_LOAD `__fastcall(entry, char fullCheck=1, int *outStatus,
    //                        int *outDepHandle, const char *accountName) → byte`
@@ -2590,7 +2664,7 @@ enum Offsets {
    //     Hash-table lookup that returns the security category index
    //     (0=SECURE, 1=INSECURE, 2=BANNED). Defaults to `1` (INSECURE)
    //     when the entry isn't in the override table.
-    FUN_ADDON_IS_LOAD_ON_DEMAND = 0x0051E6F0,
+    FUN_ADDON_IS_LOADED = 0x0051E6F0,
    FUN_ADDON_CAN_LOAD = 0x0051E780,
    FUN_ADDON_GET_SECURITY_INDEX = 0x0051E990,

@@ -47,6 +47,7 @@

 #include "Game.h"
 #include "Offsets.h"
+#include "bindings/Inject.h"

 #include <cstdint>
 #include <cstdio>
@@ -248,6 +249,14 @@ void DecideSource() {
 int __stdcall FileRead_h(int unused, const char *path, void **outBuf,
                         size_t *outSize, size_t extraBytes,
                         int flag1, int flag2) {
+    // FrameXML Bindings.xml gets an inline splice for our TARGETING
+    // additions — see `bindings/Inject.cpp`. Returns true with the
+    // patched buffer ready for the engine's binding parser to consume.
+    if (Bindings::Inject::TryHandle(unused, path, outBuf, outSize,
+                                    extraBytes, flag1, flag2, FileRead_o)) {
+        return 1;
+    }
+
    const char *suffix = StripAddonPrefix(path);
    if (suffix == nullptr) {
        // Path isn't under `Interface\AddOns\!!!ClassicAPI\` — straight
@@ -301,11 +310,58 @@ using AddonInit_t = void(__fastcall *)(const char *accountName);
 AddonInit_t AddonInit_o = nullptr;

 using TocParser_t = void(__fastcall *)(const char *name);
+using ListInsert_t = void(__thiscall *)(void *listCtrl, void *entry,
+                                         int position, int anchor);
+
+// `FUN_TOC_PARSER` appends new entries to the *tail* of the addon
+// registry's linked list, and the engine's addon-load pass at
+// `FUN_0051F600` walks that list in *insertion order* (NOT
+// alphabetical order — the alphabetical sort only applies to the
+// flat array `GetAddOnInfo(i)` reads from). So our post-hook
+// injection lands at the very end of the load order, after every
+// disk-scanned addon. Addons that consume our globals from their
+// main chunk (idTip's `FrameWatcher`, etc.) would see `nil` and
+// hard-error during their boot.
+//
+// Fix: walk the linked list, find our entry by name, and re-link
+// it to the head via `FUN_INTRUSIVE_LIST_INSERT(position=1)`. The
+// engine's own insert helper handles remove-then-insert atomically,
+// so it's safe to call on an entry that's already in the list.
+//
+// Entries are pointed to by `[VAR_ADDON_LIST_HEAD]` (`0x00BE1B6C`),
+// with the next-pointer field at `entry + 0x10` (computed as
+// `*(value-at-VAR_ADDON_LIST_CTRL) + entry + 4` = `0xC + entry + 4`
+// = `entry + 0x10`). Low-bit-1 means "sentinel" (end of list).
+// Name pointer lives at `entry + 0x14`.
+constexpr uintptr_t VAR_ADDON_LIST_HEAD = 0x00BE1B6C;
+constexpr int OFF_ADDON_ENTRY_NAME_PTR = 0x14;
+
+void MoveEmbeddedToListHead() {
+    uintptr_t entry = *reinterpret_cast<uintptr_t *>(VAR_ADDON_LIST_HEAD);
+    const int linkOffset = *reinterpret_cast<const int *>(
+        static_cast<uintptr_t>(Offsets::VAR_ADDON_LIST_CTRL));
+    while ((entry & 1) == 0 && entry != 0) {
+        const char *name = *reinterpret_cast<const char *const *>(
+            entry + OFF_ADDON_ENTRY_NAME_PTR);
+        if (name != nullptr && std::strcmp(name, kAddonName) == 0) {
+            auto fn = reinterpret_cast<ListInsert_t>(
+                Offsets::FUN_INTRUSIVE_LIST_INSERT);
+            fn(reinterpret_cast<void *>(
+                   static_cast<uintptr_t>(Offsets::VAR_ADDON_LIST_CTRL)),
+               reinterpret_cast<void *>(entry),
+               /*position=*/ 1, /*anchor=*/ 0);
+            return;
+        }
+        entry = *reinterpret_cast<const uintptr_t *>(
+            entry + linkOffset + 4);
+    }
+}

 void __fastcall AddonInit_h(const char *accountName) {
    AddonInit_o(accountName);
    auto TocParser = reinterpret_cast<TocParser_t>(Offsets::FUN_TOC_PARSER);
    TocParser(kAddonName);
+    MoveEmbeddedToListHead();
 }

 const Game::HookAutoRegister _hookFileRead{
@@ -115,13 +115,24 @@ int PushFieldOrNil(void *L, FieldByName_t accessor) {
 // `C_AddOns.GetAddOnName(indexOrName)` — the addon's directory name.
 // For numeric input, returns the engine's canonical casing. For
 // string input, returns the input verbatim once existence is
-// confirmed.
+// confirmed; nil for an unregistered name.
+//
+// String-input existence isn't free: `ResolveAddOnName` echoes the
+// string for the field accessors below (`GetAddOnTitle`, etc.) which
+// short-circuit cleanly on unknown names via the engine's own NULL-
+// return paths. `GetAddOnName` doesn't call any engine accessor, so
+// it'd otherwise echo any string. Probe the registry explicitly.
 int __fastcall Script_GetAddOnName(void *L) {
    const uint8_t *entry = ResolveAddOnName(L);
    if (entry == nullptr) {
        Game::Lua::PushNil(L);
        return 1;
    }
+    if (Game::Lua::Type(L, 1) == Game::Lua::TYPE_STRING &&
+        !AddOnExistsByName(reinterpret_cast<const char *>(entry))) {
+        Game::Lua::PushNil(L);
+        return 1;
+    }
    Game::Lua::PushString(L, reinterpret_cast<const char *>(entry));
    return 1;
 }
@@ -163,9 +174,13 @@ int __fastcall Script_IsAddOnLoadable(void *L) {
        return 2;
    }

-    auto isLoD = reinterpret_cast<EntryByteFn_t>(
-        Offsets::FUN_ADDON_IS_LOAD_ON_DEMAND);
-    if (isLoD(entry) != 0) {
+    // Already-loaded addons are trivially loadable — skip the
+    // recursive dep walk and return (true, nil) directly. `IS_LOADED`
+    // reads the byte at `entry+0x18` (the loader sets that to 1 on
+    // successful load).
+    auto isLoaded = reinterpret_cast<EntryByteFn_t>(
+        Offsets::FUN_ADDON_IS_LOADED);
+    if (isLoaded(entry) != 0) {
        Game::Lua::PushBoolean(L, 1);
        Game::Lua::PushNil(L);
        return 2;
@@ -229,6 +244,36 @@ int __fastcall Script_GetAddOnSecurity(void *L) {
    return 1;
 }

+// `C_AddOns.IsAddOnLoaded(indexOrName)` → `(loadedOrLoading, loaded)`.
+//
+// Modern WoW distinguishes "load-in-progress" from "fully loaded" —
+// matters for LoD addons whose load is split across multiple
+// `LoadAddOn` callbacks. Vanilla 1.12's `FUN_0051F240` is fully
+// synchronous: the loaded byte at `entry+0x18` flips from 0 → 1
+// inside a single call, so the "loading" state is never observable
+// from Lua. We return the same boolean twice — `loadedOrLoading`
+// and `loaded` are identical here.
+//
+// Resolves both numeric indices (via `FUN_ADDON_GET_BY_INDEX`) and
+// string names. `IS_LOADED` accepts an entry pointer as its name arg
+// because the entry's first 12 bytes are the inline NUL-terminated
+// directory name (same as the other per-field accessors), so we can
+// feed it either an entry or a Lua-side string transparently.
+int __fastcall Script_IsAddOnLoaded(void *L) {
+    const uint8_t *entry = ResolveAddOnName(L);
+    if (entry == nullptr) {
+        Game::Lua::PushBool(L, false);
+        Game::Lua::PushBool(L, false);
+        return 2;
+    }
+    auto isLoaded = reinterpret_cast<EntryByteFn_t>(
+        Offsets::FUN_ADDON_IS_LOADED);
+    const bool loaded = isLoaded(entry) != 0;
+    Game::Lua::PushBool(L, loaded);
+    Game::Lua::PushBool(L, loaded);
+    return 2;
+}
+
 // `C_AddOns.DoesAddOnExist(indexOrName)` — true iff the engine's
 // addon registry has a matching entry. For numeric input we trust
 // `GetByIndex`'s OOR-NULL; for string input we walk the flat array,
@@ -276,6 +321,8 @@ static void RegisterLuaFunctions() {
                                     &Script_GetAddOnSecurity);
    Game::Lua::RegisterTableFunction("C_AddOns", "DoesAddOnExist",
                                     &Script_DoesAddOnExist);
+    Game::Lua::RegisterTableFunction("C_AddOns", "IsAddOnLoaded",
+                                     &Script_IsAddOnLoaded);
    Game::Lua::RegisterIntegerEnum(
        "Enum", "AddOnSecurityStatus",
        kAddOnSecurityStatusEntries,
@@ -0,0 +1,159 @@
+// This file is part of ClassicAPI.
+//
+// ClassicAPI is free software: you can redistribute it and/or modify it under the terms
+// of the GNU Lesser General Public License as published by the Free Software Foundation, either
+// version 3 of the License, or (at your option) any later version.
+//
+// ClassicAPI is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
+// PURPOSE. See the GNU Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public License along with
+// ClassicAPI. If not, see <https://www.gnu.org/licenses/>.
+
+// Inject ClassicAPI-owned bindings into the engine's TARGETING group.
+//
+// Why a file-read hook rather than an addon-side Bindings.xml: vanilla
+// stores every binding in a single linearly-indexed table, and the
+// keybind UI walks that table in index order with `HEADER_*` pseudo-
+// entries splitting groups. Addon Bindings.xml files get parsed
+// AFTER FrameXML, so even with `header="TARGETING"` an addon binding
+// receives a display index higher than every engine binding — it
+// renders orphaned at the very bottom of the keybind list rather than
+// under TARGETING.
+//
+// To land inside TARGETING, the binding's display index has to fall
+// between HEADER_TARGETING and HEADER_INTERFACE. The cleanest way to
+// arrange that is to splice the bindings into the FrameXML file the
+// engine itself parses, so they take their indices from the same
+// running counter every native binding does.
+//
+// Splice site: just before `<Binding name="TOGGLECHARACTER0"` (the
+// first INTERFACE-section entry). Our injected bindings inherit
+// TARGETING from the preceding `header="TARGETING"` declaration on
+// `TARGETNEARESTENEMY` (the engine never re-asserts a header on each
+// binding — group membership is positional). They appear at the tail
+// of TARGETING, just after PETATTACK / ATTACKTARGET.
+//
+// The engine's binding parser is `FUN_004b6f70`. It calls
+// `FUN_FILE_READ` (`0x00648620`) to load the file, then walks `<Binding>`
+// elements assigning each the next display index from a running
+// counter. By the time our injected bindings are processed, the
+// engine has already emitted HEADER_TARGETING and a sequence of
+// TARGETING entries; ours append to that sequence and HEADER_INTERFACE
+// follows.
+
+#include "Inject.h"
+#include "Offsets.h"
+
+#include <cstring>
+
+namespace Bindings::Inject {
+
+namespace {
+
+constexpr const char *kFrameXMLBindingsPath = "Interface\\FrameXML\\Bindings.xml";
+
+// First INTERFACE-section binding. Splicing immediately before this
+// puts our entries at the tail of the TARGETING block.
+constexpr const char *kSpliceMarker = "<Binding name=\"TOGGLECHARACTER0\"";
+
+// LF-only line endings — vanilla's XML parser is whitespace-tolerant
+// and accepts either LF or CRLF freely. Indentation matches the
+// surrounding file (one leading tab per `<Binding>`).
+constexpr const char *kInjectedXml =
+    "<Binding name=\"FOCUSTARGET\">\n"
+    "\t\tFocusUnit(\"target\");\n"
+    "\t</Binding>\n"
+    "\t<Binding name=\"TARGETFOCUS\">\n"
+    "\t\tTargetUnit(\"focus\");\n"
+    "\t</Binding>\n"
+    "\t";
+
+char NormalizeChar(char c) {
+    if (c == '/') return '\\';
+    if (c >= 'A' && c <= 'Z') return static_cast<char>(c + 32);
+    return c;
+}
+
+bool PathEqualsCI(const char *a, const char *b) {
+    while (*a != '\0' && *b != '\0') {
+        if (NormalizeChar(*a) != NormalizeChar(*b)) return false;
+        ++a; ++b;
+    }
+    return *a == *b;
+}
+
+using SMemAlloc_t = void *(__stdcall *)(size_t size, const char *file, int line, int flags);
+using SMemFree_t = void(__stdcall *)(void *buf, const char *file, int line, int flags);
+
+const char *FindMarker(const char *content, size_t size, const char *marker) {
+    const size_t markerLen = std::strlen(marker);
+    if (size < markerLen) return nullptr;
+    for (size_t i = 0; i + markerLen <= size; ++i) {
+        if (std::memcmp(content + i, marker, markerLen) == 0)
+            return content + i;
+    }
+    return nullptr;
+}
+
+} // namespace
+
+bool TryHandle(int unused, const char *path, void **outBuf, size_t *outSize,
+               size_t extraBytes, int flag1, int flag2, FileReadFn original) {
+    if (path == nullptr || !PathEqualsCI(path, kFrameXMLBindingsPath))
+        return false;
+
+    // Pull the real file through the original reader with the caller's
+    // requested `extraBytes` honored — the original allocates a Storm
+    // buffer of `fileSize + extraBytes` and zero-fills the tail.
+    void *origBuf = nullptr;
+    size_t origSize = 0;
+    const int readOk = original(unused, path, &origBuf, &origSize,
+                                 extraBytes, flag1, flag2);
+    if (readOk == 0 || origBuf == nullptr)
+        return false;
+
+    const char *content = static_cast<const char *>(origBuf);
+    const char *splice = FindMarker(content, origSize, kSpliceMarker);
+    if (splice == nullptr) {
+        // Marker missing — likely a modified or non-vanilla FrameXML
+        // (Turtle patch level, custom build). Pass the original
+        // through unchanged rather than corrupting it.
+        if (outBuf != nullptr) *outBuf = origBuf;
+        if (outSize != nullptr) *outSize = origSize;
+        return true;
+    }
+
+    const size_t injectLen = std::strlen(kInjectedXml);
+    const size_t splicePos = static_cast<size_t>(splice - content);
+    const size_t newSize = origSize + injectLen;
+
+    auto SMemAlloc = reinterpret_cast<SMemAlloc_t>(Offsets::FUN_STORM_SMEM_ALLOC);
+    auto SMemFree = reinterpret_cast<SMemFree_t>(Offsets::FUN_STORM_SMEM_FREE);
+
+    void *newBuf = SMemAlloc(newSize + extraBytes, __FILE__, __LINE__, 0);
+    if (newBuf == nullptr) {
+        // Allocation failed — fall back to the original buffer so the
+        // engine still loads its own bindings.
+        if (outBuf != nullptr) *outBuf = origBuf;
+        if (outSize != nullptr) *outSize = origSize;
+        return true;
+    }
+
+    auto *dest = static_cast<char *>(newBuf);
+    std::memcpy(dest, content, splicePos);
+    std::memcpy(dest + splicePos, kInjectedXml, injectLen);
+    std::memcpy(dest + splicePos + injectLen,
+                content + splicePos, origSize - splicePos);
+    if (extraBytes > 0)
+        std::memset(dest + newSize, 0, extraBytes);
+
+    SMemFree(origBuf, __FILE__, __LINE__, 0);
+
+    if (outBuf != nullptr) *outBuf = newBuf;
+    if (outSize != nullptr) *outSize = newSize;
+    return true;
+}
+
+} // namespace Bindings::Inject
@@ -0,0 +1,37 @@
+// This file is part of ClassicAPI.
+//
+// ClassicAPI is free software: you can redistribute it and/or modify it under the terms
+// of the GNU Lesser General Public License as published by the Free Software Foundation, either
+// version 3 of the License, or (at your option) any later version.
+//
+// ClassicAPI is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
+// PURPOSE. See the GNU Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public License along with
+// ClassicAPI. If not, see <https://www.gnu.org/licenses/>.
+
+#pragma once
+
+#include <cstddef>
+
+namespace Bindings::Inject {
+
+// `FUN_FILE_READ` shape — Storm-style: __stdcall, returns 1 on success
+// with the buffer allocated via SMemAlloc into `*outBuf` (size in
+// `*outSize`, plus `extraBytes` of trailing zero padding).
+using FileReadFn = int(__stdcall *)(int unused, const char *path,
+                                     void **outBuf, size_t *outSize,
+                                     size_t extraBytes,
+                                     int flag1, int flag2);
+
+// Path-matches `Interface\FrameXML\Bindings.xml`. On match: fetches
+// the real file via `original`, splices our ClassicAPI bindings into
+// the TARGETING block, and returns `true` with `*outBuf` / `*outSize`
+// set to a fresh Storm buffer the caller can SMemFree normally.
+// Returns `false` for any other path — caller should fall through to
+// its own logic.
+bool TryHandle(int unused, const char *path, void **outBuf, size_t *outSize,
+               size_t extraBytes, int flag1, int flag2, FileReadFn original);
+
+} // namespace Bindings::Inject
@@ -35,6 +35,7 @@
 #include "Offsets.h"
 #include "Set.h"
 #include "event/Custom.h"
+#include "item/Location.h"
 #include "item/Swap.h"

 #include <cstdint>
@@ -330,6 +331,19 @@ int __fastcall Script_ClearIgnoredSlotsForSave(void *L) {
 // would race with). Reads the per-CGItem instance flag at
 // `OFF_ITEM_CLIENT_LOCK` bit 0 — same bit `C_Item.IsLocked` checks
 // and the engine's own pickup/unlock paths manipulate.
+//
+// Gates on `Locations::FindGUID` BEFORE consulting the lock flag:
+// for items the player has deleted/mailed/traded away, the engine's
+// CGItem cache often retains a stale entry that `ResolveByGUID`
+// still hands back, but the inventory walk no longer finds the GUID
+// anywhere. Reading the lock flag off the stale CGItem reflects
+// whatever bits were last set on it (frequently the "locked"
+// in-transaction state from when it was being deleted/swapped),
+// which would falsely report the set as "contains locked items"
+// and prevent `UseEquipmentSet` from running through addon
+// wrappers that gate on this check. The inventory presence check
+// matches modern semantics: a missing item is *missing*, not
+// *locked*.
 int __fastcall Script_EquipmentSetContainsLockedItems(void *L) {
    const uint32_t setID = ArgSetID(L, 1);
    const Set *s = Data::FindByID(setID);
@@ -340,6 +354,8 @@ int __fastcall Script_EquipmentSetContainsLockedItems(void *L) {
        const uint64_t g = s->items[i];
        if (g == GUID_EMPTY || g == GUID_IGNORED)
            continue;
+        if (Locations::FindGUID(g) == 0)
+            continue; // not in inventory — treat as missing, not locked
        const uint8_t *item = Locations::ResolveItemByGUID(g);
        if (item == nullptr)
            continue;
@@ -401,39 +417,158 @@ int __fastcall Script_UseEquipmentSet(void *L) {
    uint64_t guids[SLOT_COUNT];
    std::memcpy(guids, s->items, sizeof(guids));

+    // Snapshot empty bag slots up front. The CGItem state doesn't
+    // update between packet sends (server has to acknowledge each
+    // swap), so iterating the bag walk fresh per unequip would
+    // repeatedly pick the same "first empty" slot — second packet
+    // collides with what packet 1 just put there, and the server
+    // tries to swap that item back onto the wrong paperdoll slot
+    // → "This item cannot be equipped".
+    struct FreeSlot {
+        int bag;
+        int slot;
+    };
+    FreeSlot freeSlots[64];
+    int freeSlotCount = 0;
+    for (int bag = 0; bag <= 4 && freeSlotCount < 64; ++bag) {
+        const int slots = Item::Location::GetBagSlotCount(bag);
+        for (int slot = 1; slot <= slots && freeSlotCount < 64; ++slot) {
+            if (Item::Location::ResolveBag(L, bag, slot) == nullptr)
+                freeSlots[freeSlotCount++] = {bag, slot};
+        }
+    }
+    int nextFreeSlot = 0;
+
+    // Pre-snapshot each set item's location against the ORIGINAL
+    // state, before any swap packets fly. This mirrors how 4.3.4's
+    // `Script_UseEquipmentSet` (`0x009A15D0`) builds its action list:
+    // resolve all 19 source locations up front, then execute. The
+    // engine's CGItem / InvMgr state lags behind our packet sends
+    // (waits for server ACK), so any `FindGUID` mid-execution would
+    // return stale answers and we'd re-resolve items into the wrong
+    // place.
+    int sourceLoc[SLOT_COUNT];
+    for (int i = 0; i < SLOT_COUNT; ++i) {
+        const uint64_t g = guids[i];
+        if (g == GUID_EMPTY || g == GUID_IGNORED) {
+            sourceLoc[i] = 0;
+            continue;
+        }
+        sourceLoc[i] = Locations::FindGUID(g);
+    }
+
+    // Virtual paperdoll occupant model — seeded from the engine's
+    // initial paperdoll GUID array, then updated in-place after each
+    // swap so phase 1 can chain rotations and phase 3 can spot
+    // already-empty slots.
+    uint64_t virtualPaperdoll[SLOT_COUNT];
+    Locations::SnapshotPaperdoll(virtualPaperdoll);
+
+    // Locates the current virtual slot of a GUID on the paperdoll,
+    // or 0 if it's not currently there. Used during phase 1 so
+    // chained paperdoll-to-paperdoll moves operate on the *current*
+    // virtual position, not the stale pre-snapshot.
+    auto currentPaperdollSlot = [&](uint64_t g) -> int {
+        if (g == 0)
+            return 0;
+        for (int slot = 1; slot <= SLOT_COUNT; ++slot) {
+            if (virtualPaperdoll[slot - 1] == g)
+                return slot;
+        }
+        return 0;
+    };
+
+    // ── Phase 1: paperdoll → paperdoll ─────────────────────────────
+    // Move items already on the paperdoll into their target slots.
+    // Source and destination are both paperdoll, so atomic swaps
+    // never touch bag state — phase 2's bag lookups stay accurate.
    for (int i = 0; i < SLOT_COUNT; ++i) {
        const int targetSlot = i + 1;
        const uint64_t g = guids[i];
        if (g == GUID_EMPTY || g == GUID_IGNORED)
            continue;

-        const int loc = Locations::FindGUID(g);
+        const int loc = sourceLoc[i];
        if (loc == 0)
-            continue; // missing — nothing to do
-
-        // Already in its target slot? Skip.
-        if ((loc & LOC_BAGS) == 0 && (loc & LOC_BANK) == 0 &&
-            (loc & LOC_SLOT_MASK) == targetSlot)
            continue;
-
-        // In bank (main or bank-bag) — server rejects equip-from-bank.
        if (loc & LOC_BANK)
-            continue;
+            continue; // server rejects equip-from-bank
+        if (loc & LOC_BAGS)
+            continue; // phase 2
+
+        const int srcSlot = currentPaperdollSlot(g);
+        if (srcSlot == 0 || srcSlot == targetSlot)
+            continue; // missing or already there

        const uint8_t *item = Locations::ResolveItemByGUID(g);
        if (item == nullptr)
            continue;

-        if (loc & LOC_BAGS) {
-            const int srcBag = (loc >> LOC_BAG_SHIFT) & 0xFF;
-            const int srcSlot = loc & LOC_SLOT_MASK;
-            Item::Swap::FromBag(item, srcBag, srcSlot, targetSlot);
-        } else {
-            const int srcSlot = loc & LOC_SLOT_MASK;
-            Item::Swap::FromPaperdoll(item, srcSlot, targetSlot);
+        const uint64_t displaced = virtualPaperdoll[targetSlot - 1];
+        if (Item::Swap::FromPaperdoll(item, srcSlot, targetSlot)) {
+            virtualPaperdoll[targetSlot - 1] = g;
+            virtualPaperdoll[srcSlot - 1] = displaced;
        }
    }

+    // ── Phase 2: bag → paperdoll ───────────────────────────────────
+    // Move items from bag slots onto the paperdoll. Each atomic swap
+    // displaces the current paperdoll occupant into the bag slot the
+    // incoming item vacated. Anything we still wanted on the paperdoll
+    // was already placed by phase 1, so phase 2 displacements can't
+    // strand a future set item in a bag.
+    for (int i = 0; i < SLOT_COUNT; ++i) {
+        const int targetSlot = i + 1;
+        const uint64_t g = guids[i];
+        if (g == GUID_EMPTY || g == GUID_IGNORED)
+            continue;
+        if (virtualPaperdoll[targetSlot - 1] == g)
+            continue; // already at target (probably by phase 1)
+
+        const int loc = sourceLoc[i];
+        if (loc == 0)
+            continue;
+        if (loc & LOC_BANK)
+            continue;
+        if ((loc & LOC_BAGS) == 0)
+            continue; // not from a bag — phase 1 handled, or item missing
+
+        const uint8_t *item = Locations::ResolveItemByGUID(g);
+        if (item == nullptr)
+            continue;
+
+        const int srcBag = (loc >> LOC_BAG_SHIFT) & 0xFF;
+        const int srcSlot = loc & LOC_SLOT_MASK;
+        if (Item::Swap::FromBag(item, srcBag, srcSlot, targetSlot)) {
+            virtualPaperdoll[targetSlot - 1] = g;
+            // The displaced item lands in (srcBag, srcSlot). We
+            // don't track bag-side virtual state — by phase 3 we
+            // only care about the paperdoll occupant.
+        }
+    }
+
+    // ── Phase 3: unequip slots the set wants empty ─────────────────
+    // For each `GUID_EMPTY` slot, send the current paperdoll occupant
+    // (if any) to a pre-snapshotted free bag slot. Runs last so any
+    // displaced items from phases 1/2 that landed in the slot get
+    // unequipped here too.
+    for (int i = 0; i < SLOT_COUNT; ++i) {
+        const int targetSlot = i + 1;
+        if (guids[i] != GUID_EMPTY)
+            continue;
+        const uint64_t occupant = virtualPaperdoll[targetSlot - 1];
+        if (occupant == 0)
+            continue;
+        if (nextFreeSlot >= freeSlotCount)
+            continue;
+        const uint8_t *equipped = Locations::ResolveItemByGUID(occupant);
+        if (equipped == nullptr)
+            continue;
+        const FreeSlot &fs = freeSlots[nextFreeSlot++];
+        if (Item::Swap::ToBag(equipped, targetSlot, fs.bag, fs.slot))
+            virtualPaperdoll[targetSlot - 1] = 0;
+    }
+
    const int evt = Event::Custom::Lookup(kSwapFinishedEvent);
    if (evt >= 0)
        Event::Custom::Fire(evt, "%d%d", 1, static_cast<int>(setID));
@@ -140,8 +140,6 @@ uint32_t Create(const char *name, const char *icon) {
    EnsureLoaded();
    if (g_path.empty() || name == nullptr || name[0] == '\0')
        return 0;
-    if (g_sets.size() >= MAX_SETS)
-        return 0;
    if (FindByName(name) != nullptr)
        return 0;
    Set s;
@@ -177,4 +177,15 @@ const uint8_t *ResolveItemByGUID(uint64_t guid) {
    return Item::Location::ResolveByGUID(guid);
 }

+void SnapshotPaperdoll(uint64_t *out) {
+    for (int i = 0; i < SLOT_COUNT; ++i)
+        out[i] = 0;
+    auto *invMgr = ResolvePlayerInvMgr();
+    auto *guids = InvMgrGuidArray(invMgr);
+    if (guids == nullptr)
+        return;
+    for (int i = 0; i < SLOT_COUNT; ++i)
+        out[i] = guids[i];
+}
+
 } // namespace EquipmentSet::Locations
@@ -42,4 +42,16 @@ int FindGUID(uint64_t targetGuid);
 // isn't known to the client. Side-effect free.
 const uint8_t *ResolveItemByGUID(uint64_t guid);

+// Copies the current paperdoll GUIDs into `out[0..SLOT_COUNT-1]`,
+// where `out[i]` is the GUID at 1-based equipment slot `i+1`.
+// Empty / unequipped slots write 0. Reads from the player invMgr's
+// flat GUID array directly — no Lua stack, no engine state changes.
+//
+// Used by `UseEquipmentSet` to seed a "virtual paperdoll" model that
+// stays current across in-flight swaps. The engine's CGItem state
+// lags behind packet sends (server has to ACK each swap), so any
+// subsequent `FindGUID` after the first packet would return stale
+// pre-swap locations. Tracking moves locally bypasses that lag.
+void SnapshotPaperdoll(uint64_t *out);
+
 } // namespace EquipmentSet::Locations
@@ -56,11 +56,6 @@ inline const char *DefaultIcon() { return "INV_Misc_QuestionMark"; }
 // (1.15.x is also 32). 4.3.4 used the same buffer size.
 constexpr int MAX_NAME_LEN = 31;

-// Hard cap matching 4.3.4 behavior. Modern Classic Era (1.15) raised
-// this to 30; we follow the 4.3.4 number so legacy addons that show
-// "X / 10" don't surprise users.
-constexpr int MAX_SETS = 10;
-
 // `GetItemLocations` encoding — matches Blizzard FrameXML's
 // `EquipmentManager_UnpackLocation` (constants are in
 // `Constants.lua`: `ITEM_INVENTORY_LOCATION_*` and
@@ -18,6 +18,12 @@
 // per-frame `OnMouseDown` scripts — these fire even when the click
 // misses any UI frame.
 //
+// `IsMouseButtonDown([button])` — query the current held state of a
+// specific button by name or 1-based ID, or "any button held" when
+// called with no args. State is maintained from the same hook stream
+// as the events (single source of truth — events firing and the
+// state being readable happen at the same point in the pipeline).
+//
 // Same `WH_GETMESSAGE` thread-message hook pattern as
 // [Input::Modifier](Modifier.cpp): we intercept the WM_*BUTTON*
 // messages on the engine's main thread *before* dispatch. The hook
@@ -28,6 +34,9 @@
 #include "Game.h"
 #include "event/Custom.h"

+#include <cstdint>
+#include <cstring>
+
 #include <windows.h>

 namespace Input::GlobalMouse {
@@ -37,6 +46,19 @@ namespace {
 constexpr const char *kDownEvent = "GLOBAL_MOUSE_DOWN";
 constexpr const char *kUpEvent   = "GLOBAL_MOUSE_UP";

+// Held-state bitmap — bit `i` set means the button with 1-based
+// `IsMouseButtonDown` ID `i+1` is currently held. Modern API IDs:
+//   1 = LeftButton, 2 = RightButton, 3 = MiddleButton,
+//   4 = Button4    (XBUTTON1), 5 = Button5 (XBUTTON2).
+constexpr int BIT_LEFT_BUTTON   = 0;
+constexpr int BIT_RIGHT_BUTTON  = 1;
+constexpr int BIT_MIDDLE_BUTTON = 2;
+constexpr int BIT_BUTTON4       = 3;
+constexpr int BIT_BUTTON5       = 4;
+constexpr uint32_t MASK_ANY_BUTTON = 0x1F;
+
+uint32_t g_mouseButtonMask = 0;
+
 HHOOK g_msgHook = nullptr;

 // Maps WM_*BUTTON{DOWN,UP} → ("LeftButton"|..., isDown). Returns
@@ -60,16 +82,60 @@ const char *DecodeButton(UINT msg, WPARAM wParam, bool *outDown) {
    }
 }

+// Maps a "LeftButton"/.../"Button5" name to its bit index. -1 for
+// any other string.
+int NameToBitIdx(const char *name) {
+    if (name == nullptr)
+        return -1;
+    if (std::strcmp(name, "LeftButton") == 0)   return BIT_LEFT_BUTTON;
+    if (std::strcmp(name, "RightButton") == 0)  return BIT_RIGHT_BUTTON;
+    if (std::strcmp(name, "MiddleButton") == 0) return BIT_MIDDLE_BUTTON;
+    if (std::strcmp(name, "Button4") == 0)      return BIT_BUTTON4;
+    if (std::strcmp(name, "Button5") == 0)      return BIT_BUTTON5;
+    return -1;
+}
+
 void ProcessMouseMessage(UINT msg, WPARAM wParam) {
    bool down = false;
    const char *name = DecodeButton(msg, wParam, &down);
    if (name == nullptr)
        return;
+
+    const int bitIdx = NameToBitIdx(name);
+    if (bitIdx >= 0) {
+        const uint32_t bit = 1u << bitIdx;
+        if (down) g_mouseButtonMask |= bit;
+        else      g_mouseButtonMask &= ~bit;
+    }
+
    const int slot = Event::Custom::Lookup(down ? kDownEvent : kUpEvent);
    if (slot >= 0)
        Event::Custom::Fire(slot, "%s", name);
 }

+int __fastcall Script_IsMouseButtonDown(void *L) {
+    bool down;
+    if (Game::Lua::GetTop(L) == 0) {
+        // No-arg form: any button held.
+        down = (g_mouseButtonMask & MASK_ANY_BUTTON) != 0;
+    } else {
+        int bitIdx = -1;
+        if (Game::Lua::IsNumber(L, 1)) {
+            const int id = static_cast<int>(Game::Lua::ToNumber(L, 1));
+            if (id >= 1 && id <= 5)
+                bitIdx = id - 1;
+        } else if (Game::Lua::IsString(L, 1)) {
+            bitIdx = NameToBitIdx(Game::Lua::ToString(L, 1));
+        }
+        // Unrecognized button (bad id, unknown name) → false, matching
+        // the modern API's "did this specific button happen to be held"
+        // semantic. Bad input doesn't promote to the any-button check.
+        down = (bitIdx >= 0) && (g_mouseButtonMask & (1u << bitIdx)) != 0;
+    }
+    Game::Lua::PushBool(L, down);
+    return 1;
+}
+
 LRESULT CALLBACK GetMsgHook(int code, WPARAM wParam, LPARAM lParam) {
    // Only process when the message is being removed from the queue
    // (`PM_REMOVE` / `GetMessage`); `PM_NOREMOVE` peeks would deliver
@@ -88,7 +154,11 @@ void InstallHook() {
                                   GetCurrentThreadId());
 }

-void RegisterLuaFunctions() { InstallHook(); }
+void RegisterLuaFunctions() {
+    Game::Lua::RegisterGlobalFunction("IsMouseButtonDown",
+                                      &Script_IsMouseButtonDown);
+    InstallHook();
+}

 const Event::Custom::AutoReserve _reserveDown{kDownEvent};
 const Event::Custom::AutoReserve _reserveUp{kUpEvent};
@@ -105,6 +105,47 @@ bool FitsSlot(int slot1Based, uint32_t invType) {
    return (kSlotMaskByInvType[invType] & (1u << (slot1Based - 1))) != 0;
 }

+// ── Proficiency gate ──────────────────────────────────────────────
+// `FitsSlot` only checks invType→slot shape compatibility; without
+// also gating on the player's proficiencies this would return (e.g.)
+// mail helms for a warlock since both are `invType=HEAD`. Modern
+// WoW's equipment-set picker filters by what the player can actually
+// equip; we mirror that.
+//
+// Source of truth: the engine's per-itemClass proficiency bitmap at
+// `[VAR_PROFICIENCY_TABLE]` (17 u32 entries indexed by `m_class`).
+// SMSG_SET_PROFICIENCY's handler at `0x005E7B70` writes the bitmask
+// for each class verbatim from the wire. Bit N of `table[class]` =
+// "player can equip subclass N of this class". Same data the engine
+// itself reads for the tooltip "Mail/Leather/Plate" red-text and the
+// cursor-drop-on-paperdoll-slot check — covers both armor and weapon
+// proficiencies in one lookup.
+//
+// 4.3.4's `Script_GetInventoryItemsForSlot` does the equivalent check
+// via `FUN_00553AD0(itemClass) & (1 << subclass)`, reading from
+// `DAT_00DD4D38` (its own copy of the same packet-fed table).
+
+bool PlayerHasProficiency(uint32_t itemClass, uint32_t subclass) {
+    if (itemClass > 16)
+        return true; // table only covers 0..16; be permissive past that
+    const uint32_t mask = *reinterpret_cast<const uint32_t *>(
+        static_cast<uintptr_t>(Offsets::VAR_PROFICIENCY_TABLE) + itemClass * 4);
+    if (mask == 0)
+        return true; // table not populated yet (pre-SMSG_SET_PROFICIENCY)
+                     // — fail open so empty-mask doesn't blank the list
+    return (mask & (1u << subclass)) != 0;
+}
+
+bool PlayerCanEquip(const uint8_t *record) {
+    if (record == nullptr)
+        return true; // missing record — be permissive, don't hide the item
+    const uint32_t classCode = *reinterpret_cast<const uint32_t *>(
+        record + Offsets::OFF_ITEMSTATS_CLASS);
+    const uint32_t subclass = *reinterpret_cast<const uint32_t *>(
+        record + Offsets::OFF_ITEMSTATS_SUBCLASS);
+    return PlayerHasProficiency(classCode, subclass);
+}
+
 const uint8_t *PeekItemRecord(uint32_t itemID) {
    auto fn = reinterpret_cast<GetItemRecord_t>(Offsets::FUN_DBCACHE_ITEMSTATS_GET_RECORD);
    auto *cache = reinterpret_cast<void *>(Offsets::VAR_ITEMDB_CACHE);
@@ -112,11 +153,14 @@ const uint8_t *PeekItemRecord(uint32_t itemID) {
    return fn(cache, itemID, &zeroGuid, nullptr, nullptr, 0);
 }

-uint32_t ReadInventoryType(const uint8_t *cgItem) {
+const uint8_t *ItemRecordForCGItem(const uint8_t *cgItem) {
    const int itemID = Item::ID::FromCGItem(cgItem);
    if (itemID <= 0)
-        return 0;
-    auto *record = PeekItemRecord(static_cast<uint32_t>(itemID));
+        return nullptr;
+    return PeekItemRecord(static_cast<uint32_t>(itemID));
+}
+
+uint32_t ReadInventoryType(const uint8_t *record) {
    if (record == nullptr)
        return 0;
    return *reinterpret_cast<const uint32_t *>(
@@ -132,7 +176,10 @@ void CollectIfFits(int slot, const uint8_t *cgItem, int location,
                   std::vector<Hit> &out) {
    if (cgItem == nullptr)
        return;
-    if (!FitsSlot(slot, ReadInventoryType(cgItem)))
+    const uint8_t *record = ItemRecordForCGItem(cgItem);
+    if (!FitsSlot(slot, ReadInventoryType(record)))
+        return;
+    if (!PlayerCanEquip(record))
        return;
    out.push_back({location, cgItem});
 }
@@ -199,6 +199,38 @@ bool FromPaperdoll(const void *cgItem, int srcPaperdollSlot, int dstPaperdollSlo
                    dstPaperdollSlot);
 }

+bool ToBag(const void *cgItem, int srcPaperdollSlot, int dstBagID, int dstSlotInBag) {
+    if (srcPaperdollSlot < 1 || srcPaperdollSlot > 19)
+        return false;
+    if (cgItem == nullptr)
+        return false;
+
+    void *player = ResolvePlayer();
+    if (player == nullptr)
+        return false;
+    uint32_t playerLo = 0, playerHi = 0;
+    if (!ReadGuid(player, &playerLo, &playerHi))
+        return false;
+
+    uint32_t dstContainerLo = 0, dstContainerHi = 0, dstLinear = 0;
+    if (!EncodeBagSlot(dstBagID, dstSlotInBag,
+                       &dstContainerLo, &dstContainerHi, &dstLinear))
+        return false;
+
+    uint32_t itemLo = 0, itemHi = 0;
+    if (!ReadGuid(cgItem, &itemLo, &itemHi))
+        return false;
+
+    auto fn = reinterpret_cast<SwapFn_t>(Offsets::FUN_INVENTORY_SWAP);
+    fn(player,
+       itemLo, itemHi,
+       playerLo, playerHi,
+       static_cast<uint32_t>(srcPaperdollSlot - 1),
+       dstContainerLo, dstContainerHi, dstLinear,
+       0);
+    return true;
+}
+
 bool MoveCount(void *L, int srcBag, int srcSlot, int dstBag, int dstSlot, int count) {
    // Vanilla protocol writes count as a single byte. Clamp at 255;
    // anything larger would either truncate silently (255 sent) or
@@ -32,6 +32,12 @@ namespace Item::Swap {
 //   paperdoll slot `srcSlot` (1-based). Used for paperdoll-to-
 //   paperdoll swaps like rings 11/12, trinkets 13/14.
 //
+// - `ToBag(item, srcPaperdollSlot, dstBag, dstSlot)` — item currently
+//   in paperdoll slot, moving to a bag slot. The "unequip" direction
+//   `UseEquipmentSet` needs for slots the set wants empty. Uses the
+//   same atomic swap packet — server-side accept rules are identical
+//   (bagID 0..4, dst slot must be valid for that bag).
+//
 // All slot args are 1-based Lua-facing; helpers do the
 // linear-slot conversion. Returns `false` on bad args (slot out of
 // range, no player object, missing instance block on the item or
@@ -44,6 +50,8 @@ bool FromBag(const void *cgItem, int bagID, int slotInBag, int dstPaperdollSlot)

 bool FromPaperdoll(const void *cgItem, int srcPaperdollSlot, int dstPaperdollSlot);

+bool ToBag(const void *cgItem, int srcPaperdollSlot, int dstBagID, int dstSlotInBag);
+
 // General bag-to-bag swap — neither side is constrained to the
 // paperdoll. Same engine helper (`FUN_INVENTORY_SWAP`), which routes
 // to opcode 0x10D (same-container slot swap, e.g. backpack ↔ backpack)
@@ -21,6 +21,7 @@

 #include <cstdint>
 #include <cstdio>
+#include <cstring>

 namespace Item::Tooltip {

@@ -290,8 +291,82 @@ static int __fastcall Script_GameTooltipHasItem(void *L) {
    return 1;
 }

+// `GameTooltip:SetItemByGUID(guidString)` — modern method that renders
+// the tooltip for the specific item instance identified by GUID
+// (`"0xHHHHHHHHLLLLLLLL"` per `C_Item.GetItemGUID`). Distinct from
+// `SetItemByID`, which shows the base `ItemSparse` data with no
+// per-instance state: this path uses the live CGItem so the tooltip
+// includes enchant lines, random-suffix-decorated name + bonuses,
+// locked/broken state, etc.
+//
+// Implementation: parse the GUID string, resolve via the engine's
+// `FUN_OBJECT_RESOLVE_BY_GUID` (same path `C_Item.GetItemLocation`
+// and `GameTooltip:GetItem` use), build the fully-decorated
+// hyperlink via `Item::Link::FromCGItem` (engine helper at
+// `FUN_GAMETOOLTIP_BUILD_ITEM_LINK`), then dispatch to the engine's
+// existing `Script_GameTooltip_SetHyperlink`. SetHyperlink parses
+// the link's `item:N:enchant:gem:gem:gem:gem:suffix:unique` payload
+// back into instance-specific tooltip data — closing the loop
+// without us needing a separate engine entry point for "tooltip
+// from CGItem*".
+//
+// Silent no-op when the GUID is malformed, not loaded in the
+// client, or doesn't resolve to an item (creature/object GUIDs go
+// to a different resolver).
+static int __fastcall Script_GameTooltipSetItemByGUID(void *L) {
+    if (Game::Lua::Type(L, 1) != Game::Lua::TYPE_TABLE) {
+        Game::Lua::Error(L, "Usage: GameTooltip:SetItemByGUID(itemGUID)");
+        return 0;
+    }
+    if (Game::Lua::Type(L, 2) != Game::Lua::TYPE_STRING) {
+        Game::Lua::Error(L, "Usage: GameTooltip:SetItemByGUID(itemGUID)");
+        return 0;
+    }
+    const char *guidStr = Game::Lua::ToString(L, 2);
+    uint64_t guid = 0;
+    if (!Item::Location::ParseGUIDString(guidStr, &guid))
+        return 0;
+    const uint8_t *cgItem = Item::Location::ResolveByGUID(guid);
+    if (cgItem == nullptr)
+        return 0;
+    const char *link = Item::Link::FromCGItem(cgItem);
+    if (link == nullptr || *link == '\0')
+        return 0;
+
+    // `Item::Link::FromCGItem` returns the full
+    // `|cffXXXXXXXX|Hitem:N:E:S:S:S:S:R:U|h[Name]|h|r` decorated link
+    // (the public-link form addons paste into chat). `SetHyperlink`
+    // wants just the bare `item:N:E:S:S:S:S:R:U` payload — passing the
+    // decorated form trips its "Unknown link type" Lua error because
+    // the parser sees `|c` first and gives up. Extract the payload by
+    // finding `|Hitem:` and copying through to the closing `|h`.
+    const char *open = std::strstr(link, "|Hitem:");
+    if (open == nullptr)
+        return 0;
+    open += 2; // skip past `|H` so we start at `item:`
+    const char *close = std::strstr(open, "|h");
+    if (close == nullptr)
+        return 0;
+    const size_t payloadLen = static_cast<size_t>(close - open);
+    char payload[128];
+    if (payloadLen + 1 > sizeof(payload))
+        return 0;
+    std::memcpy(payload, open, payloadLen);
+    payload[payloadLen] = '\0';
+
+    // Replace stack[2] (the GUID) with the bare item link and
+    // dispatch to SetHyperlink with (self, "item:...").
+    Game::Lua::SetTop(L, 1);
+    Game::Lua::PushString(L, payload);
+
+    using Script_t = int(__fastcall *)(void *L);
+    auto fn = reinterpret_cast<Script_t>(Offsets::FUN_SCRIPT_GAMETOOLTIP_SET_HYPERLINK);
+    return fn(L);
+}
+
 static const Game::Lua::FrameMethodEntry g_methods[] = {
    {"SetItemByID", &Script_GameTooltipSetItemByID},
+    {"SetItemByGUID", &Script_GameTooltipSetItemByGUID},
    {"SetInventoryItemByID", &Script_GameTooltipSetInventoryItemByID},
    {"GetItem", &Script_GameTooltipGetItem},
    {"HasItem", &Script_GameTooltipHasItem},
@@ -11,18 +11,31 @@
 // You should have received a copy of the GNU Lesser General Public License along with
 // ClassicAPI. If not, see <https://www.gnu.org/licenses/>.

-// `C_Item.GetItemUniqueness(itemLocation)` — uniqueness cap. Reads
-// `ItemStats_C.m_maxCount` from the item's cached record; that's the
-// only uniqueness signal vanilla's client carries. `1` = unique
-// ("Held In Off-hand" trinkets, special quest items, etc.); `0` =
-// unlimited; higher values cap the inventory count.
+// `C_Item.GetItemUniqueness(itemLocation)` and the `*ByID` variant
+// — uniqueness cap. Both read `ItemStats_C.m_maxCount` from the
+// item's cached record; that's the only uniqueness signal vanilla
+// carries. `1` = unique-equipped (one at a time); higher values
+// cap the inventory count; `0` = unlimited.
 //
-// Modern WoW returns a 3-tuple `(maxEquipped, category, equippedCount)`
-// keyed off the post-TBC category system (e.g. "Unique-Equipped:
-// Brewfest Mug"). Vanilla has no category system, so we surface
-// `m_maxCount` as the first return and leave the category nil and
-// equipped count `0` — matching modern's "field present but inapplicable"
-// convention.
+// Modern WoW (Classic Era 1.15.x) gives the two functions **different
+// signatures**, verified against `_classic_` BlizzardInterfaceCode's
+// `ItemDocumentation.lua`:
+//
+//   GetItemUniqueness(itemLocation) →
+//       limitCategory (number, non-nilable),
+//       limitMax      (number, non-nilable)
+//
+//   GetItemUniquenessByID(itemInfo) →
+//       isUnique           (bool, non-nilable),
+//       limitCategoryName  (string, nilable),
+//       limitCategoryCount (number, nilable),
+//       limitCategoryID    (number, nilable)
+//
+// Vanilla has no `LimitCategory.dbc` system (TBC+ addition for
+// "Unique-Equipped: Brewfest Mug"-style cross-item category caps),
+// so the category fields are always nil/0. `isUnique` collapses to
+// `m_maxCount > 0`; `limitMax` and `limitCategoryCount` both surface
+// the raw `m_maxCount`.

 #include "Game.h"
 #include "Offsets.h"
@@ -50,54 +63,58 @@ const uint8_t *PeekItemRecord(uint32_t itemID) {
    return fn(cache, itemID, &zeroGuid, nullptr, nullptr, 0);
 }

-} // namespace
-
-// Pushes the 3-tuple `(maxAllowed, nil, 0)` derived from the
-// ItemStats_C record, or nil + early-return on cache miss.
-int PushFromItemID(void *L, uint32_t itemID) {
+// Returns the item's `m_maxCount` or -1 if the record isn't cached.
+// `-1` is a "warm-and-bail" sentinel; caller pushes nothing on -1
+// so the Lua side sees the modern "MayReturnNothing" behaviour.
+int ReadMaxCount(uint32_t itemID) {
    const uint8_t *record = PeekItemRecord(itemID);
    if (record == nullptr) {
        Item::Data::WarmCache(itemID);
-        Game::Lua::PushNil(L);
-        return 1;
+        return -1;
    }
-    const int maxCount = *reinterpret_cast<const int *>(
+    return *reinterpret_cast<const int *>(
        record + Offsets::OFF_ITEMSTATS_MAX_COUNT);
-    Game::Lua::PushNumber(L, static_cast<double>(maxCount));
-    Game::Lua::PushNil(L);              // category (vanilla has none)
-    Game::Lua::PushNumber(L, 0.0);      // equippedCount (not tracked)
-    return 3;
 }

+} // namespace
+
+// `GetItemUniqueness(itemLocation)` shape: `(limitCategory, limitMax)`.
 static int __fastcall Script_GetItemUniqueness(void *L) {
-    if (!Item::Location::IsLocationArg(L, 1)) {
-        Game::Lua::PushNil(L);
-        return 1;
-    }
+    if (!Item::Location::IsLocationArg(L, 1))
+        return 0;
    auto *item = Item::Location::Resolve(L, 1);
-    if (item == nullptr) {
-        Game::Lua::PushNil(L);
-        return 1;
-    }
+    if (item == nullptr)
+        return 0;
    const int itemID = Item::ID::FromCGItem(item);
-    if (itemID <= 0) {
-        Game::Lua::PushNil(L);
-        return 1;
-    }
-    return PushFromItemID(L, static_cast<uint32_t>(itemID));
+    if (itemID <= 0)
+        return 0;
+    const int maxCount = ReadMaxCount(static_cast<uint32_t>(itemID));
+    if (maxCount < 0)
+        return 0; // cache miss — modern API documents "MayReturnNothing"
+    Game::Lua::PushNumber(L, 0.0); // limitCategory (vanilla has no LimitCategory.dbc)
+    Game::Lua::PushNumber(L, static_cast<double>(maxCount));
+    return 2;
 }

+// `GetItemUniquenessByID(itemID)` shape:
+// `(isUnique, limitCategoryName, limitCategoryCount, limitCategoryID)`.
 static int __fastcall Script_GetItemUniquenessByID(void *L) {
-    if (!Game::Lua::IsNumber(L, 1)) {
-        Game::Lua::PushNil(L);
-        return 1;
-    }
+    if (!Game::Lua::IsNumber(L, 1))
+        return 0;
    const int itemID = static_cast<int>(Game::Lua::ToNumber(L, 1));
-    if (itemID <= 0) {
-        Game::Lua::PushNil(L);
-        return 1;
-    }
-    return PushFromItemID(L, static_cast<uint32_t>(itemID));
+    if (itemID <= 0)
+        return 0;
+    const int maxCount = ReadMaxCount(static_cast<uint32_t>(itemID));
+    if (maxCount < 0)
+        return 0;
+    Game::Lua::PushBool(L, maxCount > 0);
+    Game::Lua::PushNil(L);          // limitCategoryName (no categories in vanilla)
+    if (maxCount > 0)
+        Game::Lua::PushNumber(L, static_cast<double>(maxCount));
+    else
+        Game::Lua::PushNil(L);      // limitCategoryCount — nil when not limited
+    Game::Lua::PushNil(L);          // limitCategoryID
+    return 4;
 }

 static void RegisterLuaFunctions() {
@@ -11,9 +11,12 @@
 // You should have received a copy of the GNU Lesser General Public License along with
 // ClassicAPI. If not, see <https://www.gnu.org/licenses/>.

-// `C_Item.UseItemByName(itemInfo)` — finds the first item in the
-// player's bags matching `itemInfo` (itemID, link, or name) and uses
-// it via the engine's `CGItem::UseItem` primitive.
+// `C_Item.UseItemByName(itemInfo [, unit])` — finds the first item in
+// the player's bags matching `itemInfo` (itemID, link, or name) and
+// uses it via the engine's `CGItem::UseItem` primitive. Optional
+// `unit` is a unit token (`"player"`, `"target"`, `"focus"`, …)
+// passed to spell-cast items (scrolls, traps, on-use targeted
+// effects) as the cast target.
 //
 // Same structure 3.3.5's `Script_UseItemByName` uses: locate the item
 // directly, then hand it to the engine's by-item-pointer use call.
@@ -25,14 +28,19 @@
 // food / potion / hearthstone / scroll / quiver all route through
 // the same entry.
 //
-// Target arg: we pass nullptr / a zero GUID. The engine substitutes
-// the player itself for self-use items (hearthstone, food, potion);
-// 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("...")`.
+// Target arg: `FUN_ITEM_USE`'s `param_1` is read as a `uint64_t *`
+// pointing at the target's GUID. The engine writes it through to the
+// "use item" event (`DAT_00c4c1d0`/`DAT_00c4c1d4` + event 0x122) for
+// spell-cast items, and into the cast-targeting helper at
+// `FUN_006e5a90`. For self-use items (hearthstone, food, potion) the
+// engine overwrites with the item's own GUID before dispatch, so a
+// stray target is harmless. We default to a zero GUID when the caller
+// omits `unit` — matches existing call sites.
 //
 // Returns nothing. Silently no-ops on bad input, item not found in
-// bags, item locked, on cooldown, etc.
+// bags, item locked, on cooldown, etc. An unrecognized `unit` string
+// is treated as "no target" rather than raising, matching arg-1's
+// "silently no-ops on bad input" contract.

 #include "Game.h"
 #include "Offsets.h"
@@ -41,6 +49,7 @@
 #include "item/Location.h"

 #include <cstdint>
+#include <cstring>
 #include <string.h>

 namespace Item::Use {
@@ -54,6 +63,73 @@ using GetItemRecord_t = const uint8_t *(__thiscall *)(void *cache, uint32_t item
 using UseItem_t = unsigned(__thiscall *)(const void *item, const uint64_t *targetGuid,
                                          int flag);

+using TokenToGUID_t = uint64_t(__fastcall *)(const char *token);
+
+bool HasPrefix(const char *s, const char *prefix) {
+    return std::strncmp(s, prefix, std::strlen(prefix)) == 0;
+}
+
+// Walk past any "target" suffixes (`targettarget`, `focustargettarget`,
+// …); returns a pointer at the first non-"target" character.
+const char *SkipTargetSuffixes(const char *s) {
+    while (HasPrefix(s, "target"))
+        s += 6;
+    return s;
+}
+
+// Predicate mirror of the engine's token grammar inside
+// `FUN_TOKEN_TO_GUID` (`0x00515970`) plus the families our own
+// `Unit::TokenExtensions` hook adds (`focus`, `nameplateN`). The
+// engine raises a Lua error on unknown input, so we gate before
+// dispatching to keep our "silently no-ops on bad input" contract.
+//
+// Every base token may be followed by zero or more `target` suffixes
+// (`playertarget`, `party1targettarget`, …) which the engine's
+// resolver walks via `LAB_005159d3..0x00515A2C`.
+bool MatchBase(const char *s, const char *base, bool requireDigits) {
+    if (!HasPrefix(s, base))
+        return false;
+    const char *rest = s + std::strlen(base);
+    if (requireDigits) {
+        const char *p = rest;
+        while (*p >= '0' && *p <= '9')
+            ++p;
+        if (p == rest)
+            return false;
+        rest = p;
+    }
+    return *SkipTargetSuffixes(rest) == '\0';
+}
+
+bool LooksLikeToken(const char *s) {
+    if (s == nullptr || *s == '\0')
+        return false;
+    // Order matters for shared roots: longer prefix first
+    // (`partypet`/`raidpet` before `party`/`raid`).
+    if (MatchBase(s, "partypet", true))   return true;
+    if (MatchBase(s, "raidpet", true))    return true;
+    if (MatchBase(s, "party", true))      return true;
+    if (MatchBase(s, "raid", true))       return true;
+    if (MatchBase(s, "nameplate", true))  return true;
+    if (MatchBase(s, "mouseover", false)) return true;
+    if (MatchBase(s, "player", false))    return true;
+    if (MatchBase(s, "target", false))    return true;
+    if (MatchBase(s, "focus", false))     return true;
+    if (MatchBase(s, "npc", false))       return true;
+    if (MatchBase(s, "pet", false))       return true;
+    return false;
+}
+
+uint64_t ResolveUnitGuid(void *L, int idx) {
+    if (!Game::Lua::IsString(L, idx))
+        return 0;
+    const char *token = Game::Lua::ToString(L, idx);
+    if (!LooksLikeToken(token))
+        return 0;
+    auto fn = reinterpret_cast<TokenToGUID_t>(Offsets::FUN_TOKEN_TO_GUID);
+    return fn(token);
+}
+
 const uint8_t *PeekItemRecord(uint32_t itemID) {
    auto fn = reinterpret_cast<GetItemRecord_t>(Offsets::FUN_DBCACHE_ITEMSTATS_GET_RECORD);
    auto *cache = reinterpret_cast<void *>(Offsets::VAR_ITEMDB_CACHE);
@@ -107,9 +183,9 @@ int __fastcall Script_C_Item_UseItemByName(void *L) {
        return 0;
    }

-    const uint64_t zeroTarget = 0;
+    const uint64_t targetGuid = ResolveUnitGuid(L, 2);
    auto useItem = reinterpret_cast<UseItem_t>(Offsets::FUN_ITEM_USE);
-    useItem(cgItem, &zeroTarget, 0);
+    useItem(cgItem, &targetGuid, 0);
    return 0;
 }

@@ -0,0 +1,74 @@
+// This file is part of ClassicAPI.
+//
+// ClassicAPI is free software: you can redistribute it and/or modify it under the terms
+// of the GNU Lesser General Public License as published by the Free Software Foundation, either
+// version 3 of the License, or (at your option) any later version.
+//
+// ClassicAPI is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
+// PURPOSE. See the GNU Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public License along with
+// ClassicAPI. If not, see <https://www.gnu.org/licenses/>.
+
+// `IsLoggedIn()` — exposed on both Lua states (glue and in-game).
+// Returns `true` once a character has been loaded *and identified*
+// (GUID populated), `false` on glue, pre-load, and the brief window
+// between struct allocation and character-data unpack.
+//
+// Check is two-step:
+//   1. `[VAR_LOCAL_PLAYER_PTR]` non-NULL — the player aggregator
+//      struct has been allocated
+//   2. `*(uint64*)(player + OFF_LOCAL_PLAYER_GUID)` non-zero — the
+//      character's GUID has been populated into the struct
+//
+// The pointer alone is too lax: the engine allocates the struct
+// shortly before the character data lands, so there's a window where
+// the pointer is non-NULL but the GUID is still zero. Most addons
+// that check `IsLoggedIn` go straight to `UnitGUID("player")` next,
+// and we don't want them to see GUID==nil right after IsLoggedIn
+// reported true.
+//
+// 3.3.5 uses a single byte flag at `[0x00BD0793]` cleared on world
+// entry — we couldn't pin down the analogous 1.12 flag (the engine
+// path that signals event 253 wires through CVar-init machinery and
+// doesn't map cleanly across the binary). The pointer+GUID check is
+// the same effective signal: both flip together at the moment the
+// player object is ready, and stay stable across zone transitions.
+
+#include "Game.h"
+#include "Offsets.h"
+
+#include <cstdint>
+
+namespace Player::LoginStatus {
+
+namespace {
+
+int __fastcall Script_IsLoggedIn(void *L) {
+    auto *player = *reinterpret_cast<const uint8_t *const *>(
+        Offsets::VAR_LOCAL_PLAYER_PTR);
+    if (player == nullptr) {
+        Game::Lua::PushBool(L, false);
+        return 1;
+    }
+    const uint64_t guid = *reinterpret_cast<const uint64_t *>(
+        player + Offsets::OFF_LOCAL_PLAYER_GUID);
+    Game::Lua::PushBool(L, guid != 0);
+    return 1;
+}
+
+void RegisterInGame() {
+    Game::Lua::RegisterGlobalFunction("IsLoggedIn", &Script_IsLoggedIn);
+}
+
+void RegisterGlue() {
+    Game::Lua::RegisterGlueFunction("IsLoggedIn", &Script_IsLoggedIn);
+}
+
+} // namespace
+
+static const Game::ModuleAutoRegister _autoreg{&RegisterInGame};
+static const Game::GlueModuleAutoRegister _gluereg{&RegisterGlue};
+
+} // namespace Player::LoginStatus
@@ -40,15 +40,156 @@ inline const uint8_t *Peek(uint32_t questID) {
 }

 // Field offsets within the data block returned by `Lookup`.
-constexpr int OFF_TITLE = 0x9C;
+//
+// Derived from the engine's own `Script_GetQuestLog*` accessors at
+// `0x004DF930..0x004E12B0`. Each accessor calls `_GetRecord` then
+// reads from one of these offsets; the existing comment block on each
+// constant identifies the source function. See CLAUDE.md's
+// "Quest static-info cache" section for the full trace.
+
+// Numeric metadata fields, in wire order from `SMSG_QUEST_QUERY_RESPONSE`.
+//
+// The cache layout mirrors the packet's field order — the deserializer
+// at the SMSG handler unpacks 15 uint32 fields at +0x00..+0x38 before
+// the reward/choice item arrays. Names and semantics cross-referenced
+// from the in-binary serializer (`FUN_006DBCEC`) plus the canonical
+// vanilla 1.12 packet structure documented by vmangos/cmangos emulator
+// projects. Fields without a direct binary-side accessor (so just
+// known from wire-format alignment) are marked **(hypothesis)** —
+// they should be verified empirically before being relied on for
+// gameplay logic.
+//
+// QuestId — uint32, echo of the questID this entry caches.
+constexpr int OFF_QUEST_ID = 0x00;
+// QuestMethod — uint32. Server-side classification (typically `2` for
+// active-and-available, `0` for unavailable). Vanilla doesn't use
+// this for gameplay; it's stored but no engine accessor reads it.
+// **(hypothesis)**
+constexpr int OFF_QUEST_METHOD = 0x04;
+// Quest level — int32. Source: `FUN_004df340` (called by
+// `Script_GetQuestLogTitle`) does `mov eax, [block + 0x08]` and
+// pushes it as `level`.
+constexpr int OFF_LEVEL = 0x08;
+// ZoneOrSort — int32. The packet's `ZoneOrSort` field, used by the
+// quest log UI to group entries under headers:
+//   - Positive  = `AreaTable.dbc` zone areaID (e.g. 132 = Coldridge
+//                 Valley, 12 = Elwynn Forest)
+//   - Negative  = `-QuestSort.dbc` row (e.g. -263 = "Druid" sort)
+// `FUN_004dee60` reads this directly and matches it against
+// `VAR_QUEST_LOG_CATEGORY_TABLE` to find the collapsible header index.
+constexpr int OFF_ZONE_OR_SORT = 0x0C;
+// QuestInfo.dbc row — uint32 row index into the small DBC at
+// `0x00C0D9CC` (records) / `0x00C0D9D0` (count). Each record is
+// `{id@+0, char *name[locale]@+4}`; the localized name is the
+// quest-type tag string ("Dungeon", "Raid", "Group", "PvP", "Elite"
+// — modern WoW's `frequency`/`questTag`). Source: `FUN_004df2a0`.
+constexpr int OFF_QUEST_INFO_ROW = 0x10;
+// +0x14, +0x18, +0x1C, +0x20, +0x24 — five uint32 cache slots that
+// SMSG_QUEST_QUERY_RESPONSE in vanilla 1.12 doesn't populate. The
+// struct has them (the serializer at `0x006DBCEC` writes them as part
+// of the WDB save / network shape), but the response handler leaves
+// them zero-filled. Verified empirically across three diverse quests
+// (race-restricted starter, dungeon, authored-timer delivery) — all
+// five slots zero in every case.
+//
+// Wire-format docs (vmangos / cmangos emulator quest_template) name
+// them SuggestedPlayers, LimitTime, RequiredRaces, RequiredSkill,
+// RequiredSkillValue respectively, but the vanilla server *enforces*
+// these constraints server-side and filters quests before broadcasting
+// them, so the client never needs the data. Addons that want race /
+// class / skill / timer info must source from an external scraped DB
+// (pfQuest-style). Constants intentionally omitted — no use case.
+//
+// Signed money delta — int32. Positive = reward copper, negative =
+// `-required` copper. The engine has two accessors that share this
+// field with complementary sign:
+//   - `Script_GetQuestLogRewardMoney`   returns max(0, +money)
+//   - `Script_GetQuestLogRequiredMoney` returns max(0, -money)
+constexpr int OFF_MONEY_DELTA = 0x28;
+// Level-cap reward money bonus — int32. Added to the reward when
+// the player's level is ≥ 60. Source: `Script_GetQuestLogRewardMoney`
+// does `cmp [player.unit + 0x70], 0x3C` (level >= 60) then
+// `add edx, [block + 0x2C]`.
+constexpr int OFF_LEVEL_CAP_BONUS_MONEY = 0x2C;
+// Reward spellID — int32. 0 = no spell reward. Source:
+// `Script_GetQuestLogRewardSpell` does `mov eax, [block + 0x30]` then
+// resolves the SpellIcon path and locale-applied name via `Spell.dbc`.
+// This is a spell *learned by the player* on completion (recipes,
+// taught spells); not to be confused with `OFF_SRC_ITEM_ID` which
+// is the item the questgiver hands over at accept-time.
+constexpr int OFF_REWARD_SPELL_ID = 0x30;
+// SrcItemId — itemID given to the player when the quest is accepted.
+// 0 = no source item. The questgiver hands this item over so the
+// player can complete the quest objective (e.g. "Read the Verdant
+// Sigil" gives item 9580; player uses it, then turns the same item
+// back in).
+//
+// Empirically derived (the offset was originally interpreted as
+// `RewardSpellCast` from one emulator wire-order variant, but a
+// real-world dump of quest 3120 stored `9580` here while the quest's
+// own item objective also references item 9580 — consistent with
+// SrcItemId semantics, not with a spell-cast-at-turn-in).
+constexpr int OFF_SRC_ITEM_ID = 0x34;
+// Quest flags — uint32. Bit definitions match modern WoW's
+// `QUEST_FLAGS_*` enum, of which only bit 3 (`0x08` SHARABLE) is
+// confirmed-tested by the engine (`Script_GetQuestLogPushable`'s
+// `test byte ptr [block + 0x38], 0x08`). Other bits are presumed
+// stored but unverified.
+constexpr int OFF_QUEST_FLAGS = 0x38;
 // Reward and choice item arrays — up to 4 reward and 6 choice
 // itemIDs stored inline (4 bytes each). 0 in any slot means
 // "no item in this slot". Used by `GetQuestLogItemLink` /
 // `GetQuestLogItemID`.
+//
+// Each itemID array is paired with a parallel uint32 count array
+// (the "how many of this item" reward). Layout in cache memory:
+//   +0x3C  RewardItems[4]
+//   +0x4C  RewardItemsCount[4]
+//   +0x5C  ChoiceItems[6]
+//   +0x74  ChoiceItemsCount[6]
+// Verified from `Script_GetQuestLogRewardInfo` (`fild [block + slot*4 + 0x4C]`
+// for numItems) and `Script_GetQuestLogChoiceInfo` (`fild [block + slot*4 + 0x74]`).
 constexpr int OFF_REWARD_ITEMS = 0x3C;
+constexpr int OFF_REWARD_ITEMS_COUNT = 0x4C;
 constexpr int OFF_CHOICE_ITEMS = 0x5C;
+constexpr int OFF_CHOICE_ITEMS_COUNT = 0x74;
 constexpr int REWARD_COUNT = 4;
 constexpr int CHOICE_COUNT = 6;
+// Point-of-interest marker — server-supplied map coordinate hint
+// used by the questgiver objective panel to display "go here" arrows
+// in modern WoW. Set on quests that have a designated location;
+// 0/0/0 = no POI. Read sequentially by the serializer at
+// `0x006DBE5B..0x006DBE8E` using mixed integer + float wire methods.
+// **(hypothesis)**
+constexpr int OFF_POI_MAP_ID = 0x8C; // uint32
+constexpr int OFF_POI_X = 0x90;      // float
+constexpr int OFF_POI_Y = 0x94;      // float
+constexpr int OFF_POI_OPT = 0x98;    // uint32 — display option, or doubles as title length
+constexpr int OFF_TITLE = 0x9C;
+// Inline narrative text — both locale-applied and printf-style
+// format-expanded by the engine's variable substituter at
+// `0x00506F70` (handles tokens like `$N` for player name, `$C` for
+// class, etc.). Source: `Script_GetQuestLogQuestText` reads both,
+// pushes `description` first then `objectives`.
+//
+// We deliberately expose the *raw* inline bytes, not the format-
+// expanded version, because the substituter wants a 1024-byte
+// scratch buffer and the substitutions (player name, class) belong
+// in the addon layer anyway. Addons can run `string.gsub` if they
+// need the runtime values, otherwise raw text is more useful for
+// guides / databases.
+constexpr int OFF_OBJECTIVES = 0x29C;
+constexpr int OFF_DESCRIPTION = 0xA9C;
+// Completion text — the "talk to me now" body shown on the
+// quest-reward UI panel after objectives are met. 0x200 (512) bytes
+// inline. Modern API exposes this as `GetQuestLogCompletionText()`.
+// Confirmed by the cache copy at `0x00562E1F..0x00562E36` (a 0x200-byte
+// memcpy from src+0x129C to dst+0x129C) and by the serializer at
+// `0x006DBEBE` (`lea eax, [edi+0x129C]` followed by the string-writer
+// call). Vanilla LeaderBoard reads from this offset for some override
+// cases but the engine never directly exposes the text to Lua —
+// `Script_GetQuestLogQuestText` returns description + objectives only.
+constexpr int OFF_COMPLETION_TEXT = 0x129C;
 // Objective arrays — four uint32[4] parallel slabs carrying
 // SMSG_QUEST_QUERY_RESPONSE's RequiredNPCOrGo / Count / Item / Count
 // fields verbatim. NPC-or-GO is **signed**: positive = creature
@@ -66,5 +207,18 @@ constexpr int OFF_REQUIRED_NPC_OR_GO_COUNT = 0x14AC;  // uint32[4]
 constexpr int OFF_REQUIRED_ITEM = 0x14BC;             // uint32[4]
 constexpr int OFF_REQUIRED_ITEM_COUNT = 0x14CC;       // uint32[4]
 constexpr int OBJECTIVE_COUNT = 4;
+// Per-objective override text — array of 4 inline char buffers,
+// 256 (0x100) bytes per entry, indexed in objective declaration
+// order (NPC/GO slots fill first, then item slots — same order the
+// LeaderBoard accessor enumerates). Empty string = no override
+// (engine auto-formats as `"<NPC name>: X/Y"`); otherwise the
+// engine displays the buffer verbatim. Confirmed by the
+// `shl ecx, 8; mov dl, [block + ecx + 0x14DC]` access pattern in
+// `Script_GetQuestLogLeaderBoard` and by the four sequential reads
+// in the packet serializer at `0x006DBF17..0x006DBF41` (0x14DC,
+// 0x15DC, 0x16DC, 0x17DC).
+constexpr int OFF_OBJECTIVE_TEXT = 0x14DC;
+constexpr int OBJECTIVE_TEXT_STRIDE = 0x100;
+constexpr int OBJECTIVE_TEXT_COUNT = 4;

 } // namespace Quest::Cache
@@ -0,0 +1,254 @@
+// This file is part of ClassicAPI.
+//
+// ClassicAPI is free software: you can redistribute it and/or modify it under the terms
+// of the GNU Lesser General Public License as published by the Free Software Foundation, either
+// version 3 of the License, or (at your option) any later version.
+//
+// ClassicAPI is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
+// PURPOSE. See the GNU Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public License along with
+// ClassicAPI. If not, see <https://www.gnu.org/licenses/>.
+
+// `C_QuestLog.GetQuestDetails(questID)` — single accessor that returns
+// everything we know how to read from the quest static-info cache as a
+// Lua table. Powers quest-helper-style addons that want one round-trip
+// instead of N separate `C_QuestLog.GetTitleForQuestID` / etc. calls.
+//
+// Returns `nil` if the quest isn't cached. Caller should pair with
+// `C_QuestLog.RequestLoadQuestByID` + listen for `QUEST_DATA_LOAD_RESULT`.
+// All offsets read here come from the engine's own `Script_GetQuestLog*`
+// accessors — see `Cache.h` for the per-field derivation.
+
+#include "Game.h"
+#include "Offsets.h"
+#include "quest/Cache.h"
+
+#include <cstdint>
+
+namespace Quest::Details {
+
+namespace {
+
+// QuestInfo.dbc — 12-row table holding the localized quest-type tags
+// ("Dungeon" / "Raid" / "Group" / "PvP" / "Elite"). Address pair from
+// `docs/DBCs.md`.
+constexpr uintptr_t VAR_QUESTINFO_DBC_RECORDS = 0x00C0D9CC;
+constexpr uintptr_t VAR_QUESTINFO_DBC_COUNT = 0x00C0D9D0;
+
+const char *LookupQuestType(uint32_t row) {
+    if (row == 0)
+        return nullptr;
+    const int count = *reinterpret_cast<const int *>(VAR_QUESTINFO_DBC_COUNT);
+    if (count <= 0 || row > static_cast<uint32_t>(count))
+        return nullptr;
+    const uint8_t *const *records =
+        *reinterpret_cast<const uint8_t *const *const *>(
+            VAR_QUESTINFO_DBC_RECORDS);
+    if (!records)
+        return nullptr;
+    const uint8_t *record = records[row];
+    if (!record)
+        return nullptr;
+    const int localeIdx =
+        *reinterpret_cast<const int *>(Offsets::VAR_LOCALE_INDEX);
+    if (localeIdx < 0 || localeIdx > 8)
+        return nullptr;
+    auto *names = reinterpret_cast<const char *const *>(record + 4);
+    return names[localeIdx];
+}
+
+// Pushes an array of `{id=itemID, count=N}` tables for each non-zero
+// reward slot. `ids[count]` and `counts[count]` are parallel arrays
+// in the cache block. Leaves exactly one table on top of the stack.
+void PushItemArray(void *L, const uint32_t *ids, const uint32_t *counts,
+                   int count) {
+    Game::Lua::NewTable(L);
+    int next = 1;
+    for (int i = 0; i < count; ++i) {
+        if (ids[i] == 0)
+            continue;
+        Game::Lua::PushNumber(L, static_cast<double>(next++));
+        Game::Lua::NewTable(L);
+        Game::Lua::SetFieldNumber(L, "id", static_cast<double>(ids[i]));
+        Game::Lua::SetFieldNumber(L, "count", static_cast<double>(counts[i]));
+        Game::Lua::SetTable(L, -3);
+    }
+}
+
+// Per-objective override text — the 4-slot array at `+0x14DC` with
+// 256-byte stride. Index in objective-declaration order (NPC/GO first,
+// then item, same enumeration the LeaderBoard accessor walks).
+// Returns empty string for slots past the cache's 4-entry capacity
+// or for slots with an empty buffer (engine auto-formats those).
+const char *OverrideTextFor(const uint8_t *data, int objectiveSlot) {
+    if (objectiveSlot < 0 || objectiveSlot >= Quest::Cache::OBJECTIVE_TEXT_COUNT)
+        return "";
+    return reinterpret_cast<const char *>(
+        data + Quest::Cache::OFF_OBJECTIVE_TEXT +
+        objectiveSlot * Quest::Cache::OBJECTIVE_TEXT_STRIDE);
+}
+
+void PushRequirements(void *L, const uint8_t *data) {
+    Game::Lua::NewTable(L);
+    int next = 1;
+    int overrideSlot = 0;
+
+    auto *npcOrGo = reinterpret_cast<const int32_t *>(
+        data + Quest::Cache::OFF_REQUIRED_NPC_OR_GO);
+    auto *npcOrGoCount = reinterpret_cast<const uint32_t *>(
+        data + Quest::Cache::OFF_REQUIRED_NPC_OR_GO_COUNT);
+    for (int i = 0; i < Quest::Cache::OBJECTIVE_COUNT; ++i) {
+        const int32_t v = npcOrGo[i];
+        if (v == 0)
+            continue;
+        Game::Lua::PushNumber(L, static_cast<double>(next++));
+        Game::Lua::NewTable(L);
+        Game::Lua::SetFieldString(L, "kind", v > 0 ? "monster" : "object");
+        Game::Lua::SetFieldNumber(L, "id",
+                                  static_cast<double>(v > 0 ? v : -v));
+        Game::Lua::SetFieldNumber(L, "count",
+                                  static_cast<double>(npcOrGoCount[i]));
+        Game::Lua::SetFieldString(L, "text",
+                                  OverrideTextFor(data, overrideSlot++));
+        Game::Lua::SetTable(L, -3);
+    }
+
+    auto *items = reinterpret_cast<const uint32_t *>(
+        data + Quest::Cache::OFF_REQUIRED_ITEM);
+    auto *itemCounts = reinterpret_cast<const uint32_t *>(
+        data + Quest::Cache::OFF_REQUIRED_ITEM_COUNT);
+    for (int i = 0; i < Quest::Cache::OBJECTIVE_COUNT; ++i) {
+        if (items[i] == 0)
+            continue;
+        Game::Lua::PushNumber(L, static_cast<double>(next++));
+        Game::Lua::NewTable(L);
+        Game::Lua::SetFieldString(L, "kind", "item");
+        Game::Lua::SetFieldNumber(L, "id", static_cast<double>(items[i]));
+        Game::Lua::SetFieldNumber(L, "count",
+                                  static_cast<double>(itemCounts[i]));
+        Game::Lua::SetFieldString(L, "text",
+                                  OverrideTextFor(data, overrideSlot++));
+        Game::Lua::SetTable(L, -3);
+    }
+}
+
+int __fastcall Script_GetQuestDetails(void *L) {
+    if (!Game::Lua::IsNumber(L, 1)) {
+        Game::Lua::Error(L, "Usage: C_QuestLog.GetQuestDetails(questID)");
+        return 0;
+    }
+    const int questID = static_cast<int>(Game::Lua::ToNumber(L, 1));
+    if (questID <= 0)
+        return 0;
+
+    const uint8_t *data = Quest::Cache::Peek(static_cast<uint32_t>(questID));
+    if (data == nullptr)
+        return 0;
+
+    const auto u32 = [data](int off) {
+        return *reinterpret_cast<const uint32_t *>(data + off);
+    };
+    const auto i32 = [data](int off) {
+        return *reinterpret_cast<const int32_t *>(data + off);
+    };
+    const auto str = [data](int off) {
+        return reinterpret_cast<const char *>(data + off);
+    };
+
+    const auto f32 = [data](int off) {
+        return *reinterpret_cast<const float *>(data + off);
+    };
+
+    Game::Lua::NewTable(L);
+
+    Game::Lua::SetFieldNumber(L, "questID", static_cast<double>(questID));
+    Game::Lua::SetFieldString(L, "title", str(Quest::Cache::OFF_TITLE));
+    Game::Lua::SetFieldNumber(L, "level",
+                              static_cast<double>(i32(Quest::Cache::OFF_LEVEL)));
+
+    if (const char *tag =
+            LookupQuestType(u32(Quest::Cache::OFF_QUEST_INFO_ROW))) {
+        if (*tag != '\0')
+            Game::Lua::SetFieldString(L, "questType", tag);
+    }
+
+    // Race / class / skill / timer / suggested-players gates aren't
+    // here intentionally — vanilla 1.12's quest-query response leaves
+    // those cache slots (+0x14..+0x24) zero-filled; the server enforces
+    // those constraints and only ships quests to clients who could
+    // accept them. Addons that need that data must source it from an
+    // external scraped DB (pfQuest-style).
+    const int32_t money = i32(Quest::Cache::OFF_MONEY_DELTA);
+    Game::Lua::SetFieldNumber(L, "rewardMoney",
+                              money > 0 ? static_cast<double>(money) : 0.0);
+    Game::Lua::SetFieldNumber(L, "requiredMoney",
+                              money < 0 ? static_cast<double>(-money) : 0.0);
+    Game::Lua::SetFieldNumber(
+        L, "rewardMoneyAtMaxLevel",
+        static_cast<double>(i32(Quest::Cache::OFF_LEVEL_CAP_BONUS_MONEY)));
+    Game::Lua::SetFieldNumber(
+        L, "rewardSpellID",
+        static_cast<double>(i32(Quest::Cache::OFF_REWARD_SPELL_ID)));
+    Game::Lua::SetFieldNumber(
+        L, "srcItemID",
+        static_cast<double>(u32(Quest::Cache::OFF_SRC_ITEM_ID)));
+
+    const uint32_t flags = u32(Quest::Cache::OFF_QUEST_FLAGS);
+    Game::Lua::SetFieldNumber(L, "questFlags", static_cast<double>(flags));
+    Game::Lua::SetFieldBool(L, "isSharable", (flags & 0x08) != 0);
+
+    Game::Lua::SetFieldString(L, "description",
+                              str(Quest::Cache::OFF_DESCRIPTION));
+    Game::Lua::SetFieldString(L, "objectives",
+                              str(Quest::Cache::OFF_OBJECTIVES));
+    Game::Lua::SetFieldString(L, "completionText",
+                              str(Quest::Cache::OFF_COMPLETION_TEXT));
+
+    if (const uint32_t mapID = u32(Quest::Cache::OFF_POI_MAP_ID)) {
+        Game::Lua::PushString(L, "poi");
+        Game::Lua::NewTable(L);
+        Game::Lua::SetFieldNumber(L, "mapID", static_cast<double>(mapID));
+        Game::Lua::SetFieldNumber(L, "x", static_cast<double>(f32(Quest::Cache::OFF_POI_X)));
+        Game::Lua::SetFieldNumber(L, "y", static_cast<double>(f32(Quest::Cache::OFF_POI_Y)));
+        Game::Lua::SetFieldNumber(L, "opt",
+                                  static_cast<double>(u32(Quest::Cache::OFF_POI_OPT)));
+        Game::Lua::SetTable(L, -3);
+    }
+
+    Game::Lua::PushString(L, "rewardItems");
+    PushItemArray(L,
+                  reinterpret_cast<const uint32_t *>(
+                      data + Quest::Cache::OFF_REWARD_ITEMS),
+                  reinterpret_cast<const uint32_t *>(
+                      data + Quest::Cache::OFF_REWARD_ITEMS_COUNT),
+                  Quest::Cache::REWARD_COUNT);
+    Game::Lua::SetTable(L, -3);
+
+    Game::Lua::PushString(L, "choiceItems");
+    PushItemArray(L,
+                  reinterpret_cast<const uint32_t *>(
+                      data + Quest::Cache::OFF_CHOICE_ITEMS),
+                  reinterpret_cast<const uint32_t *>(
+                      data + Quest::Cache::OFF_CHOICE_ITEMS_COUNT),
+                  Quest::Cache::CHOICE_COUNT);
+    Game::Lua::SetTable(L, -3);
+
+    Game::Lua::PushString(L, "requirements");
+    PushRequirements(L, data);
+    Game::Lua::SetTable(L, -3);
+
+    return 1;
+}
+
+void RegisterLuaFunctions() {
+    Game::Lua::RegisterTableFunction("C_QuestLog", "GetQuestDetails",
+                                     &Script_GetQuestDetails);
+}
+
+} // namespace
+
+static const Game::ModuleAutoRegister _autoreg{&RegisterLuaFunctions};
+
+} // namespace Quest::Details
Author	SHA1	Message	Date
Brues	41bb687608	Add FOCUSTARGET / TARGETFOCUS bindings under TARGETING Splice into the engine's FrameXML Bindings.xml at load time via a file-read hook so the new bindings receive display indices from the same running counter as native bindings — landing visually inside the TARGETING block instead of orphaned at the bottom (where addon-side Bindings.xml entries always render, regardless of header="TARGETING").	2026-06-02 17:29:49 -05:00
Brues	d9cc3f9d7e	sort Items category	2026-06-02 16:51:15 -05:00
Brues	6b19c8bbb5	move useitembyname to Item section	2026-06-02 16:22:54 -05:00
Brues	09e57c3d97	UseItemByName now accepts a unit arg	2026-06-02 14:51:05 -05:00
Brues	2f3c67be1a	Script_EquipmentSetContainsLockedItems: Missing items are not locked	2026-05-31 12:42:40 -05:00
Brues	f94af6cb73	Fix C_Item.GetItemUniqueness* return shapes The two functions have different signatures in modern (Classic Era 1.15.x) WoW, verified against BlizzardInterfaceCode's generated ItemDocumentation.lua: GetItemUniqueness(itemLocation) → (limitCategory, limitMax) GetItemUniquenessByID(itemID) → (isUnique, limitCategoryName, limitCategoryCount, limitCategoryID) We were returning a 3-tuple in the wrong order for both. For a "Unique (10)" item the byID variant now correctly returns (true, nil, 10, nil) instead of (10, nil, 0).	2026-05-31 10:20:19 -05:00
Brues	1d370ada65	GetInventoryItemsForSlot: filter by player proficiency Mail helms were showing up for cloth classes — the function only checked invType→slot shape, not whether the player could actually equip the item. Adds a proficiency gate using the engine's per-itemClass mask table at [0x00C4D4A0], populated by the SMSG_SET_PROFICIENCY handler at 0x005E7B70. `table[itemClass] & (1 << subclass)` is the same lookup 4.3.4's Script_GetInventoryItemsForSlot does (via FUN_00553AD0 -> DAT_00DD4D38), and the same source the engine's own tooltip red-text coloring and cursor-drop equip check read from. Covers both armor and weapon proficiencies in one mask lookup.	2026-05-31 00:54:36 -05:00
Brues	35c78ea6be	C_AddOns.GetAddOnName returns nil for addons that don't exist	2026-05-30 23:13:32 -05:00
Brues	ad83eb9575	IsMouseButtonDown Adds the modern (2.0.1+) query function backed by the same WH_GETMESSAGE hook stream that drives GLOBAL_MOUSE_DOWN/UP — state flips at the exact same point the events fire. Accepts the 1..5 ID form, the "LeftButton".."Button5" name form, or no arg for "any button held".	2026-05-30 22:36:30 -05:00
Brues	8995e82627	UseEquipmentSet: pre-snapshot locations, two-phase execution Engine InvMgr state lags behind our atomic-swap packets (server has to ACK before CGItem moves register locally), so mid-loop FindGUID lookups returned stale locations and could undo prior swaps. Mirrors 4.3.4's `Script_UseEquipmentSet` at 0x009A15D0, which walks all 19 set slots up front to build an action list before any execution. Combined with two-phase sequencing: 1. paperdoll→paperdoll only — keeps bag state untouched, supports chained rotations via a virtual-paperdoll walk 2. bag→paperdoll — atomic swap displaces current occupants into the source bag slot, never strands a future set item 3. unequip slots the set wants empty into pre-snapshotted free bag slots Eliminates the "trinket A in 14, B in bags" failure mode where an earlier bag-to-paperdoll swap displaced an item later needed by the set, then stale FindGUID returned the pre-swap paperdoll location.	2026-05-30 22:23:32 -05:00
Brues	94b521881b	remove max equipment sets	2026-05-30 21:38:49 -05:00
Brues	634a440def	set addon toc to dev	2026-05-30 21:38:33 -05:00
brues-code	4dce58a457	Fix State section formatting in README.md	2026-05-30 19:54:31 -05:00
Brues	99e9621590	IsLoggedIn	2026-05-30 18:54:30 -05:00
Brues	e8fc583f19	Expand GetQuestDetails: srcItemID, completionText, poi, objective text Trace SMSG_QUEST_QUERY_RESPONSE serializer at 0x006DBCEC to map the remaining cache-block field offsets, exposing four new fields plus per-requirement override text. Empirical dumps across three quests confirmed the +0x14..+0x24 slots (would-be SuggestedPlayers / LimitTime / RequiredRaces / RequiredSkill / RequiredSkillValue) are never populated by the vanilla server — those constraints are enforced server-side and never broadcast, so addons needing them must use an external DB. Also corrects OFF_SORT_PTR -> OFF_ZONE_OR_SORT (int32, positive = zone areaID, negative = -QuestSort.dbc row).	2026-05-30 17:15:18 -05:00
Brues	03f63d391a	GameTooltip_Hide	2026-05-30 16:50:10 -05:00
Brues	6df403444c	C_QuestLog.GetQuestDetails	2026-05-30 16:21:12 -05:00
Brues	cb7953b503	GameTooltip:SetItemByGUID Modern method that renders the tooltip for a specific item instance identified by GUID — same string `C_Item.GetItemGUID` returns. Distinct from `SetItemByID` (which uses base `ItemSparse` data with no per-instance state): this path goes through the live CGItem, so the tooltip includes enchant lines, random-suffix-decorated name + bonuses, and locked/broken state. Implementation: parse GUID via `Item::Location::ParseGUIDString`, resolve through the engine's `FUN_OBJECT_RESOLVE_BY_GUID`, then build the per-instance hyperlink via `Item::Link::FromCGItem`. Strip the `\|cff…\|H…\|h[…]\|h\|r` decoration to the bare `item:N:enchant:gem:gem: gem:gem:suffix:unique` payload (SetHyperlink rejects the decorated form with "Unknown link type") and dispatch to the engine's existing SetHyperlink. Closes the loop with `GameTooltip:GetItem()`, which returns the same dressed link back.	2026-05-30 15:40:06 -05:00
Brues	774df8d0d4	UseEquipmentSet unequips slots the set wants empty Previously only `GUID_IGNORED` and `GUID_EMPTY` were both treated as "skip this slot," so equipment sets with cleared (but not ignored) slots couldn't be used to unequip — running a "naked" set returned `true` but left the player's gear on. Now `GUID_EMPTY` triggers a paperdoll-to-bag move. Implementation: - `Item::Swap::ToBag` — new atomic primitive (paperdoll → bag) using the same `FUN_INVENTORY_SWAP` engine helper as the equip variants, just with player+slot as the source side and a bag-encoded destination. - `Script_UseEquipmentSet` snapshots all empty bag slots at entry and consumes them sequentially. Snapshotting up front avoids the client-side stale-state collision where iterating `ResolveBag` per unequip would keep picking the same "first empty" slot — the client's bag state doesn't update between packet sends, so the second packet would target a slot the first had already filled, and the server would try to swap the previously-unequipped item back onto the wrong paperdoll slot ("This item cannot be equipped").	2026-05-30 15:17:01 -05:00
Brues	36e1aa87e4	C_AddOns.IsAddOnLoaded	2026-05-30 14:53:45 -05:00
Brues	40532aca8e	Ensure !!!ClassicAPI is loaded early	2026-05-30 14:31:06 -05:00
Brues	8592254b2d	Fixed items equipped string in SetEquipmentSet tooltip	2026-05-30 13:59:28 -05:00
brues-code	289f82a7e7	Remove `IconDataProviderMixin` documentation Removed the `IconDataProviderMixin` section and its details from the API documentation.	2026-05-30 13:53:22 -05:00