From 0d19deaee0fe19cf6735a7789870d45b787fbfee Mon Sep 17 00:00:00 2001 From: Brues <5278969+brues-code@users.noreply.github.com> Date: Mon, 26 Oct 2026 00:36:24 -0500 Subject: [PATCH] Add ItemHasRange global and C_Item.ItemHasRange Global returns 1/nil like 3.3.5; namespaced form returns a bool. Both resolve the item to its on-use spell and use the shared SpellIDHasRange engine check. Verified in-game: ItemHasRange(1251) -> 1, C_Item.ItemHasRange(6948) -> false. --- README.md | 2 +- docs/API.md | 21 +++++++++++++++++++++ src/item/InRange.cpp | 33 +++++++++++++++++++++++++++++++++ 3 files changed, 55 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 670bf639..f87c229a 100644 --- a/README.md +++ b/README.md @@ -108,7 +108,7 @@ In the Frame rows, a name that starts with `:` is a method of the widget that th | [Hooks](docs/API.md#hooks) | `hooksecurefunc` | | [Input](docs/API.md#input) | `GetMouseButtonClicked`, `IsLeftAltKeyDown`, `IsLeftControlKeyDown`, `IsLeftShiftKeyDown`, `IsModifierKeyDown`, `IsMouseButtonDown`, `IsRightAltKeyDown`, `IsRightControlKeyDown`, `IsRightShiftKeyDown` | | [Instance](docs/API.md#instance) | `GetInstanceInfo`, `IsActiveBattlefieldArena` | -| [Item: C_Item](docs/API.md#item) | `C_Item.DoesItemExist` / `C_Item.DoesItemExistByID`, `C_Item.EquipItemByName`, `C_Item.GetCurrentItemLevel`, `C_Item.GetDetailedItemLevelInfo`, `C_Item.GetEnchantInfo`, `C_Item.GetItemClassInfo`, `C_Item.GetItemCount`, `C_Item.GetItemData` / `C_Item.GetItemDataByID`, `C_Item.GetItemFamily`, `C_Item.GetItemGUID`, `C_Item.GetItemIcon` / `C_Item.GetItemIconByID`, `C_Item.GetItemID`, `C_Item.GetItemInfo`, `C_Item.GetItemInfoInstant`, `C_Item.GetItemInventorySlotInfo`, `C_Item.GetItemInventorySlotKey`, `C_Item.GetItemInventoryType` / `C_Item.GetItemInventoryTypeByID`, `C_Item.GetItemLink`, `C_Item.GetItemLocation`, `C_Item.GetItemMaxStackSize` / `C_Item.GetItemMaxStackSizeByID`, `C_Item.GetItemName` / `C_Item.GetItemNameByID`, `C_Item.GetItemQuality` / `C_Item.GetItemQualityByID`, `C_Item.GetItemSellPrice` / `C_Item.GetItemSellPriceByID`, `C_Item.GetItemSetID` / `C_Item.GetItemSetIDByID`, `C_Item.GetItemSetInfo`, `C_Item.GetItemSpell`, `C_Item.GetItemStatDelta`, `C_Item.GetItemStats`, `C_Item.GetItemSubClassInfo`, `C_Item.GetItemTempEnchantInfo`, `C_Item.GetItemUniqueness` / `C_Item.GetItemUniquenessByID`, `C_Item.GetStackCount`, `C_Item.GetWeaponEnchantInfo`, `C_Item.IsBound`, `C_Item.IsConsumableItem`, `C_Item.IsEquippableItem`, `C_Item.IsEquippedItem`, `C_Item.IsItemDataCached` / `C_Item.IsItemDataCachedByID`, `C_Item.IsItemGUIDInInventory`, `C_Item.IsItemInRange`, `C_Item.IsItemOpenable`, `C_Item.IsLocked`, `C_Item.IsUsableItem`, `C_Item.LockItem`, `C_Item.LockItemByGUID`, `C_Item.UnlockItem`, `C_Item.UnlockAllItems`, `C_Item.PickupItem`, `C_Item.RequestLoadItemData` / `C_Item.RequestLoadItemDataByID`, `C_Item.UseAtCursor`, `C_Item.UseAtUnit`, `C_Item.UseItemByName` | +| [Item: C_Item](docs/API.md#item) | `C_Item.DoesItemExist` / `C_Item.DoesItemExistByID`, `C_Item.EquipItemByName`, `C_Item.GetCurrentItemLevel`, `C_Item.GetDetailedItemLevelInfo`, `C_Item.GetEnchantInfo`, `C_Item.GetItemClassInfo`, `C_Item.GetItemCount`, `C_Item.GetItemData` / `C_Item.GetItemDataByID`, `C_Item.GetItemFamily`, `C_Item.GetItemGUID`, `C_Item.GetItemIcon` / `C_Item.GetItemIconByID`, `C_Item.GetItemID`, `C_Item.GetItemInfo`, `C_Item.GetItemInfoInstant`, `C_Item.GetItemInventorySlotInfo`, `C_Item.GetItemInventorySlotKey`, `C_Item.GetItemInventoryType` / `C_Item.GetItemInventoryTypeByID`, `C_Item.GetItemLink`, `C_Item.GetItemLocation`, `C_Item.GetItemMaxStackSize` / `C_Item.GetItemMaxStackSizeByID`, `C_Item.GetItemName` / `C_Item.GetItemNameByID`, `C_Item.GetItemQuality` / `C_Item.GetItemQualityByID`, `C_Item.GetItemSellPrice` / `C_Item.GetItemSellPriceByID`, `C_Item.GetItemSetID` / `C_Item.GetItemSetIDByID`, `C_Item.GetItemSetInfo`, `C_Item.GetItemSpell`, `C_Item.GetItemStatDelta`, `C_Item.GetItemStats`, `C_Item.GetItemSubClassInfo`, `C_Item.GetItemTempEnchantInfo`, `C_Item.GetItemUniqueness` / `C_Item.GetItemUniquenessByID`, `C_Item.GetStackCount`, `C_Item.GetWeaponEnchantInfo`, `C_Item.IsBound`, `C_Item.IsConsumableItem`, `C_Item.IsEquippableItem`, `C_Item.IsEquippedItem`, `C_Item.IsItemDataCached` / `C_Item.IsItemDataCachedByID`, `C_Item.IsItemGUIDInInventory`, `C_Item.IsItemInRange`, `C_Item.IsItemOpenable`, `C_Item.IsLocked`, `C_Item.IsUsableItem`, `C_Item.ItemHasRange`, `C_Item.LockItem`, `C_Item.LockItemByGUID`, `C_Item.UnlockItem`, `C_Item.UnlockAllItems`, `C_Item.PickupItem`, `C_Item.RequestLoadItemData` / `C_Item.RequestLoadItemDataByID`, `C_Item.UseAtCursor`, `C_Item.UseAtUnit`, `C_Item.UseItemByName` | | [Item: info](docs/API.md#getitemclassinfoclassid) | `GetItemClassInfo`, `GetItemSubClassInfo`, `GetItemIcon`, `IsConsumableItem`, `IsUsableItem` | | [Item: inventory](docs/API.md#getaverageitemlevel) | `GetAverageItemLevel`, `GetInventoryItemID`, `GetInventoryItemDurability`, `GetInventoryItemRepairCost`, `GetInventoryItemsForSlot`, `OffhandHasWeapon` | | [Item: item IDs](docs/API.md#getitemid--companions-to-the-engines-getitemlink-family) | `GetAuctionItemID`, `GetAuctionSellItemID`, `GetCraftReagentItemID`, `GetInboxItemID`, `GetLootRollItemID`, `GetLootSlotItemID`, `GetMerchantItemID`, `GetQuestItemID`, `GetQuestLogItemID`, `GetTradePlayerItemID`, `GetTradeTargetItemID`, `GetTradeSkillItemID`, `GetTradeSkillReagentItemID` | diff --git a/docs/API.md b/docs/API.md index 1b850b6e..7f9ba2c4 100644 --- a/docs/API.md +++ b/docs/API.md @@ -492,6 +492,7 @@ build instructions. - [`C_Item.IsEquippedItem(item)`](#c_itemisequippeditemitem) - [`C_Item.IsItemDataCachedByID(item)` / `C_Item.IsItemDataCached(itemLocation)`](#c_itemisitemdatacachedbyiditem--c_itemisitemdatacacheditemlocation) - [`C_Item.IsItemGUIDInInventory(itemGUID)`](#c_itemisitemguidininventoryitemguid) + - [`C_Item.ItemHasRange(item)` / `ItemHasRange(item)`](#c_itemitemhasrangeitem--itemhasrangeitem) - [`C_Item.IsItemInRange(item, targetUnit)`](#c_itemisiteminrangeitem-targetunit) - [`C_Item.IsItemOpenable(itemLocation)`](#c_itemisitemopenableitemlocation) - [`C_Item.IsLocked(itemLocation)`](#c_itemislockeditemlocation) @@ -11475,6 +11476,26 @@ Accepts the GUID string [`C_Item.GetItemGUID`](#c_itemgetitemguiditemlocation) / `UnitGUID` return; returns `false` for a malformed or zero GUID. To also cover the bank, use `C_Item.GetItemCount(itemID, true) > 0` instead. +### `C_Item.ItemHasRange(item)` / `ItemHasRange(item)` + +Whether the item has a range restriction — i.e. its on-use spell +reports a nonzero min or max range through the engine's own resolver. +Items with no on-use spell, or whose spell is rangeless (potions, food, +self-buff trinkets, hearthstone), have none. + +`item` is an itemID, `"item:NNN"` string, or item link, same as +[`C_Item.IsItemInRange`](#c_itemisiteminrangeitem-targetunit). Uncached +items read as having no range and fire no load. + +The two forms return different types. `ItemHasRange` returns `1` or +`nil`, like 3.3.5. `C_Item.ItemHasRange` returns `true` or `false`. + +```lua +ItemHasRange(1251) -- Linen Bandage → 1 (has a range) +C_Item.ItemHasRange(118) -- Minor Healing Potion → false +C_Item.ItemHasRange(6948) -- Hearthstone → false +``` + ### `C_Item.IsItemInRange(item, targetUnit)` Returns `true` if the item is in range of `targetUnit`, `false` if out diff --git a/src/item/InRange.cpp b/src/item/InRange.cpp index b6b3f5f0..86fbfc9e 100644 --- a/src/item/InRange.cpp +++ b/src/item/InRange.cpp @@ -17,6 +17,10 @@ // (names aren't resolvable — vanilla has no name→ID map — and yield nil); // `targetUnit` is a unit token ("target", "mouseover", "party1", …). // +// `C_Item.ItemHasRange(item)` / `ItemHasRange(item)` — whether the item +// has a range restriction at all (same `item` shapes). The global keeps +// 3.3.5's 1/nil; the namespaced form returns a bool. +// // An item's range comes from the spell it fires on use: we resolve the // item to its on-use spell (`Item::Spell::OnUseSpellIDForItemID`) and run // the same range test as `C_Spell.IsSpellInRange`, via the shared @@ -62,9 +66,38 @@ int __fastcall Script_C_Item_IsItemInRange(void *L) { return 1; } +// Shared core: true iff the item's on-use spell reports a non-near-zero +// min or max range via the engine's own resolver. A missing record, an +// item with no on-use spell, and a rangeless spell all read as false — +// passive, no cache warm, matching 3.3.5's `Script_ItemHasRange`. +bool ItemHasRange(int itemID) { + const int spellID = + itemID > 0 ? Item::Spell::OnUseSpellIDForItemID( + static_cast(itemID)) + : 0; + // `::Spell` — unqualified `Spell` would bind to `Item::Spell` here. + return ::Spell::Range::SpellIDHasRange(spellID); +} + +int __fastcall Script_ItemHasRange(void *L) { + if (ItemHasRange(Item::Arg::ResolveItemID(L, 1))) + Game::Lua::PushNumber(L, 1.0); + else + Game::Lua::PushNil(L); + return 1; +} + +int __fastcall Script_C_Item_ItemHasRange(void *L) { + Game::Lua::PushBool(L, ItemHasRange(Item::Arg::ResolveItemID(L, 1))); + return 1; +} + void RegisterLuaFunctions() { Game::Lua::RegisterTableFunction("C_Item", "IsItemInRange", &Script_C_Item_IsItemInRange); + Game::Lua::RegisterGlobalFunction("ItemHasRange", &Script_ItemHasRange); + Game::Lua::RegisterTableFunction("C_Item", "ItemHasRange", + &Script_C_Item_ItemHasRange); } const Game::ModuleAutoRegister _autoreg{&RegisterLuaFunctions};