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;
}