Wow API Unit Player

---
name: wow-api-unit-player
description: "Complete reference for WoW Retail Unit and Player APIs — UnitId tokens, GUIDs, health/power/stats, auras, roles, casting, threat, inspection, paper doll, death/resurrection, and player-specific functions. Use when querying unit identity, health, power, auras, stats, combat state, group membership, casting info, threat, or player character details."
---

# Unit & Player API (Retail — Patch 12.0.0)

Comprehensive reference for all Unit, Player, UnitAuras, UnitRole, PaperDollInfo, and PlayerInfo APIs. Covers unit identification (UnitId tokens, GUIDs), health, power, stats, auras, casting, threat, group membership, inspection, and player-specific character functions.

> **Source of truth:** https://warcraft.wiki.gg/wiki/World_of_Warcraft_API#Unit
> **UnitId reference:** https://warcraft.wiki.gg/wiki/UnitId
> **GUID reference:** https://warcraft.wiki.gg/wiki/GUID
> **Current as of:** Patch 12.0.0 (Build 65655) — January 28, 2026
> **Scope:** Retail only. No deprecated or removed functions.

## Scope

This skill covers these API systems:
- **Unit** — Core unit query functions (`UnitName`, `UnitHealth`, `UnitClass`, etc.)
- **UnitAuras** — Aura/buff/debuff system (`C_UnitAuras`)
- **UnitRole** — Group role assignment and queries
- **PlayerInfo** — Player-specific info (`C_PlayerInfo`)
- **PaperDollInfo** — Equipment, stats, inspection (`C_PaperDollInfo`)
- **PlayerScript** — Global player functions (stats, combat ratings, PvP, death, movement)
- **DeathInfo / IncomingSummon** — Death, resurrection, summoning
- **CreatureInfo** — Creature data helpers

## When to Use This Skill

Use this skill when you need to:
- Query unit identity: name, class, race, level, faction, GUID
- Read or display health, power (mana/rage/energy), or stats
- Work with auras (buffs, debuffs, private auras)
- Check unit state: alive, dead, ghost, combat, AFK, stealthed, flying
- Determine group membership, roles, or raid position
- Inspect other players (item level, spec, PvP data)
- Get player character stats: crit, haste, mastery, armor, attack power
- Handle casting info (what a unit is casting/channeling)
- Query threat situation
- Work with UnitId tokens or GUIDs

## Reference Files

| Reference | Contents |
|-----------|----------|
| [UNIT-IDENTITY.md](references/UNIT-IDENTITY.md) | UnitId tokens, GUIDs, name/class/race/level/faction |
| [UNIT-HEALTH-POWER.md](references/UNIT-HEALTH-POWER.md) | Health, power, stats, armor, combat ratings |
| [UNIT-STATE.md](references/UNIT-STATE.md) | Combat, dead/ghost, casting, vehicle, movement, group state |
| [UNIT-AURAS.md](references/UNIT-AURAS.md) | C_UnitAuras — buffs, debuffs, private auras |
| [UNIT-THREAT-COMBAT.md](references/UNIT-THREAT-COMBAT.md) | Threat, targeting, selection, inspection |
| [PLAYER-FUNCTIONS.md](references/PLAYER-FUNCTIONS.md) | Player-specific: XP, money, PvP, death, resurrection, stats |

---

## UnitId Tokens — Quick Reference

A UnitId (unit token) identifies a unit by relationship to the player. Case insensitive.

### Base Tokens

| Token | Description |
|-------|-------------|
| `"player"` | The current player |
| `"target"` | The current player's target |
| `"focus"` | The player's focus target (set by `/focus`) |
| `"pet"` | The player's pet |
| `"vehicle"` | The player's vehicle |
| `"mouseover"` | Unit currently (or most recently) moused over |
| `"none"` | Valid token that always refers to no unit |
| `"npc"` | NPC the player is interacting with (merchant/quest/gossip frame open) |
| `"questnpc"` | Quest giver NPC being interacted with |

### Indexed Tokens

| Pattern | Range | Description |
|---------|-------|-------------|
| `"partyN"` | 1–4 | Nth party member (excluding player) |
| `"raidN"` | 1–40 | Nth raid member |
| `"partypetN"` | 1–4 | Pet of Nth party member |
| `"raidpetN"` | 1–40 | Pet of Nth raid member |
| `"bossN"` | 1–8 | Active boss in current encounter |
| `"arenaN"` | 1–5 | Opposing arena member |
| `"nameplateN"` | 1–40 | Nth nameplate (cannot be targeted) |

### Soft Targeting (Patch 10.0+)

| Token | Description |
|-------|-------------|
| `"softenemy"` | Current soft target that is hostile |
| `"softfriend"` | Current soft target that is friendly |
| `"softinteract"` | Current soft target that can be interacted with |
| `"anyenemy"` | Resolves to `"target"` or `"softenemy"` (target priority) |
| `"anyfriend"` | Resolves to `"target"` or `"softfriend"` (target priority) |
| `"anyinteract"` | Resolves to `"target"` or `"softinteract"` (target priority) |

### Target Chaining

Append `target` to any UnitId to refer to its target. Can be repeated:
- `"targettarget"` — your target's target
- `"raid7target"` — 7th raid member's target
- `"pettarget"` — your pet's target
- `"Cogwheel-target"` — named player's target (if in group)

> **Source:** https://warcraft.wiki.gg/wiki/UnitId

---

## GUID (Globally Unique Identifier) — Quick Reference

GUIDs uniquely identify everything the player can interact with. Returned by `UnitGUID(unit)`.

### GUID Formats

| Type | Format | Example |
|------|--------|---------|
| Player | `Player-[serverID]-[playerUID]` | `Player-970-0002FD64` |
| Creature | `Creature-0-[serverID]-[instanceID]-[zoneUID]-[npcID]-[spawnUID]` | `Creature-0-1465-0-2105-448-000043F59F` |
| Pet | `Pet-0-[serverID]-[instanceID]-[zoneUID]-[npcID]-[spawnUID]` | `Pet-0-4234-0-6610-165189-0202F859E9` |
| Vehicle | `Vehicle-0-[serverID]-[instanceID]-[zoneUID]-[npcID]-[spawnUID]` | Same format as Creature |
| GameObject | `GameObject-0-[serverID]-[instanceID]-[zoneUID]-[objectID]-[spawnUID]` | Same format as Creature |
| Item | `Item-[serverID]-0-[spawnUID]` | `Item-1598-0-4000000A369860E1` |
| Vignette | `Vignette-0-[serverID]-[instanceID]-[zoneUID]-[vignetteID]-[spawnUID]` | — |
| BattlePet | `BattlePet-0-[ID]` | `BattlePet-0-00000338F951` |
| Cast | `Cast-[type]-[serverID]-[instanceID]-[zoneUID]-[spellID]-[castUID]` | — |

### Extracting NPC ID from GUID

```lua
local npcID = select(6, strsplit("-", UnitGUID("target")))
print(tonumber(npcID)) -- e.g., 448 for Hogger

Key Rules

• Players keep their GUID forever (unless faction change/transfer)
• Creatures get a new GUID each spawn cycle
• Pets get a new GUID each time summoned
• GUIDs are recycled after server/instance restart

Source: https://warcraft.wiki.gg/wiki/GUID

Core Unit Functions — Overview

Identity

Health

Power (Mana/Rage/Energy/etc.)

Power Types (Enum.PowerType)

State Checks

Group Membership

Casting Info

12.0.0 Change: notInterruptible in UnitCastingInfo is now nilable. New castBarID return added.

Threat

C_UnitAuras — Aura System

The aura API provides buff/debuff data for units. Returns AuraData tables.

Key Functions

Aura Filter Strings

Filters are space-separated strings passed to aura query functions:

Combine with spaces: "HELPFUL PLAYER" = buffs cast by player.

AuraData Structure

Fields returned in an AuraData table:

Private Auras

Private auras are auras where the spell data is hidden from addons. Used for encounter mechanics.

Aura Iteration Pattern

-- Modern pattern: iterate by aura instance IDs
local function GetAllAuras(unit, filter)
    local auras = {}
    local ids = C_UnitAuras.GetUnitAuraInstanceIDs(unit, filter)
    for _, id in ipairs(ids) do
        local aura = C_UnitAuras.GetAuraDataByAuraInstanceID(unit, id)
        if aura then
            table.insert(auras, aura)
        end
    end
    return auras
end

-- Get all player debuffs
local debuffs = GetAllAuras("player", "HARMFUL")

UNIT_AURA Event

-- UNIT_AURA fires when any aura changes on a unit
-- Payload: unitTarget, updateInfo
-- updateInfo contains: addedAuras, updatedAuraInstanceIDs, removedAuraInstanceIDs
-- isFullUpdate (bool) — if true, full refresh is needed

local frame = CreateFrame("Frame")
frame:RegisterUnitEvent("UNIT_AURA", "player")
frame:SetScript("OnEvent", function(self, event, unit, updateInfo)
    if updateInfo.isFullUpdate then
        -- re-scan all auras
        return
    end
    if updateInfo.addedAuras then
        for _, aura in ipairs(updateInfo.addedAuras) do
            print("Added:", aura.name, aura.spellId)
        end
    end
    if updateInfo.removedAuraInstanceIDs then
        for _, id in ipairs(updateInfo.removedAuraInstanceIDs) do
            print("Removed aura instance:", id)
        end
    end
end)

C_PlayerInfo — Player Information

Source: https://warcraft.wiki.gg/wiki/World_of_Warcraft_API#PlayerLocationInfo

C_PaperDollInfo — Equipment & Inspection

Inspection Flow

-- 1. Request inspection data
NotifyInspect("target")

-- 2. Wait for INSPECT_READY event
local frame = CreateFrame("Frame")
frame:RegisterEvent("INSPECT_READY")
frame:SetScript("OnEvent", function(self, event, inspecteeGUID)
    local spec = GetInspectSpecialization("target")
    local ilvl = C_PaperDollInfo.GetInspectItemLevel("target")
    print("Spec:", spec, "iLvl:", ilvl)
    ClearInspectPlayer() -- Clean up
    self:UnregisterEvent("INSPECT_READY")
end)

UnitRole — Group Roles

Player Character Stats

These global functions query the player's character stats.

Combat Ratings & Stats

Player XP & Level

Money & Economy

Movement

Death & Resurrection

Secret Values — 12.0.0 Impact on Unit APIs

Many unit functions now return secret values under certain conditions. See the wow-api-important instructions for full details.

Functions Returning Secrets

Safe Pattern: Display Health

-- CORRECT: Pass secret values directly to widgets
local hp = UnitHealth("target")
local maxHp = UnitHealthMax("target")
myStatusBar:SetMinMaxValues(0, maxHp) -- accepts secrets
myStatusBar:SetValue(hp)              -- accepts secrets

-- WRONG: Do NOT compare or do math
-- if hp < maxHp * 0.3 then -- ERROR: cannot compare secrets

Checking Restrictions

-- Check if unit identity is restricted
local isSecret = C_Secrets.ShouldUnitIdentityBeSecret("target")
local isHealthSecret = C_Secrets.ShouldUnitHealthMaxBeSecret("target")
local isPowerSecret = C_Secrets.ShouldUnitPowerBeSecret("target")

Common Patterns

Unit Frame Health Bar

local frame = CreateFrame("Frame", nil, UIParent)
local healthBar = CreateFrame("StatusBar", nil, frame)
healthBar:SetStatusBarTexture("Interface\\TargetingFrame\\UI-StatusBar")
healthBar:SetMinMaxValues(0, 1)

local function UpdateHealth(unit)
    local hp = UnitHealth(unit)
    local maxHp = UnitHealthMax(unit)
    healthBar:SetMinMaxValues(0, maxHp)
    healthBar:SetValue(hp)
end

frame:RegisterUnitEvent("UNIT_HEALTH", "target")
frame:RegisterUnitEvent("UNIT_MAXHEALTH", "target")
frame:SetScript("OnEvent", function(self, event, unit)
    UpdateHealth(unit)
end)

Check if Unit is a Healable Friendly

local function IsHealableUnit(unit)
    return UnitExists(unit)
        and UnitCanAssist("player", unit)
        and not UnitIsDeadOrGhost(unit)
        and UnitIsConnected(unit)
end

Get NPC ID from Target

local function GetNPCID(unit)
    local guid = UnitGUID(unit)
    if not guid then return nil end
    local unitType, _, _, _, _, npcID = strsplit("-", guid)
    if unitType == "Creature" or unitType == "Vehicle" then
        return tonumber(npcID)
    end
end

Related Events

Restrictions & Gotchas

Sources:

• https://warcraft.wiki.gg/wiki/World_of_Warcraft_API#Unit
• https://warcraft.wiki.gg/wiki/World_of_Warcraft_API#UnitAuras
• https://warcraft.wiki.gg/wiki/World_of_Warcraft_API#UnitRole
• https://warcraft.wiki.gg/wiki/World_of_Warcraft_API#PlayerScript
• https://warcraft.wiki.gg/wiki/World_of_Warcraft_API#PaperDollInfo
• https://warcraft.wiki.gg/wiki/World_of_Warcraft_API#PlayerLocationInfo
• https://warcraft.wiki.gg/wiki/UnitId
• https://warcraft.wiki.gg/wiki/GUID