Superior Shop is a KubeJS-first shop system built for modpacks that need more than a basic buy/sell menu.
Create clean shop categories, register custom entries, lock items behind progression, scale prices based on purchases, and run timed flash sales with custom effects. It stays simple for small shops, but gives modpack makers enough control for full economy systems, seasonal events, and progression-heavy gameplay.
ServerEvents.superiorShopCategories(event => {
event.category('starter', cat => {
cat.title('Starter Supplies') // Name shown in the shop
cat.icon('minecraft:emerald') // Icon used for the category
cat.order(0) // Lower numbers appear first
cat.hidden(false) // Set to true to hide the category
})
})
ServerEvents.superiorShopItems(event => {
const starter = event.category('starter') // Get the category by id
starter.item('minecraft:bread', 'buy', 5) // item id, side, base price
.hoverTheme('light_green') // Optional entry color/theme
.order(0) // Optional sort position in the category
starter.item('minecraft:rotten_flesh', 'sell', 2) // Sell entry example
.hoverTheme('dark_red')
.order(1)
})
ServerEvents.superiorShopItems(event => {
event.category('starter')
.item('minecraft:golden_apple', 'buy', 25)
.limit(5) // This entry can only be bought 5 times per player
.scalingMultiply(1.5) // Price increases by 1.5x after each purchase
.scalingRound('ceil') // Round the new price upward
.scalingMax(200) // Stop the price from going above 200
.hoverTheme('gold')
})
ServerEvents.superiorShopItems(event => {
event.category('starter')
.item('minecraft:elytra', 'buy', 2500)
.visibleIf(player => player.persistentData.getBoolean('killed_dragon'))
// Only shows if this player data flag is true
.hoverTheme('light_blue')
})
ServerEvents.superiorShopItems(event => {
event.category('starter')
.item('minecraft:iron_pickaxe', 'buy', 40)
.entryTag('mining_fever') // Tag lets a sale target this entry
})
SuperiorShop.startSale('mining_fever', 120, sale => { // 120 is how many seconds to run the event for
sale.message('Mining Fever: tagged items are 50% off for 2 minutes!')
sale.affectEntryTag('mining_fever', rule => rule.mulBuyPrice(0.5))
// Any entry with this tag gets the discount while the sale is active
})
ServerEvents.superiorShopBuyEntry(event => {
// Runs whenever a player buys from the shop
event.player.tell(`You spent ${event.totalPrice} shop currency.`)
})
ServerEvents.superiorShopSellEntry(event => {
// Runs whenever a player sells to the shop
if (event.totalPrice >= 100) {
// Example: give a small bonus for bigger sales
Utils.server.runCommandSilent(`/superior_shop add ${event.player.username} 10`)
}
})
// Categories are defined in one object so the shop layout is easy to edit.
const SHOP_CATEGORIES = {
starter_supplies: {
title: 'Starter Supplies',
icon: 'minecraft:bread',
order: 0,
hidden: false,
},
mob_drops: {
title: 'Mob Drops',
icon: 'minecraft:bone',
order: 1,
hidden: false,
},
special_offers: {
title: 'Special Offers',
icon: 'minecraft:golden_apple',
order: 2,
hidden: false,
},
}
// Items are grouped by category and then registered in a loop.
const SHOP_ITEMS = {
starter_supplies: {
defaults: {
side: 'buy', // Most entries in this category are buy entries
hoverTheme: 'light_green',
},
entries: [
{
item: 'minecraft:bread',
price: 5,
quantity: 8, // Buying this entry gives 8 bread
},
{
item: 'minecraft:torch',
price: 3,
quantity: 16,
},
{
item: 'minecraft:iron_pickaxe',
price: 40,
entryTag: 'starter_sale', // Lets a flash sale target this entry
},
],
},
mob_drops: {
defaults: {
side: 'sell', // Most entries in this category are sell entries
hoverTheme: 'dark_red',
},
entries: [
{
item: 'minecraft:rotten_flesh',
price: 2,
},
{
item: 'minecraft:bone',
price: 3,
},
{
item: 'minecraft:string',
price: 4,
},
],
},
special_offers: {
defaults: {
side: 'buy',
hoverTheme: 'gold',
},
entries: [
{
item: 'minecraft:golden_apple',
price: 25,
id: 'special_golden_apple', // Custom id for this shop entry
limit: 5, // Can only be bought 5 times
scalingPrice: {
mode: 'multiply',
factor: 1.5, // Price goes up by 1.5x after each purchase
round: 'ceil',
max: 200, // Price will never go above 200
},
},
{
item: 'minecraft:enchanted_book',
price: 150,
nbt: '{StoredEnchantments:[{id:"minecraft:unbreaking",lvl:3s}]}',
// Example of selling a specific NBT item
},
{
item: 'minecraft:elytra',
price: 2500,
visibleIf: player => player.persistentData.getBoolean('killed_dragon'),
// Only shows if you set this player data flag somewhere else in KubeJS
},
],
},
}
ServerEvents.superiorShopCategories(event => {
Object.entries(SHOP_CATEGORIES).forEach(([id, data]) => {
event.category(id, cat => {
cat.title(data.title)
cat.icon(data.icon)
cat.order(data.order)
cat.hidden(data.hidden)
})
})
})
function applyShopEntry(builder, entry, index, defaults) {
const hoverTheme = entry.hoverTheme ?? defaults.hoverTheme
const side = entry.side ?? defaults.side
if (entry.id) builder.id(entry.id)
if (entry.nbt) builder.nbt(entry.nbt)
if (hoverTheme) builder.hoverTheme(hoverTheme)
if (entry.entryTag) builder.entryTag(entry.entryTag)
if (entry.quantity !== undefined) builder.quantity(entry.quantity)
if (entry.limit !== undefined) builder.limit(entry.limit)
if (entry.scalingPrice) {
const scaling = entry.scalingPrice
if (scaling.mode === 'multiply') builder.scalingMultiply(scaling.factor)
if (scaling.round) builder.scalingRound(scaling.round)
if (scaling.max !== undefined) builder.scalingMax(scaling.max)
}
if (entry.visibleIf) builder.visibleIf(entry.visibleIf)
builder.order(entry.order ?? index)
}
ServerEvents.superiorShopItems(event => {
Object.entries(SHOP_ITEMS).forEach(([categoryId, categoryData]) => {
const category = event.category(categoryId)
const defaults = categoryData.defaults || {}
categoryData.entries.forEach((entry, index) => {
const side = entry.side ?? defaults.side ?? 'buy'
const builder = category.item(entry.item, side, entry.price)
applyShopEntry(builder, entry, index, defaults)
})
})
})
