feat(unit): UnitCreatedBySpell + consolidate the unit-token resolver

Add `UnitCreatedBySpell(unit)` — the spell that summoned a unit (a totem's
totem-drop spell, a pet/guardian's summon spell), read from the unit's
UNIT_CREATED_BY_SPELL descriptor field (byte +0x230). It is the same field
the engine's unit-title builder consults to pick the Pet/Minion/Guardian/
Creation title, and it is broadcast, so it resolves for any unit in range.
This is the summoning spell, distinct from the (server-only) spell a totem
casts.

Also add a single `Game::ResolveUnitToken(token)` helper that wraps the
engine token->CGUnit* resolver, and route unit/Pet.cpp through it plus the
Game::Read<T> field accessors — removing the hand-rolled ResolveUnitToken_t
typedef and raw reinterpret_casts from this module. The name was already
referenced in Offsets.h and CLAUDE.md but had never been implemented.
This commit is contained in:
Brues
2026-08-30 16:43:54 -05:00
parent 1458d60b51
commit 94e77ef5af
5 changed files with 94 additions and 6 deletions
+21
View File
@@ -621,6 +621,7 @@ build instructions.
- [`UnitIsPet(unit)`](#unitispetunit)
- [`UnitIsOtherPlayersPet(unit)`](#unitisotherplayerspetunit)
- [`UnitOwnerGUID(unit)`](#unitownerguidunit)
- [`UnitCreatedBySpell(unit)`](#unitcreatedbyspellunit)
- [`UnitStandState(unit)`](#unitstandstateunit)
- [`UnitInRange(unit)`](#unitinrangeunit)
- [`UnitDistanceSquared(unit)`](#unitdistancesquaredunit)
@@ -14876,6 +14877,26 @@ if owner == UnitGUID("player") then ... end -- is it my minion?
Reads the same owner field the pet predicates use (`CharmedBy`, else
`CreatedBy` in the unit's `m_objectFields`).
### `UnitCreatedBySpell(unit)`
Returns the spell ID that summoned `unit`: the totem-drop spell for a totem,
or the summon spell for a pet or guardian. Returns `nil` for an unresolved
unit, and for a unit that no spell summoned (players and world creatures).
This is the summoning spell, not a spell that the unit casts later. The spell
that a totem casts stays on the server and never reaches the client. The
client receives this value for every summoned unit, so it works for any unit
in range, not only your own summons. Use `GetSpellInfo` to get a readable
name.
A ClassicAPI extension, not a stock WoW global.
```lua
UnitCreatedBySpell("pet") -- your pet's summon spell id
local id = UnitCreatedBySpell("target") -- target a totem → its totem spell id
if id then print(GetSpellInfo(id)) end -- prints the name, like "Searing Totem"
```
### `UnitStandState(unit)`
Returns the unit's standstate as an integer, matching the modern
+6
View File
@@ -17,6 +17,12 @@
namespace Game {
void *ResolveUnitToken(const char *token) {
using ResolveUnitToken_t = void *(__fastcall *)(const char *token);
auto fn = reinterpret_cast<ResolveUnitToken_t>(Offsets::FUN_RESOLVE_UNIT_TOKEN);
return fn(token);
}
namespace Lua {
// Each entry binds a typed function pointer in `Game::Lua::` to the
// corresponding raw VA in `Offsets`. The X-macro keeps the column-aligned
+13
View File
@@ -57,6 +57,19 @@ inline T &Ref(uintptr_t address) {
return *reinterpret_cast<T *>(address);
}
// --- Engine primitives ------------------------------------------------------
// Resolve a unit token (`"player"`, `"target"`, `"party3"`, `"nameplate1"`,
// …) to its live `CGUnit_C *`, through the engine's own resolver
// (`FUN_RESOLVE_UNIT_TOKEN`). Returns null for a valid token that currently
// has no unit (e.g. `"target"` with nothing targeted). NOTE: the engine
// RAISES a Lua error for a string that isn't a valid token form (an arbitrary
// name like `"Bob"`), so only pass real unit tokens — the same contract every
// stock `Unit*` global carries. Centralizes the
// `reinterpret_cast<…>(FUN_RESOLVE_UNIT_TOKEN)` idiom that was copy-pasted
// across a dozen modules.
void *ResolveUnitToken(const char *token);
using FrameScript_Initialize_t = bool(__fastcall *)();
using LoadScriptFunctions_t = void(__fastcall *)();
+13
View File
@@ -1089,6 +1089,19 @@ enum Offsets {
OFF_UNIT_FIELD_CHARMEDBY = 0x10,
OFF_UNIT_FIELD_CREATEDBY = 0x20,
// UNIT_CREATED_BY_SPELL — the spell that summoned this unit (descriptor
// byte +0x230, field index 0x8C). Set for every spell-summoned unit:
// totems (the shaman's totem-drop spell), pets, guardians, wild summons.
// Verified two ways: the unit-title builder `FUN_0052FD30` reads
// `[desc+0x230]` as the summoning spell (then switches on its Spell.dbc
// Effect[0] to pick "Guardian"/"Creation"), and the server stamps it
// with `m_spellInfo->Id` (tortoise-wow `EffectSummonTotem`/
// `EffectSummonGuardian`/`EffectSummon`). A broadcast field, so it's
// readable for any unit in range. `Unit::Pet` exposes it as
// `UnitCreatedBySpell`. NB: this is the SUMMONING spell — distinct from
// the spell a totem casts (that's server-side only, never broadcast).
OFF_UNIT_FIELD_CREATED_BY_SPELL = 0x230,
// Pet-vs-minion discriminator for an owned unit: `int __fastcall(unit)`.
// `0x00605570` is really the engine's **creature-type resolver** — it's
// `Script_UnitCreatureType`'s (`0x0051A280`) inner helper and returns the
+41 -6
View File
@@ -56,7 +56,6 @@ namespace Unit::Pet {
namespace {
using ResolveUnitToken_t = void *(__fastcall *)(const char *token);
// `int __fastcall(unit)` → 1 for a controllable pet, non-1 otherwise.
// The engine's pet-vs-minion title discriminator. See
// FUN_UNIT_PET_MINION_CLASS.
@@ -68,16 +67,14 @@ const uint8_t *ResolveUnit(void *L) {
const char *token = Game::Lua::ToString(L, 1);
if (token == nullptr)
return nullptr;
auto resolve = reinterpret_cast<ResolveUnitToken_t>(Offsets::FUN_RESOLVE_UNIT_TOKEN);
return static_cast<const uint8_t *>(resolve(token));
return static_cast<const uint8_t *>(Game::ResolveUnitToken(token));
}
// The unit's owner/controller GUID: CharmedBy, else CreatedBy (the two
// fields the engine itself uses for ownership). 0 for players, world
// creatures, and anything unowned.
uint64_t OwnerGuid(const uint8_t *unit) {
auto *desc = *reinterpret_cast<const uint8_t *const *>(
unit + Offsets::OFF_UNIT_DESCRIPTOR);
auto *desc = Game::Read<const uint8_t *>(unit, Offsets::OFF_UNIT_DESCRIPTOR);
if (desc == nullptr)
return 0;
const int owners[] = {
@@ -85,13 +82,24 @@ uint64_t OwnerGuid(const uint8_t *unit) {
Offsets::OFF_UNIT_FIELD_CREATEDBY,
};
for (int off : owners) {
const uint64_t g = *reinterpret_cast<const uint64_t *>(desc + off);
const uint64_t g = Game::Read<uint64_t>(desc, off);
if (g != 0)
return g;
}
return 0;
}
// The spell that summoned this unit (its UNIT_CREATED_BY_SPELL descriptor
// field): the totem-drop spell for a totem, the summon spell for a
// pet/guardian, etc. 0 for a unit not summoned by a spell (players, world
// creatures) or an object with no descriptor.
uint32_t CreatedBySpell(const uint8_t *unit) {
auto *desc = Game::Read<const uint8_t *>(unit, Offsets::OFF_UNIT_DESCRIPTOR);
if (desc == nullptr)
return 0;
return Game::Read<uint32_t>(desc, Offsets::OFF_UNIT_FIELD_CREATED_BY_SPELL);
}
// `UnitIsMinion(unit)` — true iff the unit is a player's minion (pet,
// guardian, totem, or charmed creature): player-controlled but not itself
// a player. NPCs, world creatures, and players return false. A bad or
@@ -184,6 +192,31 @@ int __fastcall Script_UnitOwnerGUID(void *L) {
return 1;
}
// `UnitCreatedBySpell(unit)` — the spell ID that summoned this unit, read
// from its UNIT_CREATED_BY_SPELL field: the shaman totem-drop spell for a
// totem, the summon spell for a pet/guardian, and so on. This is the same
// field the engine's unit-title builder consults to pick the
// "Pet"/"Minion"/"Guardian"/"Creation" title. It is a broadcast descriptor
// field, so it works for any unit in range, not just your own summons.
// Returns nil for an unresolved unit and for anything not summoned by a
// spell (players, world creatures). Note this is the *summoning* spell —
// the spell a totem casts is server-side only and never reaches the client.
// A ClassicAPI extension — not a stock WoW global.
int __fastcall Script_UnitCreatedBySpell(void *L) {
const uint8_t *unit = ResolveUnit(L);
if (unit == nullptr) {
Game::Lua::PushNil(L);
return 1;
}
const uint32_t spellId = CreatedBySpell(unit);
if (spellId == 0) {
Game::Lua::PushNil(L);
return 1;
}
Game::Lua::PushNumber(L, static_cast<double>(spellId));
return 1;
}
} // namespace
static void RegisterLuaFunctions() {
@@ -192,6 +225,8 @@ static void RegisterLuaFunctions() {
Game::Lua::RegisterGlobalFunction("UnitIsOtherPlayersPet",
&Script_UnitIsOtherPlayersPet);
Game::Lua::RegisterGlobalFunction("UnitOwnerGUID", &Script_UnitOwnerGUID);
Game::Lua::RegisterGlobalFunction("UnitCreatedBySpell",
&Script_UnitCreatedBySpell);
}
static const Game::ModuleAutoRegister _autoreg{&RegisterLuaFunctions};