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