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

This commit is contained in:
Brues
2026-07-08 20:12:16 -05:00
parent 8b6760cd77
commit 23cdbe196d
4 changed files with 97 additions and 49 deletions
+32 -19
View File
@@ -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
+48 -27
View File
@@ -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,9 +140,16 @@ 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
@@ -151,39 +157,54 @@ 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;
}
+6
View File
@@ -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
+11 -3
View File
@@ -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;
}