🏪 PhysicShop - Advanced Shop System for Minecraft

---

📋 Overview

PhysicShop transforms your Minecraft server into a thriving marketplace where players can own, customize, and operate their own physical shops. Built with performance and user experience in mind, this plugin offers an intuitive GUI-based system combined with powerful features for both shop owners and customers.

---

✨ Features

🏗️ Dynamic Shop System

• 🌍 Dedicated Shopping World - Isolated void world with custom generation
• 🏢 Multi-Floor Architecture - Automatic floor creation with configurable layouts
• 🎨 Modern Shop Design - Beautiful pre-built shops with smooth stone floors, blackstone ceilings, and quartz walls
• 🚪 Glass Storefronts - 4x3 entrance with glass panels for visibility
• 🔄 Auto-Expansion - New floors automatically generated when all shops are sold

💰 Economy Integration

• 💳 Vault Support - Full integration with any Vault-compatible economy plugin
• 💵 Configurable Pricing - Set shop purchase prices and refund percentages
• 🏦 Partial Refunds - Get money back when selling your shop (configurable percentage)
• 📊 Transaction Tracking - Complete buy/sell history for shops

🛒 Trading System

• 📝 Sign-Based Trading - Create [Buy] and [Sell] signs on chests
• 📦 Bulk Trading - Configure item quantities (1-64 per transaction)
• 💱 Flexible Pricing - Support for both European (comma) and US (dot) decimal formats
• 🔔 Real-Time Notifications - Shop owners receive instant alerts on transactions
• ✅ Smart Validation - Automatic checks for stock, space, and funds

⭐ Rating System

• 🌟 5-Star Rating - Let customers rate shops from 1 to 5 stars
• 📈 Top Rated Shops - Browse the best shops sorted by rating
• 📊 Rating Analytics - View rating distribution and averages
• 🏆 Leaderboard - See top-performing shops
• 💬 Owner Notifications - Get notified when someone rates your shop
• 🔄 Auto-Reset - Ratings cleared when shop changes ownership

🎮 User Interface

• 🖼️ Beautiful GUIs - Intuitive menus for all interactions
• 📱 Main Menu - Central hub for all features
• 🏬 My Shops - Manage all your owned shops
• 🗺️ Floor Browser - Navigate between floors with shop availability info
• ⚡ Quick Actions - Teleport, rate, buy, and sell with simple clicks
• 📄 Pagination - Smooth navigation through large shop lists (45 shops per page)

🔒 Protection System

• 🛡️ Shop Ownership - Only owners can build in their shops
• 🚫 Block Protection - Prevent unauthorized modifications
• 🔐 Container Security - Lock chests, furnaces, and all containers
• 🎯 Entity Protection - Secure item frames, armor stands, and paintings
• 🚪 Interaction Control - Protected doors, buttons, and levers
• 👑 Admin Override - Configurable admin permissions for management

⚙️ Configuration

• 📝 Messages System - Fully customizable messages in messages.yml
• 🎨 Color Support - Full color code support (&a, &c, etc.)
• 🌐 Multi-Language Ready - Easy translation support
• 🔧 Flexible Settings - Configure shop size, prices, limits, and more
• 📊 Shop Limits - Set maximum shops per player
• 💾 Data Persistence - All data saved in organized YAML files

🏃 Performance

• ⚡ Optimized Generation - Efficient world and shop creation
• 💾 Smart Caching - Reduced database queries
• 🔄 Async Operations - Non-blocking shop operations
• 📦 Lightweight - Minimal server impact

---

📜 Commands & Permissions

Commands

Command	Description	Permission
/physicshop or /ps	Open main menu	None
/ps create	Create a new floor	physicshop.admin.create
/ps delete <id>	Delete a floor	physicshop.admin.delete
/ps tp <id>	Teleport to a floor	physicshop.teleport
/ps list	List all floors	physicshop.list
/ps info <id>	View floor information	physicshop.info
/ps myshops	View your owned shops	None
/ps sell <id>	Sell one of your shops	None
/ps menu	Reopen main menu	None

Permissions

Permission	Description	Default
physicshop.*	All permissions	OP
physicshop.admin.*	All admin permissions	OP
physicshop.user.*	All user permissions	All Players
physicshop.admin.create	Create floors	OP
physicshop.admin.delete	Delete floors	OP
physicshop.admin.build	Build anywhere in PhysicShop world	OP
physicshop.teleport	Teleport to floors	All Players
physicshop.list	List all floors	All Players
physicshop.info	View floor info	All Players

---

🎯 How It Works

🏪 For Shop Owners

1. Purchase a Shop

   • Right-click on a "FOR SALE" sign in any shop
   • Confirm purchase in the GUI
   • Shop is instantly yours!

2. Build Your Shop

   • Place blocks, chests, and decorations inside
   • Your shop, your rules!
   • Protected from other players

3. Set Up Trading

   • Place a chest with items
   • Attach a sign to the chest
   • Write:

     [Sell]  or  [Buy]
     16      (quantity)
     10.50   (price)
     (auto-filled item name)

4. Manage Your Empire
   • View all shops: /ps myshops
   • Teleport instantly to any shop
   • Track your ratings and reputation

🛍️ For Customers

1. Browse Shops

   • Open menu: /ps
   • View "Top Rated Shops" ⭐
   • Filter by floor or rating

2. Shop & Trade

   • Right-click trade signs to buy/sell
   • Instant transactions
   • Safe and secure

3. Rate Your Experience

   • Right-click any shop in Top Rated GUI
   • Give 1-5 stars
   • Help others find the best shops!

---

🔧 Installation

1. Requirements

   • Spigot/Paper 1.21+
   • Vault
   • Economy plugin (EssentialsX, CMI, etc.)

2. Install

   1. Download PhysicShop.jar
   2. Place in /plugins/ folder
   3. Restart server
   4. Configure config.yml and messages.yml
   5. Reload or restart

3. First Setup
   • First floor is auto-created on startup
   • Default world: PhysicShopWorld
   • Access via /ps command

---

⚙️ Configuration

config.yml

# Shop dimensions
shop-size:
  length: 10   # Length along corridor (X axis)
  width: 10    # Depth away from corridor (Z axis)
  height: 5    # Height of the shop

# Corridor settings
corridor-length: 50  # Total corridor length

# Economy
shop-price: 1000.0              # Purchase price
shop-refund-percentage: 50.0    # Refund on sell (0-100)
max-shop-per-player: 3          # Max shops per player

messages.yml

Fully customizable messages with color codes:

• All player messages
• GUI titles and descriptions
• Error messages
• Success notifications

Example:

shop:
  purchased: "&aSuccessfully purchased shop #{id}!"
  purchase-price: "&7Price: &6${price}"

---

🎨 Customization

Trade Signs

Create unlimited trading possibilities:

• Buy signs (shop purchases from players)
• Sell signs (shop sells to players)
• Custom quantities
• Flexible pricing

---

📊 Data Storage

All data stored in organized YAML files:

• data.yml - Shop ownership, coordinates, ratings
• messages.yml - All text and messages
• config.yml - Plugin configuration

---

📝 License

This plugin is proprietary software. All rights reserved.

---

🙏 Credits

Built with ❤️ for the Minecraft community

Dependencies:

• Vault
• Spigot/Paper

---