From 33c5f3041d02567df7228c57d5e7f2fc4aedecfe Mon Sep 17 00:00:00 2001
From: Brues <5278969+brues-code@users.noreply.github.com>
Date: Sat, 18 Jul 2026 04:06:11 -0500
Subject: [PATCH] container: add C_Container.GetContainerItemInfo
Backport the modern structured-table accessor. Vanilla's global
GetContainerItemInfo (Script_GetContainerItemInfo, 0x004F9670) returns
only a flat texture/itemCount/locked/quality/readable tuple; assemble the
full ContainerItemInfo table from the same descriptor + item-cache sources
plus the fields 1.12 never surfaced (hyperlink, hasNoValue, itemID,
isBound, itemName).
Live per-instance fields (stackCount, isLocked, isBound, itemID, hyperlink)
are always present; cache-derived fields (iconFileID, quality, hasLoot,
hasNoValue, itemName) are omitted/nil until the item's static data lands.
Reuses Item::StatAccum::FetchRecord and Item::Link for the cache peek and
link/name build (no new duplication); gathers all data into locals before
building the table so the engine link/name builders never interleave with
the half-built table on the Lua stack.
readable mirrors the engine branch at 0x004F97BD (static page text OR the
per-instance readable-text id at descriptor +0x9C, added as
OFF_DESCRIPTOR_READABLE_TEXT_ID). hasLoot is a best-effort static LOOTABLE
approximation (vanilla can't track post-loot emptiness client-side).
---
README.md | 2 +-
docs/API.md | 42 ++++++++
src/Offsets.h | 6 ++
src/container/ItemInfo.cpp | 194 +++++++++++++++++++++++++++++++++++++
4 files changed, 243 insertions(+), 1 deletion(-)
create mode 100644 src/container/ItemInfo.cpp
diff --git a/README.md b/README.md
index 3c102b46..a7cca772 100644
--- a/README.md
+++ b/README.md
@@ -24,7 +24,7 @@ Full per-function reference: **[docs/API.md](docs/API.md)**.
| [Combat](docs/API.md#combat) | `InCombatLockdown` |
| [CVar](docs/API.md#cvar) | `C_CVar.GetCVarBool` |
| [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.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.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` |
| [Coroutine](docs/API.md#coroutine) | `coroutine.create`, `coroutine.resume`, `coroutine.yield`, `coroutine.status`, `coroutine.wrap` |
| [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` |
| 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` |
diff --git a/docs/API.md b/docs/API.md
index 423dc25c..b90be908 100644
--- a/docs/API.md
+++ b/docs/API.md
@@ -40,6 +40,7 @@ build instructions.
- [Container](#container)
- [`C_Container.GetContainerItemID(bagIndex, slotIndex)`](#c_containergetcontaineritemidbagindex-slotindex)
+ - [`C_Container.GetContainerItemInfo(containerIndex, slotIndex)`](#c_containergetcontaineriteminfocontainerindex-slotindex)
- [`C_Container.HasContainerItem(bagIndex, slotIndex)`](#c_containerhascontaineritembagindex-slotindex)
- [`GetItemCooldown(itemInfo)` / `C_Container.GetItemCooldown(itemID)`](#getitemcooldowniteminfo--c_containergetitemcooldownitemid)
- [`C_Container.GetContainerItemDurability(containerIndex, slotIndex)`](#c_containergetcontaineritemdurabilitycontainerindex-slotindex)
@@ -1065,6 +1066,47 @@ for slot = 1, 16 do
end
```
+### `C_Container.GetContainerItemInfo(containerIndex, slotIndex)`
+
+Returns a `ContainerItemInfo` table for the item in the given bag slot, or
+`nil` if the slot is empty / the indices are out of range. The modern
+structured-table form (namespaced + table-returning since Patch 10.0.2) of
+vanilla's flat global `GetContainerItemInfo`, which only returned
+`texture, itemCount, locked, quality, readable`.
+
+- `containerIndex = 0` — main backpack; `1..4` — equipped bag slots.
+- `slotIndex` — 1-based.
+
+Table fields:
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `iconFileID` | string | Icon **path** (1.12 has no fileID system, same as `GetItemIcon`). Absent if the item's static data isn't cached yet. |
+| `stackCount` | number | Current stack size. |
+| `isLocked` | boolean | Item is in a pending transaction (pickup/trade/mail in flight). |
+| `quality` | number\|nil | `Enum.ItemQuality` (0=Poor … 5=Legendary); `nil` until the item is cached. |
+| `isReadable` | boolean | Has readable page text (books/letters). |
+| `hasLoot` | boolean | Static LOOTABLE flag (best-effort — vanilla can't track post-loot emptiness client-side). |
+| `hyperlink` | string | Fully-decorated per-instance item link (enchant + random suffix), same as `GetContainerItemLink`. |
+| `isFiltered` | boolean | Always `false` — vanilla has no bag search-filter system. |
+| `hasNoValue` | boolean | `true` when the item's vendor sell price is 0. |
+| `itemID` | number | Item ID. |
+| `isBound` | boolean | Soulbound. |
+| `itemName` | string | Per-instance decorated display name (falls back to the base name). |
+
+Live per-instance fields (`stackCount`, `isLocked`, `isBound`, `itemID`,
+`hyperlink`) are always present; cache-derived fields (`iconFileID`,
+`quality`, `hasLoot`, `hasNoValue`, `itemName`) are omitted/`nil` until the
+item's static data arrives (listen for `GET_ITEM_INFO_RECEIVED`). Passive —
+does not warm the item cache.
+
+```lua
+local info = C_Container.GetContainerItemInfo(0, 1)
+if info then
+ print(info.itemName, info.stackCount, info.quality, info.hyperlink)
+end
+```
+
### `C_Container.HasContainerItem(bagIndex, slotIndex)`
Returns `true` if the given bag slot currently holds an item, `false`
diff --git a/src/Offsets.h b/src/Offsets.h
index 5b7a6654..38c736e2 100644
--- a/src/Offsets.h
+++ b/src/Offsets.h
@@ -1856,6 +1856,12 @@ enum Offsets {
// no durability concept (consumables, materials) have both fields 0.
OFF_DESCRIPTOR_DURABILITY = 0xA0,
OFF_DESCRIPTOR_MAX_DURABILITY = 0xA4,
+ // Per-instance "readable text" id (letters / mail-scroll items carry a
+ // server-assigned text id here). Drives the `readable` return of
+ // `Script_GetContainerItemInfo` (`0x004F9670`): at `0x004F97C1` it reads
+ // `[descriptor+0x9C]` and, when non-zero, reports the slot as readable
+ // even when the static ItemStats page-text is 0. Field index 0x27.
+ OFF_DESCRIPTOR_READABLE_TEXT_ID = 0x9C,
// Per-item repair-cost helper used by Script_GameTooltip_SetInventoryItem
// (3rd return value). __fastcall(ecx = CGItem *) -> int copperCost.
diff --git a/src/container/ItemInfo.cpp b/src/container/ItemInfo.cpp
new file mode 100644
index 00000000..5b5389eb
--- /dev/null
+++ b/src/container/ItemInfo.cpp
@@ -0,0 +1,194 @@
+// 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 .
+
+// `C_Container.GetContainerItemInfo(containerIndex, slotIndex)` — the modern
+// structured-table accessor (namespaced + table-returning since Patch
+// 10.0.2). Vanilla's global `GetContainerItemInfo` returns a flat 5-tuple
+// (`texture, itemCount, locked, quality, readable` — verified by decoding
+// `Script_GetContainerItemInfo` at `0x004F9670`); backported addons expect
+// the `ContainerItemInfo` table with the wider modern field set. We assemble
+// that table from the same sources the engine reads plus the extra fields it
+// never surfaced in 1.12.
+//
+// Field sources:
+// iconFileID — ItemStats displayInfoID → ItemDisplayInfo.dbc icon path.
+// (1.12 has no fileID system; we return the icon *path*
+// string, same convention as `GetItemIcon`.)
+// stackCount — CGItem descriptor `+OFF_DESCRIPTOR_STACK_COUNT` (the
+// engine's `itemCount` return).
+// isLocked — CGItem `+OFF_ITEM_CLIENT_LOCK & 1` (the `locked` return).
+// quality — ItemStats `+OFF_ITEMSTATS_QUALITY`; nil when uncached
+// (modern contract: `Enum.ItemQuality or nil`).
+// isReadable — static page text OR the per-instance readable-text id,
+// mirroring the engine's `readable` branch at `0x004F97BD`.
+// hasLoot — ItemStats LOOTABLE flag (best-effort static approximation:
+// vanilla can't track post-loot dynamic emptiness client-side).
+// hyperlink — engine link builder via `Item::Link::FromCGItem` (enchant /
+// random-suffix decorated, same as `GetContainerItemLink`).
+// isFiltered — always false (vanilla has no bag search-filter system).
+// hasNoValue — ItemStats sellPrice == 0.
+// itemID — instance block itemID (`Item::ID::FromCGItem`).
+// isBound — CGItem descriptor SOULBOUND flag (`C_Item.IsBound`'s bit).
+// itemName — instance-decorated display name, base ItemStats name on miss.
+//
+// Returns nil for an empty slot or an invalid bag/slot index (modern
+// contract). Cache-derived fields (icon / quality / hasLoot / hasNoValue /
+// name) are omitted/nil when the item's static data isn't cached yet — the
+// live per-instance fields (count / locked / bound / itemID / link) are always
+// present. Passive: does not warm the item cache.
+
+#include "Game.h"
+#include "Offsets.h"
+#include "dbc/Lookup.h"
+#include "item/ID.h"
+#include "item/Link.h"
+#include "item/Location.h"
+#include "item/StatAccum.h"
+
+#include
+#include
+
+namespace Container::ItemInfo {
+
+namespace {
+
+bool BuildIconPath(uint32_t displayInfoID, char *out, size_t outSize) {
+ out[0] = '\0';
+ const char *iconName = DBC::StringField(
+ Offsets::VAR_ITEMDISPLAYINFO_RECORDS, Offsets::VAR_ITEMDISPLAYINFO_COUNT,
+ displayInfoID, Offsets::OFF_ITEMDISPLAYINFO_ICON);
+ if (iconName == nullptr || iconName[0] == '\0')
+ return false;
+ std::snprintf(out, outSize, "Interface\\Icons\\%s", iconName);
+ return true;
+}
+
+// Mirrors the engine's `readable` decision (0x004F97BD..0x004F97CF): a slot
+// is readable when its static page text is set OR the per-instance
+// readable-text id is non-zero (letters / server-authored notes).
+bool ItemReadable(const uint8_t *item, const uint8_t *record) {
+ if (record != nullptr &&
+ *reinterpret_cast(record + Offsets::OFF_ITEMSTATS_PAGE_TEXT) != 0)
+ return true;
+ const uint8_t *descriptor = *reinterpret_cast(
+ item + Offsets::OFF_ITEM_DESCRIPTOR);
+ return descriptor != nullptr &&
+ *reinterpret_cast(
+ descriptor + Offsets::OFF_DESCRIPTOR_READABLE_TEXT_ID) != 0;
+}
+
+int __fastcall Script_C_Container_GetContainerItemInfo(void *L) {
+ if (!Game::Lua::IsNumber(L, 1) || !Game::Lua::IsNumber(L, 2)) {
+ Game::Lua::Error(L,
+ "Usage: C_Container.GetContainerItemInfo(containerIndex, slotIndex)");
+ return 0;
+ }
+ const int bagID = static_cast(Game::Lua::ToNumber(L, 1));
+ const int slotIndex = static_cast(Game::Lua::ToNumber(L, 2));
+
+ const uint8_t *item = Item::Location::ResolveBag(L, bagID, slotIndex);
+ if (item == nullptr) {
+ Game::Lua::PushNil(L); // empty slot / bad index → nil (modern contract)
+ return 1;
+ }
+
+ // --- Gather everything into locals BEFORE touching the Lua stack. The
+ // engine link/name builders and cache/DBC reads below are pure C; keeping
+ // them off the half-built table avoids any stack interleaving. ---
+ const int itemID = Item::ID::FromCGItem(item);
+ const uint8_t *record = (itemID > 0)
+ ? Item::StatAccum::FetchRecord(static_cast(itemID))
+ : nullptr;
+
+ // Live per-instance descriptor fields.
+ const uint8_t *descriptor = *reinterpret_cast(
+ item + Offsets::OFF_ITEM_DESCRIPTOR);
+ int stackCount = 0;
+ bool isBound = false;
+ if (descriptor != nullptr) {
+ stackCount = *reinterpret_cast(
+ descriptor + Offsets::OFF_DESCRIPTOR_STACK_COUNT);
+ isBound = (*reinterpret_cast(
+ descriptor + Offsets::OFF_DESCRIPTOR_FLAGS) &
+ Offsets::ITEM_FLAG_SOULBOUND) != 0;
+ }
+ const bool isLocked = (*reinterpret_cast(
+ item + Offsets::OFF_ITEM_CLIENT_LOCK) &
+ Offsets::ITEM_CLIENT_LOCK_BIT) != 0;
+ const bool isReadable = ItemReadable(item, record);
+
+ // Static template fields (cache-dependent).
+ bool haveIcon = false;
+ char iconPath[260];
+ bool haveQuality = false;
+ uint32_t quality = 0;
+ bool hasLoot = false;
+ bool hasNoValue = false;
+ if (record != nullptr) {
+ const uint32_t displayInfoID = *reinterpret_cast(
+ record + Offsets::OFF_ITEMSTATS_DISPLAY_INFO_ID);
+ haveIcon = BuildIconPath(displayInfoID, iconPath, sizeof(iconPath));
+ quality = *reinterpret_cast(
+ record + Offsets::OFF_ITEMSTATS_QUALITY);
+ haveQuality = true;
+ const uint32_t flags = *reinterpret_cast(
+ record + Offsets::OFF_ITEMSTATS_FLAGS);
+ hasLoot = (flags & Offsets::ITEM_FLAG_LOOTABLE) != 0;
+ hasNoValue = *reinterpret_cast(
+ record + Offsets::OFF_ITEMSTATS_SELL_PRICE) == 0;
+ }
+
+ const char *hyperlink = Item::Link::FromCGItem(item);
+
+ char nameBuf[256];
+ const char *itemName = nullptr;
+ if (Item::Link::NameFromCGItem(item, nameBuf, sizeof(nameBuf))) {
+ itemName = nameBuf;
+ } else if (record != nullptr) {
+ const char *baseName = *reinterpret_cast(
+ record + Offsets::OFF_ITEMSTATS_NAME);
+ if (baseName != nullptr && baseName[0] != '\0')
+ itemName = baseName;
+ }
+
+ // --- Build the ContainerItemInfo table (only stack-safe SetField* now). ---
+ Game::Lua::NewTable(L);
+ if (haveIcon)
+ Game::Lua::SetFieldString(L, "iconFileID", iconPath);
+ Game::Lua::SetFieldNumber(L, "stackCount", static_cast(stackCount));
+ Game::Lua::SetFieldBool(L, "isLocked", isLocked);
+ if (haveQuality)
+ Game::Lua::SetFieldNumber(L, "quality", static_cast(quality));
+ Game::Lua::SetFieldBool(L, "isReadable", isReadable);
+ Game::Lua::SetFieldBool(L, "hasLoot", hasLoot);
+ if (hyperlink != nullptr && hyperlink[0] != '\0')
+ Game::Lua::SetFieldString(L, "hyperlink", hyperlink);
+ Game::Lua::SetFieldBool(L, "isFiltered", false);
+ Game::Lua::SetFieldBool(L, "hasNoValue", hasNoValue);
+ Game::Lua::SetFieldNumber(L, "itemID", static_cast(itemID));
+ Game::Lua::SetFieldBool(L, "isBound", isBound);
+ if (itemName != nullptr)
+ Game::Lua::SetFieldString(L, "itemName", itemName);
+ return 1;
+}
+
+void RegisterLuaFunctions() {
+ Game::Lua::RegisterTableFunction("C_Container", "GetContainerItemInfo",
+ &Script_C_Container_GetContainerItemInfo);
+}
+
+const Game::ModuleAutoRegister _autoreg{&RegisterLuaFunctions};
+
+} // namespace
+
+} // namespace Container::ItemInfo