Shop

A fully-featured server shop system with category-based GUIs, per-item permissions, stock limits, spawner support, and enchanted books.

Overview

EssentialsC includes a powerful built-in shop system that lets players buy and sell items through intuitive inventory GUIs. The shop is fully configurable via YAML files and supports categories, pagination, stock limits, custom items, spawners, enchanted books, and command rewards.

All transactions are logged to a dedicated SQLite database (shop.db) for audit trails and analytics.

Tip Use /shop reload to hot-reload shop files without restarting the server.

Commands

/shop [category] [page] true
Open the main shop menu or jump directly to a category page.
/shop reload op
Reload all shop configuration files. Requires essentialsc.shop.admin.

How It Works

When a player runs /shop, the plugin opens the main menu GUI. This menu displays all enabled categories as clickable icons. Clicking a category opens its paginated item grid.

Inside a category:

  • Left-click an item to buy 1 unit.
  • Right-click an item to sell 1 unit.
  • Shift + left-click to buy a full stack (up to max-stack).
  • Shift + right-click to sell a full stack.
  • Click the balance head to refresh your balance display.
  • Use arrow buttons to navigate pages.

Permissions

essentialsc.shop true
Access the /shop command and browse categories.
essentialsc.shop.admin op
Reload shop configs with /shop reload.
essentialsc.shop.<category> true
Per-category permission. Set in the category config to restrict access.
essentialsc.shop.item.<item> true
Per-item permission. Set on individual shop items to restrict buying/selling.

Item Features

✓
Custom Display MiniMessage names, lore, glow, and item flags.
✓
Player Heads Texture URLs, base64, or skull owner support.
✓
Spawners Sell mob spawners with configurable entity types.
✓
Enchanted Books Stored enchantments with full NBT preservation.
✓
Stock Limits Set finite stock per item. Restock manually or via commands.
✓
Command Rewards Execute console commands on purchase (%player%, %amount%).

GUI Layout

The category GUI uses a 54-slot inventory with the following layout:

┌──────────────────────────────────────────────────────┐
│  0-44  Item slots (45 slots for shop items)           │
│  45    Previous page arrow                            │
│  47    Balance head (click to refresh)                │
│  48    Back to categories / Close                     │
│  49    Page indicator (Page X/Y)                      │
│  50    Balance head (main menu)                       │
│  53    Next page arrow                                │
└──────────────────────────────────────────────────────┘

Empty slots can be filled with a configurable material (default: BLACK_STAINED_GLASS_PANE).

Transaction Logging

When shop.log-transactions is enabled in config.yml, every purchase and sale is recorded to shop.db:

  • purchase_history — UUID, item ID, amount, price, timestamp
  • sell_history — UUID, item ID, amount, price, timestamp

Both tables are indexed by UUID for fast lookups.

Language Keys

shop.disabled
Sent when the shop system is disabled.
shop.invalid-category
Sent when a category does not exist.
shop.not-buyable
Sent when trying to buy a non-buyable item.
shop.not-sellable
Sent when trying to sell a non-sellable item.
shop.out-of-stock
Sent when an item has zero stock remaining.
shop.not-enough-stock
Sent when stock is lower than the requested amount.
shop.not-enough-money
Sent when the player cannot afford the purchase.
shop.inventory-full
Sent when the player has no inventory space.
shop.not-enough-items
Sent when the player lacks items to sell.
shop.purchase-success
Sent on successful purchase. Placeholders: <item>, <amount>, <price>
shop.sale-success
Sent on successful sale. Placeholders: <item>, <amount>, <price>
shop.reload-success
Sent after /shop reload completes.

Troubleshooting

"Shop is disabled"
The shop system is turned off in config.yml. Set shop.enabled: true and reload.

"Invalid category"
The category ID you passed to /shop <category> does not exist. Check the file names in plugins/EssentialsC/shop/.

Category not showing in main menu
Verify the category file exists, enabled: true is set, and you have the required permission if one is configured.

Items not appearing in category
Check that material is a valid Bukkit Material name. Invalid materials are silently skipped during load.

"You do not have permission"
You need essentialsc.shop for the base command, or a per-category/per-item permission node set by the server admin.

"Not enough money"
Your balance is lower than the item's buy-price. Check your balance with /balance.

"Inventory full"
Free up inventory space before purchasing. The plugin checks for available slots and similar item stacks.

"Out of stock"
The item has a finite stock that reached zero. An admin must increase the stock in the category YAML file and reload.

"Not enough items"
You tried to sell more of an item than you carry. For enchanted books and spawners, the item must match exactly (NBT included).

Enchantments not applying
Use modern enchantment keys like sharpness or unbreaking. Legacy Bukkit names like DAMAGE_ALL will not resolve.

Spawner type resets to Pig
The spawner-type value is not a valid Bukkit EntityType. Check the EntityType enum for valid names.

Head texture not loading
Ensure texture-url is a direct link to a Minecraft texture server, or use skull-owner with a valid player name.

Changes not applying after edit
Shop files are not live-reloaded on save. Run /shop reload or /essc reload after editing.

Auto-layout placing items on navigation slots
Reduce shop.items-per-page in config.yml or manually assign slot and page to each item.