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: accessID

Internal index identifying a combination of chatMsgType and chat target. Used to filter chat frame messages for certain API calls. Returned by ChatHistory_GetAccessID(chatType,chatTarget).

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-Gold-Background",  -- path to the background texture
  edgeFile = "Interface\\DialogFrame\\UI-DialogBox-Gold-Border",    -- path to the border texture
  tile = true,      -- true to repeat the background texture to fill the frame, false to scale it
  tileSize = 32,    -- size (width or height) of the square repeating background tiles (in pixels)
  edgeSize = 32,    -- thickness of edge segments and square size of edge corners (in pixels)
  insets = {        -- distance from the edges of the frame to those of the background texture (in pixels)
    left = 11,
    right = 12,
    top = 12,
    bottom = 11
  }
}

Type: blizzid

A unique numeric identifier, used by Blizzard in the game files and commonly found on database websites such as the WoW Armory and wowhead.com. These identifiers are not globally unique, however within a given class of ids, such as quest ids, they are used to uniquely identify a quest.

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: binding

String identifying one or more keyboard keys or mouse buttons, used with key binding and modified click API functions and the OnKeyDown/OnKeyUp script handlers. Most letter, number, and symbol keys are identified by their (uppercase) letter, number, or symbol.

Other keys are identified by a series of global variables with names prefaced by "KEY_": e.g. the localized name for the binding NUMPAD0 can be found in _G["KEY_NUMPAD0"]. Some keys have platform-specific names: e.g. the localized name for the binding PRINTSCREEN can be found in _G["KEY_PRINTSCREEN_MAC"] (revealing that it refers to the F13 key found on Mac extended keyboards).

Modifier keys are identified as follows:

Mouse buttons are identified by the token "BUTTON" followed by the button number; e.g. BUTTON1 for the primary (left) button, BUTTON2 for the right button, BUTTON3 for middle, etc.

For use in key bindings, several key/button identifiers can be strung together with hyphens to indicate a key combination; e.g. CTRL-SHIFT-SPACE, RALT-F12, SHIFT-BUTTON1.

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: expansionID

Numeric index of an expansion pack. Used as return value to GetExpansionLevel() and GetAccountExpansionLevel().

Type: frameStrata

String identifying the general layering order of frames; where frame level provides fine control over the layering of frames, frame strata provides a coarser level of layering control. Frames in a higher strata always appear "in front of" frames in lower strata regardless of frame level. Available frame strata are listed below in order from lowest to highest:

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,7,10))
      local spawnCounter = tonumber("0x"..strsub(guid,11))
      print("NPC, ID #",creatureID,"spawn #",spawnCounter)
   elseif (unitType == 0x004) then
      local petID = tonumber("0x"..strsub(guid,7,10))
      local spawnCounter = tonumber("0x"..strsub(guid,11))
      print("Pet, ID #",petID,"spawn #",spawnCounter)
   elseif (unitType == 0x005) then
      local creatureID = tonumber("0x"..strsub(guid,7,10))
      local spawnCounter = tonumber("0x"..strsub(guid,11))
      print("Vehicle, ID #",creatureID,"spawn #",spawnCounter)
   end
end

Type: |K string

A |K string is a special type of escape sequence that is used on Battle.net names (RealID).

The string is rendered as the players name in the UI ("John"), but is in fact comprised of a special escape sequence using the presenceID of the player (|Kg30|k0000|k).

The third character of the |K string is g for given name, s for surname or f if the string is a combination of the two. You can use BNTokenCombineGivenAndSurname() to combine two |K strings. If you do strlower() on the escaped string then the escape sequence will be visible when using print().

Since the presenceID is only relevant for the local client, then sending these |K strings to other players will make no sense (they will then lookup names based on their own friendslist).

If passed to another client they will be related to that clients own friendslist: presenceID 30 with me is for my friend 'Bob', but on the other client the same presenceID (30) happens to be for 'Mike' so then the client will see 'Mike'.

See also: http://www.wowwiki.com/UIescapesequences

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: instanceDifficultyID

Numeric index representing instance difficulty. Returned by GetInstanceInfo() and others. Also used when describing items in a hyperlink. More information can be acquired by using GetDifficultyInfo(difficultyID).

Type: inventoryID

This is a numeric identifier that is used by the the inventory system to identify a slot in the player's inventory. In World of Warcraft all items that the player 'owns' are part of the player's inventory, including the items they have equipped, the items in the player's bank, the bags that the player has equipped and equipped in the bank, and the keys stored in the player's key ring.

There is a system of API functions that allow you to map from one of these types of locations into an 'inventorySlot' which uniquely identifies that location. For example:

 GetInventorySlotInfo("MainHandSlot")   -- The player's mainhand weapon
 BankButtonIDToInvSlotID(3, 1)      -- The third bag in the player's bank
 BankButtonIDToInvSlotID(5, nil)    -- The fifth slot in the player's bank (not bags)
 ContainerIDToInventoryID(1)        -- The player's first bag slot
 KeyRingButtonIDToInvSlotId(4)      -- The fourth slot in the player's key-ring

In addition and for convenience there are a set of constants defined by the user interface that can be used for the items in the player's 'paper doll' frame. These are defined in FrameXML/Constants.lua and are currently as follows:

 -- Inventory slots
 INVSLOT_AMMO       = 0;
 INVSLOT_HEAD       = 1; INVSLOT_FIRST_EQUIPPED = INVSLOT_HEAD;
 INVSLOT_NECK       = 2;
 INVSLOT_SHOULDER   = 3;
 INVSLOT_BODY       = 4;
 INVSLOT_CHEST      = 5;
 INVSLOT_WAIST      = 6;
 INVSLOT_LEGS       = 7;
 INVSLOT_FEET       = 8;
 INVSLOT_WRIST      = 9;
 INVSLOT_HAND       = 10;
 INVSLOT_FINGER1        = 11;
 INVSLOT_FINGER2        = 12;
 INVSLOT_TRINKET1   = 13;
 INVSLOT_TRINKET2   = 14;
 INVSLOT_BACK       = 15;
 INVSLOT_MAINHAND   = 16;
 INVSLOT_OFFHAND        = 17;
 INVSLOT_RANGED     = 18;
 INVSLOT_TABARD     = 19;
 INVSLOT_LAST_EQUIPPED = INVSLOT_TABARD;

If you choose to use these instead of the appropriate API, you should use the constant name, not the number itself. This ensures that if Blizzard later updates their constants your code should continue to work.

The following are the convenience functions that can be used to obtain inventoryIds:

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 bitfield can be decoded using the EquipmentManager_UnpackLocation function, provided by the equipment manager system:

 local player, bank, bags, slot, bag = EquipmentManager_UnpackLocation(mask)

Type: itemQuality

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

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: justifyH

String describing the horizontal alignment of text within a widget. Possible values:

Type: justifyV

String describing the vertical alignment of text within a widget. Possible values:

Type: layer

String identifying the layer in which a region's graphics are drawn relative to those of other regions in the same frame; graphics in higher layers (as numbered below) are drawn "on top of" those in lower layers.

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: presenceID

PresenceID is a uniqe numerical value given to a player in your Battle.Net friends list. The value is persistent while you are logged in, zoning and entering/leaving instances but might change if you log out. This number is returned by the various CHAT_ MSG_ BN_ events and is used as an argument for the Battle.Net related functions.

Type: powerType

Index of different power types. The SPELLPOWER* global constants are deprecated and will be removed with the expansion after Legion. Use the contents of Enum.PowerType instead.

Type: reportType

A string identifying a reportable offense. Passed to ReportPlayer(). Valid reportTypes as of 4.3.4 live:

These identifiers are stored as global strings - the associated global keys can be found in the frameXML Constants.lua by searching for PLAYER_REPORT_TYPE_.

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: specID

Global index of different specializations used by GetSpecializationInfoByID(), GetSpecializationRoleByID(), and returned by GetArenaOpponentSpec().

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.

You can also append "pet" to a unitID to refer to that unit's pet, although it should only be appended once because pets cannot have pets. The unit pet is a shorter (and more efficient) way to write playerpet, but both refer to the same unit. raidpet1 is also the same as raid1pet. A very long unitID such as targettargetpettarget is valid, and will refer to the player's target if the player's target and the player's pet are targeting the player.

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").