Multi-Currency Payment & Auto-Conversion System

[FirebrickRed]

Summary:
Extend the shop system to support mixed-currency payments and automatic currency conversion for merchant trades.

Phase: 3 - Advanced Features
Systems: Shop System, Economy

Prerequisites:

• Native Villager Trade GUI Shop System #75 - Native Villager Trade GUI Shop System (MUST be completed first)

---

Current Limitation (Issue #75)

In the base shop system, players must pay with exact currency:

• Longsword costs 15 gold? Must pay 15 gold pieces
• Cannot pay with 150 silver pieces or 1500 copper pieces
• Each currency is treated separately

Proposed Features

1. Multi-Currency Payment Options

Allow players to see multiple payment options in the trade GUI:

Option A: Multiple Recipes Per Item

✅ Works with native Villager GUI
❌ Clutters shop with duplicate items

Option B: Smart Conversion with Change

✅ Clean shop interface
❌ Requires post-transaction validation

2. Configurable Conversion Rates

Support custom conversion rates per campaign:

# DMContent/Config/economy.yml
economy:
  currencies:
    copper:
      name: "Copper Piece"
      abbreviation: "CP"
      base_value: 1
    silver:
      name: "Silver Piece"
      abbreviation: "SP"
      base_value: 10        # 10 copper = 1 silver
    electrum:
      name: "Electrum Piece"
      abbreviation: "EP"
      base_value: 50
    gold:
      name: "Gold Piece"
      abbreviation: "GP"
      base_value: 100       # 100 copper = 1 gold = 10 silver
    platinum:
      name: "Platinum Piece"
      abbreviation: "PP"
      base_value: 1000      # 1000 copper = 1 platinum
      
  conversion_enabled: true       # Allow multi-currency payment
  auto_convert_inventory: false  # Don't auto-stack coins

DM Customization Examples:

• Gritty campaign: 1 gold = 100 silver (rarer gold)
• High magic: 1 gold = 5 silver (inflated economy)
• Custom currencies: Add "Dragon Scales" with custom value

3. Currency Utilities

// Convert payment to base currency
int totalValue = CurrencyUtil.calculateTotalValue(inventory);

// Check if player can afford item
boolean canAfford = CurrencyUtil.canAfford(player, price, currency);

// Deduct payment and give change
CurrencyUtil.processPurchase(player, price, currency);

Implementation Options

Phase 1: Multiple Recipes (Simple)

• Generate 3-5 recipes per item (copper, silver, gold, platinum)
• Easy implementation with native GUI
• Shops become cluttered with large inventories

Phase 2: Smart Conversion (Advanced)

• Post-transaction validation
• Calculate change and return to player
• Cleaner UI but more complex

Phase 3: Inventory Auto-Stacking (Optional)

• auto_convert_inventory: true setting
• Automatically converts 10 copper → 1 silver
• Players don't manage individual coins

Out of Scope

• Player-to-player trading (separate issue)
• Banking system (separate issue)
• Credit/debt tracking (separate issue)

Design Questions

1. Should we implement Option A (multiple recipes) or Option B (smart conversion)?
2. Should conversion rates be global or per-merchant?
3. Do we allow fractional currency (e.g., paying 1.5 gold pieces)?

Testing Requirements

• Buy 15 GP item with 150 silver pieces
• Buy 5 CP item with 1 gold piece (get change)
• Custom conversion rates (1 gold = 100 silver)
• Multiple currency types in inventory

Related: #75 (Shop System), #76 (Price Adjustments), #93 (Economy Config)