The following are not primitive Lua data types, but for the purposes of this Reference it is useful to recognize cases where API functions expect or return data in a standard format.

Type: 1nil

Many API functions return a value indicative of a binary state but do not use the boolean true and false values -- instead returning 1 for true and nil for false. Since Lua treats nil as false and any non-nil value as true in conditionals, these values can generally be used the same as boolean values (e.g. if IsInGuild() then ... end). However, one should avoid making direct comparisons: for example, the condition in if IsInGuild() == true then ... end will never be triggered.

Type: actionID

Index identifying one of the player's action bar slots.

In UI terms, action slots are a layer of abstraction between spells or items and the mechanisms available to the player for using them conveniently. For example, instead of the default UI internally using SetBindingSpell(), SetBindingMacro(), et al whenever the player changes the contents of the visible action bars, it instead manages a set of key bindings corresponding to the action bar slots.

Every player has at least NUM_ACTIONBAR_PAGES * NUM_ACTIONBAR_BUTTONS (in the current client, 6 * 12, or 72) action slots corresponding to the six default action bar pages. In addition, players of certain classes (or with certain talents) may have additional actionIDs available corresponding to the "bonus" action bars that automatically become available when changing stances, stealthing, shapeshifting, etc.

Type: ah-list-type

There are three different auction house listing types:

Type: anchorPoint

String identifying a point relative to the dimensions of a Region; used in frame layout. Possible values:

Type: arenaTeamID

Identifies one of the (up to three) Arena teams to which a player can belong. These indices begin at 1 for the player's smallest team and increase with team size. For example, if the player belongs to a 2v2 team and a 5v5 team, 1 indicates the 2v2 team and 2 indicates the 5v5 team. But if the player belongs to a 3v3 team and a 5v5 team, 1 indicates 3v3 and 2 indicates 5v5. If the player is on teams of all three sizes, 1 indicates 2v2, 2 is 3v3, and 3 is 5v5.

The Blizzard UI's Lua function ArenaTeam_GetTeamSizeID can be used to translate a team size (2, 3, or 5) to the appropriate arenaTeamID for the player.

Type: auraFilter

This parameter can be any of "HELPFUL", "HARMFUL", "PLAYER", "RAID", "CANCELABLE", "NOT_CANCELABLE". You can also specify several filters separated by a | or space character to chain multiple filters together (e.g. "HELPFUL|RAID" or "HELPFUL RAID" == helpful buffs that you can cast on your raid). By default UnitAura has "HELPFUL" as an implicit filter - you cannot get back BOTH helpful and harmful at the same time. Neither "HELPFUL" or "HARMFUL" have meaning for UnitBuff/UnitDebuff, and will be ignored.

Type: backdrop

A backdrop definition is a Lua table with specific attributes, that match directly with the elements in the <Backdrop> definition in an XML definition. It has the following structure:

 {
   bgFile = "Interface\\DialogFrame\\UI-DialogBox-Background",
   tileSize = 32
   edgeFile = "Interface\\DialogFrame\\UI-DialogBox-Border",
   tile = 1,
   edgeSize = 32,
   insets = {
     top = 12,
     right = 12,
     left = 12,
     bottom = 12,
   }
 }

Type: bitfield

A value combining several binary flags into one number; the flags can be inspected individually using bitlib functions. For example (using GetItemFamily and related constants): 

 GetItemFamily("Crystallized Air") 
 -- returns 1224
 bit.bor(0x0008,0x0040,0x0080,0x0400)
 -- returns 1224
 -- these are the masks for Leatherworking, Enchanting, Engineering, and Mining bags

 bit.band(GetItemFamily("Crystallized Air"), 0x0040)
 -- returns 64, or 0x0040: the item fits in an Enchanting Bag
 bit.band(GetItemFamily("Crystallized Air"), 0x0020)
 -- returns 0, or 0x0040: the item does not fit in an Herb Bag

Type: chatMsgType

String identifying the common type of a set of chat window messages; used in chat window functions for determining which windows display which messages and the colors used for displaying each message type.

Each CHAT_MSG_X event has a corresponding chatMsgType, idendified by the part of the event name following the initial CHAT_MSG_; e.g. the chatMsgType for CHAT_MSG_COMBAT_FACTION_CHANGE is COMBAT_FACTION_CHANGE. A list of pre-configured chatMsgTypes can be found as keys in the global table ChatTypeInfo.

Type: colorString

Formatting used to colorize sections of text when displayed in a FontString. Color strings take the form |c(colorvalue)(text)|r:

Examples: |cffffff00(bright yellow)|r, |cff0070dd(rare item blue)|r, |cff40c040(easy quest green)|r

Color strings can be used for display anywhere in the UI, can only be delivered in chat messages if used as part of a hyperlink.

Type: containerID

Identifies one of the player's bags or other containers. Possible values:

Type: containerSlotID

Index of an item slot within a container. Slots are numbered (as presented in the default UI) left-to-right, top-to-bottom, starting with the leftmost slot on the top row.

Type: glyphIndex

Glyph indices are ordered by the level at which they are discovered. Specifically:

  1. The major glyph at the top of the user interface (level 15)
  2. The minor glyph at the bottom of the user interface (level 15)
  3. The minor glyph at the top left of the user interface (level 30)
  4. The major glyph at the bottom right of the user interface (level 50)
  5. The minor glyph at the top right of the user interface (level 70)
  6. The major glyph at the bottom left of the user interface (level 80)

Type: GUID (Globally Unique IDentifier)

All entities in World of Warcraft are identified by a unique 64-bit number; generally presented as a string containing a hexadecimal representation of the number (e.g. "0xF530007EAC083004"). (Note that Lua in WoW does not support 64-bit integers, so this value cannot be converted with tonumber.)

The type of unit represented by a GUID can be determined by using bit.band() to mask the first three digits with 0x00F: - 0x000 - A player - 0x003 - An NPC - 0x004 - A player's pet (i.e. hunter/warlock pets and similar; non-combat pets count as NPCs) - 0x005 - A vehicle

Further content of the GUID varies by unit type:

For example, the GUID 0xF530007EAC083004 can be deconstructed as follows:

Example Code: a function to decode GUIDs

function ParseGUID(guid)
   local first3 = tonumber("0x"..strsub(guid, 3,5))
   local unitType = bit.band(first3,0x00f)

   if (unitType == 0x000) then
      print("Player, ID #", strsub(guid,6))
   elseif (unitType == 0x003) then
      local creatureID = tonumber("0x"..strsub(guid,9,12))
      local spawnCounter = tonumber("0x"..strsub(guid,13)) 
      print("NPC, ID #",creatureID,"spawn #",spawnCounter)
   elseif (unitType == 0x004) then
      local petID = tonumber("0x"..strsub(guid,6,12))
      local spawnCounter = tonumber("0x"..strsub(guid,13)) 
      print("Pet, ID #",petID,"spawn #",spawnCounter)
   elseif (unitType == 0x005) then
      local creatureID = tonumber("0x"..strsub(guid,9,12))
      local spawnCounter = tonumber("0x"..strsub(guid,13)) 
      print("Vehicle, ID #",creatureID,"spawn #",spawnCounter)
   end
end

Type: hyperlink

A string containing markup allowing the client to present it as a link, which the player can click to view more information about or take action regarding the data it represents.

Hyperlinks take the form |H(linktype):(linkdata)|h(text)|h, where (linktype) determines the type of link, (linkdata) is a code referencing the linked information, and (text) is the text visible to the player. Some API functions which operate on links do not require a full hyperlink, only its linktype:linkdata portion.

Links are often encapsulated in a colorString -- in such cases, the full colorString-wrapped link is the only form of the link allowed to be used in chat; attempting to transmit an invalid link may cause the player to be disconnected from the server.

The WoW client recognizes several kinds of hyperlinks, identified by their linktype. For linkdata elements noted as optional below, the client can still resolve the link if they are omitted:

Type: inventoryID

Identifies an inventory slot used (mostly) for the equipping of items. Inventory ID numbers exist not only for the armor and weapon slots seen in the default UI's Character window, but also for bag slots, bank bag slots, the contents of the bank's main storage area, and the contents of the keyring. Inventory slots are not defined as constants in the default UI; to obtain the inventoryID for a slot, use one of the following functions:

Type: itemID

Uniquely identifies an item; usable with APIs such as GetItemInfo(). Also useful with database sites; e.g. item ID 19019.

Type: itemLocation

A bitfield describing the location of an item owned by the player. The following example code illustrates masks which can be compared with an itemLocation to determine the exact location described:

local ITEM_INVENTORY_PLAYER = 0x00100000
local ITEM_INVENTORY_BACKPACK = 0x00200000
local ITEM_INVENTORY_BAGS = 0x00400000
local ITEM_INVENTORY_BANK = 0x00800000
local MASK_BAG = 0xf00
local MASK_SLOT = 0x3f
local bagMap = {
    [0x100] = 1,
    [0x200] = 2,
    [0x400] = 3,
    [0x800] = 4,
}
local function ItemInBag(itemLocation)
    if bit.band(itemLocation, ITEM_INVENTORY_BAGS) > 0 then
        local bag = bagMap[bit.band(itemLocation, MASK_BAG)]
        local slot = bit.band(itemLocation, MASK_SLOT)
        return bag, slot
    elseif bit.band(itemLocation, ITEM_INVENTORY_BACKPACK) > 0 then
        local slot = bit.band(itemLocation, MASK_SLOT)
        return 0, slot
    end
end

local function ItemEquipped(itemLocation)
    if bit.band(itemLocation, ITEM_INVENTORY_PLAYER) > 0 then
        local slot = bit.band(itemLocation, MASK_SLOT)
        return slot
    end
end

Type: itemQuality

Indicates the quality (or rarity) of an item. Possible values and examples:

  1. Poor (gray): Broken I.W.I.N. Button
  2. Common (white): Archmage Vargoth's Staff
  3. Uncommon (green): X-52 Rocket Helmet
  4. Rare / Superior (blue): Onyxia Scale Cloak
  5. Epic (purple): Talisman of Ephemeral Power
  6. Legendary (orange): Fragment of Val'anyr
  7. Artifact / Heirloom (light yellow): Bloodied Arcanite Reaper

Type: itemString

Refers to the linktype:linkdata portion of an item link (the part containing the itemID, e.g. item:19019); see hyperlink for details.

Type: layer

One of the graphical layers present in World of Warcraft (presented from lowest to highest). Any graphics on the HIGHLIGHT layer are only displayed when the mouse is over the parent frame.

Type: macroID

Index of one of the player's saved macros. Macros shared by all characters on player's account are indexed from 1 to MAX_ACCOUNT_MACROS; macros specific to the current character are indexed from MAX_ACCOUNT_MACROS + 1 to MAX_ACCOUNT_MACROS + MAX_CHARACTER_MACROS.

Type: rollID

The default user interface assigns a unique numeric identifier for all items that are able to be rolled on by the party. This identifier can be obtained by checking the rollID member of the specific group loot frame. For example: /run print(GroupLootFrame1.rollID).

Type: spellbookID

Index of a spell in the player's (or pet's) spellbook; usable with APIs such as GetSpellInfo().

Type: spellID

Globally and uniquely identifies a spell (and its rank); usable with APIs such as GetSpellInfo(). Also useful with database sites; e.g. spell ID 47471.

Type: standingID

Identifies a level of reputation:

  1. Hated
  2. Hostile
  3. Unfriendly
  4. Neutral
  5. Friendly
  6. Honored
  7. Revered
  8. Exalted

The default UI provides constants which can be helpful in displaying standing information.

Type: unitID

Used throughout the API to identify units of interest. Possible values:

A unitID can also be formed by appending "target" to an existing unitID, referring to that unit's target. This can be done repeatedly. For example, consider a raid situation where the token raid13 refers to a priest: raid13target might be a rogue the priest is healing, raid13targettarget might be the boss monster the rogue is attacking, and raid13targettargettarget might be the warrior tanking the boss.

Many (but not all) API functions that accept a unitID also accept the name of a unit (assuming that unit is in the player's party or raid). For example, UnitHealth("Cladhaire") will return the same value as UnitHealth("party1") if the unit party1 is the player named Cladhaire. In such situations, a unit's target can still be accessed by appending "-target"; e.g. UnitHealth("Cladhaire-target").