Shop format

Each shop is a YAML file in plugins/ShopForge/shops/. Here is the full format reference.

Complete shop file

# shops/blacksmith.yml

id: blacksmith                 # used in /shop <id> and shopforge.use.<id>
display-name: "<gray>⚒ Blacksmith"

categories:
  swords:
    icon: DIAMOND_SWORD        # the category tab
    display-name: "<aqua>⚔ Swords"
    items:
      - id: diamond_sword
        material: DIAMOND_SWORD
        display-name: "<aqua>Diamond Sword"
        lore:
          - "<gray>Forged at the anvil."
        buy-price: 500.0         # 0 or less = can't be bought
        sell-price: 200.0        # 0 or less = can't be sold
        enchants:
          sharpness: 3
          unbreaking: 2

      - id: iron_sword
        material: IRON_SWORD
        buy-price: 100.0
        sell-price: 40.0

  armor:
    icon: DIAMOND_CHESTPLATE
    display-name: "<yellow>🛡 Armor"
    items:
      - id: diamond_chestplate
        material: DIAMOND_CHESTPLATE
        buy-price: 800.0
        sell-price: 350.0
        stock: 10                # only 10 for the whole server
        stock-per-player: 1      # each player can buy 1

  special:
    icon: NETHERITE_SWORD
    display-name: "<gold>⭐ Special"
    items:
      - id: godly_sword
        material: NETHERITE_SWORD
        display-name: "<gradient:gold:red><bold>Godly Blade</bold></gradient>"
        buy-price: 5000.0
        stock: 1
        stock-per-player: 1
        permission: shop.vip     # only players with this permission can buy it
        enchants:
          sharpness: 5
          fire_aspect: 2
          mending: 1

Items can also be written as a map keyed by id (diamond_sword: instead of - id: diamond_sword); both load the same.

Item field reference

Field	Type	Default	Description
`id`	String	—	Unique id inside the shop (used in logs and `/shop give`)
`material`	String	`PAPER`	Bukkit `Material` name, or a custom item (see below)
`display-name`	String	material name	MiniMessage name shown in the menu
`lore`	List	`[]`	MiniMessage lines shown in the menu
`buy-price`	Double	`0`	Cost to buy; `0` or less = can't be bought
`sell-price`	Double	`0`	Sell value; `0` or less = can't be sold
`permission`	String	—	Permission needed to buy the item
`stock`	Integer	`-1`	Stock shared by the whole server; `-1` = unlimited
`stock-per-player`	Integer	`0`	How many each player can buy; `0` = no limit
`stock-refill-hours`	Integer	`24`	Hours until a player's own limit resets
`enchants`	Map	`{}`	`enchantment: level` pairs (Minecraft names). On an `ENCHANTED_BOOK` they are stored, so an anvil takes the book
`potion`	String	—	The potion inside a `POTION`, `SPLASH_POTION`, `LINGERING_POTION` or `TIPPED_ARROW`: `strength`, `long_strength`, `strong_strength`… (Minecraft ids; old names such as `speed` also work). Without it the item is a water bottle
`skull-texture`	String	—	Texture id for `PLAYER_HEAD` items (the hash at the end of a `textures.minecraft.net/texture/...` link)
`keep-name`	Boolean	—	`true`: the item arrives with its shop name and lore. `false`: it arrives plain. Unset: the rule below
`currency`	String	the shop's, else `shop.default-currency`	What the item is paid with (see below)
`dynamic`	Boolean / Map	`dynamic-pricing.enabled`	Market price on or off, or a section with `step`, `min`, `max`, `half-life-hours`

per-player-limit and enchantments are also accepted. Any other key is ignored and reported in the console when the shop loads.

Potions and enchanted books are bought back only as what they are. A potion: strength entry takes Strength potions and nothing else (not water, not Strength II), and a book entry takes books holding those stored enchantments at least at those levels. A named potion without potion, or an enchanted book without enchants, is reported in the console when the shop loads.

      - id: strength
        material: POTION
        display-name: "<red>Potion of Strength"
        potion: strength
        buy-price: 400
        sell-price: 100
      - id: mending_book
        material: ENCHANTED_BOOK
        enchants:
          mending: 1
        buy-price: 6000
        sell-price: 1500

What the buyer receives. If display-name is just the item's own name in colour (<white>Iron Sword on an IRON_SWORD), the player gets the plain item, without name or lore, so it stacks with the ones they already have. A name of its own (<gold>Legendary Key) is kept on the delivered item together with its lore. Enchantments and skull textures are always kept.

If your shop names are translations (<#E8D27B>Gavilla de trigo on WHEAT), set shop.plain-items: true in config.yml: every vanilla item then arrives plain and the name and lore stay in the menu. An item with keep-name: true still arrives with its name.

Currencies

Every price is in Vault money unless the item, or the shop file at its top, says otherwise:

`currency:`	Paid with
`vault`	Vault money (EssentialsX, CMI, … behind it)
`playerpoints`	PlayerPoints
`xp-levels`	the player's experience levels
`xp-points`	raw experience points
`tokenmanager`	TokenManager tokens
`coinsengine:<id>`	one currency of ExcellentEconomy / CoinsEngine, e.g. `coinsengine:gems`

Whole-number currencies (points, levels, tokens) round a price up when charging and down when paying. Vault is optional: a server without it can run shops priced only in other currencies.

Custom items

material can name an item from an item plugin. The buyer gets the exact item that plugin makes, and selling only accepts that item:

`material:`	Plugin
`itemsadder:<namespace>:<id>` (or `ia:`)	ItemsAdder
`nexo:<id>`	Nexo
`oraxen:<id>`	Oraxen
`mmoitems:<TYPE>:<ID>` (or `mmo:`)	MMOItems

While the plugin is missing or still loading, the menu shows a barrier with the reason and the item cannot be bought; /shop audit lists them.

Market prices

With dynamic: true an item's price follows demand: each unit bought raises it by step, each unit sold lowers it, never below min or above max times the configured price. The change fades back by itself (half-life-hours). Buy and sell prices move together and a batch is priced unit by unit, so buying and selling straight back never pays. The menu shows the current price and the change (Market: 12%). Defaults live in dynamic-pricing in config.yml.

      - id: wheat
        material: WHEAT
        buy-price: 2
        sell-price: 1
        dynamic:
          max: 3.0           # this item can go up to three times its price

Server stock vs per-player limit

stock: one pool for everyone. When it reaches 0, nobody can buy.
stock-per-player: each player can buy up to this many, counted per player, and their count resets every stock-refill-hours.

The menu shows what's left: Stock: 7 for server stock, Stock: 1 (per player) for a player's own limit.

Example — limited edition item:

      - id: legendary_key
        material: TRIPWIRE_HOOK
        display-name: "<gold>Legendary Key"
        buy-price: 10000.0
        stock: 50              # only 50 for the whole server
        stock-per-player: 1    # each player can get 1