feat(unit): add UnitCreatureID(unit)

The unit-token twin of C_CreatureInfo.GetCreatureID — resolves the token
to a GUID and reads the creature-template entry vanilla packs into bits
24-47. nil for players, empty tokens, and non-creature/pet GUIDs.

Factor the entry extraction + creature/pet gate out of GetCreatureID into
a shared Guid::CreatureEntry so both callers use one source of truth for
the GUID bit layout.
This commit is contained in:
Brues
2026-08-18 14:44:06 -05:00
parent a373a775cf
commit 9b34ceff9e
6 changed files with 112 additions and 7 deletions
+1 -1
View File
@@ -72,7 +72,7 @@ Full per-function reference: **[docs/API.md](docs/API.md)**.
| [Totem](docs/API.md#totem) | `GetTotemInfo`, `GetTotemTimeLeft`, `GetTotemDuration`, `TargetTotem` |
| [TradeSkillUI](docs/API.md#tradeskillui) | `C_TradeSkillUI.GetTradeSkillListLink`, `C_TradeSkillUI.GetCraftListLink`, `C_TradeSkillUI.GetTradeSkillListRecipes` |
| [UIColor](docs/API.md#uicolor) | `C_UIColor.GetColors` |
| [Unit](docs/API.md#unit) | `ClosestUnitPosition`, `GetUnitSpeed`, `UnitClassBase`, `UnitCreatureFamilyID`, `UnitCreatureTypeID`, `UnitDistanceSquared`, `UnitGUID`, `UnitHealthMissing`, `UnitInLineOfSight`, `UnitInRange`, `UnitIsAFK`, `UnitIsDND`, `UnitIsFeignDeath`, `UnitIsInMyGuild`, `UnitIsMinion`, `UnitIsOtherPlayersPet`, `UnitIsPet`, `UnitIsPossessed`, `UnitOwnerGUID`, `UnitPosition`, `UnitPower`, `UnitPowerMax`, `UnitPowerMissing`, `UnitPowerType`, `UnitRaceBase`, `UnitSpellHaste`, `UnitSpellTargetName`, `UnitStandState`, `UnitSubName`, `UnitTokenFromGUID` |
| [Unit](docs/API.md#unit) | `ClosestUnitPosition`, `GetUnitSpeed`, `UnitClassBase`, `UnitCreatureFamilyID`, `UnitCreatureID`, `UnitCreatureTypeID`, `UnitDistanceSquared`, `UnitGUID`, `UnitHealthMissing`, `UnitInLineOfSight`, `UnitInRange`, `UnitIsAFK`, `UnitIsDND`, `UnitIsFeignDeath`, `UnitIsInMyGuild`, `UnitIsMinion`, `UnitIsOtherPlayersPet`, `UnitIsPet`, `UnitIsPossessed`, `UnitOwnerGUID`, `UnitPosition`, `UnitPower`, `UnitPowerMax`, `UnitPowerMissing`, `UnitPowerType`, `UnitRaceBase`, `UnitSpellHaste`, `UnitSpellTargetName`, `UnitStandState`, `UnitSubName`, `UnitTokenFromGUID` |
| [UnitAuras](docs/API.md#unitauras) | `C_UnitAuras.GetAuraDataByIndex`, `C_UnitAuras.GetAuraDataBySpellName`, `C_UnitAuras.GetAuraDispelTypeColor`, `C_UnitAuras.GetBuffDataByIndex`, `C_UnitAuras.GetDebuffDataByIndex`, `C_UnitAuras.GetPlayerAuraBySpellID`, `C_UnitAuras.GetUnitAuraBySpellID`, `C_UnitAuras.GetUnitAuras`, `C_UnitAuras.RegisterAuraDurationModifierByTrigger`, `C_UnitAuras.RegisterComboDuration` |
| [VoiceChat](docs/API.md#voicechat) | `C_VoiceChat.GetTtsVoices`, `C_VoiceChat.GetRemoteTtsVoices`, `C_VoiceChat.SpeakText`, `C_VoiceChat.StopSpeakingText`, `C_TTSSettings.GetSpeechRate`, `C_TTSSettings.GetSpeechVolume`, `C_TTSSettings.GetSpeechVoiceID`, `C_TTSSettings.GetVoiceOptionName`, `C_TTSSettings.SetSpeechRate`, `C_TTSSettings.SetSpeechVolume`, `C_TTSSettings.SetVoiceOption`, `C_TTSSettings.SetVoiceOptionByName`, `C_TTSSettings.SetDefaultSettings`, `C_TTSSettings.RefreshVoices` |
| [XMLUtil](docs/API.md#xmlutil) | `C_XMLUtil.DoesTemplateExist`, `C_XMLUtil.GetTemplateInfo`, `C_XMLUtil.GetTemplates` |
+26
View File
@@ -557,6 +557,7 @@ build instructions.
- [`UnitSubName(unit)`](#unitsubnameunit)
- [`UnitCreatureFamilyID(unit)`](#unitcreaturefamilyidunit)
- [`UnitCreatureTypeID(unit)`](#unitcreaturetypeidunit)
- [`UnitCreatureID(unit)`](#unitcreatureidunit)
- [`GetUnitSpeed(unit)`](#getunitspeedunit)
- [`UnitClassBase(unit)`](#unitclassbaseunit)
- [`UnitRaceBase(unit)`](#unitracebaseunit)
@@ -13530,6 +13531,31 @@ resolver the engine's `UnitCreatureType` uses, which handles every unit kind
[`C_CreatureInfo.GetCreatureTypeInfo`](#c_creatureinfogetcreaturetypeinfocreaturetypeid)
to get the localized name back from the id.
### `UnitCreatureID(unit)`
Returns the numeric **creature id** — the NPC / creature-template entry — for a
unit, or `nil`. This is the unit-token twin of
[`C_CreatureInfo.GetCreatureID`](#c_creatureinfogetcreatureidguid): it does
`C_CreatureInfo.GetCreatureID(UnitGUID(unit))` for you.
```
creatureID = UnitCreatureID(unit)
```
```lua
/dump UnitCreatureID("target") -- 1842 for Hogger, nil for a player
/dump UnitCreatureID("pet") -- your pet's creature-template id
```
Vanilla packs the entry id 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
[`C_CreatureInfo.GetCreatureInfoByID`](#c_creatureinfogetcreatureinfobyidcreatureid)
to get the name from the id.
### `GetUnitSpeed(unit)`
Returns `currentSpeed, runSpeed, flightSpeed, swimSpeed` — all four
+3 -6
View File
@@ -46,12 +46,9 @@ int __fastcall Script_GetCreatureID(void *L) {
Game::Lua::PushNil(L);
return 1;
}
const Type type = Classify(guid);
if (type != Type::Creature && type != Type::Pet) {
Game::Lua::PushNil(L);
return 1;
}
const uint32_t entryID = static_cast<uint32_t>((guid >> 24) & 0xFFFFFFu);
// `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);
if (entryID == 0) {
Game::Lua::PushNil(L);
return 1;
+7
View File
@@ -51,6 +51,13 @@ const char *FormatAsString(uint64_t guid, char *buf, std::size_t cap) {
return buf;
}
uint32_t CreatureEntry(uint64_t guid) {
const Type type = Classify(guid);
if (type != Type::Creature && type != Type::Pet)
return 0;
return static_cast<uint32_t>((guid >> 24) & 0xFFFFFFu);
}
Type Classify(uint64_t guid) {
if (guid == 0)
return Type::Unknown;
+8
View File
@@ -76,6 +76,14 @@ 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`.
uint32_t CreatureEntry(uint64_t guid);
// Minimum buffer size for `FormatAsString`'s output — 16 hex digits +
// the `"0x"` prefix + a NUL terminator.
constexpr std::size_t STRING_SIZE = 19;
+67
View File
@@ -0,0 +1,67 @@
// 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 <https://www.gnu.org/licenses/>.
// `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.
//
// `nil` for: players (their 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
// missing / non-string `unit` argument or a garbage token — the standard
// `UnitX` "Unknown unit" behavior (via the token resolver).
#include "Game.h"
#include "guid/Guid.h"
#include "unit/Identity.h"
#include <cstdint>
namespace Unit::CreatureID {
namespace {
int __fastcall Script_UnitCreatureID(void *L) {
if (!Game::Lua::IsString(L, 1)) {
Game::Lua::Error(L, "Usage: UnitCreatureID(\"unit\")");
return 0;
}
const char *token = Game::Lua::ToString(L, 1);
if (token == nullptr)
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));
if (entryID == 0) {
Game::Lua::PushNil(L);
return 1;
}
Game::Lua::PushNumber(L, static_cast<double>(entryID));
return 1;
}
void RegisterLuaFunctions() {
Game::Lua::RegisterGlobalFunction("UnitCreatureID", &Script_UnitCreatureID);
}
const Game::ModuleAutoRegister _autoreg{&RegisterLuaFunctions};
} // namespace
} // namespace Unit::CreatureID