diff --git a/README.md b/README.md index c4319fb7..31f14516 100644 --- a/README.md +++ b/README.md @@ -23,7 +23,7 @@ Full per-function reference: **[docs/API.md](docs/API.md)**. | [Class](docs/API.md#class) | `FillLocalizedClassList` | | [Combat](docs/API.md#combat) | `InCombatLockdown` | | [CVar](docs/API.md#cvar) | `C_CVar.GetCVarBool` | -| [Container](docs/API.md#container) | `C_Container.GetContainerItemDurability`, `C_Container.GetContainerItemID`, `C_Container.GetContainerItemRepairCost`, `C_Container.GetContainerNumFreeSlots`, `C_Container.GetItemCooldown`, `C_Container.MoveItem`, `C_Container.PlayerHasHearthstone`, `C_Container.SwapItems`, `C_Container.UseHearthstone`, `GetItemCooldown` | +| [Container](docs/API.md#container) | `C_Container.GetContainerItemCharges`, `C_Container.GetContainerItemDurability`, `C_Container.GetContainerItemID`, `C_Container.GetContainerItemRepairCost`, `C_Container.GetContainerNumFreeSlots`, `C_Container.GetItemCooldown`, `C_Container.MoveItem`, `C_Container.PlayerHasHearthstone`, `C_Container.SwapItems`, `C_Container.UseHearthstone`, `GetItemCooldown` | | 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` | | [EquipmentSet](docs/API.md#equipmentset) | `C_EquipmentSet.CanUseEquipmentSets`, `C_EquipmentSet.ClearIgnoredSlotsForSave`, `C_EquipmentSet.CreateEquipmentSet`, `C_EquipmentSet.DeleteEquipmentSet`, `C_EquipmentSet.EquipmentSetContainsLockedItems`, `C_EquipmentSet.GetEquipmentSetID`, `C_EquipmentSet.GetEquipmentSetIDs`, `C_EquipmentSet.GetEquipmentSetInfo`, `C_EquipmentSet.GetIgnoredSlots`, `C_EquipmentSet.GetItemIDs`, `C_EquipmentSet.GetItemLocations`, `C_EquipmentSet.GetNumEquipmentSets`, `C_EquipmentSet.IgnoreSlotForSave`, `C_EquipmentSet.IsSlotIgnoredForSave`, `C_EquipmentSet.ModifyEquipmentSet`, `C_EquipmentSet.SaveEquipmentSet`, `C_EquipmentSet.UnignoreSlotForSave`, `C_EquipmentSet.UseEquipmentSet` (sets persist to `WTF\Account\...\ClassicAPI_EquipmentSets.txt`) | | [Events](docs/API.md#events) | `C_EventUtils.IsEventValid` | diff --git a/docs/API.md b/docs/API.md index 2f921ede..47be53bc 100644 --- a/docs/API.md +++ b/docs/API.md @@ -34,6 +34,7 @@ build instructions. - [`GetItemCooldown(itemInfo)` / `C_Container.GetItemCooldown(itemID)`](#getitemcooldowniteminfo--c_containergetitemcooldownitemid) - [`C_Container.GetContainerItemDurability(containerIndex, slotIndex)`](#c_containergetcontaineritemdurabilitycontainerindex-slotindex) - [`C_Container.GetContainerItemRepairCost(containerIndex, slotIndex)`](#c_containergetcontaineritemrepaircostcontainerindex-slotindex) + - [`C_Container.GetContainerItemCharges(containerIndex, slotIndex)`](#c_containergetcontaineritemchargescontainerindex-slotindex) - [`C_Container.GetContainerNumFreeSlots(bagID)`](#c_containergetcontainernumfreeslotsbagid) - [`C_Container.PlayerHasHearthstone()`](#c_containerplayerhashearthstone) - [`C_Container.UseHearthstone()`](#c_containerusehearthstone) @@ -770,6 +771,62 @@ Useful for "repair only items above N copper" smart-repair logic without scanning tooltips. ClassicAPI addition; modern WoW has no direct equivalent. +### `C_Container.GetContainerItemCharges(containerIndex, slotIndex)` + +Per-slot equivalent of +[`C_Item.GetItemCount`](#c_itemgetitemcountitem-includebank-includecharges)'s +`includeCharges=true` mode — returns the total uses available in +*this single slot*, where `GetItemCount` totals the same value +across every matching slot. + +``` +uses = C_Container.GetContainerItemCharges(containerIndex, slotIndex) +``` + +`containerIndex` accepts the same values as +[`C_Container.GetContainerItemDurability`](#c_containergetcontaineritemdurabilitycontainerindex-slotindex) +(`0` = backpack, `1..4` = equipped bags, `-1`/`5..11` = bank, etc.). +`slotIndex` is 1-based. + +Math is `stack * usesPerItem`, where `usesPerItem` is +`abs(SPELL_CHARGES[0])` for items with a negative charges field +(consume-on-use: wands, healthstones, mana gems, sapper charges) +and `1` for everything else. Worked examples: + +| Slot contents | Stack | Raw charges | Returns | +|---|---:|---:|---:| +| Wand of Decay at 50 charges | 1 | -50 | **50** | +| Wand at 1 charge | 1 | -1 | **1** | +| Healthstone | 1 | -1 | **1** | +| Stack of 20 water | 20 | -1 | **20** | +| Stack of 5 mana potions | 5 | -1 | **5** | +| Hearthstone (cooldown-only) | 1 | 0 | **1** | +| Any other item in the slot | 1 | 0 | **1** | + +Returns `nil` only when the slot is empty. + +```lua +-- "how many charges does my wand have left?" +local charges = C_Container.GetContainerItemCharges(0, 1) +print("Wand charges remaining: " .. charges) + +-- "how many drinks across the bags?" — same as GetItemCount(water, false, true) +local total = 0 +for bag = 0, 4 do + for slot = 1, GetContainerNumSlots(bag) do + if C_Container.GetContainerItemID(bag, slot) == waterID then + total = total + C_Container.GetContainerItemCharges(bag, slot) + end + end +end +``` + +ClassicAPI addition; modern WoW has no direct equivalent (modern +addons read charges off tooltip text). Useful when you need a +per-slot number rather than `GetItemCount`'s rollup — e.g. to +display "X charges" on the slot UI for a wand without re-walking +every other matching item. + ### `C_Container.GetContainerNumFreeSlots(bagID)` Returns the number of empty slots in the given bag, plus the bag's diff --git a/src/container/Charges.cpp b/src/container/Charges.cpp new file mode 100644 index 00000000..6ca14a33 --- /dev/null +++ b/src/container/Charges.cpp @@ -0,0 +1,55 @@ +// This file is part of ClassicAPI. +// +// ClassicAPI is free software: you can redistribute it and/or modify it under the terms +// of the GNU Lesser 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 Lesser General Public License for more details. +// +// You should have received a copy of the GNU Lesser General Public License along with +// ClassicAPI. If not, see . + +// `C_Container.GetContainerItemCharges(containerIndex, slotIndex)` — +// returns the `abs(SPELL_CHARGES[0])` value of the item in the +// specified bag slot, or `nil` for empty slots and items that don't +// carry a charge concept. Wands return their remaining cast count +// (e.g. 50 → 49 → …); single-use items (Healthstone, Mana Gem, +// Goblin Sapper Charge) return `1`. +// +// Modern equivalent: none — modern WoW exposes charges only through +// tooltip text scanning. `C_Item.GetItemCount(includeBank, includeCharges)` +// totals charges across every matching stack; this is the per-slot +// reader. + +#include "Game.h" +#include "item/Charges.h" +#include "item/Location.h" + +namespace Container::Charges { + +namespace { + +int __fastcall Script_C_Container_GetContainerItemCharges(void *L) { + if (!Game::Lua::IsNumber(L, 1) || !Game::Lua::IsNumber(L, 2)) { + Game::Lua::Error(L, + "Usage: C_Container.GetContainerItemCharges(containerIndex, slotIndex)"); + return 0; + } + const int bagID = static_cast(Game::Lua::ToNumber(L, 1)); + const int slotIndex = static_cast(Game::Lua::ToNumber(L, 2)); + return Item::Charges::PushChargesForItem( + L, Item::Location::ResolveBag(L, bagID, slotIndex)); +} + +void RegisterLuaFunctions() { + Game::Lua::RegisterTableFunction("C_Container", "GetContainerItemCharges", + &Script_C_Container_GetContainerItemCharges); +} + +const Game::ModuleAutoRegister _autoreg{&RegisterLuaFunctions}; + +} // namespace + +} // namespace Container::Charges diff --git a/src/item/Charges.cpp b/src/item/Charges.cpp new file mode 100644 index 00000000..49b691bd --- /dev/null +++ b/src/item/Charges.cpp @@ -0,0 +1,39 @@ +// This file is part of ClassicAPI. +// +// ClassicAPI is free software: you can redistribute it and/or modify it under the terms +// of the GNU Lesser 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 Lesser General Public License for more details. +// +// You should have received a copy of the GNU Lesser General Public License along with +// ClassicAPI. If not, see . + +#include "Charges.h" + +#include "../Game.h" +#include "../Offsets.h" + +#include + +namespace Item::Charges { + +int PushChargesForItem(void *L, const uint8_t *item) { + if (item == nullptr) + return 0; + auto *descriptor = *reinterpret_cast( + item + Offsets::OFF_ITEM_DESCRIPTOR); + if (descriptor == nullptr) + return 0; + const int32_t stack = static_cast(*reinterpret_cast( + descriptor + Offsets::OFF_DESCRIPTOR_STACK_COUNT)); + const int32_t rawCharges = *reinterpret_cast( + descriptor + Offsets::OFF_DESCRIPTOR_SPELL_CHARGES_0); + const int32_t usesPerItem = (rawCharges < 0) ? -rawCharges : 1; + Game::Lua::PushNumber(L, static_cast(stack * usesPerItem)); + return 1; +} + +} // namespace Item::Charges diff --git a/src/item/Charges.h b/src/item/Charges.h new file mode 100644 index 00000000..d75fc51f --- /dev/null +++ b/src/item/Charges.h @@ -0,0 +1,44 @@ +// This file is part of ClassicAPI. +// +// ClassicAPI is free software: you can redistribute it and/or modify it under the terms +// of the GNU Lesser 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 Lesser General Public License for more details. +// +// You should have received a copy of the GNU Lesser General Public License along with +// ClassicAPI. If not, see . + +#pragma once + +#include + +namespace Item::Charges { + +// Pushes the total uses available in this single slot — the +// per-slot equivalent of `GetItemCount(_, _, includeCharges=true)`. +// Returns `1` (pushed one value) on success, `0` (pushes nothing, +// caller surfaces as `nil`) when the item is missing or the +// descriptor is null. +// +// Math is `stack * usesPerItem` where `usesPerItem` follows +// `Item::Count::GetUsesPerItem`: +// - `SPELL_CHARGES[0] >= 0` → `1` (no destroy-on-zero behavior; +// stack count alone reflects "how many uses"). +// - `SPELL_CHARGES[0] < 0` → `abs(value)` (consume-on-use items; +// wand at 50 has `-50` so each item contributes 50). +// +// Worked examples: +// - Wand at 50 charges (stack=1, raw=-50): `1 * 50 = 50` +// - Hearthstone (stack=1, raw=0): `1 * 1 = 1` (cooldown- +// only, no charges concept; we still surface "1 use"). +// - Water stack of 20 (stack=20, raw=-1): `20 * 1 = 20` +// - Equipped sword (stack=1, raw=0): `1 * 1 = 1` +// +// Caller can `return PushChargesForItem(L, item);` to forward the +// count directly. +int PushChargesForItem(void *L, const uint8_t *item); + +} // namespace Item::Charges