Skip to content

SkyBlock Items ​

The items module (skyblock-items.ts) converts the raw Hypixel SkyBlock item registry JSON into readonly, fully-typed objects. It exposes a single parser, parseSkyBlockItems, which mirrors the raw API field-for-field with no computation or derived values. Missing numbers become 0, missing strings become "", and boolean fields are true only when the raw value is exactly true.

parseSkyBlockItems ​

Parses the SkyBlock item registry (/resources/skyblock/items) into an array of SkyBlockItem.

ts
function parseSkyBlockItems(items: unknown[]): SkyBlockItem[];

Null / empty behavior ​

  • Entries that are not non-array objects are skipped.
  • Object-array fields (salvages, gemstoneSlots, requirements, catacombsRequirements, components, recipes, and each cost list) return [] when their raw field is missing or not an array; non-object entries are filtered out.
  • upgradeCosts is a nested array: each inner entry is [] when not an array, with non-object elements filtered out.
  • Map fields (stats, enchantments, tieredStats, museumData.parent, museumData.armorSetDonationXp, recipe.ingredientSymbols, itemSpecific) keep only entries whose values are of the expected type.
  • durability is the raw durability when it is a string or number, otherwise 0.
  • hasUuid is the raw has_uuid when it is a string, otherwise the boolean has_uuid === true.
  • Always returns an array (possibly empty), never null.

Returned type tree ​

SkyBlockItem ​

An entry returned by parseSkyBlockItems.

ts
interface SkyBlockItem {
  readonly id: string;
  readonly name: string;
  readonly material: string;
  readonly durability: number | string;
  readonly skin: SkyBlockItemSkin;
  readonly itemModel: string;
  readonly category: string;
  readonly categoryDisplay: string;
  readonly tier: string;
  readonly rarity: string;
  readonly npcSellPrice: number;
  readonly motesSellPrice: number;
  readonly salvages: ReadonlyArray<SkyBlockItemCost>;
  readonly salvage: SkyBlockItemCost;
  readonly raritySalvageable: boolean;
  readonly salvageableFromRecipe: boolean;
  readonly stats: Readonly<Record<string, number>>;
  readonly tieredStats: Readonly<Record<string, ReadonlyArray<number>>>;
  readonly miningFortune: number;
  readonly unstackable: boolean;
  readonly museumData: SkyBlockItemMuseumData;
  readonly museum: boolean;
  readonly color: string;
  readonly soulbound: string;
  readonly hasUuid: boolean | string;
  readonly gemstoneSlots: ReadonlyArray<SkyBlockItemGemstoneSlot>;
  readonly glowing: boolean;
  readonly canAuction: boolean;
  readonly canTrade: boolean;
  readonly requirements: ReadonlyArray<SkyBlockItemRequirement>;
  readonly catacombsRequirements: ReadonlyArray<SkyBlockItemRequirement>;
  readonly canPlace: boolean;
  readonly generator: string;
  readonly generatorTier: number;
  readonly furniture: string;
  readonly components: ReadonlyArray<SkyBlockItemComponent>;
  readonly itemSpecific: Readonly<Record<string, SkyBlockJsonValue>>;
  readonly description: string;
  readonly upgradeCosts: ReadonlyArray<ReadonlyArray<SkyBlockItemCost>>;
  readonly gearScore: number;
  readonly dungeonItem: boolean;
  readonly dungeonItemConversionCost: SkyBlockItemCost;
  readonly canHaveAttributes: boolean;
  readonly canHaveBooster: boolean;
  readonly canRecombobulate: boolean;
  readonly cannotReforge: boolean;
  readonly forceWipeRecomb: boolean;
  readonly enchantments: Readonly<Record<string, number>>;
  readonly riftTransferrable: boolean;
  readonly loseMotesValueOnTransfer: boolean;
  readonly origin: string;
  readonly editioned: boolean;
  readonly hideFromApi: boolean;
  readonly doubleTapToDrop: boolean;
  readonly hideFromViewRecipeCommand: boolean;
  readonly swordType: string;
  readonly abilityDamageScaling: number;
  readonly crystal: string;
  readonly canBurnInFurnace: boolean;
  readonly serializable: boolean;
  readonly canInteract: boolean;
  readonly canInteractRightClick: boolean;
  readonly canInteractEntity: boolean;
  readonly privateIsland: string;
  readonly canHavePowerScroll: boolean;
  readonly isUpgradeableWithoutSoulbinding: boolean;
  readonly recipes: ReadonlyArray<SkyBlockItemRecipe>;
  readonly prestige: SkyBlockItemPrestige;
}
FieldRaw key / notes
idid.
namename.
materialmaterial.
durabilitydurability (string or number; otherwise 0).
skinskin.
itemModelitem_model.
categorycategory.
categoryDisplaycategory_display.
tiertier.
rarityrarity.
npcSellPricenpc_sell_price.
motesSellPricemotes_sell_price.
salvagessalvages.
salvagesalvage.
raritySalvageablerarity_salvageable.
salvageableFromRecipesalvageable_from_recipe.
statsstats (number map).
tieredStatstiered_stats (number-array map).
miningFortuneMINING_FORTUNE.
unstackableunstackable.
museumDatamuseum_data.
museummuseum.
colorcolor.
soulboundsoulbound.
hasUuidhas_uuid (string when string, else boolean).
gemstoneSlotsgemstone_slots.
glowingglowing.
canAuctioncan_auction.
canTradecan_trade.
requirementsrequirements.
catacombsRequirementscatacombs_requirements.
canPlacecan_place.
generatorgenerator.
generatorTiergenerator_tier.
furniturefurniture.
componentscomponents.
itemSpecificitem_specific (arbitrary JSON map).
descriptiondescription.
upgradeCostsupgrade_costs (array of cost arrays).
gearScoregear_score.
dungeonItemdungeon_item.
dungeonItemConversionCostdungeon_item_conversion_cost.
canHaveAttributescan_have_attributes.
canHaveBoostercan_have_booster.
canRecombobulatecan_recombobulate.
cannotReforgecannot_reforge.
forceWipeRecombforce_wipe_recomb.
enchantmentsenchantments (number map).
riftTransferrablerift_transferrable.
loseMotesValueOnTransferlose_motes_value_on_transfer.
originorigin.
editionededitioned.
hideFromApihide_from_api.
doubleTapToDropdouble_tap_to_drop.
hideFromViewRecipeCommandhide_from_viewrecipe_command.
swordTypesword_type.
abilityDamageScalingability_damage_scaling.
crystalcrystal.
canBurnInFurnacecan_burn_in_furnace.
serializableserializable.
canInteractcan_interact.
canInteractRightClickcan_interact_right_click.
canInteractEntitycan_interact_entity.
privateIslandprivate_island.
canHavePowerScrollcan_have_power_scroll.
isUpgradeableWithoutSoulbindingis_upgradeable_without_soulbinding.
recipesrecipes.
prestigeprestige.

SkyBlockItemSkin ​

Read from the raw skin object.

ts
interface SkyBlockItemSkin {
  readonly value: string;
  readonly signature: string;
}

SkyBlockItemCost ​

A single cost entry. Used by salvages, salvage, gemstoneSlots[].costs, upgradeCosts, dungeonItemConversionCost, and prestige.costs.

ts
interface SkyBlockItemCost {
  readonly type: string;
  readonly essenceType: string;
  readonly itemId: string;
  readonly coins: number;
  readonly amount: number;
}
FieldRaw key
typetype
essenceTypeessence_type
itemIditem_id
coinscoins
amountamount

SkyBlockItemMuseumData ​

Read from the raw museum_data object.

ts
interface SkyBlockItemMuseumData {
  readonly donationXp: number;
  readonly category: string;
  readonly parent: Readonly<Record<string, string>>;
  readonly mappedItemIds: ReadonlyArray<string>;
  readonly gameStage: string;
  readonly armorSetDonationXp: Readonly<Record<string, number>>;
}
FieldRaw key
donationXpdonation_xp
categorycategory
parentparent (string map)
mappedItemIdsmapped_item_ids
gameStagegame_stage
armorSetDonationXparmor_set_donation_xp (number map)

SkyBlockItemGemstoneSlot ​

An entry of gemstoneSlots.

ts
interface SkyBlockItemGemstoneSlot {
  readonly slotType: string;
  readonly costs: ReadonlyArray<SkyBlockItemCost>;
  readonly requirements: ReadonlyArray<SkyBlockItemGemstoneSlotRequirement>;
}
FieldRaw key
slotTypeslot_type
costscosts
requirementsrequirements

SkyBlockItemGemstoneSlotRequirement ​

An entry of SkyBlockItemGemstoneSlot.requirements.

ts
interface SkyBlockItemGemstoneSlotRequirement {
  readonly type: string;
  readonly dataKey: string;
  readonly value: string;
  readonly operator: string;
}
FieldRaw key
typetype
dataKeydata_key
valuevalue
operatoroperator

SkyBlockItemRequirement ​

Used by requirements and catacombsRequirements. Self-referential: a requirement may contain nested requirements.

ts
interface SkyBlockItemRequirement {
  readonly type: string;
  readonly skill: string;
  readonly level: number;
  readonly tier: number;
  readonly dungeonType: string;
  readonly slayerBossType: string;
  readonly collection: string;
  readonly reward: string;
  readonly faction: string;
  readonly reputation: number;
  readonly trophyType: string;
  readonly rabbit: string;
  readonly mode: string;
  readonly kuudraTier: string;
  readonly profileType: string;
  readonly amount: number;
  readonly loreIndex: number;
  readonly minimumAge: number;
  readonly minimumAgeUnit: string;
  readonly requirements: ReadonlyArray<SkyBlockItemRequirement>;
}
FieldRaw key
typetype
skillskill
levellevel
tiertier
dungeonTypedungeon_type
slayerBossTypeslayer_boss_type
collectioncollection
rewardreward
factionfaction
reputationreputation
trophyTypetrophy_type
rabbitrabbit
modemode
kuudraTierkuudra_tier
profileTypeprofile_type
amountamount
loreIndexlore_index
minimumAgeminimum_age
minimumAgeUnitminimum_age_unit
requirementsnested requirements

SkyBlockItemComponent ​

An entry of components.

ts
interface SkyBlockItemComponent {
  readonly type: string;
  readonly showItemsFirst: ReadonlyArray<string>;
  readonly showItemsLast: ReadonlyArray<string>;
  readonly excludedItems: ReadonlyArray<string>;
  readonly sortByCategory: boolean;
  readonly allowDuplicates: boolean;
  readonly sortByAccessoryTier: boolean;
}
FieldRaw key
typetype
showItemsFirstshow_items_first
showItemsLastshow_items_last
excludedItemsexcluded_items
sortByCategorysort_by_category
allowDuplicatesallow_duplicates
sortByAccessoryTiersort_by_accessory_tier

SkyBlockItemRecipe ​

An entry of recipes.

ts
interface SkyBlockItemRecipe {
  readonly output: SkyBlockItemRecipeOutput;
  readonly ingredientSymbols: Readonly<Record<string, string>>;
  readonly matrix: ReadonlyArray<string>;
  readonly allowQuickCrafting: boolean;
}
FieldRaw key
outputoutput
ingredientSymbolsingredient_symbols (string map)
matrixmatrix
allowQuickCraftingallow_quick_crafting

SkyBlockItemRecipeOutput ​

ts
interface SkyBlockItemRecipeOutput {
  readonly itemId: string;
}

itemId is read from the raw output.item_id.

SkyBlockItemPrestige ​

Read from the raw prestige object.

ts
interface SkyBlockItemPrestige {
  readonly itemId: string;
  readonly costs: ReadonlyArray<SkyBlockItemCost>;
}
FieldRaw key
itemIditem_id
costscosts

SkyBlockJsonValue ​

The recursive JSON value type used by SkyBlockItem.itemSpecific, preserving arbitrary per-item data verbatim.

ts
type SkyBlockJsonValue =
  | string
  | number
  | boolean
  | null
  | readonly SkyBlockJsonValue[]
  | { readonly [key: string]: SkyBlockJsonValue };

Released under the MIT License.