@mcsb/api / Exports

@mcsb/api ​

Table of contents ​

Classes ​

• BaseAPI
• Cache
• HttpClient
• HypixelAPI
• HypixelResources
• InMemoryCache
• MojangAPI
• RateLimitDeferPolicy
• RateLimitExceededError
• RawResponse
• ResourcesNotReadyError
• TTLCachePolicy
• UnixDate

Interfaces ​

• CachePolicy
• IDeferPolicy

Type Aliases ​

• APIOptions
• CacheItem
• CacheOptions
• HypixelAPIOptions
• HypixelBooster
• HypixelChallenge
• HypixelGame
• HypixelGameAchievements
• HypixelGamePlayerCount
• HypixelGuild
• HypixelGuildAchievements
• HypixelLeaderboard
• HypixelLeaderboards
• HypixelOneTimeAchievement
• HypixelOneTimeGuildAchievement
• HypixelPet
• HypixelPlayer
• HypixelPlayerCounts
• HypixelPunishmentStatistics
• HypixelQuest
• HypixelRarity
• HypixelRecentGame
• HypixelResourcesOptions
• HypixelSession
• HypixelSkyBlockAuction
• HypixelSkyBlockAuctions
• HypixelSkyBlockBazaarProduct
• HypixelSkyBlockBingo
• HypixelSkyBlockBingoGoal
• HypixelSkyBlockBingoProfile
• HypixelSkyBlockCollection
• HypixelSkyBlockElection
• HypixelSkyBlockEndedAuction
• HypixelSkyBlockFiresale
• HypixelSkyBlockItem
• HypixelSkyBlockMayor
• HypixelSkyBlockMayorCandidate
• HypixelSkyBlockMuseum
• HypixelSkyBlockNews
• HypixelSkyBlockProfile
• HypixelSkyBlockSkill
• HypixelStatus
• HypixelTieredAchievement
• HypixelTieredGuildAchievement
• MinecraftFormattingCode
• MojangProfile

Variables ​

• EnumHypixelGames
• EnumHypixelGuildAchievements
• EnumHypixelPetConsumables
• EnumHypixelPlayerCounts
• EnumHypixelSkyBlockDungeonClasses
• EnumMinecraftFireworkShapes
• EnumMinecraftFormatting
• MONGODB_ID_REGEX
• UUID_REGEX

Functions ​

• getFormattingCode
• networkExpToLevel
• networkExpToLevelQuadratic
• networkLevelExpDifference
• networkLevelProgress
• networkLevelRemainingExp
• networkLevelToExp

Type Aliases ​

APIOptions ​

Ƭ APIOptions: Object

Default options that all implementations of BaseAPI accept.

Type declaration ​

Defined in ​

packages/api/src/BaseAPI.ts:72

CacheItem ​

Ƭ CacheItem<T>: Object

Container for storing values of type T along with a timestamp at which the value was saved in the Cache. This is useful for CachePolicy implementations which invalidate the cached values after a certain period of time.

Type parameters ​

Type declaration ​

Defined in ​

packages/api/src/cache/Cache.ts:35

CacheOptions ​

Ƭ CacheOptions<T>: Object

The options that can be provided to a Cache constructor.

Type parameters ​

Type declaration ​

Defined in ​

packages/api/src/cache/Cache.ts:7

HypixelAPIOptions ​

Ƭ HypixelAPIOptions: APIOptions & { apiKey: string }

Extension of APIOptions that also requires a Hypixel API key.

Defined in ​

packages/api/src/HypixelAPI.ts:64

HypixelBooster ​

Ƭ HypixelBooster: z.infer<BoosterSchema>["boosters"][number]

Defined in ​

packages/api/src/schemas/hypixel/BoosterSchema.ts:9

HypixelChallenge ​

Ƭ HypixelChallenge: z.infer<ChallengesResourceSchema>["challenges"][string][number]

Defined in ​

packages/api/src/schemas/hypixel/resources/ChallengesResourceSchema.ts:6

HypixelGame ​

Ƭ HypixelGame: z.infer<GamesResourceSchema>["games"][keyof typeof EnumHypixelGames]

Defined in ​

packages/api/src/schemas/hypixel/resources/GamesResourceSchema.ts:7

HypixelGameAchievements ​

Ƭ HypixelGameAchievements: z.infer<AchievementsResourceSchema>["achievements"][string]

Defined in ​

packages/api/src/schemas/hypixel/resources/AchievementsResourceSchema.ts:6

HypixelGamePlayerCount ​

Ƭ HypixelGamePlayerCount: HypixelPlayerCounts["games"][keyof typeof EnumHypixelPlayerCounts]

Type-safe representation of the player data of a Hypixel game, retrieved from the /counts Hypixel endpoint. This type does not have its fields documented due to the size of the inferred type. Look at the source definition to see the data structure.

See

https://api.hypixel.net/#tag/Other/paths/~1counts/get

Defined in ​

packages/api/src/schemas/hypixel/PlayerCountsSchema.ts:19

HypixelGuild ​

Ƭ HypixelGuild: z.infer<GuildSchema>["guild"]

Defined in ​

packages/api/src/schemas/hypixel/GuildSchema.ts:37

HypixelGuildAchievements ​

Ƭ HypixelGuildAchievements: z.infer<GuildAchievementsResourceSchema>

Defined in ​

packages/api/src/schemas/hypixel/resources/GuildAchievementsResourceSchema.ts:6

HypixelLeaderboard ​

Ƭ HypixelLeaderboard: Exclude<HypixelLeaderboards[z.infer<typeof ZodEnumHypixelGames>], undefined>[number]

Defined in ​

packages/api/src/schemas/hypixel/LeaderboardsSchema.ts:10

HypixelLeaderboards ​

Ƭ HypixelLeaderboards: z.infer<LeaderboardsSchema>["leaderboards"]

Defined in ​

packages/api/src/schemas/hypixel/LeaderboardsSchema.ts:9

HypixelOneTimeAchievement ​

Ƭ HypixelOneTimeAchievement: HypixelGameAchievements["one_time"][string]

Defined in ​

packages/api/src/schemas/hypixel/resources/AchievementsResourceSchema.ts:8

HypixelOneTimeGuildAchievement ​

Ƭ HypixelOneTimeGuildAchievement: HypixelGuildAchievements["one_time"][string]

Defined in ​

packages/api/src/schemas/hypixel/resources/GuildAchievementsResourceSchema.ts:8

HypixelPet ​

Ƭ HypixelPet: z.infer<PetsResourceSchema>["types"][number]

Defined in ​

packages/api/src/schemas/hypixel/resources/PetsResourceSchema.ts:7

HypixelPlayer ​

Ƭ HypixelPlayer: z.infer<PlayerSchema>["player"]

Type-safe representation of the Player object retrieved from the /player Hypixel endpoint. This type does not have its fields documented due to the size of the inferred type. Look at the source definition to see the data structure.

See

https://api.hypixel.net/#tag/Player-Data/paths/~1player/get

Defined in ​

packages/api/src/schemas/hypixel/PlayerSchema.ts:22

HypixelPlayerCounts ​

Ƭ HypixelPlayerCounts: z.infer<PlayerCountsSchema>

Type-safe representation of the data retrieved from the /counts Hypixel endpoint. This type does not have its fields documented due to the size of the inferred type. Look at the source definition to see the data structure.

See

https://api.hypixel.net/#tag/Other/paths/~1counts/get

Defined in ​

packages/api/src/schemas/hypixel/PlayerCountsSchema.ts:12

HypixelPunishmentStatistics ​

Ƭ HypixelPunishmentStatistics: z.infer<PunishmentStatisticsSchema>

Defined in ​

packages/api/src/schemas/hypixel/PunishmentStatisticsSchema.ts:5

HypixelQuest ​

Ƭ HypixelQuest: z.infer<QuestsResourceSchema>["quests"][string][number]

Defined in ​

packages/api/src/schemas/hypixel/resources/QuestsResourceSchema.ts:6

HypixelRarity ​

Ƭ HypixelRarity: z.infer<PetsResourceSchema>["rarities"][number]

Defined in ​

packages/api/src/schemas/hypixel/resources/PetsResourceSchema.ts:8

HypixelRecentGame ​

Ƭ HypixelRecentGame: Exclude<z.infer<RecentGamesSchema>["games"], undefined | null>[number]

Defined in ​

packages/api/src/schemas/hypixel/RecentGamesSchema.ts:8

HypixelResourcesOptions ​

Ƭ HypixelResourcesOptions: APIOptions & { refreshInterval?: number }

Extension of APIOptions that accepts a refresh interval for resources.

Defined in ​

packages/api/src/HypixelResources.ts:44

HypixelSession ​

Ƭ HypixelSession: Exclude<HypixelStatus["session"], null | undefined>

Defined in ​

packages/api/src/schemas/hypixel/StatusSchema.ts:7

HypixelSkyBlockAuction ​

Ƭ HypixelSkyBlockAuction: Exclude<z.infer<SkyBlockAuctionSchema>["auctions"], undefined | null>[number]

Defined in ​

packages/api/src/schemas/hypixel/skyblock/SkyBlockAuctionSchema.ts:10

HypixelSkyBlockAuctions ​

Ƭ HypixelSkyBlockAuctions: Exclude<z.infer<SkyBlockAuctionsSchema>, undefined | null>

Defined in ​

packages/api/src/schemas/hypixel/skyblock/SkyBlockAuctionSchema.ts:9

HypixelSkyBlockBazaarProduct ​

Ƭ HypixelSkyBlockBazaarProduct: z.infer<SkyBlockBazaarSchema>["products"][string]

Defined in ​

packages/api/src/schemas/hypixel/skyblock/SkyBlockBazaarSchema.ts:5

HypixelSkyBlockBingo ​

Ƭ HypixelSkyBlockBingo: z.infer<SkyBlockBingoResourceSchema>

Defined in ​

packages/api/src/schemas/hypixel/resources/skyblock/SkyBlockBingoResourceSchema.ts:6

HypixelSkyBlockBingoGoal ​

Ƭ HypixelSkyBlockBingoGoal: HypixelSkyBlockBingo["goals"][number]

Defined in ​

packages/api/src/schemas/hypixel/resources/skyblock/SkyBlockBingoResourceSchema.ts:7

HypixelSkyBlockBingoProfile ​

Ƭ HypixelSkyBlockBingoProfile: z.infer<SkyBlockBingoSchema>["events"][number]

Defined in ​

packages/api/src/schemas/hypixel/skyblock/SkyBlockBingoSchema.ts:5

HypixelSkyBlockCollection ​

Ƭ HypixelSkyBlockCollection: z.infer<SkyBlockCollectionsResourceSchema>["collections"][string]

Defined in ​

packages/api/src/schemas/hypixel/resources/skyblock/SkyBlockCollectionsResourceSchema.ts:6

HypixelSkyBlockElection ​

Ƭ HypixelSkyBlockElection: z.infer<SkyBlockElectionResourceSchema>["current"]

Defined in ​

packages/api/src/schemas/hypixel/resources/skyblock/SkyBlockElectionResourceSchema.ts:8

HypixelSkyBlockEndedAuction ​

Ƭ HypixelSkyBlockEndedAuction: Exclude<z.infer<SkyBlockEndedAuctionsSchema>["auctions"], undefined | null>[number]

Defined in ​

packages/api/src/schemas/hypixel/skyblock/SkyBlockAuctionSchema.ts:11

HypixelSkyBlockFiresale ​

Ƭ HypixelSkyBlockFiresale: z.infer<SkyBlockFiresalesSchema>["sales"][number]

Defined in ​

packages/api/src/schemas/hypixel/skyblock/SkyBlockFiresalesSchema.ts:6

HypixelSkyBlockItem ​

Ƭ HypixelSkyBlockItem: z.infer<SkyBlockItemsResourceSchema>["items"][number]

Defined in ​

packages/api/src/schemas/hypixel/resources/skyblock/SkyBlockItemsResourceSchema.ts:6

HypixelSkyBlockMayor ​

Ƭ HypixelSkyBlockMayor: z.infer<SkyBlockElectionResourceSchema>["mayor"]

Defined in ​

packages/api/src/schemas/hypixel/resources/skyblock/SkyBlockElectionResourceSchema.ts:6

HypixelSkyBlockMayorCandidate ​

Ƭ HypixelSkyBlockMayorCandidate: Exclude<z.infer<SkyBlockElectionResourceSchema>["current"], null | undefined>["candidates"][number]

Defined in ​

packages/api/src/schemas/hypixel/resources/skyblock/SkyBlockElectionResourceSchema.ts:7

HypixelSkyBlockMuseum ​

Ƭ HypixelSkyBlockMuseum: z.infer<SkyBlockMuseumSchema>["members"][string]

Defined in ​

packages/api/src/schemas/hypixel/skyblock/SkyBlockMuseumSchema.ts:8

HypixelSkyBlockNews ​

Ƭ HypixelSkyBlockNews: z.infer<SkyBlockNewsSchema>["items"][number]

Defined in ​

packages/api/src/schemas/hypixel/skyblock/SkyBlockNewsSchema.ts:6

HypixelSkyBlockProfile ​

Ƭ HypixelSkyBlockProfile: z.infer<SkyBlockProfileSchema>["profile"]

Defined in ​

packages/api/src/schemas/hypixel/skyblock/SkyBlockProfileSchema.ts:10

HypixelSkyBlockSkill ​

Ƭ HypixelSkyBlockSkill: z.infer<SkyBlockSkillsResourceSchema>["skills"][string]

Defined in ​

packages/api/src/schemas/hypixel/resources/skyblock/SkyBlockSkillsResourceSchema.ts:8

HypixelStatus ​

Ƭ HypixelStatus: z.infer<StatusSchema>

Defined in ​

packages/api/src/schemas/hypixel/StatusSchema.ts:6

HypixelTieredAchievement ​

Ƭ HypixelTieredAchievement: HypixelGameAchievements["tiered"][string]

Defined in ​

packages/api/src/schemas/hypixel/resources/AchievementsResourceSchema.ts:7

HypixelTieredGuildAchievement ​

Ƭ HypixelTieredGuildAchievement: HypixelGuildAchievements["tiered"][string]

Defined in ​

packages/api/src/schemas/hypixel/resources/GuildAchievementsResourceSchema.ts:7

MinecraftFormattingCode ​

Ƭ MinecraftFormattingCode: 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | "a" | "b" | "c" | "d" | "e" | "f" | "k" | "l" | "m" | "n" | "o" | "r"

Type containing all the currently-used Minecraft formatting codes on Hypixel.

See

• https://minecraft.wiki/w/Formatting_codes
• EnumMinecraftFormatting
• getFormattingCode

Defined in ​

packages/api/src/schemas/enums.ts:222

MojangProfile ​

Ƭ MojangProfile: z.infer<typeof UuidToProfileSchema>

Defined in ​

packages/api/src/schemas/mojang/UuidToProfileSchema.ts:5

Variables ​

EnumHypixelGames ​

• Const EnumHypixelGames: Values<["QUAKECRAFT", "SKYCLASH", "BUILD_BATTLE", "UHC", "LEGACY", "SKYBLOCK", "HOUSING", "MCGO", "WOOL_GAMES", "SURVIVAL_GAMES", "BATTLEGROUND", "MURDER_MYSTERY", "ARCADE", "ARENA", "TNTGAMES"]> = ZodEnumHypixelGames.enum

Enumerable object containing all the currently-known game types available in the Hypixel API. Specifically, this enum mirrors the "Type Name" column on the official Hypixel API documentation. It is also used as the key in the value HypixelResources.games.

Example

const bedwarsModes = hypixel.getResources().games.BEDWARS.modeNames
// same as
const bedwarsModes = hypixel.getResources().games[EnumHypixelGames.BEDWARS].modeNames

const bedwarsModes = hypixel.getResources().games.BEDWARS.modeNames
// same as
const bedwarsModes = hypixel.getResources().games[EnumHypixelGames.BEDWARS].modeNames

See

HypixelGame

Defined in ​

packages/api/src/schemas/enums.ts:65

EnumHypixelGuildAchievements ​

• Const EnumHypixelGuildAchievements: Values<["EXPERIENCE_KINGS", "WINNERS", "ONLINE_PLAYERS"]> = ZodEnumHypixelGuildAchievements.enum

Enumerable object containing all the currently-known guild achievement keys.

Example

const guild = await hypixel.getGuild("b876ec32-e396-476b-a115-8438d83c67d4")
const onlinePlayersValue = guild?.achievements.ONLINE_PLAYERS ?? 0
// same as
const onlinePlayersValue = guild?.achievements[EnumHypixelGuildAchievements.ONLINE_PLAYERS] ?? 0

const guild = await hypixel.getGuild("b876ec32-e396-476b-a115-8438d83c67d4")
const onlinePlayersValue = guild?.achievements.ONLINE_PLAYERS ?? 0
// same as
const onlinePlayersValue = guild?.achievements[EnumHypixelGuildAchievements.ONLINE_PLAYERS] ?? 0

See

HypixelGuild

Defined in ​

packages/api/src/schemas/enums.ts:19

EnumHypixelPetConsumables ​

• Const EnumHypixelPetConsumables: Values<["CARROT_ITEM", "BAKED_POTATO", "FEATHER", "ROTTEN_FLESH", "SLIME_BALL", "COOKED_BEEF", "RAW_FISH", "WATER_BUCKET", "WOOD_SWORD", "MILK_BUCKET", "GOLD_RECORD", "PORK", "PUMPKIN_PIE", "LEASH"]> = ZodEnumHypixelPetConsumables.enum

Enumerable object containing all the currently-known types of food that is available for lobby pets to eat. Each value is a CAMEL_CASE representation of the item name.

Example

const player = await hypixel.getPlayer("b876ec32-e396-476b-a115-8438d83c67d4")
const slimeBallsRemaining = player?.petConsumables?.SLIME_BALL
// same as
const slimeBallsRemaining = player?.petConsumables?.[EnumHypixelPetConsumables.SLIME_BALL]

const player = await hypixel.getPlayer("b876ec32-e396-476b-a115-8438d83c67d4")
const slimeBallsRemaining = player?.petConsumables?.SLIME_BALL
// same as
const slimeBallsRemaining = player?.petConsumables?.[EnumHypixelPetConsumables.SLIME_BALL]

See

HypixelPlayer

Defined in ​

packages/api/src/schemas/enums.ts:154

EnumHypixelPlayerCounts ​

• Const EnumHypixelPlayerCounts: Values<["QUAKECRAFT", "SKYCLASH", "BUILD_BATTLE", "UHC", "LEGACY", "SKYBLOCK", "HOUSING", "MCGO", "WOOL_GAMES", "SURVIVAL_GAMES", "BATTLEGROUND", "MURDER_MYSTERY", "ARCADE", "ARENA", "TNTGAMES"]> = ZodEnumHypixelPlayerCounts.enum

Enumerable object containing all the currently-known "game types" that are listed in the player counts from the Hypixel API endpoint /counts. Each game type is formatted in CAMEL_CASE.

Example

const playerCounts = await hypixel.getPlayerCounts()
const bedwarsPlayerCount = playerCounts.BEDWARS?.players
// same as
const bedwarsPlayerCount = playerCounts[EnumHypixelPlayerCounts.BEDWARS]?.players

const playerCounts = await hypixel.getPlayerCounts()
const bedwarsPlayerCount = playerCounts.BEDWARS?.players
// same as
const bedwarsPlayerCount = playerCounts[EnumHypixelPlayerCounts.BEDWARS]?.players

See

HypixelPlayer

Defined in ​

packages/api/src/schemas/enums.ts:112

EnumHypixelSkyBlockDungeonClasses ​

• Const EnumHypixelSkyBlockDungeonClasses: Values<["healer", "archer", "mage", "tank", "berserk"]> = ZodEnumHypixelSkyBlockDungeonClasses.enum

Enumerable object containing all the currently-known classes available in SkyBlock dungeons. Each value is all lowercase.

Example

const profile = await hypixel.getSkyBlockProfile("b876ec32-e396-476b-a115-8438d83c67d4")
const dungeons = profile?.members["b876ec32-e396-476b-a115-8438d83c67d4"]?.dungeons;

const healerExp = dungeons?.player_classes?.healer?.experience ?? 0;
// same as
const healerExp = dungeons?.player_classes?.[EnumHypixelSkyBlockDungeonClasses.healer]?.experience ?? 0;

console.log(`Player has ${healerExp} experience in the healer class.`);

const profile = await hypixel.getSkyBlockProfile("b876ec32-e396-476b-a115-8438d83c67d4")
const dungeons = profile?.members["b876ec32-e396-476b-a115-8438d83c67d4"]?.dungeons;

const healerExp = dungeons?.player_classes?.healer?.experience ?? 0;
// same as
const healerExp = dungeons?.player_classes?.[EnumHypixelSkyBlockDungeonClasses.healer]?.experience ?? 0;

console.log(`Player has ${healerExp} experience in the healer class.`);

See

HypixelSkyBlockProfile

Defined in ​

packages/api/src/schemas/enums.ts:90

EnumMinecraftFireworkShapes ​

• Const EnumMinecraftFireworkShapes: Values<["BURST", "STAR", "BALL_LARGE", "BALL", "CREEPER"]> = ZodEnumMinecraftFireworkShapes.enum

Enumerable object containing all the currently-known firework shapes available in the lobby fireworks customizer. Each value is a CAMEL_CASE representation of the item name.

Example

const player = await hypixel.getPlayer("b876ec32-e396-476b-a115-8438d83c67d4")
const playerFireworks = player?.fireworkStorage ?? [];

for(const firework of playerFireworks) {
   if(firework.shape === EnumMinecraftFireworkShapes.CREEPER) {
       console.log("Sssssssss...")
   }
}

const player = await hypixel.getPlayer("b876ec32-e396-476b-a115-8438d83c67d4")
const playerFireworks = player?.fireworkStorage ?? [];

for(const firework of playerFireworks) {
   if(firework.shape === EnumMinecraftFireworkShapes.CREEPER) {
       console.log("Sssssssss...")
   }
}

See

HypixelPlayer

Defined in ​

packages/api/src/schemas/enums.ts:178

EnumMinecraftFormatting ​

• Const EnumMinecraftFormatting: Values<["BLACK", "DARK_BLUE", "DARK_GREEN", "DARK_AQUA", "DARK_RED", "DARK_PURPLE", "GOLD", "GRAY", "DARK_GRAY", "BLUE", "GREEN", "AQUA", "RED", "LIGHT_PURPLE", "YELLOW", "WHITE", "OBFUSCATED"]> = ZodEnumMinecraftFormatting.enum

Enumerable object containing all the currently-used Minecraft formatting styles on Hypixel. Each value is a CAMEL_CASE representation of the color code name. For the formatting style's code, use getFormattingCode to convert it.

See

• https://minecraft.wiki/w/Formatting_codes
• MinecraftFormattingCode
• getFormattingCode

Defined in ​

packages/api/src/schemas/enums.ts:213

MONGODB_ID_REGEX ​

• Const MONGODB_ID_REGEX: RegExp

Regular expression for MongoDB object IDs. Guilds can be fetched from the Hypixel API based on their ID, which is in this format.

See

https://www.mongodb.com/docs/manual/reference/method/ObjectId/

Defined in ​

packages/api/src/util.ts:15

UUID_REGEX ​

• Const UUID_REGEX: RegExp

Regular expression for v4 UUIDs, with the dashes being optional. The Hypixel API uses and accepts them interchangeably.

See

https://api.hypixel.net/#section/Introduction/Notes

Defined in ​

packages/api/src/util.ts:8

Functions ​

getFormattingCode ​

▸ getFormattingCode(color): MinecraftFormattingCode

Convert a CAMEL_CASE Minecraft style name into the single-digit formatting code used for inline Minecraft text styles.

Parameters ​

Returns ​

MinecraftFormattingCode

The Minecraft formatting code for the provided style. This is a single character or a number 0-9.

Example

const player = await hypixel.getPlayer("b876ec32-e396-476b-a115-8438d83c67d4")
if(!player) return;

const rankColorCode = getFormattingCode(player.monthlyRankColor)
const message = `The player ${player.displayname} has a §${rankColorCode}${player.monthlyRankColor}§r rank!`
console.log(message) // The player Player123 has a §6GOLD§r rank!

const player = await hypixel.getPlayer("b876ec32-e396-476b-a115-8438d83c67d4")
if(!player) return;

const rankColorCode = getFormattingCode(player.monthlyRankColor)
const message = `The player ${player.displayname} has a §${rankColorCode}${player.monthlyRankColor}§r rank!`
console.log(message) // The player Player123 has a §6GOLD§r rank!

See

• https://minecraft.wiki/w/Formatting_codes
• EnumMinecraftFormatting
• MinecraftFormattingCode

Defined in ​

packages/api/src/util.ts:240

networkExpToLevel ​

▸ networkExpToLevel(exp): number

Function to calculate a player's current level based on how much experience they have. The amount of experience per level increases by 2,500 for each level, and starts at 10,000 to get from level 1 to 2. Players start at level 1 (i.e., no level 0).

This function does not return partial levels, and instead rounds down. Because experience per level grows quadratically, the calculated value between two levels is not going to be linear. For example, if level 2 requires 10,000 total XP and level 3 requires 22,500 total XP, the midpoint would be 16,250. However, this equates to ~2.525 on the curve. This is likely not the desired behavior by someone using this function, so we don't include it. If you want this value, use networkExpToLevelQuadratic. To get a linear progression to the next level, use networkLevelProgress.

Parameters ​

Returns ​

number

The network level that the given amount of experience is able to get a player to, but no more.

Throws

Error if the provided value is not an integer greater than or equal to 0.

See

• networkExpToLevelQuadratic
• networkLevelRemainingExp
• networkLevelToExp
• networkLevelExpDifference
• networkLevelProgress
• networkLevelRemainingExp

Example

networkExpToLevel(10000) // 2
networkExpToLevel(22500) // 3
networkExpToLevel(37500) // 4

networkExpToLevel(10000) // 2
networkExpToLevel(22500) // 3
networkExpToLevel(37500) // 4

Defined in ​

packages/api/src/util.ts:100

networkExpToLevelQuadratic ​

▸ networkExpToLevelQuadratic(exp): number

Function to calculate a player's current level based on how much experience they have. The amount of experience per level increases by 2,500 for each level, and starts at 10,000 to get from level 1 to 2. Players start at level 1 (i.e., no level 0).

Unlike networkExpToLevel, this function does support partial levels. Because experience per level grows quadratically, the calculated value between two levels is not going to be linear. For example, if level 2 requires 10,000 total XP and level 3 requires 22,500 total XP, the midpoint would be 16,250. However, this equates to ~1.525 on the curve. This is often not the desired value, but this function is available for when it is. To get a linear progression to the next level instead, use networkExpToLevel and networkLevelProgress.

Parameters ​

Returns ​

number

The maximum network level that the given amount of experience is able to get a player to.

Throws

Error if the provided value is not an integer greater than or equal to 0.

See

• networkExpToLevel
• networkLevelRemainingExp
• networkLevelToExp
• networkLevelExpDifference
• networkLevelProgress
• networkLevelRemainingExp

Example

networkExpToLevelQuadratic(16250) // 2.524937810560445

networkExpToLevelQuadratic(16250) // 2.524937810560445

Defined in ​

packages/api/src/util.ts:67

networkLevelExpDifference ​

▸ networkLevelExpDifference(a, b): number

The difference in experience required to reach two given network levels. This is just equivalent to networkLevelToExp(b) - networkLevelToExp(a). As a result, this function cannot handle partial levels.

Parameters ​

Returns ​

number

The difference in experience required to reach the second level from the first level.

Throws

Error if either of the provided values are less than 0 or not integers.

See

• networkLevelRemainingExp
• networkExpToLevel
• networkLevelToExp
• networkLevelProgress
• networkLevelRemainingExp

Example

networkLevelExpDifference(1, 2) // 10000
networkLevelExpDifference(2, 3) // 12500
networkLevelExpDifference(2, 4) // 27500

networkLevelExpDifference(1, 2) // 10000
networkLevelExpDifference(2, 3) // 12500
networkLevelExpDifference(2, 4) // 27500

Defined in ​

packages/api/src/util.ts:160

networkLevelProgress ​

▸ networkLevelProgress(exp, target, start?): number

Linear progress between two network levels.

Parameters ​

Returns ​

number

A floating point value between 0 and 1 indicating the point at which exp sits on the linear scale between start and target. Value will be greater than 1 if exp is already greater than the required experience for the target level, or will be less than 0 if exp is less than the required experience for the start level.

Throws

• Error if either start or target are less than 0 or not integers.
• Error if target and start are equal to each other.

Example

// Progress to get to the next level.
const exp = 16250; // (level 2 EXP + level 3 EXP) / 2
const level = networkExpToLevel(exp); // 2
const remaining = networkLevelProgress(exp, level + 1, level); // 0.5

// Progress to get to the next level.
const exp = 16250; // (level 2 EXP + level 3 EXP) / 2
const level = networkExpToLevel(exp); // 2
const remaining = networkLevelProgress(exp, level + 1, level); // 0.5

See

• networkLevelRemainingExp
• networkExpToLevel
• networkLevelToExp
• networkLevelExpDifference
• networkLevelRemainingExp

Defined in ​

packages/api/src/util.ts:219

networkLevelRemainingExp ​

▸ networkLevelRemainingExp(exp, level): number

Calculates the amount of experience needed to reach a given network level starting from the provided experience.

Parameters ​

Returns ​

number

The remaining amount of XP required to reach the provided level. If the starting amount of XP is already passed the required amount of XP for the level, a negative number will be returned, indicative of how much XP it is over (or 0, if the XP is exactly the right amount).

Throws

Error if the provided level is less than 0 or not an integer.

Example

// Amount of experience remaining to get to the next level.
const exp = 50000;
const level = networkExpToLevel(exp); // 4
const remaining = networkLevelRemainingExp(exp, level + 1); // 5000

// Amount of experience remaining to get to the next level.
const exp = 50000;
const level = networkExpToLevel(exp); // 4
const remaining = networkLevelRemainingExp(exp, level + 1); // 5000

See

• networkLevelRemainingExp
• networkExpToLevel
• networkLevelToExp
• networkLevelExpDifference
• networkLevelProgress

Defined in ​

packages/api/src/util.ts:186

networkLevelToExp ​

▸ networkLevelToExp(level): number

Calculate the amount of experience required to reach a given network level starting from zero experience. This function is not able to handle partial levels (i.e., non-integer inputs). To get a linear partial level, use networkLevelExpDifference. Getting the quadratic partial level is currently not supported.

Parameters ​

Returns ​

number

The minimum amount of experience a player would need to get in order to get from 0 EXP to the provided level.

Throws

Error if the provided value is not an integer greater than or equal to 1.

See

• networkExpToLevelQuadratic
• networkLevelRemainingExp
• networkExpToLevel
• networkLevelExpDifference
• networkLevelProgress
• networkLevelRemainingExp

Example

networkLevelToExp(1) // 0
networkLevelToExp(2) // 10000
networkLevelToExp(3) // 22500
networkLevelToExp(4) // 37500

networkLevelToExp(1) // 0
networkLevelToExp(2) // 10000
networkLevelToExp(3) // 22500
networkLevelToExp(4) // 37500

Defined in ​

packages/api/src/util.ts:130