oSHOP GUI Premium

🏠 What is oSHOP GUI Premium?

A premium Minecraft server shop plugin by OreoStudios — fully paginated, multi-category, with real-time price previews and a lag-resistant transaction engine.

📦 Installation

Get oSHOP GUI Premium running in under five minutes.

Requirements

⚡ Quick Start

The fastest path from zero to a working shop.

# Minimum viable config.yml
economy:
  backend: VAULT   # or EXP_POINTS / EXP_LEVELS

main-menu:
  title: "&8» &6&lSHOP &8«"
  rows: 4config.yml

After saving, run /shop reload. Players with oshopgui.shop can immediately use /shop.

⚙️ config.yml Reference

Full reference for every key in plugins/OSHOPGUI/config.yml.

Main Menu

Economy

Anti-Dupe

Amount Selection GUI

Navigation Slots

navigation:
  back-slot:      45   # Return to main menu
  prev-slot:      48   # Previous page
  next-slot:      50   # Next page
  page-info-slot: 49   # "Page 1/2" indicatorconfig.yml

Transaction Logging

💬 messages.yml Reference

All player-facing text lives in plugins/OSHOPGUI/messages.yml. Every string supports Minecraft color codes and MiniMessage.

Available Placeholders

Example Messages

# Transaction feedback
buy-success:      "&aBought &f{amount}x {item} &afor &f{price}"
sell-success:     "&aSold &f{amount}x {item} &afor &f{price}"
not-enough-money: "&cInsufficient funds. Balance: &f{balance}"
item-not-sellable: "&cThis item cannot be sold."

# Navigation
back-button:    "&c« Back"
prev-button:    "&e« Previous"
next-button:    "&eNext »"
page-indicator: "&7Page &f{page}&7/&f{max-page}"

# Anti-dupe
cooldown-active: "&cTransaction cooldown active."
rate-limit-hit:  "&cSlow down! Too many transactions."messages.yml

📄 Shop Files

Each shop category is a YAML file in plugins/OSHOPGUI/shops/. The plugin auto-loads every .yml in that folder.

File Structure

# plugins/OSHOPGUI/shops/example.yml
shop-name: "My Shop"
shop-id:   "my_shop"
page-size: 45    # items per page (max 45)

items:
  DIAMOND:              # Bukkit Material name
    slot:         0
    buy-price:    150.0
    sell-price:   75.0
    display-name: "&b✦ Diamond"
    lore:
      - "&7Buy: &a$150.00"
      - "&7Sell: &c$75.00"
    page:         1
    custom-item:  false
    custom-item-id: ""shops/example.yml

Item Field Reference

🗂️ Main Menu Setup

The main menu is the landing GUI players see when running /shop. Buttons are configured under main-menu-items in config.yml.

main-menu-items:
  ores:
    slot:     10
    material: DIAMOND_ORE
    name:     "&b✦ Ores &7&l»"
    lore:
      - "&7Browse ores & minerals"
      - ""
      - "&eClick to browse!"
    shop-id: "ores_minerals"   # must match shop-id in the .yml

  food:
    slot:     11
    material: BREAD
    name:     "&e🍞 Food &7&l»"
    lore:
      - "&7Food & consumables"
      - ""
      - "&eClick to browse!"
    shop-id: "food"config.yml

💰 Economy System

Three backends available, switched via a single config key — no restart required.

🎨 GUI System

All GUIs are powered by SmartInvs (bundled) for safe, lag-resistant inventory management.

Click Behavior

🔄 Transaction System

Every buy and sell action goes through TransactionProcessor — balance checks, modifier application, inventory verification, and logging in a single atomic flow.

Buy Flow

Player clicks item → Amount Selection → TransactionProcessor
  1. Permission check (oshopgui.shop)
  2. Anti-dupe: cooldown + rate-limit check
  3. Lock player (if lock-during-transaction: true)
  4. Final price = base_price × modifier
  5. Check player balance >= final_price
  6. Deduct balance via economy backend
  7. Give items to player inventory
  8. Verify items landed (anti-dupe check)
  9. Log transaction to file
 10. Unlock player + send success message

Sell Flow

Player right-clicks item → Amount Selection → TransactionProcessor
  1. Permission check + anti-dupe checks
  2. Verify player has sufficient quantity
  3. Payout = sell_price × modifier
  4. Remove items from inventory
  5. Add payout to player balance
  6. Log + send success message

Transaction Log Example

# plugins/OSHOPGUI/transactions.log
[2025-06-12 14:32:07] Steve BOUGHT 64x DIAMOND for $9600.00
[2025-06-12 14:33:15] Alex SOLD 128x WHEAT for $256.00transactions.log

🛡️ Anti-Dupe Protection

A multi-layer system to prevent exploit-based item generation.

Players with oshopgui.bypass.cooldown skip the cooldown entirely. This node is intended for admin/test use only.

📊 Price Modifiers

Per-player buy/sell price multipliers with three levels of specificity. Most specific wins.

Commands

# Set modifiers
/shop modifier set <player> global <multiplier>
/shop modifier set <player> shop <shop-id> <multiplier>
/shop modifier set <player> item <shop-id> <item> <multiplier>

# Check / reset
/shop check <player>
/shop modifier reset <player>

Example Use Cases

• VIP 20% discount: /shop modifier set VIPPlayer global 0.8 (buy price × 0.8)
• Donor sell bonus: /shop modifier set DonorPlayer global 1.25 (sell price × 1.25)
• Seasonal event: Shop modifier on farming_nature for a harvest event.
• Item rarity: 2.0 buy modifier on NETHERITE_INGOT to double its cost.

🔌 Plugin Hooks

Third-party integrations are detected and initialized automatically at startup.

Custom Item Example

items:
  RUBY:
    slot:          0
    buy-price:     500.0
    sell-price:    250.0
    display-name:  "&c💎 Ruby Gem"
    custom-item:   true
    custom-item-id: "ia:gems:ruby"  # ItemsAdder namespaceshops/custom.yml

Hook status is logged at startup: [OSHOPGUI] ItemsAdder hook: ✔ or [OSHOPGUI] Nexo hook: ✔. If neither is found, custom items fall back to standard Bukkit materials.

💻 Commands

All commands registered by oSHOP GUI Premium.

🔑 Permissions

All permissions in the oshopgui.* namespace.

LuckPerms Setup Example

# All players — basic shop access
/lp group default permission set oshopgui.shop true
/lp group default permission set oshopgui.sell true

# Admin group — full control
/lp group admin permission set oshopgui.* true

🗃️ Default Shop Catalog

14 pre-configured categories, 600+ items covering all major Minecraft item groups. Every file is in plugins/OSHOPGUI/shops/ and fully editable.

Add new categories by creating a .yml file, adding a button in main-menu-items, and running /shop reload. No restart needed.

❓ FAQ

Common questions and solutions.

Players can't open the shop

Ensure the player has oshopgui.shop. It defaults to true but may be overridden with an explicit deny. Check with /lp user <name> permission check oshopgui.shop.

Economy isn't working / balance not deducting

Confirm economy.backend: VAULT and that both Vault and an economy plugin (EssentialsX, CMI…) are loaded. Check the startup log for [OSHOPGUI] Economy: Vault ✔.

Items show as "Invalid Material"

Material names must be ALL_CAPS with underscores — e.g. DIAMOND_SWORD not diamondSword. Invalid items are skipped and logged to console. Fix and run /shop reload.

Custom items (ItemsAdder/Nexo) aren't loading

Ensure ItemsAdder or Nexo loads before oSHOP GUI. Set custom-item: true with the correct custom-item-id. The hook status is logged at startup.

How do I disable buy or sell for an item?

Set buy-price: -1 to disable buying, or sell-price: -1 to disable selling. Both can be -1 for a display-only item.

Price modifiers aren't saving after restart

Modifiers are stored in plugins/OSHOPGUI/data/. Check that the server has write permissions to the plugin directory. The plugin creates the folder on first run.

How do I add a new shop category?

Create a .yml file in plugins/OSHOPGUI/shops/, add a button under main-menu-items in config.yml, then run /shop reload. No restart required.

Amount selection GUI is not appearing

Ensure amount-selection.enabled: true and that amount-selection.presets has at least one value. Reload after changes.