spell: CastAtCursor/CastAtUnit cast exact rank by spellID, accept spell name

Author: brues-code

docs/API.md

@@ -343,8 +343,8 @@ build instructions.
   - [`C_Spell.IsSpellHarmful(spellID)` / `C_Spell.IsSpellHelpful(spellID)`](#c_spellisspellharmfulspellid--c_spellisspellhelpfulspellid)
   - [`GetSpellSchool(spellID)`](#getspellschoolspellid)
   - [`CastSpellNoToggle(name | spellID)`](#castspellnotogglename--spellid)
-  - [`C_Spell.CastAtCursor(spellID)`](#c_spellcastatcursorspellid)
-  - [`C_Spell.CastAtUnit(spellID, unit)`](#c_spellcastatunitspellid-unit)
+  - [`C_Spell.CastAtCursor(spellIDOrName)`](#c_spellcastatcursorspellidorname)
+  - [`C_Spell.CastAtUnit(spellIDOrName, unit)`](#c_spellcastatunitspellidorname-unit)
   - [`C_Spell.CancelSpellByID(spellID)` / `CancelSpellByName(name)`](#c_spellcancelspellbyidspellid--cancelspellbynamename)
   - [`C_Spell.UnitCastingInfo(unit)` / `C_Spell.CastingInfo()`](#c_spellunitcastinginfounit--c_spellcastinginfo)
   - [`C_Spell.UnitChannelInfo(unit)` / `C_Spell.ChannelInfo()`](#c_spellunitchannelinfounit--c_spellchannelinfo)
@@ -5507,7 +5507,7 @@ C_Item.UseAtCursor("Iron Grenade")
 
 Implementation chains the existing item-use path
 (`Item::Location::FindByArgInBags` + `FUN_ITEM_USE`) with
-[`Spell::AtCursor::Resolve`](#c_spellcastatcursorspellid) — same
+[`Spell::AtCursor::Resolve`](#c_spellcastatcursorspellidorname) — same
 cursor-resolution helper `C_Spell.CastAtCursor` uses. When the item
 fires a non-ground-target spell, the cursor leg no-ops and returns
 `false`; the item still uses normally (any implicit target — current
@@ -5535,7 +5535,7 @@ C_Item.UseAtUnit("Iron Grenade", "player")
 Same chain as `UseAtCursor` (`Item::Location::FindByArgInBags` +
 `FUN_ITEM_USE`) but committing the placement at the unit's world
 position via
-[`Spell::AtCursor::CommitAtCoords`](#c_spellcastatunitspellid-unit)
+[`Spell::AtCursor::CommitAtCoords`](#c_spellcastatunitspellidorname-unit)
 instead of the cursor raycast. Returns `true` when the placement
 landed at the unit; `false` for non-ground-target items (the item
 still fires with any implicit target), unparseable input,
@@ -8474,28 +8474,37 @@ Using this from inside a macro action slot? See
 [`CastSpellNoToggle` as a macro cast line](#castspellnotoggle-as-a-macro-cast-line) below for the additional
 parser support that makes the slot tag correctly for action-bar UIs.
 
-### `C_Spell.CastAtCursor(spellID)`
+### `C_Spell.CastAtCursor(spellIDOrName)`
 
 Casts a ground-target spell at the player's current cursor world
 position, bypassing the manual click on the AoE reticle the engine
 would otherwise require. ClassicAPI's analog of modern's
 `/cast [@cursor] Blizzard`. Returns `true` when the cursor-placement
 leg landed; `false` for non-ground-target spells (cast still fires
-normally on the current target), unknown spellIDs, cursor over UI /
+normally on the current target), unknown spells, cursor over UI /
 off-screen, etc.
 
+Accepts a **spellID** or a **spell name**:
+
 ```lua
-C_Spell.CastAtCursor(10)    -- Blizzard rank 1 at cursor
-C_Spell.CastAtCursor(2120)  -- Flamestrike rank 1 at cursor
+C_Spell.CastAtCursor(10)                  -- Blizzard Rank 1 (exact spellID)
+C_Spell.CastAtCursor(2120)                -- Flamestrike Rank 1
+C_Spell.CastAtCursor("Blizzard")          -- highest known rank
+C_Spell.CastAtCursor("Blizzard(Rank 6)")  -- that specific rank
 ```
 
+A **numeric** spellID casts that *exact* spell — every rank is its own
+spellID, so `10` casts Blizzard Rank 1 (not the highest known rank). A
+**name** goes through the engine's own resolver, which parses a trailing
+`(Rank N)`; a bare name casts the highest rank you know.
+
 Two-stage internally:
 
-1. Initiates the cast through the same path
-   [`CastSpellByName`](docs/API.md#numeric-spellids-in-cast-and-castspellbyname)
-   uses (`FUN_RESOLVE_SPELL_NAME_TO_SLOT` + the engine's cast
-   dispatcher). If the spell needs a ground target, the engine
-   enters placement mode and arms the AoE reticle.
+1. Initiates the cast: a numeric spellID resolves to its exact spellbook
+   slot (`Spell::Lookup::FindSpellbookSlot`, so the requested rank is the one
+   that fires), a name goes through `FUN_RESOLVE_SPELL_NAME_TO_SLOT`; either
+   way it dispatches through the engine's cast dispatcher. If the spell needs
+   a ground target, the engine enters placement mode and arms the AoE reticle.
 
 2. Refreshes the cursor's screen→world raycast via
    `FUN_REFRESH_CURSOR_RAYCAST` (the same internal the engine fires
@@ -8514,24 +8523,28 @@ The companion item version is
 [`C_Item.UseAtCursor`](#c_itemuseatcursoriteminfo) — same chain via
 the item-use path for grenades / on-use ground-target items.
 
-### `C_Spell.CastAtUnit(spellID, unit)`
+### `C_Spell.CastAtUnit(spellIDOrName, unit)`
 
 Casts a ground-target spell at `unit`'s feet, bypassing the AoE
 reticle click. ClassicAPI's analog of modern's
-`/cast [@unit] Flamestrike` — `CastAtUnit(spellID, "player")` drops it
+`/cast [@unit] Flamestrike` — `CastAtUnit(spell, "player")` drops it
 at the player's position, `"target"` at the target's, and so on for
 any unit token (`"mouseover"`, `"party1"`, `"raid7"`, …). Returns
 `true` when the placement landed at the unit; `false` for
 non-ground-target spells (cast still fires normally), unknown
-spellIDs, or a unit with no resolvable position.
+spells, or a unit with no resolvable position.
+
+The first argument takes a spellID or a spell name, with the same
+exact-rank / `(Rank N)` semantics as `CastAtCursor`.
 
 ```lua
-C_Spell.CastAtUnit(2120, "target")   -- Flamestrike at the target's feet
-C_Spell.CastAtUnit(10, "player")     -- Blizzard centered on yourself
+C_Spell.CastAtUnit(2120, "target")            -- Flamestrike at the target's feet
+C_Spell.CastAtUnit(10, "player")              -- Blizzard Rank 1 on yourself
+C_Spell.CastAtUnit("Blizzard(Rank 6)", "target")
 ```
 
 Same two-stage shape as
-[`C_Spell.CastAtCursor`](#c_spellcastatcursorspellid), but instead of
+[`C_Spell.CastAtCursor`](#c_spellcastatcursorspellidorname), but instead of
 the cursor raycast, step 2 reads the unit's world position from its
 `GetPosition` virtual (the same one `CheckInteractDistance` /
 `UnitInRange` use) and commits placement there via

src/spell/AtCursor.cpp

@@ -17,13 +17,12 @@
 //
 // Implementation chains the engine's existing primitives:
 //
-//   1. Initiate the cast the same way `Script_CastSpellByName` does:
-//      resolve `spellID` (via our `Spell::CastByID` numeric-name hook)
-//      to a spellbook slot through `FUN_RESOLVE_SPELL_NAME_TO_SLOT`,
-//      then dispatch through `FUN_SPELL_CAST_DISPATCH`. For a ground-
-//      target spell, the engine enters placement mode at this point
-//      (sets `VAR_SPELL_PLACEMENT_STATE`); for a normal cast, it
-//      fires immediately.
+//   1. Initiate the cast: resolve the *exact* `spellID` to its spellbook
+//      slot (`Spell::Lookup::FindSpellbookSlot` — NOT name resolution, which
+//      would cast the highest rank) and dispatch through
+//      `FUN_SPELL_CAST_DISPATCH`. For a ground-target spell, the engine
+//      enters placement mode at this point (sets `VAR_SPELL_PLACEMENT_STATE`);
+//      for a normal cast, it fires immediately.
 //
 //   2. `Spell::AtCursor::Resolve()` then refreshes the cursor's world
 //      raycast via `FUN_REFRESH_CURSOR_RAYCAST` and commits the
@@ -41,10 +40,10 @@
 
 #include "Game.h"
 #include "Offsets.h"
+#include "spell/Lookup.h"
 #include "spell/MacroPrimarySpell.h"
 
 #include <cstdint>
-#include <cstdio>
 #include <cstring>
 
 namespace Spell::AtCursor {
@@ -141,49 +140,71 @@ bool Resolve() {
 
 namespace {
 
-using NameToSlot_t = int(__fastcall *)(const char *name, void *out);
 using CastDispatch_t = void(__fastcall *)(unsigned slot, int bookType,
                                            unsigned targetGuidLo, float targetGuidHi);
+using NameToSlot_t = int(__fastcall *)(const char *name, void *out);
+
+void DispatchSlot(int slot0Based, int bookType) {
+    auto dispatch = reinterpret_cast<CastDispatch_t>(
+        Offsets::FUN_SPELL_CAST_DISPATCH);
+    // (0, 0) GUID = no implicit target; the engine handles placement.
+    dispatch(static_cast<unsigned>(slot0Based), bookType, 0, 0.0f);
+}
 
 } // namespace
 
 bool DispatchSpellCast(int spellID) {
     if (spellID <= 0)
         return false;
 
-    // Hand the spellID off as a numeric string — our `Spell::CastByID`
-    // hook on `FUN_RESOLVE_SPELL_NAME_TO_SLOT` translates pure-numeric
-    // input into the locale-resolved spell name internally, so the
-    // engine treats it just like `CastSpellByName("Blizzard")`.
-    char numBuf[16];
-    std::snprintf(numBuf, sizeof(numBuf), "%d", spellID);
+    // Resolve the EXACT spellID to its spellbook slot. Every rank is its own
+    // slot, so we must NOT go through name resolution — that walks to the
+    // highest rank and would cast Blizzard(Rank 6) for a Rank 1 (spellID 10)
+    // request. `FindSpellbookSlot` returns a 1-based slot; the dispatcher
+    // wants the 0-based index into `VAR_PLAYER_SPELLBOOK`.
+    int bookType = 0;
+    const int slot1 = Spell::Lookup::FindSpellbookSlot(spellID, &bookType);
+    if (slot1 <= 0)
+        return false; // not in the player's spellbook
 
+    DispatchSlot(slot1 - 1, bookType);
+    return true;
+}
+
+bool DispatchSpellCastByName(const char *name) {
+    if (name == nullptr || *name == '\0')
+        return false;
+
+    // The engine's resolver strips a trailing `(Rank N)` and returns the
+    // 0-based spellbook slot (highest rank when no rank is given). This is the
+    // by-name path — for an exact rank prefer the numeric spellID overload.
     auto nameToSlot = reinterpret_cast<NameToSlot_t>(
         Offsets::FUN_RESOLVE_SPELL_NAME_TO_SLOT);
     int bookType = 0;
-    const int slot = nameToSlot(numBuf, &bookType);
+    const int slot = nameToSlot(name, &bookType);
     if (slot < 0)
         return false; // not in the player's spellbook
 
-    auto dispatch = reinterpret_cast<CastDispatch_t>(
-        Offsets::FUN_SPELL_CAST_DISPATCH);
-    dispatch(static_cast<unsigned>(slot), bookType,
-             0, 0.0f); // no implicit target unit; engine handles placement
+    DispatchSlot(slot, bookType);
     return true;
 }
 
 namespace {
 
 int __fastcall Script_C_Spell_CastAtCursor(void *L) {
-    if (!Game::Lua::IsNumber(L, 1)) {
-        Game::Lua::PushBool(L, false);
-        return 1;
+    // Accept a numeric spellID (exact rank) or a spell name (the engine's
+    // resolver parses a trailing "(Rank N)"). IsNumber is checked first so a
+    // numeric string like "10" still takes the exact-spellID path.
+    bool dispatched = false;
+    if (Game::Lua::IsNumber(L, 1)) {
+        dispatched = DispatchSpellCast(static_cast<int>(Game::Lua::ToNumber(L, 1)));
+    } else if (Game::Lua::IsString(L, 1)) {
+        dispatched = DispatchSpellCastByName(Game::Lua::ToString(L, 1));
     }
-    const int spellID = static_cast<int>(Game::Lua::ToNumber(L, 1));
 
-    // Spell not in the player's spellbook → match `CastSpellByName`'s
-    // silent failure.
-    if (!DispatchSpellCast(spellID)) {
+    // Bad input / spell not in the player's spellbook → match
+    // `CastSpellByName`'s silent failure.
+    if (!dispatched) {
         Game::Lua::PushBool(L, false);
         return 1;
     }

src/spell/AtCursor.h

@@ -46,6 +46,12 @@ bool CommitAtCoords(const float coords[3]);
 // `CommitAtCoords`); for a normal spell it fires immediately. Returns
 // true if the cast was dispatched (spell is in the player's
 // spellbook), false otherwise.
+//
+// The numeric form casts the *exact* spellID (a specific rank). The
+// name form defers to the engine's own resolver, which parses a
+// trailing `(Rank N)` — `"Blizzard"` casts the highest known rank,
+// `"Blizzard(Rank 6)"` casts that rank.
 bool DispatchSpellCast(int spellID);
+bool DispatchSpellCastByName(const char *name);
 
 } // namespace Spell::AtCursor

src/spell/AtUnit.cpp

@@ -43,11 +43,14 @@ namespace Spell::AtUnit {
 namespace {
 
 int __fastcall Script_C_Spell_CastAtUnit(void *L) {
-    if (!Game::Lua::IsNumber(L, 1) || !Game::Lua::IsString(L, 2)) {
+    // arg1: numeric spellID (exact rank) or spell name ("(Rank N)"-aware).
+    // arg2: unit token.
+    const bool byNumber = Game::Lua::IsNumber(L, 1);
+    if ((!byNumber && !Game::Lua::IsString(L, 1)) ||
+        !Game::Lua::IsString(L, 2)) {
         Game::Lua::PushBool(L, false);
         return 1;
     }
-    const int spellID = static_cast<int>(Game::Lua::ToNumber(L, 1));
     const char *token = Game::Lua::ToString(L, 2);
 
     // Resolve the unit's position before dispatching — fail fast so a
@@ -61,7 +64,12 @@ int __fastcall Script_C_Spell_CastAtUnit(void *L) {
         return 1;
     }
 
-    if (!Spell::AtCursor::DispatchSpellCast(spellID)) {
+    const bool dispatched =
+        byNumber
+            ? Spell::AtCursor::DispatchSpellCast(
+                  static_cast<int>(Game::Lua::ToNumber(L, 1)))
+            : Spell::AtCursor::DispatchSpellCastByName(Game::Lua::ToString(L, 1));
+    if (!dispatched) {
         Game::Lua::PushBool(L, false);
         return 1;
     }