feat(container): add C_Container.AutoStoreItem

Moves an item and lets the server pick the destination slot, which is
worth having because the server does not merely find an empty one: it
first merges the stack into existing stacks of the same item, splitting
it across several when that is what fits, and places a remainder only if
one is left. So one call consolidates a partial stack.

Two engine builders back it, because the wire has two autostore opcodes.
FUN_005E12E0 sends CMSG_AUTOSTORE_BAG_ITEM (0x10B) and takes a
destination container, so it can confine an item to one equipped bag or
let the server search the whole inventory. FUN_005E18F0 sends
CMSG_AUTOSTORE_BANK_ITEM (0x282) and takes no destination at all - the
server derives the direction from the source, so a bank source travels
to the inventory and an inventory source to the bank. AutoStore picks
between them and accepts only the pairs the wire can honestly serve.
Bank-to-bank is not among them, so consolidating stacks within the bank
still needs per-pair moves.

Both builders' stack-arg counts come from their RET, not from a
decompiler parameter list. 0x10B's last slot is never read by the body
but is still popped, and declaring seven args instead of eight made the
callee pop four bytes we never pushed - which shifted the caller's frame
and surfaced as a garbage Lua state pointer in the next function to run,
several frames from the call. Noted at both offsets, since this family
is not uniform in arity.

Three fixes to the shared bagID encoder found while doing it:

- EncodeBagSlot had no case for the keyring (bagID -2), so SwapItems,
  MoveItem and AutoStoreItem all rejected keyring slots. The engine's
  own map in FUN_PACK_BAG_SLOT has had it all along, and the linear base
  was already recorded in the invMgr slot map.
- Its bank constants restated named Offsets::INVMGR_* values, so they
  now derive from them, and the slot map is fully named rather than half
  constants and half comment. Each player-container range is bounded by
  both its own last linear slot and the live invMgr count - stricter
  than before, where the backpack had no upper bound at all.
- FUN_PACK_BAG_SLOT's fourth out-param was labelled outUnused. It is the
  bank flag, and it is what makes right-clicking a bank item send 0x282
  instead of using the item.

Author: brues-code

README.md

@@ -62,7 +62,7 @@ reference in **[docs/API.md](docs/API.md)**.
 | [Console](docs/API.md#console) | `CalculateStringEditDistance`, `ConsoleEcho`, `ConsoleExec`, `ConsoleGetAllCommands`, `ConsoleGetColorFromType`, `ConsoleGetFontHeight`, `ConsoleIsActive`, `ConsolePrintAllMatchingCommands`, `SetConsoleKey` |
 | [CVar](docs/API.md#cvar) | `C_CVar.AreCVarsLoaded`, `C_CVar.DoesCVarExist`, `C_CVar.GetCVarBitfield`, `C_CVar.GetCVarBool`, `C_CVar.GetCVarInfo`, `C_CVar.SetCVarBitfield` |
 | [Cursor](docs/API.md#cursor) | `GetCursorInfo` |
-| [Container](docs/API.md#container) | `C_Container.CalculateTotalNumberOfFreeBagSlots`, `C_Container.GetContainerItemCharges`, `C_Container.GetContainerItemDurability`, `C_Container.GetContainerItemID`, `C_Container.GetContainerItemInfo`, `C_Container.GetContainerItemRepairCost`, `C_Container.GetContainerNumFreeSlots`, `C_Container.GetItemCooldown`, `C_Container.HasContainerItem`, `C_Container.IsContainerItemOpenable`, `C_Container.MoveItem`, `C_Container.PlayerHasHearthstone`, `C_Container.SwapItems`, `C_Container.UseHearthstone`, `GetItemCooldown` |
+| [Container](docs/API.md#container) | `C_Container.AutoStoreItem`, `C_Container.CalculateTotalNumberOfFreeBagSlots`, `C_Container.GetContainerItemCharges`, `C_Container.GetContainerItemDurability`, `C_Container.GetContainerItemID`, `C_Container.GetContainerItemInfo`, `C_Container.GetContainerItemRepairCost`, `C_Container.GetContainerNumFreeSlots`, `C_Container.GetItemCooldown`, `C_Container.HasContainerItem`, `C_Container.IsContainerItemOpenable`, `C_Container.MoveItem`, `C_Container.PlayerHasHearthstone`, `C_Container.SwapItems`, `C_Container.UseHearthstone`, `GetItemCooldown` |
 | [Creature](docs/API.md#creature) | `C_CreatureInfo.GetCreatureID`, `C_CreatureInfo.GetCreatureInfoByID`, `C_CreatureInfo.RequestLoadCreatureByID`, `C_CreatureInfo.GetRaceInfo`, `C_CreatureInfo.GetClassInfo`, `C_CreatureInfo.GetCreatureFamilyInfo`, `C_CreatureInfo.GetCreatureFamilyIDs`, `C_CreatureInfo.GetFactionInfo`, `C_CreatureInfo.GetCreatureTypeInfo`, `C_CreatureInfo.GetCreatureTypeIDs` |
 | [Currency](docs/API.md#currency) | `GetCoinTextureString`, `C_CurrencyInfo.GetCoinTextureString` |
 | EncodingUtil | `C_EncodingUtil.CompressString`, `C_EncodingUtil.DecompressString`, `C_EncodingUtil.EncodeBase64`, `C_EncodingUtil.DecodeBase64`, `C_EncodingUtil.EncodeHex`, `C_EncodingUtil.DecodeHex`, `C_EncodingUtil.SerializeJSON`, `C_EncodingUtil.DeserializeJSON`, `C_EncodingUtil.SerializeCBOR`, `C_EncodingUtil.DeserializeCBOR` |

docs/API.md

@@ -87,6 +87,7 @@ build instructions.
   - [`C_Container.UseHearthstone()`](#c_containerusehearthstone)
   - [`C_Container.SwapItems(srcBag, srcSlot, dstBag, dstSlot)`](#c_containerswapitemssrcbag-srcslot-dstbag-dstslot)
   - [`C_Container.MoveItem(srcBag, srcSlot, dstBag, dstSlot, count)`](#c_containermoveitemsrcbag-srcslot-dstbag-dstslot-count)
+  - [`C_Container.AutoStoreItem(srcBag, srcSlot [, dstBag])`](#c_containerautostoreitemsrcbag-srcslot--dstbag)
 
 - [Creature](#creature)
   - [`C_CreatureInfo.GetCreatureID(guid)`](#c_creatureinfogetcreatureidguid)
@@ -2293,6 +2294,74 @@ constraint as `SwapItems`.
 
 Send is fire-and-forget (same as `SwapItems`).
 
+### `C_Container.AutoStoreItem(srcBag, srcSlot [, dstBag])`
+
+Moves an item and lets the server pick the destination slot. Returns
+`true` on send, `false` for bad args (missing bag, out-of-range slot,
+empty source, or a source and destination the call cannot serve).
+
+The server does not just look for an empty slot. It first merges the
+item into existing stacks of the same item, and splits it across
+several of them when that is what fits. It places a remainder in a
+free slot only if some is left over. So one call consolidates a
+partial stack:
+
+```lua
+-- Two partial stacks of item 12662: slot 1 holds 5, slot 2 holds 3.
+C_Container.AutoStoreItem(0, 2)
+-- Slot 1 now holds 8, and slot 2 is empty.
+
+-- Confine the item to bag 2
+C_Container.AutoStoreItem(0, 5, 2)
+```
+
+`dstBag` says where you want the item, and defaults to `0`:
+
+- `0` — anywhere in the main inventory that it fits. This means the
+  whole inventory, not the backpack. The backpack cannot be named
+  separately as a destination.
+- `1..4` — that equipped bag only.
+- `-1` — anywhere in the bank that it fits.
+
+Deposits and withdrawals both work, and both merge on arrival:
+
+```lua
+-- Deposit, merging into stacks already in the bank
+C_Container.AutoStoreItem(0, 3, -1)
+
+-- Withdraw bank slot 5 back into the bags
+C_Container.AutoStoreItem(-1, 5, 0)
+```
+
+A bank item always travels back to your bags, so you cannot ask for a
+new slot inside the bank. These three combinations are accepted, and
+every other pair returns `false`:
+
+| Source | `dstBag` | Result |
+|---|---|---|
+| inventory | `0..4` | stays in the inventory |
+| inventory | `-1` | goes to the bank |
+| bank | `0` | comes back to the inventory |
+
+To consolidate stacks inside the bank, use `C_Container.MoveItem` for
+each pair. Individual bank bags (`5..10`) are not valid destinations.
+
+Bank slots need the bank window open, the same as `SwapItems` and
+`MoveItem`.
+
+> **Prefer this over merging stacks yourself.** This call needs no
+> stack-size lookup, because the server decides what fits. A merge you
+> compute in Lua has to size each stack first with
+> `C_Item.GetItemMaxStackSizeByID`, which returns `nil` until that
+> item's data has arrived. A merge written that way silently skips any
+> stack it cannot size.
+
+There is no way to name the destination slot, which is the point of the
+call. Use `C_Container.SwapItems` or `C_Container.MoveItem` when you
+need to choose it.
+
+Send is fire-and-forget (same as `SwapItems` and `MoveItem`).
+
 ## Creature
 
 ### `C_CreatureInfo.GetCreatureID(guid)`

src/Offsets.h

@@ -799,8 +799,10 @@ enum Offsets {
     // `Script_EquipCursorItem` (0x00489660) uses after the cursor's
     // source location has been resolved. Sends opcode 0x10D
     // (CMSG_SWAP_INV_ITEM) for same-container swaps or 0x10C
-    // (CMSG_AUTOEQUIP_ITEM) for cross-container, then runs the
-    // packet through the engine's own send pipeline at FUN_005AB630.
+    // (CMSG_SWAP_ITEM) for cross-container, then runs the packet
+    // through the engine's own send pipeline at FUN_005AB630.
+    // (0x10C is SWAP_ITEM; CMSG_AUTOEQUIP_ITEM is 0x10A and belongs to
+    // the cursor/equip builder FUN_005E1480, not this one.)
     //
     // Signature:
     //   void __thiscall(
@@ -853,6 +855,84 @@ enum Offsets {
     //     u32 count);                           // only low byte
     FUN_INVENTORY_SPLIT = 0x005E1210,
 
+    // Third sibling in the same packet-builder family — `__thiscall`,
+    // same shared bag-byte converter (`FUN_005E13B0`), same send
+    // pipeline (`FUN_005AB630`). Builds `CMSG_AUTOSTORE_BAG_ITEM`
+    // (opcode 0x10B): "take this item and put it wherever it belongs
+    // in that container", with the DESTINATION SLOT CHOSEN BY THE
+    // SERVER. Wire format:
+    //   [0x10B, srcBag, srcLinearSlot, dstBag]
+    //
+    // Signature — EIGHT stack args, `RET 0x20`. The count is from the
+    // RET, not from a decompiler parameter list: the last slot
+    // (`EBP+0x24`) is never READ by the body, but it IS popped, so a
+    // 7-arg declaration leaves the callee popping four bytes too many
+    // and ESP walks on every call. Trailing-ignored-arg is this
+    // family's habit — it is where swap keeps its `flag` and split its
+    // `count` — but the family is NOT uniform in arity: those two take
+    // nine (`RET 0x24`), this one eight.
+    //   void __thiscall(
+    //     CGPlayer *this,
+    //     u32 unused1, u32 unused2,             // EBP+0x08/+0x0C, unread
+    //     u32 srcContainerLo, u32 srcContainerHi,
+    //     u32 srcLinearSlot,                    // only low byte hits the wire
+    //     u32 dstContainerLo, u32 dstContainerHi,
+    //     u32 unused3);                         // EBP+0x24, unread but popped
+    //
+    // Note there is no dst slot argument at all — that is the point of
+    // the opcode. Server-side (`HandleAutoStoreBagItemOpcode`) it runs
+    // `CanStoreItem(dstBag, NULL_SLOT, …)`, which is a TWO-PASS search:
+    // first "merge into existing non-full stacks of this item" (filling
+    // a position/count vector, so one stack can be distributed across
+    // several destinations), then "find a free slot" for whatever count
+    // is left. So this single packet performs partial-stack
+    // consolidation with no stack-size lookup on our side at all.
+    //
+    // Note the value in that is NOT that the client's stack size could
+    // be wrong: 1.12 has no item DBC, so stack size arrives from the
+    // server and is cached in itemcache.wdb, and the client's copy
+    // normally agrees by construction. The value is availability —
+    // `C_Item.GetItemMaxStackSizeByID` is nil until an item's data has
+    // arrived, so anything that sizes stacks first has a cold-cache
+    // hole, and the server never needs to size them.
+    //
+    // The converter returns `0xFF` for any GUID absent from the
+    // player's invMgr container array, and the player's own GUID is
+    // absent — so passing the PLAYER as the destination sends
+    // `dstBag = 0xFF` (INVENTORY_SLOT_BAG_0), which the server reads as
+    // "search every bag". The builder guards that case: a converted
+    // `0xFF` is only allowed through when the destination GUID really is
+    // the player's, otherwise it drops the send silently. Consequence:
+    // the backpack is not separately addressable as a destination (it
+    // IS the player container), so bagID 0 means "anywhere it fits".
+    FUN_INVENTORY_AUTOSTORE = 0x005E12E0,
+
+    // Bank counterpart — `CMSG_AUTOSTORE_BANK_ITEM` (opcode 0x282).
+    // THREE stack args, `RET 0xC`. Wire: [0x282, srcBag, srcSlot].
+    //   void __thiscall(
+    //     CGPlayer *this,
+    //     u32 srcContainerLo, u32 srcContainerHi,
+    //     u32 srcLinearSlot);                   // only low byte hits the wire
+    //
+    // No destination of any kind, because the server DERIVES THE
+    // DIRECTION FROM THE SOURCE (`HandleAutoStoreBankItemOpcode`):
+    // a bank source runs `CanStoreItem(NULL_BAG, NULL_SLOT, …)` and
+    // lands in the inventory; an inventory source runs
+    // `CanBankItem(NULL_BAG, NULL_SLOT, …)` and lands in the bank.
+    // Both are the same merge-into-existing-stacks-then-free-slot
+    // search as 0x10B, just aimed at the other side.
+    //
+    // So this opcode moves an item ACROSS the inventory/bank boundary
+    // and cannot move one within its own side. Bank-internal
+    // consolidation is not expressible through autostore at all — it
+    // needs per-pair moves (`FUN_INVENTORY_SPLIT` / `_SWAP`).
+    //
+    // Unlike its siblings this one validates the source itself before
+    // sending: resolves the container by GUID (`FUN_00468460` with
+    // typeMask 1), bounds-checks the slot against the container's item
+    // array, and bails when the GUID in that slot is zero.
+    FUN_INVENTORY_AUTOSTORE_BANK = 0x005E18F0,
+
     // Registers a single global Lua function. __fastcall(name, func).
     FUN_FRAMESCRIPT_REGISTER_FUNCTION = 0x00704120,
 
@@ -2516,9 +2596,17 @@ enum Offsets {
     VAR_GUILD_ROSTER_TOTAL_COUNT = 0x00B73118,
     OFF_GUILD_MEMBER_NAME = 0x08,
 
-    // PackBagSlot — __fastcall(L, void **outInvMgr, int *outLinearSlot, int *outUnused) → bool.
+    // PackBagSlot — __fastcall(L, void **outInvMgr, int *outLinearSlot, int *outIsBank) → bool.
     // Reads bagID at Lua stack[1] and slot at stack[2], validates them, and
     // returns the inventory manager + linear slot ready to feed into GetItemBySlot.
+    //
+    // The fourth out-param is NOT unused (it was labelled `outUnused`
+    // here until the bank-autostore work): it is set to 1 for a bank
+    // position — bagID -1 (main bank) and bagIDs 5..10 (bank bags) —
+    // and left 0 otherwise, keyring included. `Script_UseContainerItem`
+    // is what consumes it: a non-zero flag is what makes right-clicking
+    // a bank item send `CMSG_AUTOSTORE_BANK_ITEM` instead of using it.
+    // This is the engine's own definition of "is this a bank slot".
     FUN_PACK_BAG_SLOT = 0x004F9820,
     // Equipped-bag container-GUID getter — `uint64 __fastcall(uint bagIndex0)`
     // where `bagIndex0` is 0-based (Lua bagID 1..4 → 0..3; 4..9 are bank bags,
@@ -2563,10 +2651,18 @@ enum Offsets {
     // it hides data that's present from boot. Reading the GUID array
     // directly recovers it without ever opening the bank window.
     OFF_INVMGR_GUID_ARRAY = 0x04,
+    INVMGR_BACKPACK_FIRST_SLOT = 23,
+    INVMGR_BACKPACK_LAST_SLOT = 38,
     INVMGR_BANK_MAIN_FIRST_SLOT = 39,
     INVMGR_BANK_MAIN_LAST_SLOT = 62,
     INVMGR_BANK_BAG_FIRST_SLOT = 63,
     INVMGR_BANK_BAG_LAST_SLOT = 68,
+    // Keyring (Lua bagID -2). No LAST constant: the engine bounds this
+    // range against the invMgr's own slot count (OFF_INVMGR_SLOT_COUNT)
+    // rather than a fixed size, since keyring capacity grows with level.
+    // Base confirmed from FUN_PACK_BAG_SLOT, which maps Lua bagID -2 to
+    // `slot - 1 + 0x51`.
+    INVMGR_KEYRING_FIRST_SLOT = 81,
     // Engine's `ObjectMgr::Get`-style resolver — given a type and GUID,
     // returns the resolved CGObject pointer (or null). Same function the
     // engine itself uses inside `GetItemBySlot` (called at `0x00622904`)

src/container/AutoStoreItem.cpp

@@ -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 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 General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License along with
+// ClassicAPI. If not, see <https://www.gnu.org/licenses/>.
+
+// `C_Container.AutoStoreItem(srcBag, srcSlot [, dstBag])` — move an item
+// and let the SERVER choose the destination slot. A ClassicAPI-only
+// extension, like its siblings `SwapItems` and `MoveItem`; the modern
+// API has no equivalent, because it has no need for one.
+//
+// The reason to want it: the server does not just find an empty slot.
+// It first merges the stack into existing non-full stacks of the same
+// item, splitting it across several of them when that is what fits, and
+// only places a remainder if any is left over. So this is a one-call
+// stack consolidator that needs no stack-size lookup — the caller never
+// has to know what fits. A merge computed on this side has to size
+// every stack first, and `C_Item.GetItemMaxStackSizeByID` is nil until
+// that item's data has arrived, so a cold item cache silently skips
+// exactly the stacks it could not size.
+//
+// `dstBag` defaults to 0, which means "anywhere in the main inventory
+// that it fits" rather than "the backpack" — on the wire the backpack
+// IS the player container, so the two cannot be distinguished. Pass
+// 1..4 to confine the item to one equipped bag. Bank destinations are
+// rejected (see [[item/Swap.h]] `AutoStore`).
+//
+// Returns true once the packet is away — like the other two, the send
+// is fire-and-forget and the server confirms through the normal
+// BAG_UPDATE / SMSG_INVENTORY_CHANGE_FAILURE flow.
+
+#include "Game.h"
+#include "item/Swap.h"
+
+namespace Container::AutoStoreItem {
+
+namespace {
+
+int __fastcall Script_C_Container_AutoStoreItem(void *L) {
+    if (!Game::Lua::IsNumber(L, 1) || !Game::Lua::IsNumber(L, 2)) {
+        Game::Lua::Error(L,
+            "Usage: C_Container.AutoStoreItem(srcBag, srcSlot [, dstBag])");
+        return 0;
+    }
+    // Read every arg before calling AutoStore — its source lookup goes
+    // through ResolveBag, which stomps the Lua stack via PackBagSlot.
+    const int srcBag = static_cast<int>(Game::Lua::ToNumber(L, 1));
+    const int srcSlot = static_cast<int>(Game::Lua::ToNumber(L, 2));
+    const int dstBag = Game::Lua::IsNumber(L, 3)
+                           ? static_cast<int>(Game::Lua::ToNumber(L, 3))
+                           : 0;
+
+    const bool ok = Item::Swap::AutoStore(L, srcBag, srcSlot, dstBag);
+    Game::Lua::PushBool(L, ok);
+    return 1;
+}
+
+void RegisterLuaFunctions() {
+    Game::Lua::RegisterTableFunction("C_Container", "AutoStoreItem",
+                                     &Script_C_Container_AutoStoreItem);
+}
+
+const Game::ModuleAutoRegister _autoreg{&RegisterLuaFunctions};
+
+} // namespace
+
+} // namespace Container::AutoStoreItem