wow-api-pvp
PvP API (Retail — Patch 12.0.0)
Comprehensive reference for PvP, battlegrounds, arenas, rated PvP, war mode, and duels.
Source: https://warcraft.wiki.gg/wiki/World_of_Warcraft_API Current as of: Patch 12.0.0 (Build 65655) — January 28, 2026 Scope: Retail only.
Scope
- C_PvP — PvP info, rated stats, rewards, queuing
- Battlegrounds — BG state, score, flags
- Arenas — Arena info, teams, ratings
- War Mode — War mode toggle, bonuses
- Duels — Accept, cancel, start
- Honor/Conquest — Currency tracking
C_PvP — Core PvP System
PvP State & Info
| Function | Returns | Description |
|---|---|---|
C_PvP.IsPVPMap() |
isPVP |
In a PvP map? |
C_PvP.IsInPVPBattleground() |
inBG |
In a battleground? (deprecated name for IsInBattleground) |
C_PvP.IsInBattleground() |
inBG |
In a battleground? |
C_PvP.IsBattleground() |
isBG |
Current zone is BG? |
C_PvP.IsArena() |
isArena |
In an arena? |
C_PvP.IsSoloShuffle() |
isSoloShuffle |
In solo shuffle? |
C_PvP.IsBlitz() |
isBlitz |
In blitz BG? |
C_PvP.IsRatedBattleground() |
isRated |
In rated BG? |
C_PvP.IsRatedArena() |
isRated |
In rated arena? |
C_PvP.IsRatedMap() |
isRated |
In any rated match? |
C_PvP.IsWarModeDesired() |
isDesired |
War mode toggled on? |
C_PvP.IsWarModeActive() |
isActive |
War mode currently active? |
C_PvP.IsWarModeFeatureEnabled() |
isEnabled |
War mode feature available? |
C_PvP.CanToggleWarMode(toggle) |
canToggle |
Can toggle war mode? |
C_PvP.ToggleWarMode() |
— | Toggle war mode |
C_PvP.GetWarModeRewardBonus() |
bonusPercent |
War mode XP/resource bonus % |
C_PvP.IsPvPTalentsUnlocked() |
isUnlocked |
PvP talents available? |
C_PvP.GetPVPActiveMatchDuration() |
duration |
Active match duration |
C_PvP.GetPVPActiveMatchState() |
state |
Match state |
Rated PvP
| Function | Returns | Description |
|---|---|---|
C_PvP.GetRatedBGRewards() |
rewardInfo |
Rated BG rewards |
C_PvP.GetArenaRewards(teamSize) |
rewardInfo |
Arena rewards |
C_PvP.GetSeasonBestInfo() |
tierID, nextTierID |
Season best tier |
C_PvP.GetCurrentSeasonNumber() |
season |
Current PvP season |
C_PvP.GetRankInfo(hk, guid) |
rankName, rankNumber |
PvP rank info |
C_PvP.GetGlobalPvpScalingInfoForSpecID(specID) |
info |
PvP scaling |
C_PvP.GetLevelUpBattlegrounds() |
bgIDs |
Available BGs for level |
C_PvP.GetRandomBGInfo() |
info |
Random BG info |
C_PvP.GetRandomBGRewards() |
rewardInfo |
Random BG rewards |
C_PvP.GetRandomEpicBGInfo() |
info |
Random epic BG info |
C_PvP.GetSkirmishInfo(bracketIndex) |
info |
Skirmish info |
C_PvP.GetPvpTierInfo(tierID) |
tierInfo |
PvP tier details |
C_PvP.GetPvpTierID(bracketIndex, guid) |
tierID |
Player's tier in bracket |
Honor & Conquest
| Function | Returns | Description |
|---|---|---|
C_PvP.GetHonorRewardInfo(honorLevel) |
rewardInfo |
Honor level reward |
GetHonorLevel() |
level |
Current honor level |
UnitHonorLevel(unit) |
level |
Unit's honor level |
GetMaxPlayerHonorLevel() |
maxLevel |
Max honor level |
GetPVPLifetimeStats() |
hk, dk, highestRank |
Lifetime PvP stats |
GetPVPSessionStats() |
hk, dk |
Session PvP stats |
GetPVPYesterdayStats() |
hk, dk, honor |
Yesterday's stats |
Battleground Score
| Function | Returns | Description |
|---|---|---|
GetNumBattlefieldScores() |
numScores |
Score entries |
GetBattlefieldScore(index) |
name, killingBlows, honorKills, deaths, honorGained, faction, race, class, classToken, damageDone, healingDone, bgRating, ratingChange, preMatchMMR, mmrChange, talentSpec |
Score info |
GetBattlefieldStatData(index, statIndex) |
value |
BG-specific stat |
GetNumBattlefieldStats() |
numStats |
BG stat columns |
GetBattlefieldStatInfo(statIndex) |
name, icon, tooltip |
Stat column info |
Battleground/Arena Queue
| Function | Returns | Description |
|---|---|---|
C_PvP.RequestCrowdControlSpell(unitToken) |
— | Request CC info |
JoinBattlefield(index [, asGroup [, isRated]]) |
— | Join BG queue |
LeaveBattlefield() |
— | Leave BG |
AcceptBattlefieldPort(index, acceptFlag) |
— | Accept/decline BG port |
GetBattlefieldPortExpiration(index) |
expiration |
Port expiration time |
GetBattlefieldStatus(index) |
status, mapName, teamSize, registeredMatch, suspendedQueue, queueType, gameID, role, asGroup, shortDescription, longDescription |
Queue status |
GetMaxBattlefieldID() |
maxID |
Max battlefield ID |
GetBattlefieldInstanceRunTime() |
runTime |
Instance elapsed ms |
GetBattlefieldTimeWaited(index) |
timeWaited |
Time in queue |
GetBattlefieldEstimatedWaitTime(index) |
waitTime |
Estimated wait |
GetBattlefieldWinner() |
winner |
Winning faction |
Duel Functions
| Function | Returns | Description |
|---|---|---|
AcceptDuel() |
— | Accept duel request |
CancelDuel() |
— | Decline/cancel duel |
StartDuel(unit) |
— | Request duel |
War Game Functions
| Function | Returns | Description |
|---|---|---|
C_PvP.StartWarGame(targetName, warGameType, ...) |
— | Start war game |
C_PvP.IsWarGameByMasterAllowed() |
allowed |
Can start war games? |
Common Patterns
Check PvP Context
local function GetPvPContext()
if C_PvP.IsArena() then return "arena"
elseif C_PvP.IsInBattleground() then return "battleground"
elseif C_PvP.IsWarModeActive() then return "warmode"
else return "pve" end
end
Display Rated PvP Info
local function PrintRatedInfo()
local season = C_PvP.GetCurrentSeasonNumber()
print("PvP Season:", season)
-- Check bracket ratings
for bracketIndex = 1, 4 do
local tierID = C_PvP.GetPvpTierID(bracketIndex, UnitGUID("player"))
if tierID then
local tierInfo = C_PvP.GetPvpTierInfo(tierID)
if tierInfo then
print("Bracket", bracketIndex, ":", tierInfo.pvpTierEnum, tierInfo.tierName)
end
end
end
end
Key Events
| Event | Payload | Description |
|---|---|---|
PVP_MATCH_ACTIVE |
— | PvP match started |
PVP_MATCH_COMPLETE |
winner | Match ended |
PVP_MATCH_INACTIVE |
— | Match inactive |
UPDATE_BATTLEFIELD_STATUS |
battlefieldIndex | Queue status changed |
UPDATE_BATTLEFIELD_SCORE |
— | Scoreboard updated |
BATTLEFIELD_QUEUE_TIMEOUT |
— | Queue timed out |
WARGAME_REQUESTED |
opposingPartyMemberName, bgName, timeout, tournamentRules | War game request |
DUEL_REQUESTED |
playerName | Duel request received |
DUEL_FINISHED |
— | Duel ended |
DUEL_INBOUNDS |
— | Player in duel bounds |
DUEL_OUTOFBOUNDS |
— | Player out of bounds |
HONOR_LEVEL_UPDATE |
isHigherLevel | Honor level changed |
PVP_RATED_STATS_UPDATE |
— | Rated stats updated |
PVP_REWARDS_UPDATE |
— | PvP rewards updated |
WAR_MODE_STATUS_UPDATE |
isWarModeDesired | War mode toggled |
PLAYER_FLAGS_CHANGED |
unitTarget | PvP flag changed |
PVP_TIMER_UPDATE |
— | PvP timer updated |
PVP_VEHICLE_INFO_UPDATED |
— | PvP vehicle info changed |
PVP_WORLDSTATE_UPDATE |
— | World state updated |
ARENA_OPPONENT_UPDATE |
unitToken, updateReason | Arena opponent updated |
ARENA_PREP_OPPONENT_SPECIALIZATIONS |
— | Arena opponent specs |
ARENA_SEASON_WORLD_STATE |
— | Arena season state |
Gotchas & Restrictions
- War mode toggle location — Can only toggle war mode in Stormwind/Orgrimmar (capital cities), not anywhere.
- BG score indices —
GetBattlefieldScore()indices are 1-based and may not match player order. - Queue index —
GetBattlefieldStatus()uses queue index (1-based), not battlefield ID. - PvP talents — PvP talents are managed through
C_SpecializationInfo, notC_PvP. See the talents skill. - AcceptBattlefieldPort hardware event — Requires a hardware event to accept.
- 12.0.0 instance restrictions — In BGs and arenas, enemy player info (name, class, health) may be secret values.
- Honor is a currency — Honor and conquest are currencies. Use
C_CurrencyInfofor tracking amounts. - Season resets — Rated PvP data resets each season.
GetCurrentSeasonNumber()tracks the season.
More from jburlison/wowaddonapiagents
wow-lua-api
Verbose guide to Lua 5.1 functions available in WoW, including Blizzard-specific differences and WoW-only additions. Use for core Lua behavior in the WoW addon environment.
33wow-addon-structure
Verbose guide for WoW Retail AddOn structure, .toc metadata, loading order, SavedVariables, and C_AddOns metadata and load APIs. Use when planning addon folder layout, file order, or SavedVariables wiring.
23wow-api-currency-economy
Complete reference for WoW Retail Currency, Auction House, Token, Store, Trading Post, Black Market, Mail, and Player Trading APIs. Covers C_CurrencyInfo (currency data, tracking, backpack), Auction House (full listing/bidding/buying/selling/search/commodity), C_WowTokenPublic (WoW Token market), AccountStore (in-game shop), CatalogShop, C_PerksProgram (Trading Post — Trader's Tender), BlackMarket (BMAH), TradeInfo (player trading), MailInfo (mailbox), and related events. Use when working with currencies, auction house UI, WoW Tokens, the in-game store, Trading Post, black market, mail, or player-to-player trading.
15wow-api-map-navigation
Complete reference for WoW Retail Map, Navigation, Area POI, Taxi, Vignette, Minimap, Nameplate, Waypoint, Zone Ability, Fog of War, and Exploration APIs. Covers C_Map (50+ functions for map data, coordinates, map IDs, area info), C_MapExplorationInfo, C_AreaPoiInfo, C_TaxiMap (flight paths), C_Vignette, C_SuperTrackManager, C_Navigation (in-game navigation), C_ZoneAbility, C_FogOfWar, Minimap functions, C_NamePlateManager, and coordinate conversion. Use when working with maps, coordinates, waypoints, flight paths, minimap, nameplates, vignettes, exploration, zone abilities, or in-game navigation.
11wow-api-combat
Complete reference for WoW Retail Combat, Damage Meter, Threat, Loss of Control, Combat Text, Combat Audio Alert, Secret Values, and Spectator APIs. Covers the 12.0.0 combat log removal (CLEU no longer available to addons), C_DamageMeter built-in damage meter, C_Secrets secret predicates, C_CurveUtil/C_DurationUtil for secret value visualization, C_LossOfControl, C_CombatText, C_CombatAudioAlert, ENCOUNTER_STATE_CHANGED, threat functions, and the new COMBAT_LOG_MESSAGE event. Use when working with combat data, damage meters, threat, loss of control, combat text, encounter events, or any combat-related addon functionality.
10wow-api-lua-environment
Complete reference for the WoW Lua 5.1 runtime environment, restrictions, secure execution, taint system, addon security model, timers, hooks, frame scripting, logging, and restricted actions. Covers hooksecurefunc, C_Timer, securecallfunction, issecurevariable, taint propagation, combat lockdown, protected frames, InCombatLockdown, C_RestrictedActions, C_Log, and the FrameScript sandbox. Use when working with Lua restrictions, secure code, taint, timers, hooks, addon security, debugging, or the WoW Lua sandbox.
10