diff --git a/docs/API.md b/docs/API.md index fb5f0afb..24b1de68 100644 --- a/docs/API.md +++ b/docs/API.md @@ -2828,9 +2828,9 @@ Stored as the `bankAutosortDisabled` console variable. ### `C_CreatureInfo.GetCreatureID(guid)` -Extracts the creature template / NPC ID from a unit GUID. The entry ID -is packed directly into bits 24-47 of the 64-bit GUID for the types that -carry one; this function does the shift and mask so addons don't have to. +Returns the creature template / NPC id for a unit GUID, or `nil`. The id is +the same one the game uses to look up the creature's name, and the same one +Wowhead and Turtle's database show in their NPC pages. ```lua C_CreatureInfo.GetCreatureID(UnitGUID("target")) -- 1842 for Hogger @@ -2838,10 +2838,17 @@ C_CreatureInfo.GetCreatureID(UnitGUID("pet")) -- pet's creature template ID C_CreatureInfo.GetCreatureID(UnitGUID("player")) -- nil (no entry on players) ``` +While the unit is in view, the id is read live from the unit, so it always +matches the name you see. Some spawn points pick one of several templates, +and a respawn can pick a different one. When such a unit is out of view, the +id comes from the GUID instead, and that id is the spawn point's first +template, which can differ from the unit's current name. + Accepts creature GUIDs (`0xF130xxxx…`) and pet GUIDs (`0xF140xxxx…`). Returns `nil` for: - non-string input or malformed GUIDs -- player GUIDs — the low 32 bits hold a player ID, not a template +- player GUIDs — a player carries no template +- a pet that is out of view — a pet GUID does not carry its template - game-object / dynamic-object / corpse / item GUIDs — `C_CreatureInfo` doesn't surface entry IDs for these even though the bits are in the same range; addons that need them can shift the raw GUID themselves @@ -17450,12 +17457,14 @@ creatureID = UnitCreatureID(unit) /dump UnitCreatureID("pet") -- your pet's creature-template id ``` -The entry id is packed into the unit's GUID (bits 24-47), so this reads it -straight from the resolved GUID — no creature cache lookup. Returns `nil` for a -player (a player GUID carries no template), an unresolvable-but-valid token -(`"target"` with nothing targeted, an empty `"partyN"` slot), and any unit whose -GUID isn't a creature or pet. Raises a Lua error on a garbage token — the -standard `UnitX` behavior. Pair with +The id is read live from the unit, so it always matches the name you see, and +it is the id Wowhead and Turtle's database show for that NPC. For a unit that +is out of view, the same fallback as `C_CreatureInfo.GetCreatureID` applies. +Returns `nil` for a player (a player carries no template), an +unresolvable-but-valid token (`"target"` with nothing targeted, an empty +`"partyN"` slot), an out-of-view pet, and any unit whose GUID isn't a creature +or pet. Raises a Lua error on a garbage token — the standard `UnitX` behavior. +Pair with [`C_CreatureInfo.GetCreatureInfoByID`](#c_creatureinfogetcreatureinfobyidcreatureid) to get the name from the id. diff --git a/src/Offsets.h b/src/Offsets.h index ccc035f1..3fa30f48 100644 --- a/src/Offsets.h +++ b/src/Offsets.h @@ -1551,6 +1551,24 @@ enum Offsets { // descriptor at +0x114 — these are sibling classes under CGObject // with class-specific descriptor offsets. OFF_UNIT_DESCRIPTOR = 0x110, + // A creature's LIVE creature_template entry — in the INSTANCE BLOCK at + // `[unit + OFF_UNIT_GUID_PTR]` (GUID @+0x00, entry @+0x0C), the same + // shape as CGItem's block (GUID @+0x00, itemID @+0x0C). NOT the + // descriptor's OBJECT_FIELD_ENTRY slot (+0xC), which reads 0 for + // creatures exactly as it does for items (in-game probe: a Gordunni + // Mage-Lord read desc 0 / block 5239 / GUID bits 5236). This is what the + // engine keys the creature NAME query on: `FUN_00604600` resolves the unit + // and calls the creature cache with `[[unit+8] + 0xC]`; it is registered + // as the OBJECT-bank field-0xC handler (`FUN_006041f0` → + // `FUN_00468070(0, 0xC, 4, 0x604600)`). Do NOT derive a creature id from + // the GUID's entry bits instead: the server builds the GUID from the spawn + // row's FIRST creature id (`Creature::CreateFromProto` → + // `Object::_Create(guidlow, creature_id[0], …)`) and applies the rolled + // template with `UpdateEntry` → `SetEntry` only, so multi-id spawns (6,935 + // Turtle rows) and respawn re-rolls put a different template behind the + // same GUID entry — Turtle's Gordunni rows are {5236, 5238, 5239} and + // every one of them carries 5236 in its GUID. Read by `Unit::CreatureID`. + OFF_UNIT_INSTANCE_ENTRY = 0x0C, // CGCreature client-side creature-data cache row. Populated by the // engine when an NPC GUID becomes visible (the same row the diff --git a/src/guid/CreatureInfo.cpp b/src/guid/CreatureInfo.cpp index 6b35ea11..4f0f489e 100644 --- a/src/guid/CreatureInfo.cpp +++ b/src/guid/CreatureInfo.cpp @@ -10,6 +10,7 @@ #include "Game.h" #include "guid/Guid.h" +#include "unit/CreatureID.h" #include @@ -19,23 +20,23 @@ namespace { // `C_CreatureInfo.GetCreatureID(guid) → creatureID | nil` // -// Extracts the creature template / NPC ID from a unit GUID. Vanilla -// 1.12 packs the entry ID into bits 24-47 of the GUID for the world- -// object types that carry one (creature `0xF130`, pet `0xF140`); the -// low 24 bits are the per-spawn counter. Player GUIDs use the low 32 -// bits for the player ID and have no template, so they return nil. +// The creature template / NPC ID for a unit GUID. Resolution lives in +// `Unit::CreatureID::ForGuid`: the unit's LIVE instance-block entry while the +// object is in view (the field the engine keys the creature's name on), else +// the entry packed in a creature GUID's bits 24-47. See unit/CreatureID.cpp +// for why the two differ on this server family (multi-id spawns re-roll the +// template but keep the GUID; pet GUIDs pack the pet number). // -// Modern's `C_CreatureInfo.GetCreatureID` returns nil for any GUID -// that isn't a creature; we additionally accept pet GUIDs since -// vanilla pets carry an entry ID too (the pet's creature template, -// the same field that drives the pet bar icon). Game-object GUIDs -// have entry IDs in the same bit range but modern doesn't surface -// them through `C_CreatureInfo` — addons that need those should -// look at the GUID prefix and shift manually. +// Modern's `C_CreatureInfo.GetCreatureID` returns nil for any GUID that +// isn't a creature; we additionally answer pet GUIDs while the pet is in view +// (its template drives the pet bar icon). Game-object GUIDs carry entry IDs in +// the same bit range but modern doesn't surface them through +// `C_CreatureInfo` — addons that need those should look at the GUID prefix +// and shift manually. // // Returns nil for: non-string input, malformed GUIDs, non-creature / -// non-pet types, and entry IDs of 0 (the engine never assigns -// entry 0 to anything; treat as "no info"). +// non-pet types, an out-of-view pet, and entry IDs of 0 (the engine never +// assigns entry 0 to anything; treat as "no info"). int __fastcall Script_GetCreatureID(void *L) { if (!Game::Lua::IsString(L, 1)) { Game::Lua::PushNil(L); @@ -46,9 +47,7 @@ int __fastcall Script_GetCreatureID(void *L) { Game::Lua::PushNil(L); return 1; } - // `Guid::CreatureEntry` handles the creature/pet type gate + the bits-24-47 - // extraction, and returns 0 for players, non-creature types, and entry 0. - const uint32_t entryID = CreatureEntry(guid); + const uint32_t entryID = Unit::CreatureID::ForGuid(guid); if (entryID == 0) { Game::Lua::PushNil(L); return 1; diff --git a/src/guid/Guid.cpp b/src/guid/Guid.cpp index a3d23b31..e158cd2d 100644 --- a/src/guid/Guid.cpp +++ b/src/guid/Guid.cpp @@ -52,8 +52,7 @@ const char *FormatAsString(uint64_t guid, char *buf, std::size_t cap) { } uint32_t CreatureEntry(uint64_t guid) { - const Type type = Classify(guid); - if (type != Type::Creature && type != Type::Pet) + if (Classify(guid) != Type::Creature) // a pet GUID packs the pet number here return 0; return static_cast((guid >> 24) & 0xFFFFFFu); } diff --git a/src/guid/Guid.h b/src/guid/Guid.h index 07d62dad..ec07e49c 100644 --- a/src/guid/Guid.h +++ b/src/guid/Guid.h @@ -76,12 +76,16 @@ inline bool IsGameObject(uint64_t guid) { return Classify(guid) == Type::Game inline bool IsDynamicObject(uint64_t guid) { return Classify(guid) == Type::DynamicObject; } inline bool IsCorpse(uint64_t guid) { return Classify(guid) == Type::Corpse; } -// The creature-template / NPC entry ID packed into a creature or pet GUID -// (bits 24-47). Vanilla puts the per-spawn counter in the low 24 bits and the -// template entry above it. Returns 0 for any other GUID type (players, -// gameobjects, items, the 0 sentinel) and when the field itself is 0 — the -// engine never assigns entry 0, so 0 uniformly means "no creature template". -// Shared by `C_CreatureInfo.GetCreatureID` and `UnitCreatureID`. +// The creature-template entry packed into a CREATURE GUID (bits 24-47; the +// per-spawn counter is the low 24 bits). Returns 0 for every other GUID type +// and when the field itself is 0 — the engine never assigns entry 0, so 0 +// uniformly means "no creature template". Pet GUIDs (0xF140) deliberately +// return 0: on the (v)mangos family the pet's entry bits are the PET NUMBER +// (`Pet::Create` → `_Create(guidlow, pet_number, HIGHGUID_PET)`), not a +// template. This is only the OUT-OF-VIEW fallback — the server builds a +// creature GUID from its spawn row's first id and re-rolls the live template +// without touching the GUID, so prefer `Unit::CreatureID::ForGuid`, which +// reads the unit's live instance-block entry whenever the object is resolvable. uint32_t CreatureEntry(uint64_t guid); // Minimum buffer size for `FormatAsString`'s output — 16 hex digits + diff --git a/src/unit/CreatureID.cpp b/src/unit/CreatureID.cpp index c69f2979..f70fce94 100644 --- a/src/unit/CreatureID.cpp +++ b/src/unit/CreatureID.cpp @@ -11,26 +11,78 @@ // You should have received a copy of the GNU General Public License along with // ClassicAPI. If not, see . -// `UnitCreatureID(unit)` — the creature-template / NPC id for a unit token, -// or `nil`. The token version of `C_CreatureInfo.GetCreatureID(guid)`: it -// resolves the token to a GUID and reads the same entry field the GUID packs -// into bits 24-47. Equivalent to `C_CreatureInfo.GetCreatureID(UnitGUID(unit))` -// but without the round-trip. +// `Unit::CreatureID` — the creature-template / NPC id behind a unit, and the +// Lua `UnitCreatureID(unit)` (the token twin of `C_CreatureInfo.GetCreatureID`). // -// `nil` for: players (their GUID carries no template), an unresolvable-but- +// Three places carry an "entry", and on this server family they DISAGREE: +// +// - The unit's INSTANCE BLOCK entry (`[[unit + OFF_UNIT_GUID_PTR] + +// OFF_UNIT_INSTANCE_ENTRY]`) is the LIVE creature_template entry — the +// field the engine keys the creature NAME query on (`FUN_00604600` calls +// the creature cache with exactly this read, on creation and as the +// OBJECT-bank field-0xC handler). It is the `creature_template` primary +// key, hence also the id Wowhead / Turtle's database key NPC pages on. +// - The descriptor's OBJECT_FIELD_ENTRY slot reads 0 for creatures on this +// client (as it does for items — see the CGItem note in Offsets.h). A first +// version read it and silently fell back to the GUID bits. +// - The GUID's bits 24-47 are whatever the server put there at spawn. The +// (v)mangos family — tortoise verified — builds a creature GUID from the +// spawn row's FIRST id (`Creature::CreateFromProto` → +// `Object::_Create(guidlow, creature_id[0], …)`), then applies the rolled +// template through `UpdateEntry` → `SetEntry`. A `creature` row holds up +// to four ids (6,935 of Turtle's 79,773 rows use more than one) and a +// respawn re-rolls, so a mob whose name says template B can carry template +// A in its GUID: Turtle's Gordunni rows are {5236 Shaman, 5238 +// Battlemaster, 5239 Mage-Lord}, and a Gordunni Mage-Lord probes as +// block 5239 / GUID 5236 — "different names, same creature id" when read +// from the GUID. Pet GUIDs are worse: their entry bits are the PET NUMBER +// (`Pet::Create` → `_Create(guidlow, pet_number, HIGHGUID_PET)`), never a +// template. +// +// So the id is read from the instance block whenever the object is +// resolvable, and the GUID bits are only the out-of-view fallback for +// creature GUIDs (exact on every single-id spawn, i.e. all of stock vanilla). +// +// `UnitCreatureID` returns nil for players (entry 0), an unresolvable-but- // valid token (`target` with nothing targeted, an empty `partyN` slot), and -// any unit whose GUID isn't a creature or pet. Raises a Lua error on a -// missing / non-string `unit` argument or a garbage token — the standard -// `UnitX` "Unknown unit" behavior (via the token resolver). +// any non-creature / non-pet GUID. Raises a Lua error on a missing / +// non-string `unit` or a garbage token — the standard `UnitX` "Unknown unit" +// behavior (via the token resolver). #include "Game.h" +#include "Offsets.h" #include "guid/Guid.h" +#include "object/Resolve.h" +#include "unit/CreatureID.h" #include "unit/Identity.h" #include namespace Unit::CreatureID { +uint32_t ForObject(const void *unit) { + if (unit == nullptr) + return 0; + auto *block = Game::Read(unit, Offsets::OFF_UNIT_GUID_PTR); + if (block == nullptr) + return 0; + return Game::Read(block, Offsets::OFF_UNIT_INSTANCE_ENTRY); +} + +uint32_t ForGuid(uint64_t guid) { + const Guid::Type type = Guid::Classify(guid); + if (type != Guid::Type::Creature && type != Guid::Type::Pet) + return 0; + if (const void *unit = Object::ByGuid(Offsets::TYPEMASK_UNIT, guid)) { + const uint32_t entry = ForObject(unit); + if (entry != 0) + return entry; + } + // Out of view: only a creature GUID packs a template (a pet's packs the + // pet number → Guid::CreatureEntry yields 0 for it). + return Guid::CreatureEntry(guid); +} + namespace { int __fastcall Script_UnitCreatureID(void *L) { @@ -43,11 +95,9 @@ int __fastcall Script_UnitCreatureID(void *L) { return 0; // Token -> GUID (player fast-path, focus / nameplateN / markN, raw GUID), - // then the shared creature-entry extraction. A valid-but-empty token - // resolves to GUID 0 -> entry 0 -> nil; a player resolves to a player GUID - // -> entry 0 -> nil. - const uint32_t entryID = - Guid::CreatureEntry(Unit::Identity::GuidForToken(token)); + // then the shared block-first lookup. A valid-but-empty token resolves to + // GUID 0 -> 0 -> nil; a player resolves to a player GUID -> 0 -> nil. + const uint32_t entryID = ForGuid(Unit::Identity::GuidForToken(token)); if (entryID == 0) { Game::Lua::PushNil(L); return 1; diff --git a/src/unit/CreatureID.h b/src/unit/CreatureID.h new file mode 100644 index 00000000..3d3f5e43 --- /dev/null +++ b/src/unit/CreatureID.h @@ -0,0 +1,36 @@ +// This file is part of ClassicAPI. +// +// ClassicAPI is free software: you can redistribute it and/or modify it under the terms +// of the GNU General Public License as published by the Free Software Foundation, either +// version 3 of the License, or (at your option) any later version. +// +// ClassicAPI is distributed in the hope that it will be useful, but WITHOUT ANY +// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR +// PURPOSE. See the GNU General Public License for more details. +// +// You should have received a copy of the GNU General Public License along with +// ClassicAPI. If not, see . + +#pragma once + +#include + +// `Unit::CreatureID` — a unit's creature_template entry (the NPC id), read the +// way the engine reads it for the creature's NAME: the instance-block entry at +// `[[unit + OFF_UNIT_GUID_PTR] + OFF_UNIT_INSTANCE_ENTRY]`. See CreatureID.cpp +// for why the GUID's entry bits are only a fallback (and the descriptor slot +// is not usable at all). +namespace Unit::CreatureID { + +// The live template entry of a resolved CGUnit, or 0 for a null unit, a +// missing instance block, or a player (players carry entry 0). +uint32_t ForObject(const void *unit); + +// The creature id for a GUID: the live instance-block entry when the object is +// in the object table, else — for a CREATURE GUID only — the entry packed in +// the GUID (the spawn row's first template; exact whenever the spawn has one +// id). 0 for players and every non-unit GUID, and for a pet that is out of +// view (a pet GUID packs the pet number, not a template). +uint32_t ForGuid(uint64_t guid); + +} // namespace Unit::CreatureID