AllianceOrders

AllianceOrders is a professional and robust Item Orders & Escrow System designed for Spigot/Paper Minecraft servers. It allows players to commission resource gathering from other players with 100% financial security and automated item custody.

Video Showcase

Watch the full plugin overview and in-game demonstration:

How Does the Escrow System Work?

The system is built on a 100% Secure Financial Escrow Guarantee:

sequenceDiagram
    autonumber
    actor Contractor as 👤 Player (Contractor)
    participant System as ⚙️ AllianceOrders (Escrow)
    actor Deliverer as ⛏️ Player (Deliverer)

    Contractor->>System: Creates Order (Item, Amount, Price)
    Note over System: Contractor's funds are held in secure escrow custody
    System-->>Deliverer: Order published to public marketplace (/order search)
    Deliverer->>System: Delivers items (partial or full amount)
    System->>Deliverer: Instant proportional payment transferred
    System->>Contractor: Instant notification & item safe delivery
    Contractor->>System: Claims pending items (/order claim)

1. Order Creation: A player chooses an item from their inventory as a template, sets the total required quantity, the monetary reward, and an optional expiration deadline.
2. Escrow Reservation: The total payment is withdrawn and safely held in escrow by the plugin at the moment of creation. This guarantees that workers are always paid immediately upon delivery.
3. Partial or Full Deliveries: Any player can deliver items in flexible batches (1, 16, 64, or entire inventory). With every delivery:
   • Matching items are removed from the worker's inventory.
   • The worker receives payment instantly (minus server tax if configured).
   • If the contractor is online and has free inventory space, items are delivered directly; otherwise, they are stored safely in the collection vault (/order claim).
4. Completion & Cancellation:
   • Orders close automatically when 100% fulfilled.
   • The creator can cancel an open order at any time and get an immediate refund for all unfulfilled items.
   • Expired orders automatically refund remaining funds to the owner.

Key Features

• Multi-Version Compatibility (1.8.8 to 1.20+):
  • Dedicated version adapters (adapter-legacy, adapter-v1_13, adapter-modern).
  • Seamless handling of legacy IDs, custom heads, modern materials, and Hex color codes.
• Strict Item Matching:
  • STRICT mode: Matches item Material, Display Name, Lore, Enchantments, ItemFlags, CustomModelData, and full NBT / PersistentDataContainer.
  • MATERIAL mode: Matches item Material and basic durability.
• Interactive GUI Experience:
  • Main dashboard with player statistics.
  • Order creator with quick increment buttons (+/- 1, 10, 64, 100) and interactive chat prompts.
  • Paginated marketplace with sorting filters (Price/unit, Newest, Amount) and contractor player filter.
  • Comprehensive order delivery log showing worker names, delivered quantities, and payment timestamps.
• Thread-Safe & Anti-Duplication:
  • Granular order-level synchronization locks (OrderLocks) prevent concurrency exploits during simultaneous deliveries.
  • Automated fallback storage for offline players and full inventories.
• Dual Database Storage Engine:
  • Embedded SQLite out-of-the-box (zero configuration needed).
  • High-performance MySQL support backed by HikariCP connection pooling.
• Configurable Economy Tax:
  • Optional platform fee percentage (e.g., 5%) deducted from payouts to support server economy sinks.
• Ecosystem Integration:
  • Vault: Compatible with any Vault economy provider (EssentialsX, TNE, etc.).
  • PlaceholderAPI: Full set of native placeholders for scoreboards, TAB, and menus.

Commands & Permissions

Player Commands

Administrator Commands

PlaceholderAPI Placeholders

Configuration (config.yml)

# Database & Storage Settings
storage:
  # Database type: SQLITE or MYSQL
  type: "SQLITE"
  mysql:
    host: "localhost"
    port: 3306
    database: "allianceorders"
    user: "root"
    password: ""

# Order Settings
orders:
  # STRICT: Matches Material, Name, Lore, Enchantments, CustomModelData & NBT/PDC
  # MATERIAL: Matches Material only
  item-matching: "STRICT"

  # Maximum active orders per player
  max-per-player: 10

  # Maximum items in a single order (default: 2304 = 36 stacks)
  max-amount: 2304

  # Minimum total price to create an order
  min-price: 1.0

  # Default expiration in hours (0 = no expiration)
  default-expire-hours: 0

  # Platform tax deducted from deliverer reward (e.g. 5.0 = 5% tax)
  tax-percent: 0.0

  # Allow the contractor to deliver to their own order?
  allow-self-delivery: false

# Formatting
format:
  money: "#,##0.00"
  date: "yyyy-MM-dd HH:mm"

All GUI titles, messages, and lore are 100% customizable in messages.yml.

Installation

1. Ensure your server runs Spigot/Paper 1.8.8 to 1.20+.
2. Install Vault and an economy plugin (e.g., EssentialsX).
3. (Optional) Install PlaceholderAPI.
4. Drop AllianceOrders.jar into the plugins/ directory.
5. Restart your server.
6. Configure plugins/AllianceOrders/config.yml and use /order reload.

🛠️ Building from Source

# Clone the repository
git clone https://github.com/joseplay1012/AllianceOrders.git

# Enter project directory
cd AllianceOrders

# Build multi-module package with Maven
mvn clean package

The compiled JAR file will be in plugin/target/AllianceOrders-1.0.jar.

📄 License & Author

Developed by joseplay1012. All rights reserved.