EssentialsC / Shop Configuration

Shop Configuration

Build buy/sell categories and items for the in-game shop, all driven from YAML.

Overview

The shop lives under /plugins/EssentialsC/shop/. A main.yml file defines the categories shown in the main shop GUI, and each category points at its own file (for example farming.yml) containing the actual buyable and sellable items.

File Purpose
shop/main.yml Defines every category: its display name, icon, lore, GUI slot, and which file holds its items. Also sets items-per-page for category pagination.
shop/<category>.yml One file per category, each containing an items section keyed by item ID.
On first run, EssentialsC ships default category files for farming, mining, spawners, enchanted_books, tools, blocks, redstone, misc, and combat. Delete or edit any of these freely - they're just starting points.

Categories

Each entry under categories in main.yml controls one icon in the main shop GUI.

Key Type Description
name String Display name shown on the category icon. Supports MiniMessage formatting.
material String Bukkit material used as the category icon. Defaults to CHEST.
texture String Optional player head texture (hash, URL, or base64) if you want a custom-textured head as the icon instead of a material.
lore List Lore lines shown on the category icon. Supports MiniMessage formatting.
slot Integer Slot in the main shop GUI the category icon is placed in. Defaults to 0.
file String The filename (relative to shop/) containing this category's items. Defaults to <category-id>.yml.
permission String Optional permission required to see and open this category.
enabled Boolean Whether the category is loaded and shown at all. Defaults to true.

Items

Inside a category file, each entry under items describes one buyable/sellable item.

Key Type Description
material String Bukkit material for the item. Defaults to STONE.
amount Integer Stack size for the display item. Defaults to 1.
name String Display name. Supports MiniMessage formatting.
lore List Extra lore lines, shown above the buy/sell/stock lines and click hints that EssentialsC adds automatically.
buy-price / sell-price Double Cost to buy one unit, and payout for selling one unit. Either can be 0.
buyable / sellable Boolean Whether the item can be bought and/or sold at all. Both default to true.
stock Integer Limited stock count. Use -1 for unlimited (the default).
permission String Optional permission required to see and purchase this item.
glow Boolean Adds an enchantment glint to the display item without changing its function.
max-stack Integer Maximum quantity a single shift-click buy or sell will move at once. Defaults to 64.
commands List Console commands run on purchase, instead of (or alongside) giving the item directly.
slot / page Integer Fixed GUI slot and page for this item. If omitted, EssentialsC auto-assigns slots in order across pages based on items-per-page.
Leave slot and page out entirely if you'd rather not manage layout by hand - items without a fixed slot are packed in automatically, in file order, filling each page before moving to the next.

Special Item Types

Spawners

Set spawner: true and spawner-type to a valid entity type (for example PIG or ZOMBIE) to sell a mob spawner pre-set to spawn that entity. The material is forced to SPAWNER regardless of what's set under material.

Enchanted Books

Set enchanted-book: true and list enchantments under enchanted-book-enchants (enchantment name to level) to sell a pre-enchanted book. The material is forced to ENCHANTED_BOOK.

Player Heads

For a PLAYER_HEAD item, set either skull-owner to a player name, or texture-url to a raw texture hash, full Mojang texture URL, or base64-encoded skin value, to give the head a custom skin.

Enchantments & NBT

Regular enchantments (enchantment name to level) can be applied to any item the same way as enchanted-book-enchants. Arbitrary string key/value pairs can also be written into the item's persistent data via NBT entries, useful for tagging items your other systems read back later.

Buying & Selling

Inside a category, clicking an item interacts with it directly - there's no separate confirm screen.

Click Action
Left-click Buys 1 unit.
Shift + Left-click Buys up to max-stack units in one go.
Right-click Sells 1 unit.
Shift + Right-click Sells up to max-stack units in one go.

Example

A farming category with a sellable wheat stack and a spawner for sale.

farming.yml 
items:
  wheat:
    material: WHEAT
    amount: 1
    name: "<#F5C842>Wheat"
    buy-price: 2.5
    sell-price: 1.0
    stock: -1
    max-stack: 64
  pig_spawner:
    material: SPAWNER
    name: "<#06FFA5>Pig Spawner"
    spawner: true
    spawner-type: PIG
    buy-price: 500.0
    sellable: false
    permission: "essentialsc.shop.spawners"

General Settings

A few shop-wide settings live in the main config.yml rather than in the shop/ folder.

Key Description Default
shop.enabled Master toggle for the entire shop system. true
shop.currency.singular Currency name used in shop lore when the amount is singular. Dollar
shop.currency.plural Currency name used in shop lore when the amount is plural. Dollars
shop.log-transactions Whether buy/sell transactions are written to the shop's transaction log. true

Commands

Command Description
/shop Opens the main shop GUI.
/shop <category> [page] Opens a specific category directly, optionally to a given page.
/shop reload Reloads main.yml and every category file from disk without restarting the server.

Permissions

Node Description Default
essentialsc.shop Allows opening and using the shop. Everyone
essentialsc.shop.admin Allows reloading the shop configuration with /shop reload. Operators
essentialsc.shop.bypass Bypasses shop restrictions such as stock limits. Operators

Per-category and per-item permission fields are checked in addition to essentialsc.shop - a player needs both the base permission and the specific node to see a restricted category or item.