Shopkeeper

🧭 Overview

The Shopkeeper is a core game mechanic that allows players to purchase items during the preparation phase. Items are grouped into categories to make browsing and purchasing fast and intuitive.

---

📦 Items

All items are stored inside the /items/ folder. Each item has its own file and configuration.

Every item file is made up of modules, which define how the item behaves in the shop.

---

📚 Categories

Category	Description
Permanent / Upgrades	Items that persist and can be upgraded (e.g., swords, armor).
Consumables	Items that can be purchased repeatedly (e.g., Golden Apples, Ender Pearls).
Eggs	Special items that spawn minions when right-clicked.
TNT	Throwable explosives activated by left-clicking.

---

🛠 Creating Items

1. Open the /items/ directory.

2. Choose an existing item file as a template.

3. Duplicate it.

4. Rename the copy to your new item’s name.

5. Edit the configuration to define your item’s behavior.

• Organize your /items/ folder logically — one file per item.

• Use shared-id for clear upgrade paths.

• Keep categories small and intuitive for players.

• Combine modules creatively — e.g., Upgrade + Enchant + Mythic for complex items.

---

🧩 Item Modules

Each module defines a specific part of how the item works.

---

🪄 Mythic Module

mythic:
  is-mythic: true

Marks the item as Mythic, linking it to mythic-related features (e.g., augments, rare effects).

---

💰 Purchase Module

purchase:
  gold-cost: 750
  round-unlock: 1
  consumable: true
  category: "SUMMONS"

Defines purchase details and availability.

Key	Description
gold-cost	How much gold the item costs.
round-unlock	Round number when the item becomes available.
consumable	Whether it can be bought multiple times.
category	The category this item belongs to.

---

🔼 Upgrade Module

upgrade:
  shared-id: "chestplate"
  upgrade-tier: 2

Items with the same shared-id form an upgrade path. Higher upgrade-tier values = better versions.

---

✨ Enchant Module

Example 1 (basic):

enchant:
  is-enchant: true
  max-purchases: 2
  cost-increase-per-purchase: 25
  apply-to:
    - BOW
  apply-enchants:
    - "enchant{PUNCH} power{1}"

Example 2 (advanced, per-item):

enchant:
  is-enchant: true
  apply-to:
    LEATHER_BOOTS:
      - "enchant{FEATHER_FALLING} power{4}"
    DIAMOND_CHESTPLATE:
      - "enchant{PROTECTION} power{1}"

cost-increase-per-purchase is a percentage increase per buy.

Example with 25% increase:

• Level 1: 500 Gold

• Level 2: 625 Gold

• Level 3: 750 Gold

---

🧱 Equipment Builder Module

equipment-builder:
  39:
    ignore-slot: false
    lore:
      - "&8Permanent"
    type: IRON_HELMET
    amount: 1
    damage: 0
    model: 0
    glint: false
    attributes:
      - "attribute{ARMOR} operation{ADD_NUMBER} value{2.5}"
      - "attribute{ARMOR_TOUGHNESS} operation{ADD_NUMBER} value{1.0}"

Controls what item is given, its visuals, and stats.

Key	Description
ignore-slot	Whether the slot should be ignored when given.
type	The item type (e.g., IRON_HELMET).
attributes	Attribute modifiers (armor, damage, etc.).
enchants	Optional enchantments.
lore	Text lines shown in the tooltip.

---

💡 Examples

⚔️ Iron Sword

purchase:
  gold-cost: 500
  round-unlock: 5
  consumable: false
  category: "WEAPONS"

upgrade:
  shared-id: "sword"
  upgrade-tier: 2

equipment-builder:
  0:
    ignore-slot: false
    lore:
      - "&8Permanent"
    type: IRON_SWORD
    attributes:
      - "attribute{ATTACK_DAMAGE} operation{ADD_NUMBER} value{5.0}"
      - "attribute{ATTACK_SPEED} operation{ADD_NUMBER} value{-2.6}"

---

🧪 Potion

purchase:
  gold-cost: 500
  round-unlock: 1
  consumable: true
  category: "POTIONS"

equipment-builder:
  0:
    ignore-slot: true
    lore:
      - "&8Consumable"
    type: SPLASH_POTION
    potions:
      - "effect{HASTE} duration{200} amplifier{0} ambient{false} particles{true}"

---

🪄 Breeze Egg

purchase:
  gold-cost: 750
  round-unlock: 1
  consumable: true
  category: "SUMMONS"

equipment-builder:
  0:
    ignore-slot: true
    lore:
      - "&8Consumable"
    type: BREEZE_SPAWN_EGG

---

🌟 Sharpness Enchant

purchase:
  gold-cost: 500
  round-unlock: 1
  category: "ENCHANTS"

enchant:
  is-enchant: true
  max-purchases: 5
  cost-increase-per-purchase: 25
  apply-to:
    - WOODEN_SWORD
    - STONE_SWORD
    - IRON_SWORD
    - DIAMOND_SWORD
    - NETHERITE_SWORD
  enchants:
    - "enchant{SHARPNESS} power{1}"

---

🃏 Random Augment

mythic:
  is-mythic: true

enchant:
  is-enchant: true

command:
  - "console->al player {PLAYER} ROLL_AUGMENT PRISMATIC"

equipment-builder:
  0:
    name: "&cRandom Augment"
    type: PAPER
    model: 11205302

---

🧩 ItemsAdder Integration

purchase:
  gold-cost: 500
  round-unlock: 5
  consumable: false
  category: "WEAPONS"

upgrade:
  shared-id: "sword"
  upgrade-tier: 2

equipment-builder:
  0:
    ignore-slot: false
    custom: "namespace:id"