wow-api-unit-player

wow-api-unit-player is a skill for Claude Code, Codex from JBurlison/WoWAddonAPIAgents. It costs 0 tokens per session (8,971 once invoked), scanned A, original, MIT.

A reference guide to the World of Warcraft Retail programming interface for units and player characters. It covers information such as health, abilities, buffs, combat state, group membership, and character details.

In plain words
What is it for?
Use it when building or debugging WoW addons that inspect units, players, health, power, auras, casting, threat, roles, groups, or character stats.
Why use it?
It gives an agent the correct functions and identifiers for reading game state without guessing or relying on removed interfaces.

Skill for Claude CodeCodex

Install

Getting it into your agent

One page per mod, every tool's command on it. A separate URL per tool would split the same page into five that compete with each other.

agentmods
npx agentmods add skills/jburlison/wowaddonapiagents/wow-api-unit-player
Any agent
npx skills add JBurlison/WoWAddonAPIAgents --skill wow-api-unit-player
Clone the repo
git clone --depth 1 https://github.com/JBurlison/WoWAddonAPIAgents

Made for: Claude Code, Codex.

Wrote this? Show the measurements

A badge with what this costs and how it scanned, read live from this page, so it follows the numbers instead of freezing them. Markdown for a README, HTML for a documentation site or a project page.

agentmods badge for wow-api-unit-player

README.md
[![agentmods](https://agentmods.dev/badge/skills/jburlison/wowaddonapiagents/wow-api-unit-player.svg)](https://agentmods.dev/skills/jburlison/wowaddonapiagents/wow-api-unit-player)
Your own site
<a href="https://agentmods.dev/skills/jburlison/wowaddonapiagents/wow-api-unit-player"><img src="https://agentmods.dev/badge/skills/jburlison/wowaddonapiagents/wow-api-unit-player.svg" alt="Measured on agentmods" height="20"></a>
Per session 0 Skills are progressive disclosure: only the name and description are preloaded; the body loads when the skill is used.
When invoked 8,971 The whole file, excluding the scripts and references it only reads on demand.
Security scan A 0 findings. Scan, not verified.
Origin original No closer match found in the catalogue.
Token cost

What it costs to keep this loaded

Counted locally with the o200k_base tokenizer, which is exact for GPT models; Claude uses its own tokenizer and its counts differ. Treat this as one consistent yardstick across the catalogue rather than a bill. Prices are per million input tokens.

ModelPer sessionOnce invoked
Fable 5 $0.00000 $0.08971
Opus 5 $0.00000 $0.04485
Sonnet 5 $0.00000 $0.01794
Haiku 4.5 $0.00000 $0.00897

Measured 4d ago against content hash e04ccbd1b945, method: parsed. Prices are Anthropic first-party input rates as of 2026-08-30, from the pricing page.

Security

Grade A, and why

wow-api-unit-player scanned grade A with 0 findings against 26 rules in 11 categories — prompt injection, anti-refusal, data exfiltration, privilege escalation, supply chain, agent snooping, system-prompt leakage, SSRF and excessive agency — measured 4d ago.

A static scan of the body, not an audit. Every finding is printed with the line that produced it so you can judge whether it matters here. A mod is markdown that instructs an agent; that is exactly why what it instructs is worth reading.

Nothing flagged

None of the 26 patterns this scan looks for appear in this file: no shell pipes, no recursive deletes, no credential paths, no hidden text, no instruction-override or anti-refusal phrasing, no agent-config snooping. That is not a guarantee, it is the absence of the things that are checkable.

.github/skills/wow-api-unit-player/SKILL.md · 724 lines

How it starts

The opening of the file, as written. The whole thing — 724 lines — stays where its author put it; the contents beside it link to each section on GitHub.

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

Function Returns Description
UnitName(unit) unitName, unitServer Unit's name and realm
UnitFullName(unit) unitName, unitServer Full name with server
UnitNameUnmodified(unit) unitName, unitServer Name without modifications
UnitNameFromGUID(guid) unitName, unitServer Name from GUID
UnitGUID(unit) guid GUID string
UnitTokenFromGUID(guid) unitToken UnitId from GUID
UnitClass(unit) className, classFilename, classID Class info
UnitClassBase(unit) classFilename, classID Non-localized class
UnitClassFromGUID(guid) className, classFilename, classID Class from GUID
UnitRace(unit) localizedRace, englishRace, raceID Race info
UnitSex(unit) sex Gender (1=unknown, 2=male, 3=female)
UnitLevel(unit) level Unit level
UnitEffectiveLevel(unit) level Scaled level
UnitFactionGroup(unit [, checkDisplayRace]) factionTag, localized Horde/Alliance
UnitClassification(unit) class "normal", "elite", "worldboss", etc.
UnitCreatureType(unit) name, id Beast, Humanoid, Undead, etc.
UnitCreatureFamily(unit) name, id Creature family (e.g., Crab)
UnitCreatureID(unit) creatureID NPC ID
UnitPVPName(unit) name Name with title
GetPlayerInfoByGUID(guid) class, engClass, race, engRace, sex, name, realm Info from GUID

Health

Function Returns Notes
UnitHealth(unit [, usePredicted]) health Returns secret value in 12.0 — pass directly to widgets
UnitHealthMax(unit) maxHealth Returns secret value in 12.0
UnitHealthMissing(unit [, usePredicted]) missing Health deficit
UnitHealthPercent(unit [, usePredicted [, curve]]) percent Health percentage
UnitPercentHealthFromGUID(guid) percent Health % from GUID
UnitGetIncomingHeals(unit [, healer]) amount Predicted heals
UnitGetTotalAbsorbs(unit) amount Damage absorb shield
UnitGetTotalHealAbsorbs(unit) amount Healing absorb shield
GetUnitHealthModifier(unit) modifier Health modifier
GetUnitMaxHealthModifier(unit) modifier Max health modifier

Power (Mana/Rage/Energy/etc.)

Function Returns Notes
UnitPower(unit [, powerType [, unmodified]]) power Current power
UnitPowerMax(unit [, powerType [, unmodified]]) maxPower Maximum power
UnitPowerMissing(unit [, powerType [, unmodified]]) missing Power deficit
UnitPowerPercent(unit [, powerType [, ...]]) percent Power percentage
UnitPartialPower(unit [, powerType [, unmodified]]) partialPower Fractional power
UnitPowerType(unit [, index]) powerType, token, r, g, b e.g., 0=Mana, 1=Rage
UnitPowerDisplayMod(powerType) mod Display modifier
GetUnitPowerModifier(unit) modifier Power modifier

Power Types (Enum.PowerType)

Value Token Description
0 Mana Mana
1 Rage Rage
2 Focus Focus (Hunter pets)
3 Energy Energy (Rogues, Monks, etc.)
4 ComboPoints Combo Points
5 Runes Death Knight Runes
6 RunicPower Runic Power
7 SoulShards Warlock Soul Shards
8 LunarPower Balance Druid
9 HolyPower Paladin Holy Power
11 Maelstrom Shaman Maelstrom
12 Chi Monk Chi
13 Insanity Shadow Priest
16 ArcaneCharges Arcane Mage
17 Fury Demon Hunter Fury
18 Pain Vengeance DH (legacy)
19 Essence Evoker Essence

State Checks

Function Returns Description
UnitExists([unit]) bool Unit exists and can be targeted
UnitIsVisible([unit]) bool Visible to client (not necessarily line of sight)
UnitIsConnected(unit) bool Not offline
UnitIsDead(unit) bool Dead
UnitIsDeadOrGhost(unit) bool Dead or ghost form
UnitIsGhost(unit) bool Ghost form
UnitAffectingCombat(unit) bool In combat
UnitIsAFK(unit) bool AFK (friendly only)
UnitIsDND(unit) bool Do Not Disturb
UnitIsPlayer([unit]) bool Is a player character
UnitIsEnemy(unit, target) bool Units are hostile
UnitIsFriend(unit, target) bool Units are friendly
UnitCanAttack(unit, target) bool First can attack second
UnitCanAssist(unit, target) bool First can assist second
UnitCanCooperate(unit, target) bool Can cooperate
UnitIsUnit(unit1, unit2) bool Same unit
UnitIsPVP(unit) bool PvP flagged
UnitIsCharmed([unit]) bool Charmed / mind controlled
UnitIsFeignDeath(unit) bool Feigning death (group only)
UnitIsTapDenied(unit) bool Tap denied (grey health bar)
UnitIsTrivial(unit) bool Grey to player
UnitIsBossMob(unit) bool Boss unit
IsFalling([unit]) bool Currently falling
IsFlying([unit]) bool On flying mount
IsSwimming([unit]) bool Swimming
IsStealthed() bool Player is stealthed
PlayerIsInCombat() bool Player in combat

Group Membership

Function Returns Description
UnitInParty([unit]) bool In your party
UnitInRaid([unit]) index In your raid (returns index)
UnitInAnyGroup([unit]) bool In any group
UnitPlayerOrPetInParty([unit]) bool Player or pet in party
UnitPlayerOrPetInRaid([unit]) bool Player or pet in raid
UnitInRange(unit) inRange, checked Within 40yd (25yd Evoker) #grouponly
UnitIsGroupLeader(unit [, cat]) bool Is group leader
UnitIsGroupAssistant(unit) bool Is assist
UnitGroupRolesAssigned([unit]) role "TANK", "HEALER", "DAMAGER", "NONE"
UnitIsInMyGuild(unit) bool Same guild

Casting Info

Function Returns Description
UnitCastingInfo(unit) name, displayName, textureID, startTimeMs, endTimeMs, isTradeskill, castID, notInterruptible, castingSpellID, castBarID Current cast info
UnitChannelInfo(unit) name, displayName, textureID, startTimeMs, endTimeMs, isTradeskill, notInterruptible, spellID, isEmpowered, numEmpowerStages, castBarID Channel info
UnitCastingDuration(unit) duration Cast duration
UnitChannelDuration(unit) duration Channel duration
UnitEmpoweredChannelDuration(unit [, includeHold]) duration Empower duration

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

Threat

Function Returns Description
UnitThreatSituation(unit [, mob]) status 0=low, 1=close, 2=unsafe, 3=tanking
UnitDetailedThreatSituation(unit, mob) isTanking, status, scaledPct, rawPct, rawThreat Detailed threat
UnitThreatPercentageOfLead(unit, mob) percent % of lead
UnitThreatLeadSituation(unit, mob) status Lead situation

C_UnitAuras — Aura System

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

Key Functions

Function Returns Description
C_UnitAuras.GetAuraDataByIndex(unit, index [, filter]) aura Aura by index
C_UnitAuras.GetAuraDataByAuraInstanceID(unit, auraInstanceID) aura Aura by instance ID
C_UnitAuras.GetAuraDataBySlot(unit, slot) aura Aura by slot
C_UnitAuras.GetAuraDataBySpellName(unit, spellName [, filter]) aura Aura by spell name
C_UnitAuras.GetBuffDataByIndex(unit, index [, filter]) aura Buff specifically
C_UnitAuras.GetDebuffDataByIndex(unit, index [, filter]) aura Debuff specifically
C_UnitAuras.GetPlayerAuraBySpellID(spellID) aura Player aura by spell ID
C_UnitAuras.GetAuraSlots(unit [, filter [, max [, token]]]) continuation, slots... Iterate aura slots
C_UnitAuras.GetUnitAuraInstanceIDs(unit, filter [, max [, sort [, dir]]]) auraInstanceIDs All aura instance IDs
C_UnitAuras.GetUnitAuras(unit, filter [, max [, sort [, dir]]]) auras All aura data
C_UnitAuras.GetAuraDuration(unit, auraInstanceID) duration Remaining duration
C_UnitAuras.GetAuraBaseDuration(unit, auraID [, spellID]) duration Base duration
C_UnitAuras.DoesAuraHaveExpirationTime(unit, auraID) bool Has timer
C_UnitAuras.IsAuraFilteredOutByInstanceID(unit, auraID, filter) bool Filtered by current filter
C_UnitAuras.WantsAlteredForm(unit) bool Wants altered form

Aura Filter Strings

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

Filter Description
"HELPFUL" Buffs only
"HARMFUL" Debuffs only
"PLAYER" Only auras cast by the player
"RAID" Only auras relevant to the raid
"CANCELABLE" Only cancelable auras
"NOT_CANCELABLE" Only non-cancelable auras
"INCLUDE_NAME_PLATE_ONLY" Include nameplate-only auras
"MAW" Maw-specific auras

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

AuraData Structure

Fields returned in an AuraData table:

Field Type Description
name string Aura name
icon number Texture file ID
applications number Stack count
dispelName string? Dispel type: "Magic", "Curse", "Disease", "Poison"
duration number Total duration (0 = indefinite)
expirationTime number GetTime() when it expires
isFromPlayerOrPlayerPet bool Cast by player or player's pet
isHarmful bool Is a debuff
isHelpful bool Is a buff
isNameplateOnly bool Only shows on nameplates
isRaid bool Shows in raid frames
isStealable bool Can be spellstolen
sourceUnit UnitId? Caster
spellId number Spell ID
points table Aura effect values
auraInstanceID number Unique instance ID for this application
timeMod number Time modifier
charges number Number of charges
isBossAura bool Boss aura
nameplateShowAll bool Show all stacks on nameplate
nameplateShowPersonal bool Show personal on nameplate

Private Auras

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

Function Description
C_UnitAuras.AddPrivateAuraAnchor(args) Anchor a frame to a private aura's display position → anchorID
C_UnitAuras.RemovePrivateAuraAnchor(anchorID) Remove private aura anchor
C_UnitAuras.AddPrivateAuraAppliedSound(sound) Play sound when private aura applied → soundID
C_UnitAuras.RemovePrivateAuraAppliedSound(soundID) Remove private aura sound
C_UnitAuras.AuraIsPrivate(spellID) Check if spell is private
C_UnitAuras.AuraIsBigDefensive(spellID) Check if big defensive CD
C_UnitAuras.SetPrivateWarningTextAnchor(parent [, anchor]) Set warning text anchor
C_UnitAuras.TriggerPrivateAuraShowDispelType(show) Toggle dispel type display

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

Read the full file on GitHub · 724 lines

Files

What ships with it

6 files beside SKILL.md in the same directory: the scripts, references and assets a skill reads on demand. Not counted in the per-session cost; read them before you install if any of them is executable.

Changes

What this file has done since we first saw it

Hashed on every crawl. A supply-chain change to an agent config is a question of when, not whether, so the history is kept rather than the latest state alone.

  1. 4d ago First seen · 724 lines · 0 tokens per session scan A e04ccbd1b945

Subscribe to this mod's changes

wow-api-unit-player is a skill published in the GitHub repository JBurlison/WoWAddonAPIAgents (43 stars, last pushed 6mo ago), licensed MIT. It costs nothing until one of its globs matches a file; then it loads 8,971 tokens. A static security scan graded it A with 0 findings. No closer match exists in the catalogue, so it is treated as the original; first seen 2026-08-30.