Shop Config

Complete reference for shop YAML files: main.yml, category files, and per-item configuration.

File Structure

All shop files live in plugins/EssentialsC/shop/. The folder is created automatically on first run.

plugins/EssentialsC/shop/
├── main.yml          # Category definitions & main menu settings
├── farming.yml       # Example category file
├── mining.yml
├── blocks.yml
├── combat.yml
├── tools.yml
├── redstone.yml
├── spawners.yml
├── enchanted_books.yml
└── misc.yml

Category files are auto-discovered. Any .yml file in the shop folder (except main.yml) becomes a category.

main.yml

Defines the main menu layout and category references. Categories listed here get custom slots; files not listed are auto-placed.

title: "Server Shop"
size: 54
fill-empty: true
fill-material: "BLACK_STAINED_GLASS_PANE"

categories:
  farming:
    name: "Farming"
    material: "WHEAT"
    slot: 20
    file: "farming.yml"
    lore:
      - "Buy and sell farming items"
      - ""
      - "Click to open"
    permission: "essentialsc.shop.farming"
    enabled: true

  mining:
    name: "Mining"
    material: "DIAMOND_PICKAXE"
    slot: 22
    file: "mining.yml"

Category Fields

name
Display name in MiniMessage format. Shown on the category icon and in the category GUI title.
material
Bukkit Material name for the category icon. Default: CHEST
slot
Inventory slot (0-based) for the category icon in the main menu. Default: 0
file
YAML filename containing the items for this category. Default: <id>.yml
lore
String list of MiniMessage lore lines shown on the category icon.
permission
Optional LuckPerms permission node required to see this category. Default: none
enabled
Whether the category is visible. Default: true

Category Files

Each category file contains an items section where every key is a unique item ID.

items:
  wheat:
    material: "WHEAT"
    name: "Wheat"
    lore:
      - "Basic farming crop"
      - ""
      - "Good for bread!"
    amount: 1
    buy-price: 10.0
    sell-price: 5.0
    buyable: true
    sellable: true
    slot: 10
    page: 1
    max-stack: 64
    stock: -1
    glow: false

  diamond_sword:
    material: "DIAMOND_SWORD"
    name: "Sharp Blade"
    buy-price: 250.0
    sell-price: 125.0
    enchantments:
      sharpness: 5
      unbreaking: 3
    slot: 11
    page: 1
    permission: "essentialsc.shop.item.diamond_sword"

  zombie_spawner:
    material: "SPAWNER"
    name: "Zombie Spawner"
    spawner: true
    spawner-type: "ZOMBIE"
    buy-price: 5000.0
    sellable: false
    slot: 12
    page: 1

  mending_book:
    material: "ENCHANTED_BOOK"
    name: "Mending Book"
    enchanted-book: true
    enchanted-book-enchants:
      mending: 1
    buy-price: 1500.0
    sell-price: 750.0
    slot: 13
    page: 1

  custom_head:
    material: "PLAYER_HEAD"
    name: "Special Head"
    texture-url: "https://textures.minecraft.net/texture/abc123..."
    buy-price: 100.0
    slot: 14
    page: 1

  reward_item:
    material: "DIAMOND"
    name: "Rank Upgrade"
    buy-price: 10000.0
    commands:
      - "lp user %player% parent set vip"
      - "broadcast %player% upgraded to VIP!"
    slot: 15
    page: 1

Item Fields

material required
Bukkit Material name. Default: STONE
name
MiniMessage display name. If unset, uses the item ID.
lore
String list of MiniMessage lore lines.
amount
Base stack size of the item. Default: 1
buy-price
Price per unit to buy. Default: 0.0
sell-price
Price per unit to sell. Default: 0.0
buyable
Whether players can buy this item. Default: true
sellable
Whether players can sell this item. Default: true
slot
Inventory slot (0-44) for this item. Auto-assigned if omitted.
page
Page number (1-based) for this item. Auto-assigned if omitted.
max-stack
Maximum stack size for shift-click transactions. Default: 64
stock
Finite stock amount. -1 means unlimited. Default: -1
permission
LuckPerms node required to see/buy/sell this item. Default: none
glow
Adds a hidden enchantment glow. Default: false
enchantments
Map of enchantment keys to levels (e.g., sharpness: 5). Applied directly to the item.
texture-url
Full URL to a player head texture. Only for PLAYER_HEAD.
skull-owner
Player name for the skull owner. Only for PLAYER_HEAD.
spawner
Set to true to treat this item as a mob spawner. Default: false
spawner-type
EntityType for the spawner (e.g., ZOMBIE, SKELETON). Default: PIG
enchanted-book
Set to true to treat this item as an enchanted book. Default: false
enchanted-book-enchants
Map of stored enchantments for books (e.g., mending: 1). Uses stored enchant NBT.
commands
List of console commands executed on purchase. Placeholders: %player%, %amount%

Auto Layout

If you omit slot and page from items, EssentialsC automatically lays them out:

  1. Items are placed sequentially starting from slot 0 on page 1.
  2. Each page holds up to shop.items-per-page items (default 28).
  3. When a page fills, the next item starts on page 2, and so on.
  4. Available slots are 0-44 (the bottom row is reserved for navigation).

To use explicit layout, define slot and page on every item. Mixing auto and explicit layout in the same category is not recommended.

Reloading

Changes to shop files are not live. Use one of these methods to apply:

  • In-game: /shop reload (requires essentialsc.shop.admin)
  • Console: essc reload (reloads all plugin configs including shop)
  • Server restart
Note Reloading does not reset player stock. Stock values are held in memory and reset only on full restart unless you manually edit the config and reload.

Troubleshooting

"Invalid shop fill-material"
The material name in shop.fill-material is not a valid Bukkit Material. Check the Material enum for valid names.

Category not showing
Verify the file exists in plugins/EssentialsC/shop/, the category is enabled: true, and you have the required permission.

Items not appearing
Check that material is a valid Bukkit Material. Invalid materials silently skip the item during load.

Enchantments not working
Use modern NamespacedKey names (e.g., sharpness not DAMAGE_ALL). The plugin resolves them via Registry.ENCHANTMENT.

Spawner type resets to Pig
The spawner-type value must be a valid Bukkit EntityType. Invalid values fall back to PIG.

Head texture not loading
Ensure the texture-url is a direct link to a Minecraft texture server. Base64 textures are also supported via the internal texture system.