Skip to content

Home

Jump to bottom
Parthiv Gamit edited this page Sep 13, 2026 · 1 revision

PixelGUIShop (Free) - Complete Documentation

Welcome to the official documentation for the Free Edition of PixelGUIShop! This plugin provides a modern, living economy for your server where item prices organically fluctuate based on player demand.

🌟 Key Features

  1. Modern GUI Interface: Highly polished, responsive shop interface natively rendering player heads, strikethrough text for sales, and dynamic pricing lore.
  2. Dynamic Market Engine: Every 90 minutes, the plugin automatically evaluates server-wide purchase history. Items frequently bought will enter High Demand (raising prices), while untouched items will go on Sale (lowering prices).
  3. Unlimited Stock: Unlike strict traditional shops, players in the Free version can always purchase whatever they need. Stock is calculated strictly in the background to fuel the demand algorithm without restricting gameplay.
  4. Vault Integration: Fully hooks into Vault and your server's economy provider.
  5. Custom Amount Purchasing: Players can seamlessly input custom purchase amounts via chat.

📜 Commands & Permissions

Command Description Permission Default
/shop, /market, /store Opens the main GUI shop. pixelguishop.use True
/shop reload Reloads config.yml and categories.yml dynamically without resetting the active 90-minute cycle. pixelguishop.reload / pixelguishop.admin OP
/shop update or /shop market update Forces an immediate market calculation (updates prices based on recent purchases) and resets the timer securely to 90 minutes. pixelguishop.market.update / pixelguishop.admin OP

🏷️ PlaceholderAPI (PAPI) Placeholders

PixelGUIShop supports PlaceholderAPI out-of-the-box. You can use these in scoreboards, holograms, or chat plugins!

Placeholder Description Output Example
%pixelguishop_market_time_remaining% Formatted remaining time until the next cycle. 45m 30s or Updating...
%pixelguishop_market_next_update% Raw seconds until the next cycle. 2730s
%pixelguishop_item_buy_price_<ITEM_ID>% Current dynamic buy price of the item. 11.50
%pixelguishop_item_sell_price_<ITEM_ID>% Standard sell price of the item. 2.00
%pixelguishop_item_price_state_<ITEM_ID>% Current price state. NORMAL, SALE, or HIGH_DEMAND
%pixelguishop_item_stock_state_<ITEM_ID>% Current stock state. NORMAL, LOW_STOCK, OUT_OF_STOCK
%pixelguishop_item_stock_<ITEM_ID>% Current stock quantity (or 'Unlimited'). Unlimited

(Note: Replace <ITEM_ID> with the exact Bukkit Material name, e.g., DIAMOND_SWORD).

🛒 How to Buy & Sell

When a player clicks an item in the category menu, the Transaction GUI opens, offering the following intuitive options:

  • Buy (Presets): Click the preset buttons to buy 1x or 64x immediately.
  • Buy Custom Amount: Click the custom amount button. The GUI will close and prompt the player in chat: "Please type the amount to buy in chat". Typing a valid number processes the transaction instantly.
  • Sell (Presets): Click the preset buttons to sell 1x or 64x from your inventory.
  • Sell All: Click the "Sell All" button to instantly liquidate all matching items from the player's inventory for profit.

⚙️ Configuration (A-Z)

The plugin generates two files inside plugins/PixelGUIShop/:

1. config.yml

Controls global behaviors and textual announcements.

  • market.update-announcement: The chat message broadcasted server-wide when the 90-minute cycle completes.
  • market.demand-quantity-weight & market.demand-transaction-weight: Internal backend algorithm weights tuning how strongly bulk-buying vs. frequent small-purchasing affects high demand.
  • blacklist: A strict security list of materials that the plugin will never load into the shop, even if mistakenly added to categories.yml (e.g., BEDROCK, COMMAND_BLOCK).

2. categories.yml

Defines the shop layout, categories, and item baseline prices.

Blocks:
  items:
    STONE:
      buy-price: 10.0
      sell-price: 2.0
    GLOW_BERRIES:
      buy-price: 15.0
      sell-price: 3.0
  • The category name (Blocks) represents the menu section.
  • Under items, list the exact Paper/Bukkit 1.21 Material names.
  • Provide a buy-price and sell-price.
  • Important: Use valid inventory items. If you use a block state (like CAVE_VINES), the plugin safely ignores it to prevent crashes.

📈 The Dynamic Market System Explained

The beating heart of PixelGUIShop is the automated, asynchronous MarketEngine.

  1. Transaction Logging: Every time a player buys an item, the exact quantity is logged into the market_history SQLite database.
  2. The 90-Minute Cycle: A strict, non-stoppable timer counts down. If your server restarts, the exact remaining time is durably preserved.
  3. The Calculation: When the timer hits 0 (or an admin runs /shop update), the engine calculates the total quantity and transaction frequency of all items over the past 90 minutes.
  4. State Shifts:
    • Items with high volume and high frequency shift to High Demand, increasing their buy-price by a multiplier.
    • Items ignored by players for a cycle may randomly trigger a Sale, visually slashing their prices in the GUI with strikethrough text to encourage buying.

By design, this ecosystem organically regulates itself without suffocating players via hard stock limits.

Clone this wiki locally