Superior Shop

🛒 Superior Shop

Superior Shop 是一套以 KubeJS 为核心的商店系统，专为需要的不只是基础买卖菜单的整合包打造。

创建简洁的商店分类、注册自定义商品、将物品设为需要进度解锁、根据购买次数调整价格，还能运行带有自定义效果的限时特卖。小型商店可以轻松上手，整合包作者也能充分掌控完整的经济系统、季节性活动和注重进度的玩法。

✨ 功能特色

• 📦 完全通过 KubeJS 注册购买和出售商品
• 🗂️ 创建带有图标、排序和可见性设置的自定义分类
• 💰 为每件商品设置价格、数量、NBT、悬停主题和排序
• 📈 添加购买次数限制和价格递增
• 🔒 根据玩家进度检查设置商品解锁条件
• ⚡ 对分类或带标签的商店商品开展限时特卖
• 🧩 通过KubeJS 事件响应商店活动
• 🎯 非常适合用于教程、战利品箱、资源兑换、修饰项和限时活动

🧪 简单的 KubeJS 示例

📁 创建分类

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: '初始补给',
    icon: 'minecraft:bread',
    order: 0,
    hidden: false,
  },

  mob_drops: {
    title: '生物掉落物',
    icon: 'minecraft:bone',
    order: 1,
    hidden: false,
  },

  special_offers: {
    title: '特别优惠',
    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)
    })
  })
})