Shop Basics

Everything from shopping..

🛒 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

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.

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:

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:

armor:

then the menu button must use:

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:

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

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:

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.

item:
  material: DIAMOND_SWORD

Use a valid material name for your Minecraft version.

2. Quantity

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.

item:
  material: WOOD
  damage: 1

Only use this where needed.

4. Custom name

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

5. Lore

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.

item:
  material: DIAMOND_SWORD
  flags:
    - HIDE_ATTRIBUTES

Useful for cleaner premium-style shop items.

7. Unbreakable

item:
  material: DIAMOND_PICKAXE
  unbreakable: true

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

8. Glow

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

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

Example: stronger sword

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

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:

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

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

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

Example information dummy item

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

buyPrice: 1200
sellPrice: 450

Move the GUI position

slot: 22

Change the display name

name: "&6Golden Bread"

Make it buy-only

sellPrice: -1

Make it sell-only

buyPrice: -1

Add more lore

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

Add or remove enchantments

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+

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.

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.

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)

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)

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

Tipped arrow example

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

Firework example

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

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

Oraxen example

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

Nexo example

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

MMOItems example

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

MythicMobs item example

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

HeadDatabase example

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

Custom Items example

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

Executable Items example

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

Executable Blocks example

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

CraftEngine example

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

QualityArmory example

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

Slimefun example

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

WeaponMechanics weapon example

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

WeaponMechanics ammo example

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.

item:
  material: CREEPER_SPAWN_EGG
  quantity: 1

1.9 - 1.12

Use a monster egg plus a valid mob entry.

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.

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:

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

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

PreviousShopGUI+NextDepency

Last updated 6 days ago

hashtag🛒 ShopGUI+

hashtagℹ️ Learn More

hashtag❗ Important Notice

hashtag📁 Where shops are made

hashtag🏪 How to create a shop

hashtagBasic shop structure

hashtagWhat each part means

hashtagarmor:

hashtagname:

hashtagsize:

hashtagfillItem:

hashtagitems:

hashtag🧭 How to add the shop into the main menu

hashtagExplanation

hashtagshop:

hashtagslot:

hashtag🧱 How item entries work

hashtag📦 Type: item

hashtagBasic item example

hashtagWhat this does

hashtag💰 Price behavior

hashtagRules

hashtagbuyPrice

hashtagsellPrice

hashtagslot

hashtag🪄 Editing item meta properly

hashtag1. Material

hashtag2. Quantity

hashtag3. Damage / data value

hashtag4. Custom name

hashtag5. Lore

hashtag6. Item flags

hashtag7. Unbreakable

hashtag8. Glow

hashtag✨ How to add enchantments to an item

hashtagExample: enchanted pickaxe

hashtagExample: stronger sword

hashtagImportant note

hashtag📘 Type: enchantment

hashtagExample pattern

hashtagWhen to use this

hashtagImportant behavior

hashtag🛡️ Type: permission

hashtagPractical use cases

hashtagRecommended approach

hashtagImportant note

hashtag🖥️ Type: command

hashtagExample command shop item

hashtagWhy this is powerful

hashtagBest practice

hashtag🧩 Type: dummy

hashtagExample decorative dummy item

hashtagExample information dummy item

hashtag🧠 How to modify an existing item

hashtagChange the price

hashtagMove the GUI position

hashtagChange the display name

hashtagMake it buy-only

hashtagMake it sell-only

hashtagAdd more lore

hashtagAdd or remove enchantments

hashtag👤 How to add player heads and skins

hashtagMethod 1: player head by owner

hashtag1.13+

hashtagMethod 2: custom skin texture

hashtagWhen to use which

hashtag🧵 How to add custom model data

hashtagImportant note

hashtag🧪 Potions, tipped arrows, and fireworks

hashtagPotion example (1.9 - 1.20.1 style)

hashtagPotion example (1.20.2+ style)

hashtagTipped arrow example

hashtagFirework example

hashtag🧬 NBT items

hashtagImportant warnings

hashtagExample idea

hashtag🔌 External custom items and plugin items

hashtagSupported examples from the docs/plugin listing

hashtagItemsAdder example

hashtagOraxen example

🛒 ShopGUI+

ℹ️ Learn More

❗ Important Notice

📁 Where shops are made

🏪 How to create a shop

Basic shop structure

What each part means

`armor:`

`name:`

`size:`

`fillItem:`

`items:`

🧭 How to add the shop into the main menu

Explanation

`shop:`

`slot:`

🧱 How item entries work

📦 Type: item

Basic item example

What this does

💰 Price behavior

Rules

`buyPrice`

`sellPrice`

`slot`

🪄 Editing item meta properly

1. Material

2. Quantity

3. Damage / data value

4. Custom name

5. Lore

6. Item flags

7. Unbreakable

8. Glow

✨ How to add enchantments to an item

Example: enchanted pickaxe

Example: stronger sword

Important note

📘 Type: enchantment

Example pattern

When to use this

Important behavior

🛡️ Type: permission

Practical use cases

Recommended approach

Important note

🖥️ Type: command

Example command shop item

Why this is powerful

Best practice

🧩 Type: dummy

Example decorative dummy item

Example information dummy item

🧠 How to modify an existing item

Change the price

Move the GUI position

Change the display name

Make it buy-only

Make it sell-only

Add more lore

Add or remove enchantments

👤 How to add player heads and skins

Method 1: player head by owner

1.13+

Method 2: custom skin texture

When to use which

🧵 How to add custom model data

Important note

🧪 Potions, tipped arrows, and fireworks

Potion example (1.9 - 1.20.1 style)

Potion example (1.20.2+ style)

Tipped arrow example

Firework example

🧬 NBT items

Important warnings

Example idea

🔌 External custom items and plugin items

Supported examples from the docs/plugin listing

ItemsAdder example

Oraxen example