From 94e77ef5afcbbb6b3522edaaa1ec00dfeb8a921c Mon Sep 17 00:00:00 2001 From: Brues <5278969+brues-code@users.noreply.github.com> Date: Sun, 30 Aug 2026 16:43:11 -0500 Subject: [PATCH] feat(unit): UnitCreatedBySpell + consolidate the unit-token resolver MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 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. --- docs/API.md | 21 +++++++++++++++++++++ src/Game.cpp | 6 ++++++ src/Game.h | 13 +++++++++++++ src/Offsets.h | 13 +++++++++++++ src/unit/Pet.cpp | 47 +++++++++++++++++++++++++++++++++++++++++------ 5 files changed, 94 insertions(+), 6 deletions(-) diff --git a/docs/API.md b/docs/API.md index e483d577..5023d9f8 100644 --- a/docs/API.md +++ b/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 diff --git a/src/Game.cpp b/src/Game.cpp index 2bf63b54..fd457d12 100644 --- a/src/Game.cpp +++ b/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(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 diff --git a/src/Game.h b/src/Game.h index ccc7f333..36944fc6 100644 --- a/src/Game.h +++ b/src/Game.h @@ -57,6 +57,19 @@ inline T &Ref(uintptr_t address) { return *reinterpret_cast(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 *)(); diff --git a/src/Offsets.h b/src/Offsets.h index 9105f38c..96aac046 100644 --- a/src/Offsets.h +++ b/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 diff --git a/src/unit/Pet.cpp b/src/unit/Pet.cpp index 4192e894..77788d4e 100644 --- a/src/unit/Pet.cpp +++ b/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,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(Offsets::FUN_RESOLVE_UNIT_TOKEN); - return static_cast(resolve(token)); + return static_cast(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( - unit + Offsets::OFF_UNIT_DESCRIPTOR); + auto *desc = Game::Read(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(desc + off); + const uint64_t g = Game::Read(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(unit, Offsets::OFF_UNIT_DESCRIPTOR); + if (desc == nullptr) + return 0; + return Game::Read(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(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};