# Shop Basics

## 🛒 ShopGUI+

This is a configuration product.

This page is written as a **real setup guide** for ShopGUI+, focused on the part most people actually need: **how to build shops, add every kind of shop item, and edit item meta properly**.

It follows the same clean GitBook tone as your existing documentation, but the content is based on the actual ShopGUI+ structure and item setup system.

***

#### ℹ️ Learn More

This guide is based on the ShopGUI+ documentation by **brcdev** and reorganized into a clearer wiki-style explanation for config authors.

#### ❗ Important Notice

This page focuses on **configuration and setup**. It is not an installation guide.

## 📁 Where shops are made

ShopGUI+ shops are created inside:

```
/plugins/ShopGUIPlus/shops/
```

Each **shop file** is one category.

Examples:

```
blocks.yml
food.yml
armor.yml
spawners.yml
```

Inside each file, the **main section name must match the filename**.

Example:

* file name: `armor.yml`
* main section: `armor:`

If they do not match, the shop can break or fail to open.

***

## 🏪 How to create a shop

A shop is not just a list of items.

A proper shop has:

* a shop id
* a display name
* an optional GUI size
* an optional fill item
* an `items:` section
* a matching button in the main menu

***

### Basic shop structure

```yml
armor:
  name: "&4&lArmor (page %page%)"
  size: 45
  fillItem:
    material: STAINED_GLASS_PANE
    damage: 15
    name: " "
  items: {}
```

### What each part means

#### `armor:`

This is the **shop id**.

It must be unique.

This is also the id used in:

* `/shop armor`
* `shopguiplus.shops.armor`
* `config.yml` main menu buttons

#### `name:`

This is the title shown at the top of the shop GUI.

You can use color codes and `%page%` when the shop has multiple pages.

#### `size:`

Controls the inventory size.

Accepted values are:

```
9, 18, 27, 36, 45, 54
```

#### `fillItem:`

This is optional.

It fills empty slots with a decorative item so the menu looks cleaner.

#### `items:`

This is where every shop entry is added.

***

## 🧭 How to add the shop into the main menu

Creating `armor.yml` alone is **not enough**.

If the shop is not linked in `config.yml`, players cannot access it from `/shop`.

Example main menu button:

```yml
shopMenuItems:
  1:
    item:
      material: DIAMOND_CHESTPLATE
      quantity: 1
      name: "&4&lArmor"
    shop: "armor"
    slot: 15
```

### Explanation

#### `shop:`

This must match the shop id from the shop file.

If your shop file starts with:

```yml
armor:
```

then the menu button must use:

```yml
shop: "armor"
```

#### `slot:`

This is where the category button appears in the main shop menu.

***

## 🧱 How item entries work

Inside `items:`, every shop entry gets its own unique key.

Example:

```yml
items:
  1:
  2:
  3:
```

These keys only need to be unique inside that shop.

You can use numbers like `1`, `2`, `3`, or names if you prefer, as long as they are unique and clean.

Every entry has a `type`.

Valid ShopGUI+ item types include:

* `item`
* `permission`
* `enchantment`
* `command`
* `dummy`

That means a shop entry can be:

* a real item players receive
* a permission purchase
* an enchantment purchase
* a command purchase
* a decorative or clickable dummy item

***

## 📦 Type: item

This is the most common type.

Use `type: item` when you want the player to receive a normal Minecraft item or a supported external-plugin item.

### Basic item example

```yml
food:
  name: "&5Food Shop"
  items:
    1:
      type: item
      item:
        material: BREAD
        quantity: 32
        damage: 0
        name: "&aYummy Bread"
        lore:
          - "&7Fresh food for survival"
      buyPrice: 120
      sellPrice: 25
      slot: 0
```

### What this does

* shows bread in the GUI
* gives 32 bread when bought
* lets players sell it back for 25
* puts the item in slot 0

***

## 💰 Price behavior

Every shop entry usually has these three values:

```yml
buyPrice: 120
sellPrice: 25
slot: 0
```

### Rules

#### `buyPrice`

* above `0` = player can buy it
* `0` = free
* below `0` = cannot be bought

#### `sellPrice`

* above `0` = player can sell it
* `0` = sells for nothing
* below `0` = cannot be sold

#### `slot`

This controls where the item appears in the GUI.

Normal single-page shop slots run from:

```
0 to 53
```

***

## 🪄 Editing item meta properly

The `item:` section is where you build the real item.

This is the part you edit when you want:

* custom names
* lore
* enchantments
* flags
* skins
* models
* potion data
* banners
* fireworks
* NBT

***

### 1. Material

The required part is the material.

```yml
item:
  material: DIAMOND_SWORD
```

Use a valid material name for your Minecraft version.

***

### 2. Quantity

```yml
item:
  material: GOLDEN_APPLE
  quantity: 8
```

This defines how many items the player receives.

***

### 3. Damage / data value

Used mostly on older items or version-specific setups.

```yml
item:
  material: WOOD
  damage: 1
```

Only use this where needed.

***

### 4. Custom name

```yml
item:
  material: DIAMOND_SWORD
  name: "&bStarter Blade"
```

***

### 5. Lore

```yml
item:
  material: DIAMOND_SWORD
  name: "&bStarter Blade"
  lore:
    - "&7A basic sword for new players"
    - "&8Not tradeable"
```

Each lore line is a separate list line.

***

### 6. Item flags

Use flags when you want to hide default tooltips.

```yml
item:
  material: DIAMOND_SWORD
  flags:
    - HIDE_ATTRIBUTES
```

Useful for cleaner premium-style shop items.

***

### 7. Unbreakable

```yml
item:
  material: DIAMOND_PICKAXE
  unbreakable: true
```

Useful for kits, donor tools, or permanent utility items.

***

### 8. Glow

```yml
item:
  material: STONE
  quantity: 64
  glow: true
```

This adds the enchantment glow effect even if the item is just being used for display.

***

## ✨ How to add enchantments to an item

If you want to sell an **enchanted item** like a sword, pickaxe, armor piece, or tool, the easiest way is usually still `type: item` and then add enchantments under `item:`.

### Example: enchanted pickaxe

```yml
1:
  type: item
  item:
    material: STONE_PICKAXE
    quantity: 1
    name: "&8Crappy Pickaxe"
    enchantments:
      - EFFICIENCY:1
  buyPrice: 50
  sellPrice: 25
  slot: 0
```

### Example: stronger sword

```yml
2:
  type: item
  item:
    material: DIAMOND_SWORD
    quantity: 1
    name: "&cWar Sword"
    lore:
      - "&7Sharp and ready"
    enchantments:
      - SHARPNESS:4
      - LOOTING:1
    flags:
      - HIDE_ATTRIBUTES
  buyPrice: 5000
  sellPrice: -1
  slot: 1
```

### Important note

For **enchanted gear and tools**, use:

* `type: item`
* `item.enchantments:`

That is the cleanest setup.

***

## 📘 Type: enchantment

ShopGUI+ also supports a dedicated `enchantment` shop item type.

Use this when you want the shop entry itself to behave like an enchantment purchase instead of giving a pre-made enchanted item.

### Example pattern

```yml
1:
  type: enchantment
  enchantment: FORTUNE
  enchantmentLevel: 2
  item:
    material: DIAMOND_PICKAXE
    quantity: 1
    name: "&8Fortune II"
    enchantments:
      - FORTUNE:2
  buyPrice: 50
  slot: 0
```

### When to use this

Use `type: enchantment` when your goal is specifically to sell an enchantment purchase.

Use `type: item` when you just want to sell an already-enchanted item.

### Important behavior

Amount-selection GUI behavior applies to normal items. Permission, enchantment, and command purchases are bought immediately rather than through amount selection.

***

## 🛡️ Type: permission

Use `type: permission` when buying the entry should grant a permission node instead of a physical item.

This is useful for things like:

* donor perks
* special warp access
* extra commands
* rank utility features
* cosmetic access

### Practical use cases

* `/fly` access
* extra homes
* donor crate access
* premium repair command
* access to a VIP shop

### Recommended approach

For permission purchases, keep the displayed item simple and make the lore explain exactly what the buyer receives.

Example display structure:

```yml
1:
  type: permission
  item:
    material: NETHER_STAR
    quantity: 1
    name: "&6Fly Access"
    lore:
      - "&7Grants permanent /fly access"
      - "&8One-time purchase"
  buyPrice: 250000
  sellPrice: -1
  slot: 10
```

### Important note

The exact permission-grant fields can vary depending on your setup and version, so after adding a permission-type item you should always test the purchase on a non-operator account before publishing it live.

If your goal is only to run a console command that grants the permission, using `type: command` is often the most flexible option.

***

## 🖥️ Type: command

Use `type: command` when buying the shop entry should execute one or more commands.

This is one of the most useful types because it can be connected to almost anything.

You can use it for:

* giving custom plugin items
* granting ranks
* giving keys
* unlocking perks
* running furniture, cosmetics, or crate commands

### Example command shop item

```yml
1:
  type: command
  item:
    material: CHEST
    quantity: 1
    name: "&eStreetlamp"
    lore:
      - "&7Buy a decorative furniture item"
  commands:
    - "/furniture give Streetlamp"
  buyPrice: 250
  sellPrice: -1
  slot: 10
```

### Why this is powerful

`type: command` is usually the easiest way to bridge ShopGUI+ with other plugins.

If another plugin can give something with a command, ShopGUI+ can often sell it through this type.

### Best practice

Use command items when:

* the product is not a normal Bukkit item
* the target plugin already has a give command
* you want the command to control delivery

***

## 🧩 Type: dummy

`dummy` items are not normal products.

They are mainly used as:

* decoration
* separators
* info buttons
* clickable utility buttons
* fake placeholder items

### Example decorative dummy item

```yml
99:
  type: dummy
  item:
    material: BLACK_STAINED_GLASS_PANE
    quantity: 1
    name: " "
  slot: 13
```

### Example information dummy item

```yml
100:
  type: dummy
  item:
    material: BOOK
    quantity: 1
    name: "&eInformation"
    lore:
      - "&7All purchases are final"
      - "&7Use /shop for more categories"
  slot: 49
```

Dummy items are perfect when you want your shop to look designed instead of randomly filled.

***

## 🧠 How to modify an existing item

To modify an item already in a shop, edit the entry directly.

### Change the price

```yml
buyPrice: 1200
sellPrice: 450
```

### Move the GUI position

```yml
slot: 22
```

### Change the display name

```yml
name: "&6Golden Bread"
```

### Make it buy-only

```yml
sellPrice: -1
```

### Make it sell-only

```yml
buyPrice: -1
```

### Add more lore

```yml
lore:
  - "&7Line one"
  - "&7Line two"
  - "&8Seasonal product"
```

### Add or remove enchantments

```yml
enchantments:
  - SHARPNESS:5
  - FIRE_ASPECT:2
```

***

## 👤 How to add player heads and skins

ShopGUI+ supports player heads.

There are two main ways to do this.

***

### Method 1: player head by owner

#### 1.13+

```yml
1:
  type: item
  item:
    material: PLAYER_HEAD
    quantity: 1
    skullOwner: Notch
    name: "&eNotch Head"
  buyPrice: 500
  sellPrice: -1
  slot: 0
```

Use this when you want the head skin of a specific player account.

***

### Method 2: custom skin texture

If you want a fully custom head texture, use the base64 skin value.

```yml
1:
  type: item
  item:
    material: PLAYER_HEAD
    quantity: 1
    skin: eyJ0ZXh0dXJlcyI6eyJTS0lOIjp7InVybCI6Imh0dHA6Ly90ZXh0dXJlcy5taW5lY3JhZnQubmV0L3RleHR1cmUv..." 
    name: "&bCustom Icon"
  buyPrice: 2000
  sellPrice: -1
  slot: 1
```

Use this when you want:

* menu icons
* cosmetic heads
* custom decoration items
* non-player head textures

### When to use which

* `skullOwner` = easiest for real player heads
* `skin` = best for custom textures and icon-style heads

***

## 🧵 How to add custom model data

If your resource pack uses custom model data, ShopGUI+ can display it.

```yml
1:
  type: item
  item:
    material: LEATHER_HELMET
    quantity: 1
    model: 123
    name: "&dCustom Helmet"
  buyPrice: 5000
  sellPrice: -1
  slot: 5
```

### Important note

Custom model support works on **1.14+**.

This is useful for:

* texture-pack items
* menu icons
* cosmetic products
* custom-display dummy items

***

## 🧪 Potions, tipped arrows, and fireworks

These are not handled like ordinary stone or food items. They need item meta.

***

### Potion example (1.9 - 1.20.1 style)

```yml
1:
  type: item
  item:
    material: SPLASH_POTION
    quantity: 16
    potion:
      type: SPEED
      level: 1
      extended: true
      color: BLUE
  buyPrice: 750
  sellPrice: -1
  slot: 8
```

### Potion example (1.20.2+ style)

```yml
1:
  type: item
  item:
    material: POTION
    quantity: 1
    potion:
      type: STRONG_STRENGTH
  buyPrice: 1200
  sellPrice: -1
  slot: 9
```

### Tipped arrow example

```yml
1:
  type: item
  item:
    material: TIPPED_ARROW
    quantity: 16
    potion:
      type: SPEED
  buyPrice: 300
  sellPrice: -1
  slot: 10
```

### Firework example

```yml
1:
  type: item
  item:
    material: FIREWORK
    quantity: 32
    damage: 0
    fireworkPower: 2
    fireworkEffects:
      1:
        type: BALL_LARGE
        colors:
          - YELLOW
          - ORANGE
      2:
        type: CREEPER
        colors:
          - YELLOW
          - ORANGE
  buyPrice: 10
  sellPrice: -1
  slot: 0
```

***

## 🧬 NBT items

ShopGUI+ supports NBT-configured items, but this is one of the more advanced parts of the system.

### Important warnings

* only use NBT when simpler item-provider support is not enough
* the docs recommend using item providers where possible instead
* `compareMeta` must be enabled for the item if you use the `nbt` option

### Example idea

NBT is useful for:

* special custom items
* uncommon vanilla variants
* advanced server-specific item builds

If you are not deliberately building an advanced NBT item, do **not** jump to NBT first. Use standard item meta, custom model data, or external item providers instead.

***

## 🔌 External custom items and plugin items

ShopGUI+ supports many external plugin item types.

This is one of the biggest reasons people use it.

### Supported examples from the docs/plugin listing

* Brewery / BreweryX
* CrackShot
* CraftEngine
* Custom Items
* Executable Blocks
* Executable Items
* HeadDatabase
* ItemsAdder
* MMOItems
* MythicMobs
* Nexo
* Oraxen
* QualityArmory
* Slimefun
* WeaponMechanics
* several supported spawner plugins

***

### ItemsAdder example

```yml
1:
  type: item
  item:
    itemsAdder: "ruby_sword"
  buyPrice: 50
  sellPrice: 25
  slot: 0
```

### Oraxen example

```yml
1:
  type: item
  item:
    oraxen: "obsidian_pickaxe"
  buyPrice: 50
  sellPrice: 25
  slot: 1
```

### Nexo example

```yml
1:
  type: item
  item:
    nexo: "mithril_helmet"
  buyPrice: 50
  sellPrice: 25
  slot: 2
```

### MMOItems example

```yml
1:
  type: item
  item:
    mmoItems:
      type: ARMOR
      id: MYTHRIL_CHAINMAIL
  buyPrice: 50
  sellPrice: 25
  slot: 3
```

### MythicMobs item example

```yml
1:
  type: item
  item:
    mythicMobs:
      item: "PIG_BONE"
  buyPrice: 50
  sellPrice: 25
  slot: 4
```

### HeadDatabase example

```yml
1:
  type: item
  item:
    headDatabase: 1734
  buyPrice: 50
  sellPrice: 25
  slot: 5
```

### Custom Items example

```yml
1:
  type: item
  item:
    customItems: "item1"
  buyPrice: 50
  sellPrice: 25
  slot: 6
```

### Executable Items example

```yml
1:
  type: item
  item:
    executableItems: "heal"
  buyPrice: 50
  sellPrice: 25
  slot: 7
```

### Executable Blocks example

```yml
1:
  type: item
  item:
    executableBlocks: "teleporter"
  buyPrice: 50
  sellPrice: 25
  slot: 8
```

### CraftEngine example

```yml
1:
  type: item
  item:
    craftEngine: "customcrops:apple"
  buyPrice: 50
  sellPrice: 25
  slot: 9
```

### QualityArmory example

```yml
1:
  type: item
  item:
    qualityArmory: "PISTOL"
  buyPrice: 50
  sellPrice: 25
  slot: 10
```

### Slimefun example

```yml
1:
  type: item
  item:
    slimefun: "GRANDMAS_WALKING_STICK"
  buyPrice: 50
  sellPrice: 25
  slot: 11
```

### WeaponMechanics weapon example

```yml
1:
  type: item
  item:
    weaponMechanics:
      weapon: AK_47
      quantity: 1
  buyPrice: 50
  sellPrice: 25
  slot: 12
```

### WeaponMechanics ammo example

```yml
1:
  type: item
  item:
    weaponMechanics:
      ammo: Rocket
      quantity: 1
  buyPrice: 50
  sellPrice: 25
  slot: 13
```

***

## 🧱 Spawners and spawn eggs

ShopGUI+ can also sell mob-related items, but the setup depends on the Minecraft version and the plugin/provider involved.

### Spawn egg basics

#### 1.13+

Use the direct egg material name.

```yml
item:
  material: CREEPER_SPAWN_EGG
  quantity: 1
```

#### 1.9 - 1.12

Use a monster egg plus a valid `mob` entry.

```yml
item:
  material: MONSTER_EGG
  quantity: 1
  mob: Creeper
```

#### 1.7 - 1.8

Older setups may still rely on damage values.

***

## 🔐 Shop permissions

Players usually need:

* `shopguiplus.shop`
* access to the specific shop permission node

Per-shop access is controlled with:

```
shopguiplus.shops.SHOP_ID
```

Examples:

```
shopguiplus.shops.food
shopguiplus.shops.armor
shopguiplus.shops.blocks
```

### What this means in practice

If your shop id is `donator`, the node becomes:

```
shopguiplus.shops.donator
```

If a player has `/shop` permission but not the specific shop node, the category can still fail when clicked.

***

## ⌨️ Useful commands for config work

```
/shop
```

Open the main shop menu.

```
/shop <shopname>
```

Open one shop directly.

```
/shop reload
```

Reload the configuration after editing files.

```
/shop check
```

Get information on the item in your hand.

```
/shop worth
```

Check the sale value of the held item.

```
/sell hand [quantity]
```

Sell the held item.

```
/sell handall
```

Sell all matching items like the one being held.

```
/sell all [shop]
```

Sell all items from inventory.

***

## 🧪 Recommended workflow when building a new shop

Use this order every time.

### Step 1

Create the new file in `/plugins/ShopGUIPlus/shops/`

Example:

```
weapons.yml
```

### Step 2

Make the top section match the file name.

```yml
weapons:
```

### Step 3

Set name, size, and fill item.

### Step 4

Create your `items:` section.

### Step 5

Add entries one by one using the correct `type`.

### Step 6

Put the shop into `config.yml` under `shopMenuItems`.

### Step 7

Reload with:

```
/shop reload
```

### Step 8

Test with a normal player account.

Do not test only with operator because:

* operator can bypass permission issues
* commands may work differently
* some products may look correct but fail for normal players

***

## ❌ Common mistakes

### Shop file name does not match shop id

Wrong:

* file = `blocks.yml`
* top section = `shop:`

Correct:

* file = `blocks.yml`
* top section = `blocks:`

***

### Shop was created but not added to main menu

The shop exists, but players cannot access it from `/shop` because no menu item was added in `config.yml`.

***

### Invalid material name

This happens a lot when copying configs between Minecraft versions.

***

### Wrong slot placement

Two items using the same slot can make the layout look broken.

***

### Using `type: item` when you really need `type: command`

If the product comes from another plugin and is normally delivered by command, using `command` is often easier than trying to fake it as a vanilla item.

***

### Forgetting to test permissions

A shop can open for staff and fail for real players.

***

### Going to NBT too early

NBT is powerful, but it is the wrong starting point for most items.

***

## ✅ Best practice advice

### Use `type: item` for normal products

This includes most blocks, tools, armor, food, and custom items that already have provider support.

### Use `type: command` for plugin rewards

This is usually best for crates, furniture, rank actions, or perk-delivery commands.

### Use `type: dummy` for design

It makes the shop look intentional.

### Keep lore informative

Tell the buyer exactly what they get.

### Separate categories properly

Do not mix blocks, food, donor perks, and crates in one page unless there is a good reason.

### Test every purchase flow

Especially:

* enchanted items
* external plugin items
* command products
* permission purchases
* player heads / skins

***

## 📚 Quick example: a full custom mini shop

```yml
special:
  name: "&6&lSpecial Items"
  size: 27
  fillItem:
    material: BLACK_STAINED_GLASS_PANE
    name: " "
  items:
    1:
      type: item
      item:
        material: DIAMOND_SWORD
        quantity: 1
        name: "&cWar Sword"
        lore:
          - "&7Sharp and ready"
        enchantments:
          - SHARPNESS:4
          - LOOTING:1
        flags:
          - HIDE_ATTRIBUTES
      buyPrice: 5000
      sellPrice: -1
      slot: 10
    2:
      type: command
      item:
        material: CHEST
        quantity: 1
        name: "&eStreetlamp"
        lore:
          - "&7Furniture reward"
      commands:
        - "/furniture give Streetlamp"
      buyPrice: 250
      sellPrice: -1
      slot: 12
    3:
      type: item
      item:
        material: PLAYER_HEAD
        quantity: 1
        skullOwner: Notch
        name: "&eCollector Head"
      buyPrice: 1200
      sellPrice: -1
      slot: 14
    4:
      type: dummy
      item:
        material: BOOK
        quantity: 1
        name: "&bNotice"
        lore:
          - "&7All purchases are final"
      slot: 22
```