ItemLocation: cleanup and guid support

This commit is contained in:
Brues
2026-05-13 23:09:31 -05:00
parent cc04c9d291
commit ca204181d7
17 changed files with 275 additions and 183 deletions
+19 -8
View File
@@ -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)`
+1 -1
View File
@@ -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;
}
+2 -2
View File
@@ -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;
}
+1 -1
View File
@@ -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;
}
+1 -1
View File
@@ -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;
}
+17 -128
View File
@@ -12,8 +12,6 @@
// ClassicAPI. If not, see <https://www.gnu.org/licenses/>.
#include "Game.h"
#include "Offsets.h"
#include "item/ID.h"
#include "item/Location.h"
#include <cstdint>
@@ -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<GetItemRecord_t>(Offsets::FUN_DBCACHE_ITEMSTATS_GET_RECORD);
auto *cache = reinterpret_cast<void *>(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<uint32_t>(bagItemID));
if (record == nullptr)
return 0;
return static_cast<int>(*reinterpret_cast<const uint32_t *>(
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<uint64_t>(d);
}
if (s[18] != '\0')
return false;
*out = v;
return true;
}
uint64_t ReadGUID(const uint8_t *item) {
auto *instance = *reinterpret_cast<const uint8_t *const *>(
item + Offsets::OFF_ITEM_INSTANCE_BLOCK);
if (instance == nullptr)
return 0;
return *reinterpret_cast<const uint64_t *>(
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() {
+1 -1
View File
@@ -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;
}
+1 -1
View File
@@ -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;
}
+1 -1
View File
@@ -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;
}
+1 -1
View File
@@ -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;
}
+56 -22
View File
@@ -13,15 +13,17 @@
#include "Game.h"
#include "Offsets.h"
#include "item/Location.h"
#include <cstdint>
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<double>(eqSlot));
auto fn = reinterpret_cast<ScriptFn_t>(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<double>(bagID));
Game::Lua::PushNumber(L, static_cast<double>(slotIndex));
auto fn = reinterpret_cast<ScriptFn_t>(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<double>(eqSlot));
auto fn = reinterpret_cast<ScriptFn_t>(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<double>(bagID));
Game::Lua::PushNumber(L, static_cast<double>(slotIndex));
auto fn = reinterpret_cast<ScriptFn_t>(Offsets::FUN_SCRIPT_GET_CONTAINER_ITEM_LINK);
return fn(L);
}
TryReadIntField(L, 1, "slotIndex", &slotIndex))
return DispatchBagLink(L, bagID, slotIndex);
return 0;
}
+124 -1
View File
@@ -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<const uint8_t *>(GetItemBySlot(invMgr, linearSlot));
}
// --- GUID-walk helpers ---------------------------------------------------
const uint8_t *PeekItemRecord(uint32_t itemID) {
auto fn = reinterpret_cast<GetItemRecord_t>(Offsets::FUN_DBCACHE_ITEMSTATS_GET_RECORD);
auto *cache = reinterpret_cast<void *>(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<uint32_t>(bagItemID));
if (record == nullptr)
return 0;
return static_cast<int>(*reinterpret_cast<const uint32_t *>(
record + Offsets::OFF_ITEMSTATS_CONTAINER_SLOTS));
}
uint64_t ReadCGItemGUID(const uint8_t *item) {
auto *instance = *reinterpret_cast<const uint8_t *const *>(
item + Offsets::OFF_ITEM_INSTANCE_BLOCK);
if (instance == nullptr)
return 0;
return *reinterpret_cast<const uint64_t *>(
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<uint64_t>(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;
+46 -11
View File
@@ -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
+1 -1
View File
@@ -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;
}
+1 -1
View File
@@ -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;
}
+1 -1
View File
@@ -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;
}
+1 -1
View File
@@ -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;
}