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.

Author: brues-code

docs/API.md

@@ -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

src/Game.cpp

@@ -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

src/Game.h

@@ -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 *)();
 

src/Offsets.h

@@ -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

src/unit/Pet.cpp

@@ -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,30 +67,39 @@ 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[] = {
         Offsets::OFF_UNIT_FIELD_CHARMEDBY,
         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};