Last Updated: 2009-01-31 for 1.0.14-alpha

Getting Started with LibUnitID

LibUnitID is framework-independent; its only dependency is LibStub, so you'll start by getting a handle for the library. For alpha builds, you'll need:

local libunitid = LibStub("LibUnitID-1.0-alpha")

while beta and release builds will be available as:

local libunitid = LibStub("LibUnitID-1.0")

This separation ensures that your addon or library can embed a stable version of LibUnitID, and not worry about some other addon replacing it with a potentially unstable alpha build. If you want the latest version no matter what, you can use something like:

local libunitid = LibStub("LibUnitID-1.0-alpha",true) or LibStub("LibUnitID-1.0")

Event Registration

Before LibUnitID can inform you about changes to unit identities, you need to tell it what you want it to keep track of. This is done by registering your callback function in one of three ways, depending on how the callback is defined:

local function mycallback(event, delta) ... end
libunitid:RegisterUnit("targettarget", mycallback)

or

function myhandler:mycallback(event, delta) ... end
libunitid:RegisterUnit("targettarget", myhandler.mycallback, myhandler)

or

function myhandler:mycallback(event, delta) ... end
libunitid:RegisterUnit("targettarget", "mycallback", myhandler)

LibUnitID will now call mycallback whenever the identity of the "targettarget" UnitID changes. This might be in response to UNIT_TARGET for "target", or it might be a side effect of PLAYER_TARGET_CHANGED, but your callback doesn't have to worry about that -- whenever it runs, it's because "targettarget" now refers to something else, for whatever reason. More details on callbacks are below. The myhandler argument is optional. If provided, then it will be passed as the first argument to your callback, which is primarily useful for callbacks which are methods and need their base table provided as "self" (as in the example). When a handler is provided, then the callback may be given as a string; in this case it will be looked up on the handler table whenever it is called. RegisterUnit will return true if the callback was successfully registered, and false otherwise. It is allowed to register the same UnitID/callback/handler combination multiple times, but has no effect. It is also allowed to register the same callback with multiple handlers, or use the same handler for multiple callbacks; each pair will be treated separately.

Batch Registration

A number of additional methods are available for registering batches of related unitids:

libunitid:RegisterParty(mycallback, myhandler)  -- fires for any "party#"
libunitid:RegisterPartyTargets(mycallback, myhandler)  -- fires for any "party#target"
libunitid:RegisterPartyPets(mycallback, myhandler)  -- fires for any "partypet#"
libunitid:RegisterPartyPetTargets(mycallback, myhandler)  -- fires for any "partypet#target"
libunitid:RegisterAllParty(mycallback, myhandler)  -- fires for any party-related unitid above

libunitid:RegisterRaid(mycallback, myhandler)  -- fires for any "raid##"
libunitid:RegisterRaidTargets(mycallback, myhandler)  -- fires for any "raid##target"
libunitid:RegisterRaidPets(mycallback, myhandler)  -- fires for any "raidpet##"
libunitid:RegisterRaidPetTargets(mycallback, myhandler)  -- fires for any "raidpet##target"
libunitid:RegisterAllRaid(mycallback, myhandler)  -- fires for any raid-related unitid above

libunitid:RegisterAll(mycallback, myhandler)  -- fires for any supported unitid

The batch registration methods will return the number of UnitIDs that the callback was successfully registered for. Note that this is not dependent on the current size of the player's party or raid -- the party UnitIDs "party1" .. "party5" can still be registered while not in a party, and RegisterParty should still return 5 in this case.

Unregistration

To unregister a callback function, the syntax is identical except for "Unregister" in place of "Register". Again, each UnitID/callback/handler combination is unique, and must be unregistered in the same manner it was registered.

Callbacks

Whenever a game event indicates a change in the identity of one or more UnitIDs, LibUnitID will notify all applicable callbacks. Note that a single callback/handler pair can be registered for more than one UnitID, and a single game event can result in changes to more than one UnitID. In order to let the callback functions do as little work as possible, LibUnitID will only call a given callback/handler pair once per game event, even if multiple associated UnitIDs have changed. If a callback is registered for more than one UnitID, then it needs to check its delta argument to determine which UnitIDs actually changed. The delta table is shared and provided to all involved callbacks during a single dispatch phase, so it is not allowed for callbacks to modify it. In fact, to avoid accidental changes that could interfere with other addons, the delta table is protected from modification using a metatable. As a side effect, the # size operator and the next(), pairs() and ipairs() functions will not work on it. Instead, the numeric index 0 of the delta table will hold the number of changed UnitIDs (which can be used instead of #delta). Each subsequent numeric index up to this limit will contain a UnitID that changed. In addition, each changed UnitID is itself a key of the delta table, whose value is the boolean true. For example, a delta table might look like this:

{
  0 = 4,
  1 = "party3",
  2 = "party3target",
  3 = "partypet3",
  4 = "partypet3target",
  party3 = true,
  party3target = true,
  partypet3 = true,
  partypet3target = true
}

The 0 index == 4 means there are 4 changed UnitIDs for this callback to consider. The indecies 1-4 name the UnitIDs that changed, and those UnitIDs are themselves keys which evaluate to true. As an example, the following callback function will print all changed UnitIDs and their new GUIDs, along with the name of the game event that triggered the update:

local function mycallback(event, delta)
  local n = delta[0]
  local s = ""
  for i=1,n do
    s = s .. ", " .. delta[i] .. "(" .. tostring(LibUnitID:GetUnitGUID(delta[i])) .. ")"
  end
  print(event .. " => " .. strsub(s,3))
 end

GUIDs

To query LibUnitID's GUID cache, you can use either of two styles:

myLibRef:GetUnitGUID("party3")
myLibRef.UnitGUID("party3")

Note that the second call is done in function style, which allows you to do something like this:

local UnitGUID = myLibRef.UnitGUID
...
UnitGUID("party3")

Cache Caveats

The cache is only updated when the library receives event notifications from the game engine, which may happen in any order. If you have your own event handlers for events that affect UnitIDs, and if you try to query the cache during those event handlers, you may receive out-of-date information if the library has not yet received the same event and updated itself. Also note that the library will not track UnitIDs for which nobody has registered a callback, and will also not take the time to verify that in :GetUnitGUID() or :UnitGUID(); if you request the GUID of a UnitID that you did not register a callback for, you will get nil unless someone else happened to register for that UnitID. For best results, only query the cache from a callback that you registered with LibUnitID, or during events that do not affect UnitIDs. Last Updated: 2009-01-31 for 1.0.14-alpha