m (→GUID Types: link to api category) Tag: WoW API docs |
EithrisBot (talk | contribs) (→Cast: bot edit) Tag: WoW API docs |
||
(26 intermediate revisions by 5 users not shown) | |||
Line 1: | Line 1: | ||
− | {{wowapitype}} |
+ | {{wowapitype|t=t}} |
GUIDs uniquely identify almost everything the player character can interact with in World of Warcraft -- including players, pets, vehicle, and interactive world objects (think [[Midsummer Fire Festival|Midsummer bonfires]]). GUIDs are represented in WoW as a long string of hex numbers separated by hyphens. |
GUIDs uniquely identify almost everything the player character can interact with in World of Warcraft -- including players, pets, vehicle, and interactive world objects (think [[Midsummer Fire Festival|Midsummer bonfires]]). GUIDs are represented in WoW as a long string of hex numbers separated by hyphens. |
||
__TOC__ |
__TOC__ |
||
Line 11: | Line 11: | ||
* However, units that "transform" into other units may not switch GUID immediately. |
* However, units that "transform" into other units may not switch GUID immediately. |
||
− | == |
+ | ==Types== |
===BattlePet=== |
===BattlePet=== |
||
* GUIDs for [[World_of_Warcraft_API#Pet_Journal|Battle Pets]], also referred to sometimes as <code>petID</code>. ''(Not to be confused with [[BattlePetSpeciesID|speciesID]])'' |
* GUIDs for [[World_of_Warcraft_API#Pet_Journal|Battle Pets]], also referred to sometimes as <code>petID</code>. ''(Not to be confused with [[BattlePetSpeciesID|speciesID]])'' |
||
BattlePet-0-[ID] |
BattlePet-0-[ID] |
||
Prints the currently active companion pet. |
Prints the currently active companion pet. |
||
− | + | <syntaxhighlight lang="lua"> |
|
/dump C_PetJournal.GetSummonedPetGUID() |
/dump C_PetJournal.GetSummonedPetGUID() |
||
> "BattlePet-0-00000338F951" |
> "BattlePet-0-00000338F951" |
||
Line 24: | Line 24: | ||
* GUIDs for Battle.net accounts are returned from {{api|C_Club.GetMemberInfo}}() or {{api|C_VoiceChat.GetMemberGUID}}() |
* GUIDs for Battle.net accounts are returned from {{api|C_Club.GetMemberInfo}}() or {{api|C_VoiceChat.GetMemberGUID}}() |
||
BNetAccount-0-[accountID] |
BNetAccount-0-[accountID] |
||
− | + | <syntaxhighlight lang="lua"> |
|
local playerAccountGUID = string.format("BNetAccount-0-%012X", (BNGetNumFriends() + 1)); |
local playerAccountGUID = string.format("BNetAccount-0-%012X", (BNGetNumFriends() + 1)); |
||
local isBattleNetGUID = C_AccountInfo.IsGUIDBattleNetAccountType(playerAccountGUID); |
local isBattleNetGUID = C_AccountInfo.IsGUIDBattleNetAccountType(playerAccountGUID); |
||
Line 40: | Line 40: | ||
The <code>type</code> parameter has the following known variants. |
The <code>type</code> parameter has the following known variants. |
||
− | {| class="sortable darktable zebra" style="margin-left: 2em" |
+ | {| class="sortable darktable zebra col1-center" style="margin-left: 2em" |
− | |- |
||
! Type !! Description !! Example |
! Type !! Description !! Example |
||
|- |
|- |
||
− | + | | 2 || Represents a spell cast that only exists locally on the client, typically for casts that have failed due to requirements not being met. || <code>Cast-2-0-0-0-116-000000017D</code> |
|
|- |
|- |
||
− | + | | 3 || Represents a spell cast for an active ability, such as [[Frostbolt]]. Most spell casts will be of this type. || <code>Cast-3-4170-0-8-84714-000CB03025</code> |
|
|- |
|- |
||
− | + | | 4 || Represents a spell cast for a passive effect. These appear to be fairly rare, but may be seen on initial login. || <code>Cast-4-4170-0-11-197886-0000302E85</code> |
|
|- |
|- |
||
− | + | | 13 || Represents a single tick from spells such as [[Divine Hymn]] and [[Spinning Crane Kick]]. ||<code>Cast-13-4170-1643-17-64844-0004B03416</code> |
|
|- |
|- |
||
− | + | | 16 || Represents a single tick from spells such as [[Flurry]] and [[Fists of Fury]]. || <code>Cast-16-2083-0-20-228354-0000307226</code> |
|
|} |
|} |
||
Line 58: | Line 57: | ||
For all other known spell cast types, the cast UID component is similar to Creature and Vehicle GUIDs; the lowest 23 bits represent the timestamp of the cast measured in seconds since the UNIX epoch as returned by {{api|GetServerTime}}() modulo <code>2^23</code>, and the higher bits appear to be an incrementing number for spell casts that occur within the same second. |
For all other known spell cast types, the cast UID component is similar to Creature and Vehicle GUIDs; the lowest 23 bits represent the timestamp of the cast measured in seconds since the UNIX epoch as returned by {{api|GetServerTime}}() modulo <code>2^23</code>, and the higher bits appear to be an incrementing number for spell casts that occur within the same second. |
||
+ | |||
+ | ===ClientActor=== |
||
+ | ClientActors are NPCs which are only simulated by the game client instead of the server. |
||
+ | ClientActor-x-yy-zzzz |
||
⚫ | |||
⚫ | |||
+ | > "Unleashed Hatred", "ClientActor-3-5-1340" |
||
⚫ | |||
===Creature=== |
===Creature=== |
||
− | * Types: <code>"Creature", "Pet", "GameObject", "Vehicle |
+ | * Types: <code>"Creature", "Pet", "GameObject", "Vehicle"</code> |
[unitType]-0-[serverID]-[instanceID]-[zoneUID]-[ID]-[spawnUID] |
[unitType]-0-[serverID]-[instanceID]-[zoneUID]-[ID]-[spawnUID] |
||
+ | <syntaxhighlight lang="lua"> |
||
− | Prints the guid and name of the unit. |
||
+ | /dump UnitName("target"), UnitGUID("target") |
||
⚫ | |||
⚫ | |||
⚫ | |||
⚫ | |||
</syntaxhighlight> |
</syntaxhighlight> |
||
+ | <syntaxhighlight lang="lua"> |
||
+ | local npcID = select(6, strsplit("-", UnitGUID("target"))) |
||
+ | print(npcID, tonumber(npcID)) |
||
+ | > "448", 448 |
||
+ | </syntaxhighlight> |
||
+ | |||
+ | GameObject GUIDs can be obtained by querying the "npc" unit token when interacting with an object such as a Mailbox, or from the {{api|GetLootSourceInfo}}() API when looting resources gathered from herbalism or mining nodes. |
||
+ | |||
+ | ====Spawn UIDs==== |
||
− | For Creature and Vehicle GUIDs the <code>spawnUID</code> component encodes a wrapping spawn time offset of the entity in the low 23 bits of the field, measured in seconds since the UNIX epoch as returned by {{api|GetServerTime}}() modulo <code>2^23</code>. Higher bits appear to be a unique counter for individual spawns within the same time unit. |
+ | For Creature, GameObject, and Vehicle GUIDs the <code>spawnUID</code> component encodes a wrapping spawn time offset of the entity in the low 23 bits of the field, measured in seconds since the UNIX epoch as returned by {{api|GetServerTime}}() modulo <code>2^23</code>. Higher bits appear to be a unique counter for individual spawns within the same time unit. |
− | + | <syntaxhighlight lang="lua"> |
|
local guid = UnitGUID("target") |
local guid = UnitGUID("target") |
||
local unitType, _, _, _, _, _, spawnUID = strsplit("-", guid) |
local unitType, _, _, _, _, _, spawnUID = strsplit("-", guid) |
||
Line 97: | Line 112: | ||
For Pet GUIDs the <code>spawnUID</code> component encodes a unique identifier in the low 32 bits, similar to Player GUIDs, and a wrapping counter in the upper 8 bits representing the number of times the pet has been summoned. |
For Pet GUIDs the <code>spawnUID</code> component encodes a unique identifier in the low 32 bits, similar to Player GUIDs, and a wrapping counter in the upper 8 bits representing the number of times the pet has been summoned. |
||
− | + | <syntaxhighlight lang="lua"> |
|
local guid = UnitGUID("target") |
local guid = UnitGUID("target") |
||
local unitType, _, _, _, _, _, spawnUID = strsplit("-", guid) |
local unitType, _, _, _, _, _, spawnUID = strsplit("-", guid) |
||
Line 113: | Line 128: | ||
> "Unique Pet ID:", "02F859E9" |
> "Unique Pet ID:", "02F859E9" |
||
> "Spawn index:", 2 |
> "Spawn index:", 2 |
||
+ | </syntaxhighlight> |
||
+ | |||
+ | ===Follower=== |
||
+ | * GUIDs for [[Garrison followers]] are e.g. returned from {{api|C_Garrison.GetFollowers}}() |
||
+ | |||
+ | <syntaxhighlight lang="lua"> |
||
+ | local followers = C_Garrison.GetFollowers() |
||
+ | print(followers[1].name, followers[1].followerID) |
||
+ | > "Calia Menethil", "0x0000000004CBDB61" |
||
</syntaxhighlight> |
</syntaxhighlight> |
||
===Item=== |
===Item=== |
||
− | * GUIDs for items are returned from {{api|C_Item.GetItemGUID}} |
+ | * GUIDs for items are returned from {{api|C_Item.GetItemGUID}}, [[ItemMixin|ItemMixin:GetItemGUID]] and {{api|GetLootSourceInfo}}. ''(Not to be confused with [[ItemLink|ItemID]]s)'' |
Item-[serverID]-0-[spawnUID] |
Item-[serverID]-0-[spawnUID] |
||
Prints the GUID of the item in the player's head slot. |
Prints the GUID of the item in the player's head slot. |
||
− | + | <syntaxhighlight lang="lua"> |
|
local itemLoc = ItemLocation:CreateFromEquipmentSlot(INVSLOT_HEAD) |
local itemLoc = ItemLocation:CreateFromEquipmentSlot(INVSLOT_HEAD) |
||
local item = Item:CreateFromItemLocation(itemLoc) |
local item = Item:CreateFromItemLocation(itemLoc) |
||
Line 130: | Line 154: | ||
* GUIDs for [[UnitId|Units]] are returned from {{api|UnitGUID}}() |
* GUIDs for [[UnitId|Units]] are returned from {{api|UnitGUID}}() |
||
Player-[serverID]-[playerUID] |
Player-[serverID]-[playerUID] |
||
+ | <syntaxhighlight lang="lua"> |
||
− | Prints the GUID of the player. |
||
⚫ | |||
/dump UnitGUID("player") |
/dump UnitGUID("player") |
||
> "Player-970-0002FD64" |
> "Player-970-0002FD64" |
||
</syntaxhighlight> |
</syntaxhighlight> |
||
⚫ | It should be noted that the act of transferring characters, either server to server, account to account, or even account to account while remaining on the same server will generate a new character GUID, because of how the process works (the character "ceases to exist" for a short period, and is then recreated). This act erases friend and ignore lists. Renaming a character does not trigger a new GUID, as that process is much simpler than a full character move. |
||
− | ==Cross-server and GUID "uniqueness"== |
||
⚫ | |||
+ | ===Vignette=== |
||
− | Uniqueness is guaranteed in cross-realm battlegrounds by masking the player GUID with a server specific unique identifier, when needed. |
||
+ | [[Vignette]]s are used for one-time rare mobs and treasure chests, see also {{api|C_VignetteInfo.GetVignetteInfo}}() |
||
− | |||
+ | Vignette-0-[serverID]-[instanceID]-[zoneUID]-0-[spawnUID] |
||
− | NPC GUID collisions have also been observed. It is unknown why or when in specific they occur, but differing mob types have had a NPC ID number which corresponded to an entirely different NPC. This is considered a very rare phenomenon. |
||
+ | <syntaxhighlight lang="lua"> |
||
+ | "Vignette-0-970-1116-7-0-0017CAE465" -- for rare mob Sulfurious |
||
+ | </syntaxhighlight> |
||
==Patch changes== |
==Patch changes== |
||
− | * {{Patch 6.0.2|note= |
+ | * {{Patch 6.0.2|note=Changed to a new format, e.g. for players: <code>Player-[serverID]-[playerUID]</code>}} |
− | ** For players: Player-[server ID]-[player UID] (Example: "Player-976-0002FD64") |
||
− | ** For creatures, pets, objects, and vehicles: [Unit type]-0-[server ID]-[instance ID]-[zone UID]-[ID]-[Spawn UID] (Example: "Creature-0-976-0-11-31146-000136DF91") |
||
− | ** Unit Type Names: "Creature", "Pet", "GameObject", and "Vehicle" |
||
− | ** For vignettes: Vignette-0-[server ID]-[instance ID]-[zone UID]-0-[spawn UID] (Example: "Vignette-0-970-1116-7-0-0017CAE465" for rare mob Sulfurious)}} |
||
* {{Patch 5.1.0|note=Bits shifted. NPCID is now characters 6-9, not 7-10 (counting from 1).}} |
* {{Patch 5.1.0|note=Bits shifted. NPCID is now characters 6-9, not 7-10 (counting from 1).}} |
||
* {{Patch 4.0.1|note=Bits shifted. NPCID is now characters 5-8, not 7-10 (counting from 1).}} |
* {{Patch 4.0.1|note=Bits shifted. NPCID is now characters 5-8, not 7-10 (counting from 1).}} |
||
* {{Patch 3.3.0|note=Bits shifted. NPCID is now characters 7-10, not 6-9 (counting from 1).}} |
* {{Patch 3.3.0|note=Bits shifted. NPCID is now characters 7-10, not 6-9 (counting from 1).}} |
||
− | * {{Patch 2.4.0|note=Added |
+ | * {{Patch 2.4.0|note=Added, an example of the old format is <code>"0xF130C3030000037F2"</code>}} |
==References== |
==References== |
Latest revision as of 00:56, 12 March 2023
GUIDs uniquely identify almost everything the player character can interact with in World of Warcraft -- including players, pets, vehicle, and interactive world objects (think Midsummer bonfires). GUIDs are represented in WoW as a long string of hex numbers separated by hyphens.
Details
GUIDs are intended to provide a unique way to identify units; the following general rules apply:
- A monster has a single GUID from spawn until death (or despawn). When it respawns it gets a new GUID.
- Pets get a new GUID each time they are summoned.
- Monster and pet GUIDs can be recycled after server (or instance) restart.
- Players keep their GUID forever, and are unique even in cross-server battlegrounds.
- However, units that "transform" into other units may not switch GUID immediately.
Types
BattlePet
- GUIDs for Battle Pets, also referred to sometimes as
petID
. (Not to be confused with speciesID)
BattlePet-0-[ID]
Prints the currently active companion pet.
/dump C_PetJournal.GetSummonedPetGUID()
> "BattlePet-0-00000338F951"
BNetAccount
- GUIDs for Battle.net accounts are returned from C_Club.GetMemberInfo() or C_VoiceChat.GetMemberGUID()
BNetAccount-0-[accountID]
local playerAccountGUID = string.format("BNetAccount-0-%012X", (BNGetNumFriends() + 1));
local isBattleNetGUID = C_AccountInfo.IsGUIDBattleNetAccountType(playerAccountGUID);
local isLocalPlayerGUID = C_AccountInfo.IsGUIDRelatedToLocalAccount(playerAccountGUID);
print(playerAccountGUID, isBattleNetGUID, isLocalPlayerGUID);
> "BNetAccount-0-000000000016", true, true
The accountID
portion of the GUID is, at least for friend accounts, a hexadecimal form of the Battle.net account ID as used by C_BattleNet.GetAccountInfoByID()
Cast
- GUIDs for spell casts are obtained from spell cast events or as a return value from UnitCastingInfo()
Cast-[type]-[serverID]-[instanceID]-[zoneUID]-[spellID]-[castUID]
The type
parameter has the following known variants.
Type | Description | Example |
---|---|---|
2 | Represents a spell cast that only exists locally on the client, typically for casts that have failed due to requirements not being met. | Cast-2-0-0-0-116-000000017D
|
3 | Represents a spell cast for an active ability, such as [Frostbolt]. Most spell casts will be of this type. | Cast-3-4170-0-8-84714-000CB03025
|
4 | Represents a spell cast for a passive effect. These appear to be fairly rare, but may be seen on initial login. | Cast-4-4170-0-11-197886-0000302E85
|
13 | Represents a single tick from spells such as [Divine Hymn] and [Spinning Crane Kick]. | Cast-13-4170-1643-17-64844-0004B03416
|
16 | Represents a single tick from spells such as [Flurry] and [Fists of Fury]. | Cast-16-2083-0-20-228354-0000307226
|
For local spell casts, the server, instance, and zone ID components will always be zero, and the cast UID will be a locally-incrementing integer.
For all other known spell cast types, the cast UID component is similar to Creature and Vehicle GUIDs; the lowest 23 bits represent the timestamp of the cast measured in seconds since the UNIX epoch as returned by GetServerTime() modulo 2^23
, and the higher bits appear to be an incrementing number for spell casts that occur within the same second.
ClientActor
ClientActors are NPCs which are only simulated by the game client instead of the server.
ClientActor-x-yy-zzzz
/dump UnitName("target"), UnitGUID("target")
> "Unleashed Hatred", "ClientActor-3-5-1340"
Creature
- Types:
"Creature", "Pet", "GameObject", "Vehicle"
[unitType]-0-[serverID]-[instanceID]-[zoneUID]-[ID]-[spawnUID]
/dump UnitName("target"), UnitGUID("target")
> "Hogger", "Creature-0-1465-0-2105-448-000043F59F"
local npcID = select(6, strsplit("-", UnitGUID("target")))
print(npcID, tonumber(npcID))
> "448", 448
GameObject GUIDs can be obtained by querying the "npc" unit token when interacting with an object such as a Mailbox, or from the GetLootSourceInfo() API when looting resources gathered from herbalism or mining nodes.
Spawn UIDs
For Creature, GameObject, and Vehicle GUIDs the spawnUID
component encodes a wrapping spawn time offset of the entity in the low 23 bits of the field, measured in seconds since the UNIX epoch as returned by GetServerTime() modulo 2^23
. Higher bits appear to be a unique counter for individual spawns within the same time unit.
local guid = UnitGUID("target")
local unitType, _, _, _, _, _, spawnUID = strsplit("-", guid)
if unitType == "Creature" or unitType == "Vehicle" then
local spawnEpoch = GetServerTime() - (GetServerTime() % 2^23)
local spawnEpochOffset = bit.band(tonumber(string.sub(spawnUID, 5), 16), 0x7fffff)
local spawnIndex = bit.rshift(bit.band(tonumber(string.sub(spawnUID, 1, 5), 16), 0xffff8), 3)
local spawnTime = spawnEpoch + spawnEpochOffset
if spawnTime > GetServerTime() then
-- This only occurs if the epoch has rolled over since a unit has spawned.
spawnTime = spawnTime - ((2^23) - 1)
end
print(guid)
print("Spawned at:", date("%Y-%m-%d %H:%M:%S", spawnTime))
print("Spawn index:", spawnIndex)
end
> "Creature-0-4170-0-41-68662-00000F4B37"
> "Spawned at:", "2021-01-25 22:50:31"
> "Spawn index:", 0
For Pet GUIDs the spawnUID
component encodes a unique identifier in the low 32 bits, similar to Player GUIDs, and a wrapping counter in the upper 8 bits representing the number of times the pet has been summoned.
local guid = UnitGUID("target")
local unitType, _, _, _, _, _, spawnUID = strsplit("-", guid)
if unitType == "Pet" then
local petUID = string.sub(spawnUID, 3)
local spawnIndex = tonumber(string.sub(spawnUID, 1, 2), 16)
print(guid)
print("Unique Pet ID:", petUID)
print("Spawn index:", spawnIndex)
end
> "Pet-0-4234-0-6610-165189-0202F859E9"
> "Unique Pet ID:", "02F859E9"
> "Spawn index:", 2
Follower
- GUIDs for Garrison followers are e.g. returned from C_Garrison.GetFollowers()
local followers = C_Garrison.GetFollowers()
print(followers[1].name, followers[1].followerID)
> "Calia Menethil", "0x0000000004CBDB61"
Item
- GUIDs for items are returned from C_Item.GetItemGUID, ItemMixin:GetItemGUID and GetLootSourceInfo. (Not to be confused with ItemIDs)
Item-[serverID]-0-[spawnUID]
Prints the GUID of the item in the player's head slot.
local itemLoc = ItemLocation:CreateFromEquipmentSlot(INVSLOT_HEAD)
local item = Item:CreateFromItemLocation(itemLoc)
print(item:GetItemGUID())
> "Item-1598-0-4000000A369860E1"
Player
Player-[serverID]-[playerUID]
/dump UnitGUID("player")
> "Player-970-0002FD64"
It should be noted that the act of transferring characters, either server to server, account to account, or even account to account while remaining on the same server will generate a new character GUID, because of how the process works (the character "ceases to exist" for a short period, and is then recreated). This act erases friend and ignore lists. Renaming a character does not trigger a new GUID, as that process is much simpler than a full character move.
Vignette
Vignettes are used for one-time rare mobs and treasure chests, see also C_VignetteInfo.GetVignetteInfo()
Vignette-0-[serverID]-[instanceID]-[zoneUID]-0-[spawnUID]
"Vignette-0-970-1116-7-0-0017CAE465" -- for rare mob Sulfurious
Patch changes
- Patch 6.0.2 (2014-10-14): Changed to a new format, e.g. for players:
Player-[serverID]-[playerUID]
- Patch 5.1.0 (2012-11-27): Bits shifted. NPCID is now characters 6-9, not 7-10 (counting from 1).
- Patch 4.0.1 (2010-10-12): Bits shifted. NPCID is now characters 5-8, not 7-10 (counting from 1).
- Patch 3.3.0 (2009-12-08): Bits shifted. NPCID is now characters 7-10, not 6-9 (counting from 1).
- Patch 2.4.0 (2008-03-25): Added, an example of the old format is
"0xF130C3030000037F2"
References
- p3lim 2014-07-20. Data Changes in WoD.
- Meorawr 2021-01-25. Creature Spawn UID Inspection.