🛒 Superior Shop

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.

✨ Features

• 📦 Register buy and sell entries entirely through KubeJS
• 🗂️ Create custom categories with icons, ordering, and visibility
• 💰 Set per-entry prices, quantities, NBT, hover themes, and order
• 📈 Add purchase limits and scaling prices
• 🔒 Gate entries behind player progression checks
• ⚡ Run flash sales on categories or tagged shop entries
• 🧩 Hook into shop activity with KubeJS events
• 🎯 Perfect for tutorials, loot boxes, resource exchanges, modifiers, and limited-time events

🧪 Simple KubeJS Examples

📁 Create a Category

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
  })
})

🛍️ Add Basic Buy and Sell Entries

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)
})

📈 Add a Limited Item with Scaling Price

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')
})

🔒 Hide an Entry Until the Player Unlocks It

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')
})

⚡ Tag Entries and Run a Flash Sale

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
})

🎁 React to Purchases or Sales

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`)
  }
})

🧱 Data-Driven Shop Example

// 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)
    })
  })
})