Economy Batching

The batch processing system dramatically improves performance by consolidating multiple currency transactions into single database operations.

---

What is Batching?

Instead of processing each currency gain immediately (which requires a database operation), the batch processor collects all currency gains over a period and processes them as a single batch.

Performance Impact

Example

Without Batching:

• 100 players online

• Each player kills 1 mob every 5 seconds

• Each mob drops 3 different currencies

• Result: 3,600 database transactions per minute, but instant updates via placeholders.

With Batching (40 ticks = 2 seconds):

• Same scenario

• Batched every 2 seconds

• Result: ~90 database transactions per minute, however placeholders don't update instantly.

---

Configuration

Location

Batch processing settings are in config.yml:

batch-processors:
  economy:
    enabled: true
    interval-ticks: 40

Important: Changes to batch processor settings require a server restart to take effect.

---

How It Works

1

Currency Gain

When a player earns currency (e.g., killing a mob):

Player kills Zombie → Drops 100 Money, 50 Souls, 25 XP

2

Queued for Batching

Instead of immediately updating the database, the gains are queued:

Player's Batch Queue:
  - Money: +100
  - Souls: +50
  - XP: +25

3

Additional Gains

If the player earns more currency before the batch processes:

Player kills another Zombie → Drops 100 Money, 50 Souls, 25 XP

Player's Batch Queue:
  - Money: +200  (100 + 100)
  - Souls: +100  (50 + 50)
  - XP: +50      (25 + 25)

4

Batch Processing

After interval-ticks (e.g., 40 ticks = 2 seconds), all queued gains are processed:

Single database operation per currency:
  - UPDATE balance SET money = money + 200
  - UPDATE balance SET souls = souls + 100
  - UPDATE balance SET xp = xp + 50

---

Tuning Recommendations

High Player Count (100+ players)

batch-processors:
  economy:
    enabled: true
    interval-ticks: 60  # Process every 3 seconds

---

Low Player Count (< 20 players)

batch-processors:
  economy:
    enabled: true
    interval-ticks: 10  # Process every 1 second

---

Events & API

Currency Gain Event

The PlayerCurrencyGainEvent is fired when the batch processes:

@EventHandler
public void onCurrencyGain(PlayerCurrencyGainEvent event) {
    String currency = event.getCurrencyId();
    double amount = event.getFinalAmount();
    
    // Modify amount before it's added
    event.setFinalAmount(amount * 2);
    
    // Or cancel the gain
    event.setCancelled(true);
}

The event fires during batch processing, not when currency is queued.

---

Manual Flushing (API)

Developers can manually flush a player's batch:

EconomyManager economyManager = plugin.getEconomyManager();
economyManager.flush(playerUUID); // Flushes batch immediately

---

Common Questions

Will players see currency updates immediately?

This depends on your settings, if you decide not to do batch updates, then the placeholder updates are in real time.

What happens if the server crashes before batching?

Currency gains queued in the batch may be lost if the server crashes before the next batch interval. However, this window is typically only 1-3 seconds.

To minimize risk, use a shorter interval-ticks (e.g., 20-40 ticks). We may implement a safety mechanism for this in the future, but no guarantee.

Can I disable batching for specific currencies?

No, batching applies to all economies globally. It's an all-or-nothing setting.

Does batching affect admin commands?

Admin commands (/money give, /money set, etc.) bypass batching and update balances immediately.