WoW API: UnitGUID
Returns the GUID of the unit specified. Works on both players and NPC.
UnitGUID("unit")
What does it all mean?
The GUID is a unique hexadecimal string for each unit in the game. Just how unique are they? Slouken[1] has this to say on it:
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.
The strings always begin with '0x', which is the normal prefix for hexadecimal numbers. The '0x' prefix isn't actually part of the ID number, it's just to say "this is a hex string."
Determine if it's a player, pet or NPC
- It's a player if the upper bits masked with 0x00f = 0x000
- It's a creature if the upper bits masked with 0x00f = 0x003
- It's a pet if the upper bits masked with 0x00f = 0x004
- It's a vehicle (carries others) if the upper bits masked with 0x00f = 0x005
Since, as explained below, attempting to convert a GUID to a number in Lua results in garbage, it may be easier to use substrings than actually converting to a number and masking, as in this example:
myGUID = "0xF530004D2B008852" -- the example used below myUnitType = myGUID:sub(5,5)
The value you get will be either 0, 3, 4, or 5 corresponding to players, creatures, pets and vehicles respectively.
Format for players
- The GUID is a simple number in the order characters are created. An older character has a lower number than a new.
The top three digits are reserved. It's unknown if any of the lower digits are also reserved.
Renaming and transfering to another server, or to another account gives your character a new GUID. Player GUIDs remain unique in cross-realm battlegroups [2].
Format for non-pet NPCs
- The first three characters masked with 0x00f will result in 0x003.
- The next three digits are unknown. It's usually '000'.
- The next four digits are the NPC id.
- The last six digits are the spawn counter.
If you take the 'NPC id' and convert it to decimal you can check wowhead and see what NPC it is. See examples below.
Format for pets
- The first three characters masked with 0x00f will result in 0x004.
- The next seven digits are the pet id (a counter like players based on the order of creation).
- The last six digits are the spawn counter.
You must log out before the pet gets this GUID. If queried during the same session that you tamed it, your pet will have its pre-taming GUID.
Spawn counter
Spawn counter is a unique number given all non-player mobs. It's a simple incremental number, instances and outside world are probably handled differently. The number in itself is not relevant, but combined with the rest of the string it always give this exact mob a unique identifier.
An example of a GUID
We have a GUID: "0xF530004D2B008852".
First of all, let's find out what kind of unit it is. Take the first three digits in the GUID, ie "F53" (or 0xF53 to show it's an hex value) and apply an AND mask of 0x00F.
0xF53 & 0x00F = 0x003
This GUID is for a normal NPC, not a pet and not a player.
We can also extract the Unit ID by taking the sixth to tenth digit and converting it to decimal form: "4D2B", or converted to decimal form "19755". A quick visit to wowhead shows that the NPC with that id is "Mo'arg Weaponsmith", [3]. All "Mo'arg Weaponsmiths" will have that id to identify them.
The last six digits, "008852" is the spawn counter. There will never be two "Mo'arg Weaponsmith", possible even never two mobs in the outside world, with the same spawn number. This spawn counter, combined with the rest makes it possible to always refer to exactly this "Mo'arg Weaponsmith", and not the one next to it.
Cross-server and GUID "uniqueness"
Player GUIDs are local on a per-server basis, making the "global" scope to be bound to the specific server. Every time a character is created, a new GUID is assigned from a simple +1 counter and then given to that character. 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.
Uniqueness is guaranteed in cross-realm battlegrounds by masking the player GUID with a server specific unique identifier, when needed.
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.
Returns
- GUID
- Returns the unit GUID in hexdecimal.
Example
local name = UnitName("target"); local guid = UnitGUID("target"); ChatFrame1:AddMessage(name.." has the GUID: "..guid);
Result
Cyan has the GUID: 0x00000000012729FD
Conversion to decimal?
GUIDs are 64-bit numbers, and are far too long to convert to decimal numbers using lua's libraries as a whole. E.g. running tonumber(guid, 16) will produce erronous results.