wow-api-pvp

name

wow-api-pvp

description

Complete reference for WoW Retail PvP, Battlegrounds, Arenas, Rated PvP, War Mode, Duels, War Games, and Honor/Conquest APIs. Covers C_PvP (PvP info, rated stats, rewards, battlegrounds, arenas, war mode, brawls, special events), duel functions (AcceptDuel, CancelDuel, StartDuel), war game functions, honor/conquest tracking, PvP talent integration, and PvP-related events. Use when working with PvP systems, battlegrounds, arenas, rated PvP, war mode, honor, conquest, duels, or PvP UI.

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

---

Gotchas & Restrictions

1. War mode toggle location — Can only toggle war mode in Stormwind/Orgrimmar (capital cities), not anywhere.
2. BG score indices — GetBattlefieldScore() indices are 1-based and may not match player order.
3. Queue index — GetBattlefieldStatus() uses queue index (1-based), not battlefield ID.
4. PvP talents — PvP talents are managed through C_SpecializationInfo, not C_PvP. See the talents skill.
5. AcceptBattlefieldPort hardware event — Requires a hardware event to accept.
6. 12.0.0 instance restrictions — In BGs and arenas, enemy player info (name, class, health) may be secret values.
7. Honor is a currency — Honor and conquest are currencies. Use C_CurrencyInfo for tracking amounts.
8. Season resets — Rated PvP data resets each season. GetCurrentSeasonNumber() tracks the season.