AlbionMarket

AlbionMarket is an enterprise-grade, asynchronous Spigot/Paper Minecraft plugin designed to bring the localized, dual-sided order book marketplace architecture of Albion Online directly to your server. Unlike global auction house plugins where items instantaneously teleport, AlbionMarket introduces true economic geography where trading is localized, physical, and governed by a robust bid/ask matching engine.

Core Features (Available in V1.0.0)

• Entity-Agnostic Localized Markets: Establish independent markets mapped to specific entities using persistent data tagging (PDC). Works seamlessly with Citizens NPCs, vanilla Villagers, or modern Minecraft Interaction entities.
• Dual-Sided Matching Engine: Supports limit Sell Orders, Buy Orders, Quick Buy, and Quick Sell transactions. The engine processes trades dynamically, matching buyers and sellers based on Maker's pricing and order queues.
• Localized Virtual Mailboxes: Items and cash fills are delivered directly to the node's mailbox database. Players must physically visit the respective NPC to retrieve their purchased items or trade profits.
• Asynchronous Database Concurrency: Uses thread-safe SQLite storage powered by HikariCP connection pooling, performing all calculations and queries asynchronously to protect server performance.
• Precise Integer Arithmetic: Prevents floating-point drift in tax calculations and balances by operating strictly in integer silver currency.
• NBT-Based Item Identity: Identifies items precisely by combining material type with a cryptographic SHA-256 hash of their NBT data, ensuring exact matching for durability and item states.

Requirements & Compatibility

• Vault (Required): A compatible economy plugin (e.g., EssentialsX, CMI) is required to handle all financial transactions.
• Citizens (Optional / Highly Recommended): Supported out of the box for creating custom NPC merchants.
• Vanilla Entities / Interaction Entities (Optional): You can link market nodes to vanilla entities (like Villagers) without needing Citizens.
• PlaceholderAPI (Soon to be added): Planned integration for showing active orders, pending mailbox counts, and node stats.

Detailed Development Roadmap (Upcoming Releases)

Phase 2: Platform & Engine Refinement (Soon to be added)

• MySQL & MariaDB Support (Soon to be added): High-performance database toggle with WAL mode and connection pool tuning for multi-server networks.
• Advanced Item Sanitization (Soon to be added): Integration hooks for MMOItems, Oraxen, and ItemsAdder to allow custom items to match across servers.
• Order Expiry Background Cleanup (Soon to be added): Configurable asynchronous batch tasks to automatically expire active orders and route items to player mailboxes.
• Anvil/Sign Packet GUI Input (Soon to be added): Protocol-level virtual Anvil and Sign packet interfaces for smooth numeric inputs, eliminating chat prompts.
• GUI Sorting & Filtering Polish (Soon to be added): Advanced sorting options (price, date) and pagination controls in the browse views.

Phase 3: Permissions & Player QoL (Soon to be added)

• Permission-Based Taxes (Soon to be added): Dynamic setup fees and transaction taxes with permission-based discount multipliers (e.g. VIP/Premium player tax rates).
• Real-Time Notifications (Soon to be added): Online Actionbar audio-visual alerts and offline login toasts aggregated using Kyori Adventure.
• PlaceholderAPI Expansion (Soon to be added): Placeholder expansions tracking pending items, pending cash, and active order counts per node.
• Player Trade History & Stats (Soon to be added): Detailed in-game history of executed trades and personal volume/fee stats.

Phase 4: Economic Intelligence (Soon to be added)

• Transaction Logging & Price History (Soon to be added): Full ledger of every trade execution to generate price histories and moving average calculations (7-day/30-day SMA).
• Admin Revenue Dashboard (Soon to be added): Visual reports of tax and setup fee revenue by node, with CSV export capabilities.
• Market Analytics GUI (Soon to be added): Heatmaps of busy trading hours and popular items by value/volume.
• Audit Logs & Compliance Tools (Soon to be added): Log files for all administrative actions and duplication detection filters.

Phase 5: Platform & Scale (Soon to be added)

• Embedded HTTP API (Soon to be added): Async REST HTTP server powered by native Java packages, returning JSON data for external integration.
• Web Dashboard (Soon to be added): A responsive external web interface for players to browse active orders, prices, and statistics.
• Webhook System (Soon to be added): Configurable webhook endpoints to dispatch trade details to external systems like Discord.
• Order Modification (Soon to be added): Allow players to directly edit active order prices or quantities without cancel-and-recreate operations.

Command Reference

Active Commands (V1.0.0)
/market - Opens the localized market interface when interacting with a linked NPC.
/market admin link <node_id> - Links the targeted NPC or entity to a specific market node.
/market admin reload - Reloads the plugin configuration files.
/market admin info <node_id> - Displays current details and configuration for the specified market node.

Upcoming Commands (Soon to be added)
/market stats [player] (Soon to be added) - View economic volume, trades, and taxes paid for a player.
/market admin purge <node_id> (Soon to be added) - Force-expires all active orders at a node, returning assets to mailboxes.
/market admin stats (Soon to be added) - Displays cross-node stats on trade volume and collected taxes.
/market admin revenue <node_id> (Soon to be added) - Generates a detailed fee collection report for the node.
/market admin audit <player> (Soon to be added) - View detailed compliance and trade logs for a specific player.

Permissions

Active Permissions (V1.0.0)

• albionmarket.use: Allows players to interact with market NPCs and place orders. (Default: True)
• albionmarket.admin: Grants access to all administrative commands. (Default: OP)

Upcoming Permissions (Soon to be added)

• albionmarket.tax.premium (Soon to be added): Provides premium tax multiplier discounts.
• albionmarket.tax.vip (Soon to be added): Provides VIP tax multiplier discounts.
• albionmarket.stats.others (Soon to be added): Allows looking up other players' market stats.

Installation Guide

1. Place the AlbionMarket JAR file into your server's plugins directory.
2. Ensure you have Vault (Required) and a compatible economy plugin (e.g., EssentialsX, CMI) installed.
3. (Highly Recommended) Install Citizens if you wish to create custom NPC merchants.
4. Start the server to generate default configurations (config.yml and markets.yml).
5. Customize your configurations as needed.