diff --git a/docs/API.md b/docs/API.md index 71ef73e1..08a99195 100644 --- a/docs/API.md +++ b/docs/API.md @@ -1364,6 +1364,24 @@ state on top. ## Item +> ### `itemLocation` argument shapes +> +> Every `C_Item.*` function on this page that takes `itemLocation` accepts +> any of three forms, matching the modern `ItemLocation` mixin plus a +> GUID-string convenience form: +> +> ```lua +> { equipmentSlotIndex = N } -- 1-based, character pane +> { bagID = B, slotIndex = S } -- both required +> "0xHHHHHHHHLLLLLLLL" -- a GUID string from C_Item.GetItemGUID +> ``` +> +> Table forms are O(1) — the engine knows the slot. The GUID-string form +> is O(~80) — the function walks equipment slots 1..19 and bags 0..4 +> comparing each CGItem's stored GUID against the requested one. Bank and +> keyring are not walked. Fine for sporadic addon use; avoid for per-frame +> polling. + ### `C_Item.IsBound(itemLocation)` Returns `true` if the item at the given location is soulbound, `false` otherwise @@ -1374,17 +1392,10 @@ the only way to read it from Lua was a scan-tooltip hack constant) — slow, locale-fragile, and one of the hottest paths during bag updates. -`itemLocation` is a table with one of these shapes (matching the modern -`ItemLocation` mixin): - -```lua -{ equipmentSlotIndex = N } -- 1-based, character pane -{ bagID = B, slotIndex = S } -- both required -``` - ```lua if C_Item.IsBound({equipmentSlotIndex = INVSLOT_HEAD}) then ... end if C_Item.IsBound({bagID = 0, slotIndex = 1}) then ... end +if C_Item.IsBound(itemGUID) then ... end ``` ### `C_Item.GetItemID(itemLocation)` diff --git a/src/item/Bound.cpp b/src/item/Bound.cpp index 8520943e..fd32549b 100644 --- a/src/item/Bound.cpp +++ b/src/item/Bound.cpp @@ -30,7 +30,7 @@ static bool ItemIsSoulbound(const uint8_t *item) { } static int __fastcall Script_IsBound(void *L) { - if (Game::Lua::Type(L, 1) != Game::Lua::TYPE_TABLE) { + if (!Item::Location::IsLocationArg(L, 1)) { Game::Lua::Error(L, "Usage: C_Item.IsBound(itemLocation)"); return 0; } diff --git a/src/item/Data.cpp b/src/item/Data.cpp index d1791526..5f6f916a 100644 --- a/src/item/Data.cpp +++ b/src/item/Data.cpp @@ -137,7 +137,7 @@ static int __fastcall Script_IsItemDataCachedByID(void *L) { } static int __fastcall Script_IsItemDataCached(void *L) { - if (Game::Lua::Type(L, 1) != Game::Lua::TYPE_TABLE) { + if (!Item::Location::IsLocationArg(L, 1)) { Game::Lua::Error(L, "Usage: C_Item.IsItemDataCached(itemLocation)"); return 0; } @@ -196,7 +196,7 @@ static int __fastcall Script_RequestLoadItemDataByID(void *L) { } static int __fastcall Script_RequestLoadItemData(void *L) { - if (Game::Lua::Type(L, 1) != Game::Lua::TYPE_TABLE) { + if (!Item::Location::IsLocationArg(L, 1)) { Game::Lua::Error(L, "Usage: C_Item.RequestLoadItemData(itemLocation)"); return 0; } diff --git a/src/item/Exists.cpp b/src/item/Exists.cpp index ffe4353b..372f6ce7 100644 --- a/src/item/Exists.cpp +++ b/src/item/Exists.cpp @@ -42,7 +42,7 @@ const uint8_t *PeekItemRecord(uint32_t itemID) { // player's inventory manager. Empty slots and invalid tables return // false without raising. static int __fastcall Script_C_Item_DoesItemExist(void *L) { - if (Game::Lua::Type(L, 1) != Game::Lua::TYPE_TABLE) { + if (!Item::Location::IsLocationArg(L, 1)) { Game::Lua::PushBoolean(L, 0); return 1; } diff --git a/src/item/GUID.cpp b/src/item/GUID.cpp index 94745045..6e2f515f 100644 --- a/src/item/GUID.cpp +++ b/src/item/GUID.cpp @@ -34,7 +34,7 @@ namespace Item::GUID { // Returns nil if the location is invalid, empty, or the instance block // is somehow missing (shouldn't happen for live items). static int __fastcall Script_C_Item_GetItemGUID(void *L) { - if (Game::Lua::Type(L, 1) != Game::Lua::TYPE_TABLE) { + if (!Item::Location::IsLocationArg(L, 1)) { Game::Lua::Error(L, "Usage: C_Item.GetItemGUID(itemLocation)"); return 0; } diff --git a/src/item/GetItemLocation.cpp b/src/item/GetItemLocation.cpp index 21a62bf8..8cb41ee5 100644 --- a/src/item/GetItemLocation.cpp +++ b/src/item/GetItemLocation.cpp @@ -12,8 +12,6 @@ // ClassicAPI. If not, see . #include "Game.h" -#include "Offsets.h" -#include "item/ID.h" #include "item/Location.h" #include @@ -22,110 +20,6 @@ namespace Item::GetItemLocation { namespace { -using GetItemRecord_t = const uint8_t *(__thiscall *)(void *cache, uint32_t itemID, - const uint64_t *guid, void *callback, - void *userData, int unused); - -const uint8_t *PeekItemRecord(uint32_t itemID) { - auto fn = reinterpret_cast(Offsets::FUN_DBCACHE_ITEMSTATS_GET_RECORD); - auto *cache = reinterpret_cast(Offsets::VAR_ITEMDB_CACHE); - const uint64_t zeroGuid = 0; - return fn(cache, itemID, &zeroGuid, nullptr, nullptr, 0); -} - -// Mirrors `Item::Bag::ResolveBagInfo`'s slot-count derivation: backpack is -// fixed at 16, equipped bags read `m_containerSlots` off the cache record. -// Returns 0 for empty bag slots or out-of-range bagIDs — those iterations -// get skipped. -int SlotCountForBag(int bagID) { - if (bagID == 0) - return Offsets::BACKPACK_NUM_SLOTS; - if (bagID < 1 || bagID > 4) - return 0; - auto *bagItem = Item::Location::ResolveEquipmentSlot( - Offsets::INVSLOT_BAG1 + bagID - 1); - if (bagItem == nullptr) - return 0; - const int bagItemID = Item::ID::FromCGItem(bagItem); - if (bagItemID == 0) - return 0; - auto *record = PeekItemRecord(static_cast(bagItemID)); - if (record == nullptr) - return 0; - return static_cast(*reinterpret_cast( - record + Offsets::OFF_ITEMSTATS_CONTAINER_SLOTS)); -} - -// Parses the `"0xHHHHHHHHLLLLLLLL"` form `C_Item.GetItemGUID` produces. -// Strict — exactly 18 chars (`0x` prefix + 16 hex), case-insensitive -// hex. Anything else fails; we leave malformed input as a nil return -// rather than raising, matching modern's "guid not found → nil". -bool ParseGUID(const char *s, uint64_t *out) { - if (s == nullptr) - return false; - if (s[0] != '0' || (s[1] != 'x' && s[1] != 'X')) - return false; - uint64_t v = 0; - for (int i = 0; i < 16; ++i) { - const char c = s[2 + i]; - int d; - if (c >= '0' && c <= '9') d = c - '0'; - else if (c >= 'a' && c <= 'f') d = c - 'a' + 10; - else if (c >= 'A' && c <= 'F') d = c - 'A' + 10; - else return false; - v = (v << 4) | static_cast(d); - } - if (s[18] != '\0') - return false; - *out = v; - return true; -} - -uint64_t ReadGUID(const uint8_t *item) { - auto *instance = *reinterpret_cast( - item + Offsets::OFF_ITEM_INSTANCE_BLOCK); - if (instance == nullptr) - return 0; - return *reinterpret_cast( - instance + Offsets::OFF_INSTANCE_BLOCK_GUID); -} - -// Equipment-slot search: walks 1..19, returns the 1-based slot on a -// match or 0 if not found. No Lua-stack interaction — safe to run -// before bag iteration (which does stomp the stack). -int FindInEquipmentSlots(uint64_t target) { - for (int slot = Offsets::EQUIPMENT_SLOT_FIRST; - slot <= Offsets::EQUIPMENT_SLOT_LAST; ++slot) { - auto *item = Item::Location::ResolveEquipmentSlot(slot); - if (item == nullptr) - continue; - if (ReadGUID(item) == target) - return slot; - } - return 0; -} - -// Bag search: walks backpack + equipped bags 1..4. Stomps the Lua -// stack (via `Item::Location::ResolveBag`'s `PackBagSlot` call) on -// every iteration — caller must rebuild whatever it needs on the -// stack afterwards. -bool FindInBags(void *L, uint64_t target, int *outBagID, int *outSlotIndex) { - for (int bagID = 0; bagID <= 4; ++bagID) { - const int slotCount = SlotCountForBag(bagID); - for (int slot = 1; slot <= slotCount; ++slot) { - auto *item = Item::Location::ResolveBag(L, bagID, slot); - if (item == nullptr) - continue; - if (ReadGUID(item) == target) { - *outBagID = bagID; - *outSlotIndex = slot; - return true; - } - } - } - return false; -} - void PushEquipmentLocation(void *L, int slot) { Game::Lua::SetTop(L, 0); Game::Lua::NewTable(L); @@ -154,38 +48,33 @@ void PushBagLocation(void *L, int bagID, int slotIndex) { // unknown / non-resident GUIDs. // // Modern WoW returns an `ItemLocation` mixin object; we return a -// plain table with the same field shape the rest of the -// `C_Item.*` API accepts as input (`{equipmentSlotIndex=N}` or -// `{bagID=B, slotIndex=S}`), so you can pipe the result straight -// into `C_Item.GetItemQuality`, `C_Item.GetItemLink`, etc. +// plain table with the same field shape every other `C_Item.*` API +// in ClassicAPI accepts as input (`{equipmentSlotIndex=N}` or +// `{bagID=B, slotIndex=S}`), so the result pipes straight into +// `C_Item.GetItemQuality(loc)`, `C_Item.GetItemLink(loc)`, etc. // // Walked scope: character-pane equipment (slots 1..19) + backpack -// (bagID 0) + the four equipped bags (bagIDs 1..4). Bank and -// keyring are NOT walked — same scope as the existing -// `C_Container.*` APIs. Worst case is ~80 slot lookups; fine for -// sporadic use, not appropriate for per-frame polling. +// (bagID 0) + the four equipped bags (bagIDs 1..4). Bank and keyring +// are NOT walked — same scope as the rest of the `C_Container.*` +// family. static int __fastcall Script_C_Item_GetItemLocation(void *L) { if (Game::Lua::Type(L, 1) != Game::Lua::TYPE_STRING) { Game::Lua::Error(L, "Usage: C_Item.GetItemLocation(itemGUID)"); return 0; } - uint64_t target = 0; - if (!ParseGUID(Game::Lua::ToString(L, 1), &target) || target == 0) + uint64_t guid = 0; + if (!Item::Location::ParseGUIDString(Game::Lua::ToString(L, 1), &guid)) return 0; - if (const int slot = FindInEquipmentSlots(target); slot != 0) { - PushEquipmentLocation(L, slot); - return 1; - } + Item::Location::ByGUIDResult found; + if (!Item::Location::FindByGUID(L, guid, &found)) + return 0; - int bagID = 0; - int slotIndex = 0; - if (FindInBags(L, target, &bagID, &slotIndex)) { - PushBagLocation(L, bagID, slotIndex); - return 1; - } - - return 0; + if (found.equipmentSlotIndex != 0) + PushEquipmentLocation(L, found.equipmentSlotIndex); + else + PushBagLocation(L, found.bagID, found.slotIndex); + return 1; } static void RegisterLuaFunctions() { diff --git a/src/item/ID.cpp b/src/item/ID.cpp index e975a40a..f496abe2 100644 --- a/src/item/ID.cpp +++ b/src/item/ID.cpp @@ -32,7 +32,7 @@ int FromCGItem(const uint8_t *item) { } static int __fastcall Script_GetItemID(void *L) { - if (Game::Lua::Type(L, 1) != Game::Lua::TYPE_TABLE) { + if (!Item::Location::IsLocationArg(L, 1)) { Game::Lua::Error(L, "Usage: C_Item.GetItemID(itemLocation)"); return 0; } diff --git a/src/item/Info.cpp b/src/item/Info.cpp index 9e84cfcb..a886294f 100644 --- a/src/item/Info.cpp +++ b/src/item/Info.cpp @@ -177,7 +177,7 @@ static int __fastcall Script_GetItemIcon(void *L) { // Routes through `Item::Location::Resolve` → CGItem → itemID, then the // same cache lookup as the other variants. static int __fastcall Script_C_Item_GetItemIcon(void *L) { - if (Game::Lua::Type(L, 1) != Game::Lua::TYPE_TABLE) { + if (!Item::Location::IsLocationArg(L, 1)) { Game::Lua::Error(L, "Usage: C_Item.GetItemIcon(itemLocation)"); return 0; } diff --git a/src/item/InventoryType.cpp b/src/item/InventoryType.cpp index aa54edd8..9312bcb7 100644 --- a/src/item/InventoryType.cpp +++ b/src/item/InventoryType.cpp @@ -65,7 +65,7 @@ int PushInventoryTypeForItemID(void *L, int itemID) { // `GetItemInfoInstant`; this is for modern code that expects the // integer. static int __fastcall Script_C_Item_GetItemInventoryType(void *L) { - if (Game::Lua::Type(L, 1) != Game::Lua::TYPE_TABLE) { + if (!Item::Location::IsLocationArg(L, 1)) { Game::Lua::Error(L, "Usage: C_Item.GetItemInventoryType(itemLocation)"); return 0; } diff --git a/src/item/Level.cpp b/src/item/Level.cpp index c189684f..5e32a451 100644 --- a/src/item/Level.cpp +++ b/src/item/Level.cpp @@ -57,7 +57,7 @@ int PushItemLevelForItemID(void *L, int itemID) { // level are the same value. Direct `m_itemLevel` read, no `GetItemInfo` // chaining. static int __fastcall Script_C_Item_GetCurrentItemLevel(void *L) { - if (Game::Lua::Type(L, 1) != Game::Lua::TYPE_TABLE) { + if (!Item::Location::IsLocationArg(L, 1)) { Game::Lua::Error(L, "Usage: C_Item.GetCurrentItemLevel(itemLocation)"); return 0; } diff --git a/src/item/Link.cpp b/src/item/Link.cpp index c6ce887c..63eef07d 100644 --- a/src/item/Link.cpp +++ b/src/item/Link.cpp @@ -13,15 +13,17 @@ #include "Game.h" #include "Offsets.h" +#include "item/Location.h" + +#include namespace Item::Link { +namespace { + using ScriptFn_t = int(__fastcall *)(void *L); -// Read an int field off the location table at stack `locIdx`. Returns -// true and writes `*out` on a numeric field; leaves the Lua stack as -// it found it. -static bool TryReadIntField(void *L, int locIdx, const char *fieldName, int *out) { +bool TryReadIntField(void *L, int locIdx, const char *fieldName, int *out) { Game::Lua::PushString(L, fieldName); Game::Lua::GetTable(L, locIdx); const bool ok = Game::Lua::IsNumber(L, -1); @@ -31,6 +33,29 @@ static bool TryReadIntField(void *L, int locIdx, const char *fieldName, int *out return ok; } +// Stomps the stack and tail-calls `Script_GetInventoryItemLink` +// with `("player", eqSlot)`. The engine pushes the dressed-link +// string and returns 1; we forward that count. +int DispatchEquipmentLink(void *L, int eqSlot) { + Game::Lua::SetTop(L, 0); + Game::Lua::PushString(L, "player"); + Game::Lua::PushNumber(L, static_cast(eqSlot)); + auto fn = reinterpret_cast(Offsets::FUN_SCRIPT_GET_INVENTORY_ITEM_LINK); + return fn(L); +} + +// Same shape as the equipment dispatcher, but for bag/slot via +// `Script_GetContainerItemLink`. +int DispatchBagLink(void *L, int bagID, int slotIndex) { + Game::Lua::SetTop(L, 0); + Game::Lua::PushNumber(L, static_cast(bagID)); + Game::Lua::PushNumber(L, static_cast(slotIndex)); + auto fn = reinterpret_cast(Offsets::FUN_SCRIPT_GET_CONTAINER_ITEM_LINK); + return fn(L); +} + +} // namespace + // `C_Item.GetItemLink(itemLocation)` — returns the fully-decorated // per-instance hyperlink for the item at the location, matching what // `GetContainerItemLink(bag, slot)` or `GetInventoryItemLink("player", @@ -38,37 +63,46 @@ static bool TryReadIntField(void *L, int locIdx, const char *fieldName, int *out // and any other per-instance data the server attached to the CGItem // are preserved. // -// Implementation: read the location table's (bagID, slotIndex) or -// (equipmentSlotIndex) fields, blow the Lua stack, push the right -// args, and tail-call the engine's link script function +// Accepts table form (`{equipmentSlotIndex=N}` or `{bagID=B, +// slotIndex=S}`) and GUID string form (the value +// `C_Item.GetItemGUID` returns). For the GUID form we walk +// equipment + bags to find the matching CGItem, then dispatch to +// the same engine helper using the recovered slot tuple. +// +// Implementation: blow the Lua stack, push the right args, and +// tail-call the engine's link script function // (`Script_GetContainerItemLink` or `Script_GetInventoryItemLink`). // The engine reads its args from stack[1]/[2] and pushes the link // string as its return value — we forward its return count to the // Lua caller, so a nil push for an empty slot stays nil. static int __fastcall Script_C_Item_GetItemLink(void *L) { - if (Game::Lua::Type(L, 1) != Game::Lua::TYPE_TABLE) { + if (!Item::Location::IsLocationArg(L, 1)) { Game::Lua::Error(L, "Usage: C_Item.GetItemLink(itemLocation)"); return 0; } - int eqSlot = 0; - if (TryReadIntField(L, 1, "equipmentSlotIndex", &eqSlot)) { - Game::Lua::SetTop(L, 0); - Game::Lua::PushString(L, "player"); - Game::Lua::PushNumber(L, static_cast(eqSlot)); - auto fn = reinterpret_cast(Offsets::FUN_SCRIPT_GET_INVENTORY_ITEM_LINK); - return fn(L); + // GUID-string form: walk to find the resident slot, then dispatch + // by whichever kind of slot it lives in. + if (Game::Lua::Type(L, 1) == Game::Lua::TYPE_STRING) { + uint64_t guid = 0; + if (!Item::Location::ParseGUIDString(Game::Lua::ToString(L, 1), &guid)) + return 0; + Item::Location::ByGUIDResult found; + if (!Item::Location::FindByGUID(L, guid, &found)) + return 0; + if (found.equipmentSlotIndex != 0) + return DispatchEquipmentLink(L, found.equipmentSlotIndex); + return DispatchBagLink(L, found.bagID, found.slotIndex); } + int eqSlot = 0; + if (TryReadIntField(L, 1, "equipmentSlotIndex", &eqSlot)) + return DispatchEquipmentLink(L, eqSlot); + int bagID = 0, slotIndex = 0; if (TryReadIntField(L, 1, "bagID", &bagID) && - TryReadIntField(L, 1, "slotIndex", &slotIndex)) { - Game::Lua::SetTop(L, 0); - Game::Lua::PushNumber(L, static_cast(bagID)); - Game::Lua::PushNumber(L, static_cast(slotIndex)); - auto fn = reinterpret_cast(Offsets::FUN_SCRIPT_GET_CONTAINER_ITEM_LINK); - return fn(L); - } + TryReadIntField(L, 1, "slotIndex", &slotIndex)) + return DispatchBagLink(L, bagID, slotIndex); return 0; } diff --git a/src/item/Location.cpp b/src/item/Location.cpp index c2d40bf2..ea07029b 100644 --- a/src/item/Location.cpp +++ b/src/item/Location.cpp @@ -15,6 +15,7 @@ #include "../Game.h" #include "../Offsets.h" +#include "ID.h" namespace Item::Location { @@ -24,6 +25,9 @@ using GetItemBySlot_t = void *(__thiscall *)(void *thisInvMgr, int slot); using PackBagSlot_t = int(__fastcall *)(void *L, void **outInvMgr, int *outLinearSlot, int *outUnused); using ResolveUnitToken_t = void *(__fastcall *)(const char *token); +using GetItemRecord_t = const uint8_t *(__thiscall *)(void *cache, uint32_t itemID, + const uint64_t *guid, void *callback, + void *userData, int unused); void *ResolveActivePlayerInvMgr() { auto ResolveUnitToken = @@ -68,6 +72,46 @@ const uint8_t *ResolveBagSlot(void *L, int bagID, int slotIndex) { return static_cast(GetItemBySlot(invMgr, linearSlot)); } +// --- GUID-walk helpers --------------------------------------------------- + +const uint8_t *PeekItemRecord(uint32_t itemID) { + auto fn = reinterpret_cast(Offsets::FUN_DBCACHE_ITEMSTATS_GET_RECORD); + auto *cache = reinterpret_cast(Offsets::VAR_ITEMDB_CACHE); + const uint64_t zeroGuid = 0; + return fn(cache, itemID, &zeroGuid, nullptr, nullptr, 0); +} + +// Mirrors `Item::Bag::ResolveBagInfo`'s slot-count derivation: backpack +// is fixed at 16, equipped bags read `m_containerSlots` off the cache +// record. Returns 0 for empty bag slots or out-of-range bagIDs — those +// iterations get skipped. +int SlotCountForBag(int bagID) { + if (bagID == 0) + return Offsets::BACKPACK_NUM_SLOTS; + if (bagID < 1 || bagID > 4) + return 0; + auto *bagItem = ResolveEquipmentSlot(Offsets::INVSLOT_BAG1 + bagID - 1); + if (bagItem == nullptr) + return 0; + const int bagItemID = Item::ID::FromCGItem(bagItem); + if (bagItemID == 0) + return 0; + auto *record = PeekItemRecord(static_cast(bagItemID)); + if (record == nullptr) + return 0; + return static_cast(*reinterpret_cast( + record + Offsets::OFF_ITEMSTATS_CONTAINER_SLOTS)); +} + +uint64_t ReadCGItemGUID(const uint8_t *item) { + auto *instance = *reinterpret_cast( + item + Offsets::OFF_ITEM_INSTANCE_BLOCK); + if (instance == nullptr) + return 0; + return *reinterpret_cast( + instance + Offsets::OFF_INSTANCE_BLOCK_GUID); +} + } // namespace const uint8_t *ResolveEquipmentSlot(int slot1Based) { @@ -86,8 +130,87 @@ const uint8_t *ResolveBag(void *L, int bagID, int slotIndex) { return ResolveBagSlot(L, bagID, slotIndex); } +bool ParseGUIDString(const char *s, uint64_t *out) { + if (s == nullptr) + return false; + if (s[0] != '0' || (s[1] != 'x' && s[1] != 'X')) + return false; + uint64_t v = 0; + for (int i = 0; i < 16; ++i) { + const char c = s[2 + i]; + int d; + if (c >= '0' && c <= '9') d = c - '0'; + else if (c >= 'a' && c <= 'f') d = c - 'a' + 10; + else if (c >= 'A' && c <= 'F') d = c - 'A' + 10; + else return false; + v = (v << 4) | static_cast(d); + } + if (s[18] != '\0') + return false; + *out = v; + return true; +} + +bool FindByGUID(void *L, uint64_t guid, ByGUIDResult *out) { + if (guid == 0) + return false; + + // Equipment slots first — no Lua stack interaction, so cheaper. + for (int slot = Offsets::EQUIPMENT_SLOT_FIRST; + slot <= Offsets::EQUIPMENT_SLOT_LAST; ++slot) { + auto *item = ResolveEquipmentSlot(slot); + if (item == nullptr) + continue; + if (ReadCGItemGUID(item) == guid) { + out->equipmentSlotIndex = slot; + out->bagID = 0; + out->slotIndex = 0; + out->item = item; + return true; + } + } + + // Bag slots — `ResolveBag` stomps the Lua stack on each call. Caller + // beware: any data the caller stashed on the stack will be gone after + // this returns true. + for (int bagID = 0; bagID <= 4; ++bagID) { + const int slotCount = SlotCountForBag(bagID); + for (int slotIndex = 1; slotIndex <= slotCount; ++slotIndex) { + auto *item = ResolveBag(L, bagID, slotIndex); + if (item == nullptr) + continue; + if (ReadCGItemGUID(item) == guid) { + out->equipmentSlotIndex = 0; + out->bagID = bagID; + out->slotIndex = slotIndex; + out->item = item; + return true; + } + } + } + + return false; +} + +bool IsLocationArg(void *L, int idx) { + const int t = Game::Lua::Type(L, idx); + return t == Game::Lua::TYPE_TABLE || t == Game::Lua::TYPE_STRING; +} + const uint8_t *Resolve(void *L, int locIdx) { - if (Game::Lua::Type(L, locIdx) != Game::Lua::TYPE_TABLE) + const int t = Game::Lua::Type(L, locIdx); + + if (t == Game::Lua::TYPE_STRING) { + uint64_t guid = 0; + if (!ParseGUIDString(Game::Lua::ToString(L, locIdx), &guid)) + return nullptr; + ByGUIDResult found; + if (!FindByGUID(L, guid, &found)) + return nullptr; + return found.item; + } + + if (t != Game::Lua::TYPE_TABLE) return nullptr; int eqSlot = 0; diff --git a/src/item/Location.h b/src/item/Location.h index d2b60ea2..8416cb36 100644 --- a/src/item/Location.h +++ b/src/item/Location.h @@ -17,23 +17,35 @@ namespace Item::Location { -// Resolves an item-location table at Lua stack index `locIdx` to a `CGItem *` +// Resolves an item-location arg at Lua stack index `locIdx` to a `CGItem *` // pointer (returned as a raw byte pointer for use with `OFF_*` offsets). // -// Accepts the same shapes the modern `ItemLocation` mixin uses: -// { equipmentSlotIndex = N } 1-based slot index, character pane -// { bagID = B, slotIndex = S } both required, bag/slot tuple +// Accepts: +// - location tables: `{ equipmentSlotIndex = N }` or +// `{ bagID = B, slotIndex = S }` — same shapes the modern +// `ItemLocation` mixin uses. +// - GUID strings: `"0xHHHHHHHHLLLLLLLL"` — the form +// `C_Item.GetItemGUID` returns. The GUID is looked up by walking +// equipment slots 1..19 + bags 0..4; bank and keyring are not +// walked. // -// Returns `nullptr` when the stack value isn't a table, the table doesn't -// carry a valid location, or the resolved slot is empty. Does NOT raise a -// Lua error — callers should validate the argument type beforehand if they -// want a typed error message. +// Returns `nullptr` when the value isn't a valid location arg, the +// table doesn't carry recognizable fields, the GUID is malformed, or +// the resolved slot is empty / the GUID isn't resident. Does NOT +// raise a Lua error — callers should validate the argument type +// beforehand with `IsLocationArg` if they want a typed error. // -// Walking the bag path stomps the Lua stack (a requirement of the engine's -// `PackBagSlot` helper, which reads its inputs from stack[1] and stack[2]). -// Only safe to call from inside a Lua callback. +// Both paths may stomp the Lua stack (the bag-form table uses +// `PackBagSlot`; the GUID path iterates bag slots via the same +// helper). Only safe to call from inside a Lua callback. const uint8_t *Resolve(void *L, int locIdx); +// Type-check helper: returns true if the value at `idx` could be a +// valid location arg (a table or a string). Used by every C_Item.* +// function that takes a location, to validate before calling +// `Resolve`. Does not dereference the value. +bool IsLocationArg(void *L, int idx); + // Resolves a `(bagID, slotIndex)` pair directly to a `CGItem *`. Used by // the positional-arg C_Container.* APIs that don't go through the // ItemLocation table shape. Stomps the Lua stack — same caveat as @@ -48,4 +60,27 @@ const uint8_t *ResolveBag(void *L, int bagID, int slotIndex); // Returns nullptr for out-of-range slots or empty equipment. const uint8_t *ResolveEquipmentSlot(int slot1Based); +// GUID-walk result. `equipmentSlotIndex != 0` means the item was +// found in a character-pane equipment slot; otherwise it's in +// `bagID`/`slotIndex`. `item` always points to the found CGItem +// when the function returns true. +struct ByGUIDResult { + int equipmentSlotIndex; // 1..19, or 0 if bag form + int bagID; + int slotIndex; + const uint8_t *item; +}; + +// Walks the local player's inventory (equipment 1..19 + bags 0..4) +// looking for a CGItem with a matching GUID. Returns false when the +// GUID isn't found, true (and fills `*out`) on a hit. Stomps the +// Lua stack — only safe from inside a Lua callback. +bool FindByGUID(void *L, uint64_t guid, ByGUIDResult *out); + +// Parses the `"0xHHHHHHHHLLLLLLLL"` GUID string format +// `C_Item.GetItemGUID` returns. Strict: requires exactly `0x` prefix +// + 16 case-insensitive hex digits. Returns false (and leaves `*out` +// untouched) on malformed input. +bool ParseGUIDString(const char *s, uint64_t *out); + } // namespace Item::Location diff --git a/src/item/Lock.cpp b/src/item/Lock.cpp index f945ab3e..6338d171 100644 --- a/src/item/Lock.cpp +++ b/src/item/Lock.cpp @@ -37,7 +37,7 @@ static constexpr uint32_t ITEM_FLAG_LOCKED = 0x04; // can still read this flag to gate UI actions; they just can't request // the lock themselves. static int __fastcall Script_C_Item_IsLocked(void *L) { - if (Game::Lua::Type(L, 1) != Game::Lua::TYPE_TABLE) { + if (!Item::Location::IsLocationArg(L, 1)) { Game::Lua::PushBoolean(L, 0); return 1; } diff --git a/src/item/MaxStackSize.cpp b/src/item/MaxStackSize.cpp index 27ed13d6..83d6db7c 100644 --- a/src/item/MaxStackSize.cpp +++ b/src/item/MaxStackSize.cpp @@ -58,7 +58,7 @@ int PushMaxStackSizeForItemID(void *L, int itemID) { // item, use `C_Item.GetStackCount`. Non-stackable items return 1. // nil for empty / uncached / invalid locations. static int __fastcall Script_C_Item_GetItemMaxStackSize(void *L) { - if (Game::Lua::Type(L, 1) != Game::Lua::TYPE_TABLE) { + if (!Item::Location::IsLocationArg(L, 1)) { Game::Lua::Error(L, "Usage: C_Item.GetItemMaxStackSize(itemLocation)"); return 0; } diff --git a/src/item/Name.cpp b/src/item/Name.cpp index a1d4657d..0b5a6cae 100644 --- a/src/item/Name.cpp +++ b/src/item/Name.cpp @@ -63,7 +63,7 @@ int PushNameForItemID(void *L, int itemID) { // inputs. Reads `m_name[0]` straight off `ItemStats_C` — no engine // round-trip, no `GetItemInfo` chaining. static int __fastcall Script_C_Item_GetItemName(void *L) { - if (Game::Lua::Type(L, 1) != Game::Lua::TYPE_TABLE) { + if (!Item::Location::IsLocationArg(L, 1)) { Game::Lua::Error(L, "Usage: C_Item.GetItemName(itemLocation)"); return 0; } diff --git a/src/item/Quality.cpp b/src/item/Quality.cpp index fd5fe836..205b5518 100644 --- a/src/item/Quality.cpp +++ b/src/item/Quality.cpp @@ -84,7 +84,7 @@ constexpr QualityConstant kQualityConstants[] = { // equipped/bagged item's quality, no `GetItemInfo` chaining. Returns // nil on empty / uncached / invalid input. static int __fastcall Script_C_Item_GetItemQuality(void *L) { - if (Game::Lua::Type(L, 1) != Game::Lua::TYPE_TABLE) { + if (!Item::Location::IsLocationArg(L, 1)) { Game::Lua::Error(L, "Usage: C_Item.GetItemQuality(itemLocation)"); return 0; }