### Installation Steps

Source: https://github.com/linghun91/globalshop/blob/master/README.md

Step-by-step guide for installing the GlobalShop plugin on a Minecraft server.

```APIDOC
Installation Steps:
1. Download the latest version of the GlobalShop plugin.
2. Place the plugin file into your server's `plugins` directory.
3. Install the Vault plugin and an economy plugin (e.g., EssentialsX).
4. Optionally, install the PlayerPoints plugin for voucher support.
5. Restart the server.
6. Modify configuration files as needed.
```

--------------------------------

### Auction Command Examples

Source: https://github.com/linghun91/globalshop/blob/master/README.md

Demonstrates the usage of the /auction command for selling items with different pricing options (starting bid, buy-it-now price, currency type).

```shell
/auction sell 100          # 起拍价100金币
/auction sell 100 500      # 起拍价100，一口价500金币
/auction sell 100 500 2    # 起拍价100，一口价500点券
```

--------------------------------

### Usage Guide

Source: https://github.com/linghun91/globalshop/blob/master/README.md

A guide to using the GlobalShop plugin's commands for players, covering listing items, searching, opening the auction house, managing auctions, and collecting items.

```APIDOC
Usage Guide:
1. Listing Items: Hold the item and use `/auction sell <price>`.
2. Searching Items: Use `/auction search <keyword>`.
3. Opening Auction House: Use `/auction open` to open the main interface.
4. Managing Auctions: Use `/auction my` to view your own auctions.
5. Collecting Items: Use `/auction collect` to claim items to be collected.
```

--------------------------------

### Installation Requirements

Source: https://github.com/linghun91/globalshop/blob/master/README.md

System requirements for installing the GlobalShop plugin, including Minecraft version, server type, Java version, and required/optional dependencies.

```APIDOC
System Requirements:
  - Minecraft Version: 1.20.1 - 1.21.5
  - Server Type: Paper (recommended) / Spigot / Bukkit
  - Java Version: Java 17+
  - Dependencies:
    - Vault (Required)
    - PlayerPoints (Optional)
```

--------------------------------

### Auction Search Command Examples

Source: https://github.com/linghun91/globalshop/blob/master/README.md

Illustrates how to use the /auction search command to find items containing specific keywords.

```shell
/auction search 钻石        # 搜索包含"钻石"的物品
/auction search 剑          # 搜索包含"剑"的物品
```

--------------------------------

### Permission Group Recommendations

Source: https://github.com/linghun91/globalshop/blob/master/README.md

Provides example configurations for common player permission groups, integrating dynamic listing limits.

```yaml
# Normal player group - uses global config limits
default:
  permissions:
    - globalshop.use
    - globalshop.sell
    - globalshop.buy
    - globalshop.bid
    - globalshop.search

# VIP player group - can list 10 items
vip:
  permissions:
    - globalshop.use
    - globalshop.sell
    - globalshop.buy
    - globalshop.bid
    - globalshop.search
    - globalshop.maxsell.10

# SVIP player group - can list 20 items
svip:
  permissions:
    - globalshop.use
    - globalshop.sell
    - globalshop.buy
    - globalshop.bid
    - globalshop.search
    - globalshop.maxsell.20

# Admin group - almost unlimited
admin:
  permissions:
    - globalshop.*
```

--------------------------------

### Auction HUD Command Examples

Source: https://github.com/linghun91/globalshop/blob/master/README.md

Shows commands for managing holographic displays for the auction house, including creation and removal.

```shell
/auction hud create 主城拍卖行    # 创建名为"主城拍卖行"的全息显示
/auction hud remove 主城拍卖行    # 移除该全息显示
```

--------------------------------

### Dynamic Listing Limit System (Permissions)

Source: https://github.com/linghun91/globalshop/blob/master/README.md

Explains the priority and examples of using permission nodes like `globalshop.maxsell.X` to dynamically set player listing limits.

```yaml
# Permission priority: Custom Permissions > Global Config
# If a player has globalshop.maxsell.X, use that quantity.
# If multiple globalshop.maxsell.X permissions exist, the highest value is used.
# If no relevant permission exists, use config.yml's max_listings_per_player setting.
```

```yaml
# Permission examples (LuckPerms/PermissionsEx)
permissions:
  # Normal player - uses global config (default 3)
  default:
    - globalshop.use
    - globalshop.sell
    - globalshop.buy
    - globalshop.bid
    - globalshop.search

  # VIP player - can list 10 items
  vip:
    - globalshop.maxsell.10

  # SVIP player - can list 20 items
  svip:
    - globalshop.maxsell.20

  # Admin - almost unlimited
  admin:
    - globalshop.maxsell.999
```

--------------------------------

### Auction Item Data Model

Source: https://github.com/linghun91/globalshop/blob/master/README.md

Defines the structure for an auction item, including its unique ID, seller information, item data, pricing details (starting price, buy-it-now price, current bid), time information (start, end, remaining), and status (active, sold, expired). It also stores bidding history and provides utility methods for status checks and time formatting.

```Java
public class AuctionItem {
    private UUID id;
    private UUID sellerId;
    private String sellerName;
    private ItemStack itemStack;
    private double startPrice;
    private double buyItNowPrice;
    private double currentBid;
    private UUID currentBidderId;
    private long startTime;
    private long endTime;
    private AuctionStatus status;
    private CurrencyType currencyType;
    // ... other fields like bidding history

    public boolean isActive() {
        return status == AuctionStatus.ACTIVE && System.currentTimeMillis() < endTime;
    }

    public boolean isExpired() {
        return status == AuctionStatus.ACTIVE && System.currentTimeMillis() >= endTime;
    }

    public String getFormattedRemainingTime() {
        // Format remaining time into a human-readable string (e.g., "2h 30m")
        return "...";
    }

    // Enum for AuctionStatus: ACTIVE, SOLD, EXPIRED, CANCELLED
}

enum AuctionStatus { ACTIVE, SOLD, EXPIRED, CANCELLED }
```

--------------------------------

### Quick Configuration

Source: https://github.com/linghun91/globalshop/blob/master/README.md

Instructions for performing initial configuration of the GlobalShop plugin, including editing config files and reloading settings.

```APIDOC
Quick Configuration:
1. Edit `plugins/GlobalShop/config.yml` to set database and economy configurations.
2. Edit `plugins/GlobalShop/message.yml` to customize interface texts.
3. Use the command `/auction reload` to reload configurations.
4. Use the command `/auction open` to test the auction house functionality.
```

--------------------------------

### GlobalShop Plugin Commands

Source: https://github.com/linghun91/globalshop/blob/master/README.md

Provides an overview of the commands available for users, administrators, and for managing holographic displays within the GlobalShop plugin. Includes command usage, descriptions, and required permissions.

```APIDOC
GlobalShop Commands:

User Commands:
  /auction help
    - Displays help information.
    - Permission: globalshop.use

  /auction open
    - Opens the main auction house GUI.
    - Permission: globalshop.use

  /auction sell <start_price> [buy_it_now_price] [currency_type]
    - Lists the item in hand for auction.
    - currency_type: 1 for Gold, 2 for Points.
    - Permission: globalshop.sell

  /auction search <keyword>
    - Searches for items by keyword.
    - Permission: globalshop.use

  /auction my
    - Shows the player's ongoing auctions.
    - Permission: globalshop.use

  /auction collect
    - Collects items that are ready to be claimed.
    - Permission: globalshop.use

Administrator Commands:
  /auction reload
    - Reloads all plugin configuration files.
    - Permission: globalshop.admin

  /auction close
    - Forcefully closes all active auctions.
    - Permission: globalshop.admin

  /auction checkexpired
    - Manually checks for and processes expired items.
    - Permission: globalshop.admin

  /auction info <player>
    - Queries auction information for a specific player.
    - Permission: globalshop.admin

Hologram Display Commands:
  /auction hud create <name>
    - Creates a holographic auction house at the current location.
    - Permission: globalshop.admin

  /auction hud remove <name>
    - Removes a holographic auction house by its name.
    - Permission: globalshop.admin

  /auction hud list
    - Lists all configured holographic auction houses.
    - Permission: globalshop.admin

  /auction hud reload
    - Reloads the configuration for holographic auction houses.
    - Permission: globalshop.admin
```

--------------------------------

### Configuration Management

Source: https://github.com/linghun91/globalshop/blob/master/README.md

Manages plugin configurations, including core settings for database, economy, and GUI. Supports loading from `config.yml` and provides hot-reloading functionality for configuration changes. Also manages limits for item listings and prices.

```Java
public class ConfigManager {

    private static ConfigManager instance;
    private FileConfiguration config;

    public static ConfigManager getInstance() {
        if (instance == null) {
            instance = new ConfigManager();
        }
        return instance;
    }

    public void loadConfig(Plugin plugin) {
        // Save default config if it doesn't exist
        plugin.saveDefaultConfig();
        this.config = plugin.getConfig();
        // Load specific settings...
    }

    public boolean isHotReloadEnabled() {
        return config.getBoolean("settings.hot-reload", true);
    }

    public int getMaxListingLimit() {
        return config.getInt("limits.max-listings", 10);
    }

    // ... other configuration getters
}
```

--------------------------------

### Command System

Source: https://github.com/linghun91/globalshop/blob/master/README.md

Provides a comprehensive command structure for users and administrators. User commands include `help`, `sell`, `search`, `my`, and `collect`. Administrator commands cover `reload`, `close`, `checkexpired`, and `info`. It also includes commands for managing holograms (`hud create`, `hud remove`, etc.) and supports full tab completion for all commands.

```Java
public class AuctionCommand implements CommandExecutor, TabCompleter {

    @Override
    public boolean onCommand(CommandSender sender, Command command, String label, String[] args) {
        if (!(sender instanceof Player)) {
            sender.sendMessage("Only players can use this command.");
            return true;
        }
        Player player = (Player) sender;

        if (args.length == 0) {
            // Show help or main menu
            // GuiManager.getInstance().openMainMenu(player);
            return true;
        }

        String subCommand = args[0].toLowerCase();
        switch (subCommand) {
            case "sell":
                // Handle sell command
                // ...
                break;
            case "search":
                // Handle search command
                // ...
                break;
            case "my":
                // Handle my auctions command
                // ...
                break;
            case "reload":
                // Handle reload command (admin)
                // ...
                break;
            case "hud":
                // Handle hud commands (admin)
                // ...
                break;
            default:
                player.sendMessage("Unknown command. Type /globalshop help.");
                break;
        }
        return true;
    }

    @Override
    public List<String> onTabComplete(CommandSender sender, Command command, String alias, String[] args) {
        // Implement tab completion logic for commands and arguments
        // ...
        return Collections.emptyList();
    }
}
```

--------------------------------

### Web Interface System (v1.4.0.9)

Source: https://github.com/linghun91/globalshop/blob/master/README.md

Overview of the web interface system, including its responsive design, real-time data display, security controls, and performance optimizations.

```APIDOC
Feature: Web Interface System
Version: v1.4.0.9

Description:
  - Responsive design: supports both PC and mobile devices.
  - Real-time data: displays current auction items.
  - Security control: access permissions and security protection.
  - High performance: asynchronous processing and cache optimization.

Web Interface Features:
  - Responsive UI for all devices.
  - Live auction item display.
  - Access control and security measures.
  - Optimized for performance.
```

--------------------------------

### Java: WebServer - Built-in lightweight HTTP server

Source: https://github.com/linghun91/globalshop/blob/master/README.md

The WebServer class implements a built-in lightweight HTTP server. It is designed for responsive access from both PC and mobile devices, incorporating security controls for access permissions and protection. The server is optimized for high performance through asynchronous processing and caching.

```java
/**
 * WebServer.java - Web服务器
 * Implements a built-in lightweight HTTP server:
 * - HTTP service: built-in lightweight HTTP server
 * - Responsive design: supports PC and mobile access
 * - Security control: access permissions and security protection
 * - High performance: asynchronous processing and cache optimization
 */
// Actual code for WebServer would go here.
```

--------------------------------

### Database Configuration

Source: https://github.com/linghun91/globalshop/blob/master/README.md

Defines settings for connecting to the database, supporting SQLite and MySQL with options for host, port, credentials, and table prefixes.

```yaml
database:
  type: "sqlite"              # Database type: sqlite/mysql
  mysql:
    host: "localhost"         # MySQL host address
    port: 3306               # MySQL port
    database: "globalshop"    # Database name
    username: "root"          # Username
    password: "password"      # Password
    table_prefix: "gs_"       # Table prefix to avoid conflicts
```

--------------------------------

### GUI Interface Configuration

Source: https://github.com/linghun91/globalshop/blob/master/README.md

Customizes the graphical user interface (GUI) for the auction house, including main menu and search menu titles, sizes, and pagination settings.

```yaml
gui:
  main_menu:
    title: "§6§l全球拍卖行"    # Main menu title
    size: 54                  # GUI size
    items_per_page: 45        # Items displayed per page

  search_menu:
    title: "§e§l搜索物品"     # Search menu title
    history_limit: 10         # Search history limit

  sort:
    default_type: "TIME_DESC" # Default sort order: TIME_ASC/TIME_DESC/PRICE_ASC/PRICE_DESC/NAME_ASC/NAME_DESC
```

--------------------------------

### GlobalShop Plugin Main Class

Source: https://github.com/linghun91/globalshop/blob/master/README.md

The main class of the GlobalShop plugin, responsible for initializing and managing all other components. It handles plugin startup, registration of commands and event listeners, scheduling of tasks, and provides unified access to various managers. It also integrates with bStats for usage statistics.

```Java
public class GlobalShop extends JavaPlugin {

    @Override
    public void onEnable() {
        // Initialize configuration manager
        ConfigManager.getInstance().loadConfig(this);

        // Initialize database manager
        DatabaseManager.getInstance().initializeDatabase(this);

        // Initialize economy manager
        EconomyManager.getInstance().initializeEconomy(this);

        // Initialize GUI manager
        GuiManager.getInstance().initializeGui(this);

        // Register commands
        getCommand("globalshop").setExecutor(new AuctionCommand());

        // Register event listeners
        getServer().getPluginManager().registerEvents(new GuiListener(), this);

        // Start scheduled tasks (e.g., auction checks, hologram updates)
        // ...

        // Integrate bStats
        // ...

        getLogger().info("GlobalShop has been enabled!");
    }

    @Override
    public void onDisable() {
        // Clean up resources
        // ...
        getLogger().info("GlobalShop has been disabled.");
    }
}
```

--------------------------------

### Core Features Implemented

Source: https://github.com/linghun91/globalshop/blob/master/README.md

List of core features that have been fully implemented in the GlobalShop plugin.

```APIDOC
Completed Features:
  - Full Auction System (Starting Price, Buy Now, Bidding)
  - Dual Currency System (Vault + PlayerPoints)
  - Holographic Display System
  - Web Interface System
  - Client Auto Translation System (Paper Component API)
  - Smart Broadcast System
  - Powerful Search Functionality
  - Data Statistics System
  - Administrator Tools
  - Item Mailbox System
```

--------------------------------

### Economy Configuration

Source: https://github.com/linghun91/globalshop/blob/master/README.md

Configures economic aspects, including currency names, symbols, fee rates for buyers and sellers, and minimum fees for both Vault and PlayerPoints integration.

```yaml
economy:
  vault:
    currency_name: "金币"     # Currency name
    currency_symbol: "¥"      # Currency symbol
    buyer_fee_rate: 0.05      # Buyer fee rate (5%)
    seller_fee_rate: 0.03     # Seller fee rate (3%)
    min_fee: 1.0             # Minimum fee

  playerpoints:
    currency_name: "点券"     # Points name
    currency_symbol: "P"      # Points symbol
    buyer_fee_rate: 0.02      # Buyer fee rate (2%)
    seller_fee_rate: 0.01     # Seller fee rate (1%)
    min_fee: 1               # Minimum fee

  max_price_digits: 10       # Maximum digits allowed for price
```

--------------------------------

### Database System (v1.4.0.8)

Source: https://github.com/linghun91/globalshop/blob/master/README.md

Details on the database system, supporting dual databases (SQLite, MySQL), table prefix support, data integrity, and performance optimizations.

```APIDOC
Feature: Database System
Version: v1.4.0.8

Description:
  - Dual database support: SQLite (default) and MySQL.
  - Table prefix support: custom table prefixes for MySQL to avoid conflicts.
  - Data integrity: comprehensive data validation and error handling.
  - Performance optimization: asynchronous database operations and connection management.

Database Options:
  - Default: SQLite
  - Supported: MySQL
  - MySQL Table Prefix: configurable.
  - Operations: Asynchronous for performance.
```

--------------------------------

### Holographic Display System (v1.4.0.10)

Source: https://github.com/linghun91/globalshop/blob/master/README.md

Information on the holographic display system, featuring 3D item display, dynamic text, history records, and multi-point support.

```APIDOC
Feature: Holographic Display System
Version: v1.4.0.10

Description:
  - 3D item display: realistic 3D item rotation display.
  - Dynamic text: real-time updated auction information.
  - History records: display of auction history.
  - Multi-point support: ability to create multiple holographic auction houses.

Capabilities:
  - 3D item rendering.
  - Real-time data updates.
  - Display of auction history.
  - Support for multiple holographic locations.
```

--------------------------------

### Broadcast System Configuration

Source: https://github.com/linghun91/globalshop/blob/master/README.md

Enables and configures various broadcast events (item listed, sold, bid placed) and their display locations (chat, bossbar, title, actionbar).

```yaml
broadcast:
  enabled: true               # Global broadcast toggle

  events:
    item_listed: true         # Item listed broadcast
    item_sold: true           # Item sold broadcast
    bid_placed: true          # Bid placed broadcast
    bid_confirmed: true       # Bid confirmed broadcast

  locations:
    chat: true                # Broadcast in chat
    bossbar: false            # Broadcast on boss bar
    title: false              # Broadcast with title
    subtitle: false           # Broadcast with subtitle
    actionbar: false          # Broadcast on action bar

  bossbar:
    color: "YELLOW"           # Boss bar color
    style: "SOLID"            # Boss bar style
    duration: 5               # Display duration (seconds)

  title:
    fade_in: 10               # Fade in time (ticks)
    stay: 40                  # Stay duration (ticks)
    fade_out: 10              # Fade out time (ticks)
```

--------------------------------

### GUI Interface Optimizations (v1.4.0.12)

Source: https://github.com/linghun91/globalshop/blob/master/README.md

Optimizations for the GUI interface, including custom listing times, pagination system fixes, bidding system repairs, and sold items interface improvements.

```APIDOC
Feature: GUI Interface Optimizations
Version: v1.4.0.12

Description:
  - Custom listing time: clock button supports flexible time settings.
  - Pagination system optimization: fixed unresponsive pagination buttons.
  - Bidding system repair: resolved various exceptions in the bidding interface.
  - Sold items interface: improved sales statistics and revenue display.

GUI Improvements:
  - Flexible listing time settings.
  - Fixed pagination button issues.
  - Resolved bidding interface errors.
  - Enhanced sold items display.
```

--------------------------------

### Client Auto Translation System (v1.5.2.23)

Source: https://github.com/linghun91/globalshop/blob/master/README.md

Details on the client auto translation system, highlighting its removal of hardcoded mappings, integration with Paper Component API, zero maintenance, performance improvements, and Adventure API support.

```APIDOC
Feature: Client Auto Translation System
Version: v1.5.2.23

Description:
  - Fully removed hardcoded mappings (minecraft_lang.yml, MinecraftLanguageManager.java).
  - Integrated with Paper Component API using Material.translationKey() for true client translation.
  - Zero maintenance cost: no translation files to maintain, automatic support for all official Minecraft languages.
  - Significant performance boost: no file loading, zero memory footprint, simplified complex logic.
  - Code architecture optimized: unified MaterialTranslationManager for consistent method usage.
  - Adventure API support: added Adventure API dependency for Component support.

Key Changes:
  - Removed minecraft_lang.yml and MinecraftLanguageManager.java.
  - Utilizes Material.translationKey() for translations.
  - Supports all official Minecraft languages automatically.
  - Improved performance and reduced memory usage.
  - Integrated Adventure API for Component support.
```

--------------------------------

### Multilingual Support System (v1.4.0.12)

Source: https://github.com/linghun91/globalshop/blob/master/README.md

Overview of the multilingual support system, covering the number of supported languages, smart language detection, internationalized messages, auction task support, and dynamic switching.

```APIDOC
Feature: Multilingual Support System
Version: v1.4.0.12

Description:
  - Full support for 8 languages: Chinese, English, Spanish, German, French, Japanese, Russian, Vietnamese.
  - Smart language detection: automatically detects client language and switches the interface.
  - Message internationalization: complete translation for all GUI texts, tooltips, and error messages.
  - Auction task messages: full multilingual support for auction_task components.
  - Dynamic switching: supports runtime language switching without requiring a server restart.

Supported Languages:
  - zh_CN (Chinese)
  - en_US (English)
  - es_ES (Spanish)
  - de_DE (German)
  - fr_FR (French)
  - ja_JP (Japanese)
  - ru_RU (Russian)
  - vi_VN (Vietnamese)
```

--------------------------------

### Hologram Display Management

Source: https://github.com/linghun91/globalshop/blob/master/README.md

Manages the creation and real-time updating of 3D holographic displays for auctions. Supports multiple display points and dynamic content management for auction information. Includes configuration management for hologram settings and a dedicated command manager for hologram-related operations.

```Java
public class HologramDisplayManager {

    private List<Hologram> activeHolograms;

    public void createHologram(Location location, List<String> lines) {
        // Create a new hologram at the specified location
        // ...
    }

    public void updateHologram(Hologram hologram, List<String> newLines) {
        // Update the content of an existing hologram
        // ...
    }

    public void removeHologram(Hologram hologram) {
        // Remove a hologram from the world
        // ...
    }

    // ... methods for managing hologram lifecycle and updates
}

public class HologramUpdateTask implements Runnable {
    private HologramDisplayManager hologramManager;

    public HologramUpdateTask(HologramDisplayManager hologramManager) {
        this.hologramManager = hologramManager;
    }

    @Override
    public void run() {
        // Periodically update all active holograms
        // hologramManager.updateAllHolograms();
    }
}
```

--------------------------------

### Java: WebConfig - Manages web service configuration

Source: https://github.com/linghun91/globalshop/blob/master/README.md

WebConfig handles the configuration settings for the web service, including service ports and interface styling. It supports hot reloading of configurations, allowing changes to be applied without restarting the server.

```java
/**
 * WebConfig.java - Web配置管理
 * Manages web service configuration:
 * - Configuration management: web service related configurations
 * - Port setting: configurable service port
 * - UI configuration: web interface style and layout configuration
 * - Hot reload: supports configuration hot reloading
 */
// Actual code for WebConfig would go here.
```

--------------------------------

### Economy System Enhancements (v1.4.0.12)

Source: https://github.com/linghun91/globalshop/blob/master/README.md

Improvements to the economy system, including price limits, PlayerPoints soft dependency, transaction fee optimization, and dual currency support.

```APIDOC
Feature: Economy System Enhancements
Version: v1.4.0.12

Description:
  - Price limit system: configurable maximum digit limit for prices.
  - PlayerPoints soft dependency: improved plugin compatibility.
  - Transaction fee optimization: comprehensive calculation of buyer and seller fees.
  - Dual currency support: supports Vault (coins) and PlayerPoints (vouchers).

Supported Currencies:
  - Vault (Coins)
  - PlayerPoints (Vouchers)
```

--------------------------------

### Auction System Configuration

Source: https://github.com/linghun91/globalshop/blob/master/README.md

Sets parameters for the auction system, such as default, minimum, and maximum auction durations, player listing limits, and bidding increment rules.

```yaml
auction:
  default_duration: 86400    # Default auction duration (seconds)
  min_duration: 3600         # Minimum auction duration (1 hour)
  max_duration: 604800       # Maximum auction duration (7 days)
  max_auctions_per_player: 10 # Maximum items a player can list
  check_interval: 60         # Auction check interval (seconds)

  bidding:
    min_increment_rate: 0.05  # Minimum bid increment rate (5%)
    min_increment_amount: 1   # Minimum bid increment amount
```

--------------------------------

### Java: WebDataProvider - Provides and optimizes web data

Source: https://github.com/linghun91/globalshop/blob/master/README.md

The WebDataProvider is responsible for converting database data into web-friendly formats and optimizing data queries with caching. It provides statistical and analytical data related to auctions and ensures real-time synchronization with in-game data.

```java
/**
 * WebDataProvider.java - Web数据提供者
 * Provides and optimizes data for web services:
 * - Data conversion: converts database data to web format
 * - Query optimization: efficient data querying and caching
 * - Statistics data: provides auction statistics and analysis data
 * - Real-time synchronization: real-time synchronization with in-game data
 */
// Actual code for WebDataProvider would go here.
```

--------------------------------

### Event Listener - GUI Interactions

Source: https://github.com/linghun91/globalshop/blob/master/README.md

Handles all player interactions within the plugin's GUIs. This includes listening for inventory clicks, drags, and closes. It processes actions like selecting items, confirming purchases, placing bids, and managing personal auctions. Player chat input for bid amounts or search queries is also managed here.

```Java
public class GuiListener implements Listener {

    @EventHandler
    public void onInventoryClick(InventoryClickEvent event) {
        Player player = (Player) event.getWhoClicked();
        Inventory inventory = event.getInventory();
        ItemStack clickedItem = event.getCurrentItem();

        // Check if the inventory is one of GlobalShop's GUIs
        if (inventory.getHolder() instanceof AuctionGUIHolder) { // Assuming a custom InventoryHolder
            event.setCancelled(true);
            // Handle clicks for main menu, search, sell, bid, etc.
            // Example: handleMainMenuClick(player, clickedItem);
            // Example: handleSellMenuClick(player, clickedItem);
            // Example: handleBidMenuClick(player, clickedItem);
        }
    }

    @EventHandler
    public void onPlayerChat(AsyncPlayerChatEvent event) {
        Player player = event.getPlayer();
        String message = event.getMessage();

        // Check if the player is currently in a state requiring chat input (e.g., bidding amount)
        // if (playerStateTracker.isBiddingAmount(player)) {
        //    event.setCancelled(true);
        //    // Process bid amount input
        //    // GuiManager.getInstance().handleBidAmountInput(player, message);
        // }
    }

    // ... other event handlers like onInventoryClose, onInventoryDrag
}
```

--------------------------------

### Broadcast System Enhancements (v1.4.0.12)

Source: https://github.com/linghun91/globalshop/blob/master/README.md

Details on optimizations made to the broadcast system, including item hover information, multi-position broadcasting, message customization, quantity display fixes, and gradient color compatibility.

```APIDOC
Feature: Broadcast System Enhancements
Version: v1.4.0.12

Description:
  - Item hover information: fully preserves item information display with gradient color effects.
  - Multi-position broadcasting: supports chat box, boss bar, title, and action bar.
  - Message customization: all broadcast messages support complete custom configuration.
  - Quantity display fix: resolved issue with duplicate item quantity display.
  - Gradient color compatibility: perfect support for items with gradient color codes.

Broadcast Locations:
  - Chat Box
  - Boss Bar
  - Title
  - Action Bar
```

--------------------------------

### Debug Configuration

Source: https://github.com/linghun91/globalshop/blob/master/README.md

Settings for enabling and configuring the debug mode, including log levels and specific operations to log.

```yaml
debug:
  enabled: false              # 调试模式开关
  log_level: "INFO"          # 日志级别: DEBUG/INFO/WARN/ERROR
  log_database: false        # 记录数据库操作
  log_economy: false         # 记录经济操作
  log_gui: false             # 记录GUI操作
```

--------------------------------

### Administrator Features (v1.4.0.11)

Source: https://github.com/linghun91/globalshop/blob/master/README.md

Details on administrator functionalities, including forced delisting, configuration reload optimization, permission system, and debug system.

```APIDOC
Feature: Administrator Features
Version: v1.4.0.11

Description:
  - Forced delisting function: administrators can force delist any item.
  - Configuration reload optimization: improved hot-reloading of configurations.
  - Permission system: fine-grained permission control.
  - Debug system: comprehensive debug information and error tracking.

Admin Commands/Features:
  - Force delist items.
  - Hot-reload configurations.
  - Fine-grained permission control.
  - Access to debug information.
```

--------------------------------

### Web Service Configuration

Source: https://github.com/linghun91/globalshop/blob/master/README.md

Configuration settings for the web service component of the plugin, including its enabled state, port, refresh interval, and display limits.

```yaml
web:
  enabled: true               # Web服务开关
  port: 8080                 # 服务端口
  refresh_interval: 30       # 刷新间隔 (秒)
  max_items_display: 50      # 最大显示物品数量

  security:
    allowed_ips: []           # 允许访问的IP (空=全部允许)
    rate_limit: 100           # 请求频率限制 (每分钟)
```

--------------------------------

### Hologram Configuration

Source: https://github.com/linghun91/globalshop/blob/master/README.md

Configures the hologram system, including enabling it, setting update intervals, maximum displayed items, and visual properties for item rotation and text display.

```yaml
hologram:
  enabled: true               # Global hologram toggle
  update_interval: 20         # Update interval (ticks)
  max_display_items: 5        # Maximum items to display

  item_display:
    rotation_speed: 2.0       # Item rotation speed
    bounce_height: 0.3        # Item bounce height
    scale: 1.0               # Item scale

  text_display:
    line_height: 0.3          # Text line height
    background: true          # Text background
    shadow: true              # Text shadow
```

--------------------------------

### Permission Nodes

Source: https://github.com/linghun91/globalshop/blob/master/README.md

Lists the available permission nodes for the GlobalShop plugin, detailing their function and default status.

```APIDOC
Permission Nodes:
  globalshop.use: Basic usage permission (open interface, view my auctions, etc.) - Default: true
  globalshop.sell: Permission to list items - Default: true
  globalshop.buy: Permission to buy items - Default: true
  globalshop.bid: Permission to participate in auctions - Default: true
  globalshop.search: Permission to search items - Default: true
  globalshop.maxsell.X: Custom listing quantity permission (X is a number) - Default: false
  globalshop.admin: Administrator permission (reload, force close, etc.) - Default: op
  globalshop.admin.hud: Hologram management permission - Default: op
```

--------------------------------

### Message Management

Source: https://github.com/linghun91/globalshop/blob/master/README.md

Handles all in-game messages and GUI text. Supports multi-language configurations (up to 8 languages), dynamic placeholder replacement, and formatting with color codes. This ensures a localized and user-friendly experience.

```Java
public class MessageManager {

    private static MessageManager instance;
    private Map<String, Map<String, String>> messages;
    private String defaultLocale = "en"; // Default language

    public static MessageManager getInstance() {
        if (instance == null) {
            instance = new MessageManager();
        }
        return instance;
    }

    public void loadMessages(Plugin plugin) {
        // Load messages from language files (e.g., messages_en.yml, messages_zh.yml)
        // Store them in the 'messages' map.
    }

    public String getMessage(String key, String locale, Object... placeholders) {
        // Retrieve message based on key and locale, apply placeholders and color codes.
        // Example: return String.format(messages.get(locale).get(key), placeholders);
        return "Message for " + key;
    }

    // ... methods for setting locale, getting messages with default locale
}
```

--------------------------------

### Economy Management

Source: https://github.com/linghun91/globalshop/blob/master/README.md

Manages the dual currency system, supporting both Vault (for in-game currency) and PlayerPoints (for a point system). It handles balance checks, deductions, and additions, as well as currency formatting. Includes a configurable fee system for buyers and sellers, and logic for bid calculations and price validation.

```Java
public class EconomyManager {

    private static EconomyManager instance;
    private Economy vaultEconomy;
    private PlayerPointsAPI playerPointsAPI;

    public static EconomyManager getInstance() {
        if (instance == null) {
            instance = new EconomyManager();
        }
        return instance;
    }

    public void initializeEconomy(Plugin plugin) {
        // Hook into Vault and PlayerPoints APIs
        // ...
    }

    public double getBalance(Player player, CurrencyType type) {
        // Returns balance for Vault or PlayerPoints
        return 0.0;
    }

    public boolean withdraw(Player player, CurrencyType type, double amount) {
        // Withdraws currency
        return false;
    }

    public boolean deposit(Player player, CurrencyType type, double amount) {
        // Deposits currency
        return false;
    }

    public double calculateSellerFee(double price) {
        // Calculate seller fee based on config
        return price * getConfig().getDouble("fees.seller-rate", 0.05);
    }

    public double calculateBuyerFee(double price) {
        // Calculate buyer fee based on config
        return price * getConfig().getDouble("fees.buyer-rate", 0.02);
    }

    public double calculateMinBidIncrement(double currentPrice) {
        // Calculate minimum bid increment based on config
        return currentPrice * getConfig().getDouble("bidding.min-bid-increment-rate", 0.05);
    }

    // Enum for CurrencyType: VAULT, PLAYER_POINTS
}

enum CurrencyType { VAULT, PLAYER_POINTS }
```

--------------------------------

### Multilingual Configuration

Source: https://github.com/linghun91/globalshop/blob/master/README.md

Configuration options for the plugin's multilingual support, specifying the default language, auto-detection settings, and a list of supported languages.

```yaml
language:
  default: "zh_CN"            # 默认语言
  auto_detect: true           # 自动检测客户端语言

  supported:                  # 支持的语言列表
    - "zh_CN"                 # 中文
    - "en_US"                 # 英语
    - "es_ES"                 # 西班牙语
    - "de_DE"                 # 德语
    - "fr_FR"                 # 法语
    - "ja_JP"                 # 日语
    - "ru_RU"                 # 俄语
    - "vi_VN"                 # 越南语
```

--------------------------------

### Java: ChatUtils - Utility class for chat and text formatting

Source: https://github.com/linghun91/globalshop/blob/master/README.md

ChatUtils provides essential tools for managing chat messages and text formatting. It includes intelligent item name retrieval and formatting, user-friendly time display, and robust handling of color codes and text formatting. The class also offers comprehensive string processing and validation capabilities.

```java
/**
 * ChatUtils.java - 聊天和文本工具类
 * Provides utility functions for chat and text:
 * - Item names: intelligent item name acquisition and formatting
 * - Time formatting: friendly time display format
 * - Message formatting: color codes and format processing
 * - Text processing: string manipulation and validation
 */
// Actual code for ChatUtils would go here.
```

--------------------------------

### Features Under Development

Source: https://github.com/linghun91/globalshop/blob/master/README.md

List of features currently being developed for the GlobalShop plugin.

```APIDOC
Features Under Development:
  - UI Aesthetic Optimization
  - Performance Improvement Optimization
  - More Search Filter Options
  - Advanced Data Analysis
```

--------------------------------

### Java: WebController - Manages RESTful API routing and data interfaces

Source: https://github.com/linghun91/globalshop/blob/master/README.md

The WebController class handles RESTful API routing and provides data interfaces for auction information. It supports real-time data updates and dynamic page generation through template rendering. This component acts as the primary interface for web interactions with the auction system.

```java
/**
 * WebController.java - Web控制器
 * Manages routing and data interfaces for web services:
 * - Route handling: RESTful API route management
 * - Data interface: provides auction data API
 * - Real-time updates: supports real-time data push
 * - Template rendering: dynamic page generation
 */
// Actual code for WebController would go here.
```

--------------------------------

### Planned Features

Source: https://github.com/linghun91/globalshop/blob/master/README.md

List of features planned for future implementation in the GlobalShop plugin.

```APIDOC
Planned Features:
  - Search by Price Range
  - Optimized Sorting by Time/Price
  - Personalized Recommendation System
  - Mobile-Specific Interface
  - Auction Reminder System
  - Detailed Transaction Statistics
```

--------------------------------

### GUI Management

Source: https://github.com/linghun91/globalshop/blob/master/README.md

Manages all graphical user interfaces (GUIs) for the auction house. This includes the main menu, search interface, item selling interface, confirmation dialogs, bidding interfaces, and personal auction management screens. It handles player page tracking, search query management, and sorting states.

```Java
public class GuiManager {

    private static GuiManager instance;
    private Map<UUID, Integer> playerPageTracker;
    private Map<UUID, String> playerSearchQueryTracker;

    public static GuiManager getInstance() {
        if (instance == null) {
            instance = new GuiManager();
        }
        return instance;
    }

    public void initializeGui(Plugin plugin) {
        // Initialize maps and potentially load GUI layouts
        this.playerPageTracker = new HashMap<>();
        this.playerSearchQueryTracker = new HashMap<>();
    }

    public void openMainMenu(Player player) {
        // Create and open the main auction house GUI
        // ...
    }

    public void openSearchMenu(Player player) {
        // Create and open the search interface
        // ...
    }

    public void openSellMenu(Player player, ItemStack itemToSell) {
        // Create and open the interface for selling an item
        // ...
    }

    public void openConfirmBuyMenu(Player player, AuctionItem auctionItem) {
        // Create and open the confirmation dialog for purchasing an item
        // ...
    }

    public void openBidMenu(Player player, AuctionItem auctionItem) {
        // Create and open the interface for placing a bid
        // ...
    }

    public void openMyAuctionsMenu(Player player) {
        // Create and open the interface to view the player's own auctions
        // ...
    }

    // Methods to update player trackers, e.g.:
    public void setPlayerPage(UUID playerId, int page) {
        playerPageTracker.put(playerId, page);
    }

    public int getPlayerPage(UUID playerId) {
        return playerPageTracker.getOrDefault(playerId, 1);
    }
}
```

--------------------------------

### Java: BroadcastManager - Manages various broadcasting functionalities

Source: https://github.com/linghun91/globalshop/blob/master/README.md

The BroadcastManager class handles multiple broadcasting channels including chat, boss bar, title, subtitle, and action bar. It supports event-driven broadcasts for item listing, successful auctions, fixed-price purchases, and bid confirmations. Additionally, it features item hover information display and dynamic configuration reloading with gradient color support.

```java
/**
 * BroadcastManager.java - 广播管理器
 * Handles various broadcasting functionalities:
 * - Multi-position broadcasts: chat, boss bar, title, subtitle, action bar
 * - Event broadcasts: item listing, auction success, fixed-price purchase, bid confirmation
 * - Item hover: full item information display
 * - Dynamic configuration: supports real-time configuration reload
 * - Gradient color support: preserves item gradient color effects
 */
// Actual code for BroadcastManager would go here.
```