Native Villager Trade GUI Shop System

[FirebrickRed]

Summary

Implement merchant shops using Minecraft's native villager trade GUI with custom currency (gold/silver/copper pieces). Merchants defined in YAML with items, prices, and stock tracking.

Phase: 2 - Interaction
Systems: Shop System, Entity System, Economy

Prerequisites

• Unified Entity System Foundation #72 - Unified Entity System Foundation
• Entity Spawning Commands (DM-Only) #73 - Entity Spawning Commands
• Entity Stat Block Display #74 - Stat Block Display (optional, adds [Shop] button)

Goals

• Use Minecraft's native villager trade screen (not custom inventory)
• Custom currency items: Gold Piece, Silver Piece, Copper Piece
• YAML-configured shops (items, prices, stock)
• Stock tracking per item
• Buying AND selling support
• /entity trade <entity> command
• Right-click merchant to open shop

Custom Currency

// Create currency items with NBT tags
ItemStack goldPiece = ItemUtil.createCurrency("gold_piece", amount);
// NBT: {currency: "gold_piece", currency_value: 1}

// Future: Conversion rates
// 10 copper = 1 silver
// 10 silver = 1 gold

YAML Shop Configuration

id: balin_blacksmith
name: "Balin"

shop:
  enabled: true
  base_buy_multiplier: 1.0
  base_sell_multiplier: 0.5
  
  items:
    - item: longsword
      price: 15  # In gold pieces
      stock: 5
    - item: chainmail
      price: 75
      stock: 2
      
  # What merchant accepts when buying from players
  accepts:
    - longsword
    - dagger
    - leather_armor

Native Trade GUI

// Create Merchant and open trade screen
Merchant merchant = Bukkit.createMerchant("Balin the Blacksmith");

// Add recipes (trades)
MerchantRecipe recipe = new MerchantRecipe(
    longswordItem,  // Result
    5               // Max uses (stock)
);
recipe.addIngredient(goldPieceItem(15));  // Cost
merchant.addRecipe(recipe);

player.openMerchant(merchant, true);

Features

• Stock depletion: Trades disabled when out of stock
• Persistence: Stock persists across server restarts
• Selling to merchant: Players can sell items for gold
• Price display: Shows "15 GP" in item lore

Commands

/entity trade balin
> Opens Balin's shop

# DM can view shop config
/dmentity shop balin view --dm
> Longsword: 15 GP (5 in stock)
> Chainmail: 75 GP (2 in stock)

Next Steps

After completing this issue, tackle:

• Shop Price Adjustment System (DM-Only) #76: Price Adjustment System (modify shop prices)
• Hidden Shop Items & Discovery System #84: Hidden Shop Items (discovery system)

Related Issues

• Unified Entity System Foundation #72 - Unified Entity System Foundation (prerequisite)
• Entity Stat Block Display #74 - Entity Stat Block Display (adds shop button)
• Shop Price Adjustment System (DM-Only) #76 - Shop Price Adjustments
• Hidden Shop Items & Discovery System #84 - Hidden Shop Items
• Dual Interaction System (Commands + Right-Click) #85 - Dual Interaction System

[FirebrickRed]

Persistence Note

Related: #89 (Entity Persistence System)

Merchant shop stock must persist across server restarts to prevent stock resetting.

Save Shop Stock Data

```yaml

DMContent/Saved/Shops/shop_stock.yml

shops:
balin_blacksmith:
items:
longsword:
stock_remaining: 3 # Started with 5, sold 2
chainmail:
stock_remaining: 2 # No sales yet
```

Implementation

• Save stock changes after each trade
• Load stock on server startup
• Merge with template shop config
• Use same DMContent/Saved/ pattern as characters and entities

Note: Entity persistence (#89) should be completed first to establish the pattern.