Skip to content

Warlords ​

The Warlords module exposes a single parser, parseWarlords, which mirrors the raw stats.Battleground block of the Hypixel player API field-for-field into readonly, fully-typed objects. Every value below is read straight from the raw JSON with no computation, no ratios, and no derived totals.

parseWarlords ​

Parses a player's Warlords stats (stats.Battleground) into a typed object. The parser reads directly from the passed object, so the caller supplies the raw Battleground block.

ts
function parseWarlords(stats: Record<string, unknown>): WarlordsStats | null;

Null / empty behavior ​

parseWarlords returns null when the passed object has no keys (an empty stats.Battleground block). Otherwise it always returns a fully-populated WarlordsStats object filled in by the safe readers used throughout the module:

  • Missing or non-number values become 0.
  • Missing or non-string values become "".
  • Boolean fields are true only when the raw value is exactly true, otherwise false.
  • Array-backed fields (weaponInventory, prestiged, packages) become [] when the raw value is not an array; weaponInventory keeps only plain-object entries, prestiged/packages keep only string entries.
  • classes, loadouts, and activeBoosts always contain an entry for every key in their respective rosters.
  • The prefix-collected maps (lifeLeech.byClass, damageDelayed.byClass, woundingStrike) contain only the suffixes discovered in the raw data, so they may be empty objects.

Returned type tree ​

WarlordsStats ​

The root object returned by parseWarlords.

ts
interface WarlordsStats {
  readonly coins: number;
  readonly magicDust: number;
  readonly voidShards: number;
  readonly kills: number;
  readonly deaths: number;
  readonly assists: number;
  readonly wins: number;
  readonly losses: number;
  readonly winsBlu: number;
  readonly winsRed: number;
  readonly winStreak: number;
  readonly playStreak: number;
  readonly damage: number;
  readonly healing: number;
  readonly damagePrevented: number;
  readonly damageTaken: number;
  readonly penalty: number;
  readonly mvpCount: number;
  readonly powerupsCollected: number;
  readonly afkWarned: number;
  readonly brokenInventory: number;
  readonly legendaryBrokenInventory: number;
  readonly rewardInventory: number;
  readonly currentWeapon: number;
  readonly chosenClass: string;
  readonly selectedMount: string;
  readonly hints: boolean;
  readonly hotkeyMode: boolean;
  readonly hidePrestige: boolean;
  readonly firstDiscountUsed: boolean;
  readonly autoStrikeMode: boolean;
  readonly energyPowerups: boolean;
  readonly simplifiedResourcePack: boolean;
  readonly displayDamage: boolean;
  readonly showChatTitles: boolean;
  readonly newControlEnable: number;
  readonly newControlDisable: number;
  readonly repairSalvageCommon: boolean;
  readonly repairSalvageRare: boolean;
  readonly repairSalvageEpic: boolean;
  readonly lifeLeech: WarlordsLifeLeech;
  readonly damageDelayed: WarlordsDamageDelayed;
  readonly woundingStrike: Readonly<Record<string, number>>;
  readonly abilities: WarlordsAbilities;
  readonly crafting: WarlordsCrafting;
  readonly repair: WarlordsRepair;
  readonly salvage: WarlordsSalvage;
  readonly modes: WarlordsModes;
  readonly classes: Readonly<Record<WarlordsClassId, WarlordsClassStats>>;
  readonly loadouts: Readonly<Record<WarlordsBaseClassId, WarlordsLoadout>>;
  readonly activeBoosts: Readonly<Record<WarlordsSpecClassId, string>>;
  readonly chatOptions: WarlordsChatOptions;
  readonly leaderboardSettings: WarlordsLeaderboardSettings;
  readonly privateGames: WarlordsPrivateGames;
  readonly weaponInventory: readonly WarlordsWeapon[];
  readonly boundWeapon: WarlordsBoundWeapons;
  readonly prestiged: readonly string[];
  readonly packages: readonly string[];
}
FieldTypeRaw source / notes
coinsnumbercoins
magicDustnumbermagic_dust
voidShardsnumbervoid_shards
killsnumberkills
deathsnumberdeaths
assistsnumberassists
winsnumberwins
lossesnumberlosses
winsBlunumberwins_blu
winsRednumberwins_red
winStreaknumberwin_streak
playStreaknumberplay_streak
damagenumberdamage
healingnumberheal
damagePreventednumberdamage_prevented
damageTakennumberdamage_taken
penaltynumberpenalty
mvpCountnumbermvp_count
powerupsCollectednumberpowerups_collected
afkWarnednumberafk_warned
brokenInventorynumberbroken_inventory
legendaryBrokenInventorynumberlegendary_broken_inventory
rewardInventorynumberreward_inventory
currentWeaponnumbercurrent_weapon
chosenClassstringchosen_class
selectedMountstringselected_mount
hintsbooleanhints
hotkeyModebooleanhotkeymode
hidePrestigebooleanhide_prestige
firstDiscountUsedbooleanfirst-discount-used
autoStrikeModebooleanautostrikemode
energyPowerupsbooleanenergyPowerups
simplifiedResourcePackbooleansimplifiedresourcepack
displayDamagebooleandisplay_damage
showChatTitlesbooleanshow_chat_titles
newControlEnablenumbernewcontrol_enable
newControlDisablenumbernewcontrol_disable
repairSalvageCommonbooleanrepair_salvage_common
repairSalvageRarebooleanrepair_salvage_rare
repairSalvageEpicbooleanrepair_salvage_epic
lifeLeechWarlordsLifeLeechlife_leeched plus life_leeched_* per-class
damageDelayedWarlordsDamageDelayeddamage_delayed plus damage_delayed_* per-class
woundingStrikeReadonly<Record<string, number>>All wounding_strike_* keys, with the prefix stripped
abilitiesWarlordsAbilitiesFixed ability roster (see below)
craftingWarlordsCraftingcrafting fields
repairWarlordsRepairrepaired* fields
salvageWarlordsSalvagesalvaged_* fields
modesWarlordsModesper-mode fields
classesReadonly<Record<WarlordsClassId, WarlordsClassStats>>one entry per class (see below)
loadoutsReadonly<Record<WarlordsBaseClassId, WarlordsLoadout>>one entry per base class
activeBoostsReadonly<Record<WarlordsSpecClassId, string>>active_boost.<spec>
chatOptionsWarlordsChatOptionschat_option_* fields
leaderboardSettingsWarlordsLeaderboardSettingsleaderboardSettings
privateGamesWarlordsPrivateGamesprivategames
weaponInventoryreadonly WarlordsWeapon[]weapon_inventory (object entries only; [] when not array)
boundWeaponWarlordsBoundWeaponsbound_weapon
prestigedreadonly string[]prestiged (string entries only; [] when not array)
packagesreadonly string[]packages (string entries only; [] when not array)

Key types ​

The classes, loadouts, and activeBoosts records are keyed by string-literal union types derived from the Warlords class roster. These helper aliases are internal (not exported); they are shown here to document the record key sets.

ts
type WarlordsClassId =
  | "pyromancer"
  | "mage"
  | "thunderlord"
  | "shaman"
  | "earthwarden"
  | "aquamancer"
  | "paladin"
  | "avenger"
  | "warrior"
  | "defender"
  | "cryomancer"
  | "crusader"
  | "berserker"
  | "protector"
  | "revenant"
  | "spiritguard";

type WarlordsBaseClassId = "mage" | "warrior" | "paladin" | "shaman";

type WarlordsMageSpec = "pyromancer" | "cryomancer" | "aquamancer";
type WarlordsWarriorSpec = "berserker" | "defender" | "revenant";
type WarlordsPaladinSpec = "avenger" | "crusader" | "protector";
type WarlordsShamanSpec = "thunderlord" | "earthwarden" | "spiritguard";

type WarlordsSpecClassId =
  | WarlordsMageSpec
  | WarlordsWarriorSpec
  | WarlordsPaladinSpec
  | WarlordsShamanSpec;

activeBoosts contains one entry for each WarlordsSpecClassId (the 12 spec classes), each read from active_boost.<spec>.

WarlordsClassStats ​

Per-class aggregate stats. One entry exists for each WarlordsClassId (16 classes).

ts
interface WarlordsClassStats {
  readonly wins: number;
  readonly losses: number;
  readonly gamesPlayed: number;
  readonly damage: number;
  readonly healing: number;
  readonly damagePrevented: number;
}
FieldRaw source
winswins_<class>
losseslosses_<class>
gamesPlayed<class>_plays
damagedamage_<class>
healingheal_<class>
damagePreventeddamage_prevented_<class>

WarlordsLoadout ​

Per-base-class loadout configuration. One entry exists for each WarlordsBaseClassId.

ts
interface WarlordsLoadout {
  readonly spec: string;
  readonly armorSelection: number;
  readonly helmetSelection: number;
  readonly cooldown: number;
  readonly critChance: number;
  readonly critMultiplier: number;
  readonly energy: number;
  readonly health: number;
  readonly skill1: number;
  readonly skill2: number;
  readonly skill3: number;
  readonly skill4: number;
  readonly skill5: number;
}
FieldRaw source
spec<class>_spec
armorSelection<class>_armor_selection
helmetSelection<class>_helmet_selection
cooldown<class>_cooldown
critChance<class>_critchance
critMultiplier<class>_critmultiplier
energy<class>_energy
health<class>_health
skill1..skill5<class>_skill1 .. <class>_skill5

WarlordsWeapon ​

A single weapon entry within weaponInventory. Each scalar field maps to the raw key of the same name on the weapon entry; spec is read from the nested spec object.

ts
interface WarlordsWeapon {
  readonly id: number;
  readonly spec: WarlordsWeaponSpec;
  readonly material: string;
  readonly category: string;
  readonly ability: number;
  readonly abilityBoost: number;
  readonly damage: number;
  readonly energy: number;
  readonly chance: number;
  readonly multiplier: number;
  readonly health: number;
  readonly cooldown: number;
  readonly movement: number;
  readonly crafted: boolean;
  readonly playStreak: boolean;
  readonly unlocked: boolean;
  readonly upgradeMax: number;
  readonly upgradeTimes: number;
}
FieldRaw source
idid
specspec
materialmaterial
categorycategory
abilityability
abilityBoostabilityBoost
damagedamage
energyenergy
chancechance
multipliermultiplier
healthhealth
cooldowncooldown
movementmovement
craftedcrafted
playStreakplayStreak
unlockedunlocked
upgradeMaxupgradeMax
upgradeTimesupgradeTimes

WarlordsWeaponSpec ​

The nested spec object of a weapon.

ts
interface WarlordsWeaponSpec {
  readonly spec: number;
  readonly playerClass: number;
}
FieldRaw source
specspec.spec
playerClassspec.playerClass

WarlordsModes ​

Per-game-mode stat groups.

ts
interface WarlordsModes {
  readonly captureTheFlag: WarlordsCaptureTheFlagStats;
  readonly domination: WarlordsDominationStats;
  readonly teamDeathmatch: WarlordsTeamDeathmatchStats;
}

WarlordsCaptureTheFlagStats ​

ts
interface WarlordsCaptureTheFlagStats {
  readonly kills: number;
  readonly wins: number;
  readonly winsTeamA: number;
  readonly winsTeamB: number;
  readonly winsBlu: number;
  readonly winsRed: number;
  readonly weeklyWinsTeamA: number;
  readonly flagConquerSelf: number;
  readonly flagConquerTeam: number;
  readonly flagReturns: number;
}
FieldRaw source
killskills_capturetheflag
winswins_capturetheflag
winsTeamAwins_capturetheflag_a
winsTeamBwins_capturetheflag_b
winsBluwins_capturetheflag_blu
winsRedwins_capturetheflag_red
weeklyWinsTeamAweekly_wins_capturetheflag_a
flagConquerSelfflag_conquer_self
flagConquerTeamflag_conquer_team
flagReturnsflag_returns

WarlordsDominationStats ​

ts
interface WarlordsDominationStats {
  readonly kills: number;
  readonly wins: number;
  readonly winsTeamA: number;
  readonly winsTeamB: number;
  readonly winsBlu: number;
  readonly winsRed: number;
  readonly weeklyWinsTeamA: number;
  readonly pointCaptures: number;
  readonly pointDefends: number;
  readonly totalScore: number;
}
FieldRaw source
killskills_domination
winswins_domination
winsTeamAwins_domination_a
winsTeamBwins_domination_b
winsBluwins_domination_blu
winsRedwins_domination_red
weeklyWinsTeamAweekly_wins_domination_a
pointCapturesdom_point_captures
pointDefendsdom_point_defends
totalScoretotal_domination_score

WarlordsTeamDeathmatchStats ​

ts
interface WarlordsTeamDeathmatchStats {
  readonly kills: number;
  readonly wins: number;
  readonly winsTeamA: number;
  readonly winsTeamB: number;
  readonly winsBlu: number;
  readonly winsRed: number;
}
FieldRaw source
killskills_teamdeathmatch
winswins_teamdeathmatch
winsTeamAwins_teamdeathmatch_a
winsTeamBwins_teamdeathmatch_b
winsBluwins_teamdeathmatch_blu
winsRedwins_teamdeathmatch_red

WarlordsLifeLeech ​

total is read from life_leeched; byClass collects every life_leeched_* key with the prefix stripped.

ts
interface WarlordsLifeLeech {
  readonly total: number;
  readonly byClass: Readonly<Record<string, number>>;
}

WarlordsDamageDelayed ​

total is read from damage_delayed; byClass collects every damage_delayed_* key with the prefix stripped.

ts
interface WarlordsDamageDelayed {
  readonly total: number;
  readonly byClass: Readonly<Record<string, number>>;
}

WarlordsAbilities ​

An index-signature record of ability usage counts. The parser populates one entry for every ability in the fixed roster, each read from its raw snake_case key.

ts
interface WarlordsAbilities {
  readonly [ability: string]: number;
}

Ability keys: accelerated_spike, acid_rain, arcane_recluse, arcane_reflection, arcane_shatter, arm_of_the_almighty, augmented_chains, berserkers_fury, blade_of_willpower, blizzard_breath, blood_frenzy, burst_chain, chilly_aura, clairvoyance, devils_debt, dimensional_warp, divine_effulgence, divine_purification, divine_vindication, earthbound_infusion, electromagnetic_chains, eye_of_the_storm, fervent_force, flame_breath, frost_missile, galvanized_spark, greater_sacrality, hammer_of_judgement, healing_link, heroic_intervention, lightspeed_infusion, lustrous_crown, megalithic_boulder, meteor, mighty_fists, one_man_army, orbs_of_life, permeating_link, piercing_radiance, rallying_presence, reckless_ascent, seismic_shift, seraphim_shield, smothering_soulbind, solitary_resistance, sovereign_solitude, spiritual_deflection, steadfast_warp, symphonic_windfury, totemic_boon, transistor, typhoon_bolt, undying_steed, vigorous_infusion, vitality_boost, warding_wrath, wrath_of_the_fallen, zealous_mark.

WarlordsCrafting ​

ts
interface WarlordsCrafting {
  readonly crafted: number;
  readonly craftedRare: number;
  readonly craftedEpic: number;
  readonly craftedLegendary: number;
  readonly reroll: number;
  readonly rerollCommon: number;
  readonly rerollRare: number;
  readonly rerollEpic: number;
  readonly rerollLegendary: number;
  readonly upgradeCrafted: number;
  readonly upgradeCraftedEpic: number;
  readonly upgradeCraftedLegendary: number;
  readonly upgradeRandom: number;
  readonly upgradeRandomEpic: number;
  readonly upgradePlayStreak: number;
  readonly upgradePlayStreakEpic: number;
  readonly upgradePlayStreakLegendary: number;
  readonly upgradeRandomLegendary: number;
  readonly unlockCrafted: number;
  readonly unlockCraftedLegendary: number;
  readonly unlockPlayStreak: number;
  readonly unlockPlayStreakLegendary: number;
  readonly unlockRandom: number;
  readonly unlockRandomLegendary: number;
}
FieldRaw source
craftedcrafted
craftedRarecrafted_rare
craftedEpiccrafted_epic
craftedLegendarycrafted_legendary
rerollreroll
rerollCommonreroll_common
rerollRarereroll_rare
rerollEpicreroll_epic
rerollLegendaryreroll_legendary
upgradeCraftedupgrade_crafted
upgradeCraftedEpicupgrade_crafted_epic
upgradeCraftedLegendaryupgrade_crafted_legendary
upgradeRandomupgrade_random
upgradeRandomEpicupgrade_random_epic
upgradePlayStreakupgrade_playstreak
upgradePlayStreakEpicupgrade_playstreak_epic
upgradePlayStreakLegendaryupgrade_playstreak_legendary
upgradeRandomLegendaryupgrade_random_legendary
unlockCraftedunlock_crafted
unlockCraftedLegendaryunlock_crafted_legendary
unlockPlayStreakunlock_playstreak
unlockPlayStreakLegendaryunlock_playstreak_legendary
unlockRandomunlock_random
unlockRandomLegendaryunlock_random_legendary

WarlordsRepair ​

ts
interface WarlordsRepair {
  readonly total: number;
  readonly common: number;
  readonly rare: number;
  readonly epic: number;
  readonly legendary: number;
}
FieldRaw source
totalrepaired
commonrepaired_common
rarerepaired_rare
epicrepaired_epic
legendaryrepaired_legendary

WarlordsSalvage ​

ts
interface WarlordsSalvage {
  readonly weapons: number;
  readonly weaponsCommon: number;
  readonly weaponsRare: number;
  readonly weaponsEpic: number;
  readonly weaponsLegendary: number;
  readonly dustReward: number;
  readonly shardsReward: number;
}
FieldRaw source
weaponssalvaged_weapons
weaponsCommonsalvaged_weapons_common
weaponsRaresalvaged_weapons_rare
weaponsEpicsalvaged_weapons_epic
weaponsLegendarysalvaged_weapons_legendary
dustRewardsalvaged_dust_reward
shardsRewardsalvaged_shards_reward

WarlordsChatOptions ​

ts
interface WarlordsChatOptions {
  readonly damage: string;
  readonly energy: string;
  readonly errorMessages: string;
  readonly heal: string;
  readonly killFeed: string;
  readonly misc: string;
  readonly shouts: string;
}
FieldRaw source
damagechat_option_damage
energychat_option_energy
errorMessageschat_option_error_messages
healchat_option_heal
killFeedchat_option_kill_feed
miscchat_option_misc
shoutschat_option_shouts

WarlordsLeaderboardSettings ​

Read from the raw leaderboardSettings object.

ts
interface WarlordsLeaderboardSettings {
  readonly mode: string;
  readonly resetType: string;
}
FieldRaw source
modeleaderboardSettings.mode
resetTypeleaderboardSettings.resetType

WarlordsPrivateGames ​

Read from the raw privategames object.

ts
interface WarlordsPrivateGames {
  readonly teamSelector: boolean;
  readonly noRegeneration: boolean;
  readonly nobleSteeds: boolean;
  readonly weapon: string;
  readonly level: string;
  readonly horseSpeed: string;
  readonly health: string;
  readonly points: string;
  readonly specializations: string;
}
FieldRaw source
teamSelectorteam_selector
noRegenerationno_regeneration
nobleSteedsnoble_steeds
weaponweapon
levellevel
horseSpeedhorse_speed
healthhealth
pointspoints
specializationsspecializations

WarlordsBoundWeapons ​

Bound weapon ids per base class and spec, read from the raw bound_weapon object.

ts
interface WarlordsBoundWeapons {
  readonly mage: Readonly<Record<WarlordsMageSpec, number>>;
  readonly warrior: Readonly<Record<WarlordsWarriorSpec, number>>;
  readonly paladin: Readonly<Record<WarlordsPaladinSpec, number>>;
  readonly shaman: Readonly<Record<WarlordsShamanSpec, number>>;
}
FieldKeysRaw source
magepyromancer, cryomancer, aquamancerbound_weapon.mage.<spec>
warriorberserker, defender, revenantbound_weapon.warrior.<spec>
paladinavenger, crusader, protectorbound_weapon.paladin.<spec>
shamanthunderlord, earthwarden, spiritguardbound_weapon.shaman.<spec>

Released under the MIT License.