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

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

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

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

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

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)

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

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