How to Make a Shop

A shop is the top-level menu a player opens with a command; it holds a set of categories, either as a paged picker or as a single category the player lands in directly. This page covers creating a shop file, naming it, and laying out its parts.

Quick start

Open the shops/ folder in your EcoShop config directory.
Copy _example.yml and rename the copy, e.g. shop.yml. The file name (without .yml) becomes the shop ID.
Set command: to the command you want players to run, e.g. shop.
Under pages:, list the categories you want, each with a row and column. The category IDs must match real category files.
Save, then run /ecoshop reload.
Run your shop command in game; the category picker should open.

Naming and IDs

The file name without .yml is the shop's ID. That ID is what you use in commands, effects, and placeholders. Item fields like the arrows below use the Item Lookup System syntax.

The structure of a shop

A shop is made of four parts:

Part	What it controls
Shop info	The GUI title and the command that opens the shop
Navigation	The forward and back arrows between pages
Broadcasts and sounds	Purchase announcements and the click, buy, and sell sounds
Categories	Which categories the shop shows, and whether it is paged or direct

Here is a complete shop with every part in place:

# === Shop info: name and command ===
title: Demo Shop # The GUI title shown at the top of the shop. Supports %page% and %max_page% placeholders.
command: demoshop # The command players run to open this shop.

# === Navigation: page arrows ===
forwards-arrow: # Shown on every page except the last.
  item: arrow name:"&fNext Page" # Item syntax comes from the Item Lookup System.
  row: 6
  column: 6
backwards-arrow: # Shown on every page except the first.
  item: arrow name:"&fPrevious Page"
  row: 6
  column: 4

# === Broadcasts and sounds: feedback on actions ===
buy-broadcasts: # Announce purchases to the whole server; good for /buy menus.
  enabled: true
  message: "&b%player%&f bought &r%item%&f!" # Supports %player%, %item%, and %amount%.
  sound:
    enabled: true
    sound: ui_toast_challenge_complete
    pitch: 1.5
    volume: 2
    category: players
click-sound: # Played when a player clicks any icon in this shop.
  enabled: true
  sound: block_stone_button_click_on
  pitch: 1
  volume: 1
  category: UI
buy-sound: # Played on a successful purchase.
  enabled: true
  sound: entity_player_levelup
  pitch: 2
  volume: 1
  category: players
sell-sound: # Played on a successful sale.
  enabled: true
  sound: block_amethyst_block_place
  pitch: 1.5
  volume: 1
  category: players

# === Categories: what the shop contains ===
rows: 3 # Height of the category-picker GUI (1-6).
pages: # Add as many pages as you want.
  - page: 1
    mask: # Decorative filler behind the categories.
      items:
        - gray_stained_glass_pane
        - black_stained_glass_pane
      pattern: # 0 empty, 1 first mask item, 2 second mask item.
        - "222222222"
        - "211111112"
        - "211000112"
        - "211000112"
        - "211111112"
        - "222222222"
    categories: # Where each category icon sits in the GUI.
      - id: example
        row: 3
        column: 3
      - id: example_2
        row: 4
        column: 6
    custom-slots: [ ] # Extra decorative or command slots.

Shop info

The title and command are the only required fields a shop must have.

title: Demo Shop # The GUI title shown at the top of the shop. Supports %page% and %max_page% placeholders.
command: demoshop # The command players run to open this shop.

The arrows move players between pages and hide themselves when there is nowhere to go.

forwards-arrow: # Hidden on the last page.
  item: arrow name:"&fNext Page"
  row: 6
  column: 6
backwards-arrow: # Hidden on the first page.
  item: arrow name:"&fPrevious Page"
  row: 6
  column: 4

Broadcasts and sounds

These give feedback when players act in the shop. Broadcasts go to the whole server; the three sounds play locally for the buyer. See the Sound Configs guide for the sound fields.

buy-broadcasts:
  enabled: true # Announce every purchase in this shop to the server.
  message: "&b%player%&f bought &r%item%&f!" # Supports %player%, %item%, and %amount%.
  sound: # A sound played alongside the broadcast.
    enabled: true
    sound: ui_toast_challenge_complete
    pitch: 1.5
    volume: 2
    category: players
click-sound: # Played when an icon is clicked.
  enabled: true
  sound: block_stone_button_click_on
  pitch: 1
  volume: 1
  category: UI

Internal placeholders

These placeholders are available inside buy-broadcasts.message:

Placeholder	Value
`%player%`	The name of the player who bought the item
`%item%`	The display name of the item that was bought
`%amount%`	The amount the player bought

Where to go next

Fill your shop: How to make a Category is the next step; shops are empty without categories.
Add things to sell: How to make an Item covers the items inside a category.
Global menus: Plugin Config configures the shared buy, sell, and mass-sell GUIs.