diff --git a/README.md b/README.md index fb178c4c..beb804dc 100644 --- a/README.md +++ b/README.md @@ -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` | diff --git a/docs/API.md b/docs/API.md index b7349368..00ae3bb2 100644 --- a/docs/API.md +++ b/docs/API.md @@ -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 diff --git a/src/guid/CreatureInfo.cpp b/src/guid/CreatureInfo.cpp index 858f77e1..6b35ea11 100644 --- a/src/guid/CreatureInfo.cpp +++ b/src/guid/CreatureInfo.cpp @@ -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((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; diff --git a/src/guid/Guid.cpp b/src/guid/Guid.cpp index 2c34f459..a3d23b31 100644 --- a/src/guid/Guid.cpp +++ b/src/guid/Guid.cpp @@ -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((guid >> 24) & 0xFFFFFFu); +} + Type Classify(uint64_t guid) { if (guid == 0) return Type::Unknown; diff --git a/src/guid/Guid.h b/src/guid/Guid.h index 4ec70a12..07d62dad 100644 --- a/src/guid/Guid.h +++ b/src/guid/Guid.h @@ -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; diff --git a/src/unit/CreatureID.cpp b/src/unit/CreatureID.cpp new file mode 100644 index 00000000..c69f2979 --- /dev/null +++ b/src/unit/CreatureID.cpp @@ -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 . + +// `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 + +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(entryID)); + return 1; +} + +void RegisterLuaFunctions() { + Game::Lua::RegisterGlobalFunction("UnitCreatureID", &Script_UnitCreatureID); +} + +const Game::ModuleAutoRegister _autoreg{&RegisterLuaFunctions}; + +} // namespace + +} // namespace Unit::CreatureID