Skip to main content

Delivery System

How the delivery system works in SigmaOrders.

Overview​

Players can fulfill orders by delivering the requested items. The system supports partial deliveries, allowing multiple players to contribute to large orders.

Delivery Process​

1. Find an Order​

Players can find orders to deliver:

  • Browse /orders GUI
  • Use /orders list command
  • Search with /orders search <query>

2. Start Delivery​

/orders deliver <order-id>

This opens the delivery GUI showing:

  • Required items
  • Quantity needed
  • Price per item
  • Current delivery status

3. Select Items​

  • Items are selected from inventory
  • System validates items match order requirements
  • Supports NBT items (enchantments, custom names, etc.)

4. Complete Delivery​

  • Items are removed from inventory
  • Delivery recorded in database
  • Payment made to deliverer (if pay-on-delivery enabled)
  • Order status updated

Partial Deliveries​

Multiple players can deliver to the same order:

Order: 64 diamonds needed
- Player A delivers 32 diamonds → 32 remaining
- Player B delivers 16 diamonds → 16 remaining
- Player C delivers 16 diamonds → Order complete

Each deliverer is paid proportionally to their delivery.

Concurrent Delivery Protection​

The system uses optimistic locking to prevent:

  • Over-delivery (delivering more than needed)
  • Race conditions (multiple players delivering simultaneously)
  • Data corruption

Delivery System Improvements (v1.0.3)​

Recent improvements to the delivery system:

  • Fixed Double Item Return: Prevents double item return on delivery failure - now only returns consumed items, not all items including excess
  • Fixed Stale Delivery Data: Delivery count now reads directly from database, preventing first delivery failures caused by stale OrderItem object data
  • Improved Reliability: More reliable delivery tracking with direct database reads

Delivery Validation​

Before delivery, the system validates:

  • Item material matches order
  • Item enchantments match (if specified)
  • Item NBT data matches (if custom item)
  • Order status allows delivery
  • Order hasn't expired (if configured)
  • Player isn't delivering to own order
  • Player isn't blacklisted

Payment on Delivery​

If pay-on-delivery is enabled:

  • Deliverer is paid immediately upon delivery
  • Payment is proportional to items delivered
  • Payment comes from escrow balance
  • Transaction is logged

Delivery History​

If delivery-history is enabled:

  • All deliveries are recorded
  • Tracks who delivered what and when
  • Used for statistics and tracking

Restrictions​

Players cannot deliver if:

  • Order is cancelled
  • Order is completed
  • Order has expired (if configured)
  • Trying to deliver to own order
  • Player is blacklisted
  • Item doesn't match order requirements

Best Practices​

  1. Check Order Status: Verify order is active before delivering
  2. Validate Items: Ensure items match order requirements
  3. Partial Deliveries: Don't need to deliver everything at once
  4. Monitor Payments: Verify payments are received