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

Author: brues-code

src/equipmentset/Api.cpp

@@ -35,6 +35,7 @@
 #include "Offsets.h"
 #include "Set.h"
 #include "event/Custom.h"
+#include "item/Location.h"
 #include "item/Swap.h"
 
 #include <cstdint>
@@ -401,11 +402,54 @@ 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;
+
     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)
+
+        // GUID_IGNORED: leave whatever the player has in this slot
+        // as-is. Distinct from GUID_EMPTY (= 0), which means "this
+        // slot should be empty after the swap" — handled below.
+        if (g == GUID_IGNORED)
+            continue;
+
+        if (g == GUID_EMPTY) {
+            // Set wants this slot empty. If it already is, no-op.
+            // Otherwise unequip whatever's there into the next bag
+            // slot we reserved during the pre-loop snapshot. If
+            // we've exhausted the snapshot, silently skip — matches
+            // the modern API which surfaces no per-slot reason.
+            const uint8_t *equipped =
+                Item::Location::ResolveEquipmentSlot(targetSlot);
+            if (equipped == nullptr)
+                continue;
+            if (nextFreeSlot >= freeSlotCount)
+                continue;
+            const FreeSlot &fs = freeSlots[nextFreeSlot++];
+            Item::Swap::ToBag(equipped, targetSlot, fs.bag, fs.slot);
             continue;
+        }
 
         const int loc = Locations::FindGUID(g);
         if (loc == 0)

src/item/Swap.cpp

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

src/item/Swap.h

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