From 47fc4ebcc19fb46319a4a2f1873b143871e9f784 Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 3 Jan 2026 21:12:55 +0000 Subject: [PATCH] Add comprehensive implementation plan for CNPC+ 1.11 Market Update This plan covers three major features: - Auction House: New Auctioneer NPC role with global auction system - Currency System: VaultAPI integration for Bukkit hybrid servers - Trader Enhancements: Stock/inventory system with reset timers Includes detailed architecture, data structures, and implementation order. --- docs/CNPC_1.11_MARKET_UPDATE_PLAN.md | 1871 ++++++++++++++++++++++++++ 1 file changed, 1871 insertions(+) create mode 100644 docs/CNPC_1.11_MARKET_UPDATE_PLAN.md diff --git a/docs/CNPC_1.11_MARKET_UPDATE_PLAN.md b/docs/CNPC_1.11_MARKET_UPDATE_PLAN.md new file mode 100644 index 000000000..fb1c33158 --- /dev/null +++ b/docs/CNPC_1.11_MARKET_UPDATE_PLAN.md @@ -0,0 +1,1871 @@ +# CustomNPC+ 1.11 Market Update - Implementation Plan + +## Overview + +This document outlines the implementation plan for the CustomNPC+ 1.11 update, focusing on three major features: + +1. **Auction House** - A new NPC role allowing players to access a global auction system +2. **Currency System** - Built-in currency integration with VaultAPI for Bukkit hybrid servers +3. **Trader Enhancements** - Stock/Inventory system with per-player/per-server options and reset timers + +--- + +## Table of Contents + +1. [Architecture Overview](#architecture-overview) +2. [Feature 1: Currency System](#feature-1-currency-system) +3. [Feature 2: Trader Enhancements](#feature-2-trader-enhancements) +4. [Feature 3: Auction House](#feature-3-auction-house) +5. [Implementation Order](#implementation-order) +6. [File Summary](#file-summary) +7. [Testing Strategy](#testing-strategy) + +--- + +## Architecture Overview + +### Current Codebase Patterns + +The implementation will follow existing patterns found in the codebase: + +| Pattern | Used By | Will Be Applied To | +|---------|---------|-------------------| +| Singleton Controller | `BankController`, `QuestController` | `AuctionController`, `CurrencyController` | +| Role Interface | `RoleTrader`, `RoleBank` | `RoleAuctioneer` | +| Player Data Extension | `PlayerBankData`, `PlayerQuestData` | `PlayerAuctionData`, `PlayerCurrencyData` | +| Cooldown System | `Quest.repeat`, `JobItemGiver` | Trader Stock Reset | +| Optional Addon | `PixelmonHelper`, `DBCAddon` | `VaultHelper` | +| NBT Serialization | All data classes | All new data classes | +| Cache System | `Market.java`, `CacheHashMap` | Auction listings cache | + +### Package Structure for New Features + +``` +noppes/npcs/ +├── controllers/ +│ ├── AuctionController.java # Manages global auction house +│ ├── CurrencyController.java # Manages currency settings +│ └── data/ +│ ├── AuctionListing.java # Single auction listing +│ ├── AuctionData.java # World auction data +│ ├── PlayerAuctionData.java # Per-player auction history +│ ├── PlayerCurrencyData.java # Per-player currency balance +│ └── TraderStock.java # Trader stock configuration +├── roles/ +│ └── RoleAuctioneer.java # Auctioneer NPC role +├── containers/ +│ ├── ContainerAuction*.java # Auction GUI containers +│ └── ContainerNPCTraderStock.java # Stock management container +├── client/gui/ +│ ├── player/ +│ │ └── GuiAuction*.java # Player-facing auction GUIs +│ └── roles/ +│ └── GuiNpcAuctioneerSetup.java # Auctioneer configuration GUI + +kamkeel/npcs/ +├── controllers/ +│ └── CurrencyController.java # Currency management +├── network/packets/ +│ ├── data/ +│ │ ├── AuctionSyncPacket.java # Sync auction data +│ │ └── CurrencySyncPacket.java # Sync currency data +│ └── player/ +│ ├── AuctionActionPacket.java # Auction actions (bid, buy, sell) +│ └── CurrencyActionPacket.java # Currency transactions +└── compat/ + └── VaultHelper.java # VaultAPI integration +``` + +--- + +## Feature 1: Currency System + +### 1.1 Overview + +The currency system provides a unified economy layer that can: +- Use VaultAPI when available on Bukkit hybrid servers (Cauldron, Thermos, Mohist) +- Fall back to an internal item-based currency when VaultAPI is unavailable +- Be configured per-world or globally + +### 1.2 VaultAPI Integration + +#### 1.2.1 Dependency Setup + +**File: `dependencies.gradle`** +```gradle +// VaultAPI - compile-only for optional integration +compileOnly("net.milkbowl.vault:VaultAPI:1.4") { + transitive = false +} +``` + +**File: `repositories.gradle`** +```gradle +maven { + name = "vault-repo" + url = "https://nexus.hc.to/content/repositories/pub_releases/" +} +``` + +> **Note:** VaultAPI 1.4.1 works with 1.7.10 Bukkit hybrid servers. The dependency is compile-only so the mod works without Vault present. + +#### 1.2.2 VaultHelper Class + +**File: `src/main/java/kamkeel/npcs/compat/VaultHelper.java`** + +```java +package kamkeel.npcs.compat; + +import cpw.mods.fml.common.Loader; +import net.minecraft.entity.player.EntityPlayer; +import noppes.npcs.LogWriter; +import org.bukkit.Bukkit; +import org.bukkit.plugin.RegisteredServiceProvider; + +public class VaultHelper { + public static boolean Enabled = false; + public static boolean Available = false; + + // Cached via reflection + private static Object economy = null; + private static Class economyClass = null; + private static java.lang.reflect.Method getBalance; + private static java.lang.reflect.Method withdrawPlayer; + private static java.lang.reflect.Method depositPlayer; + private static java.lang.reflect.Method hasMethod; + private static java.lang.reflect.Method format; + + public static void load() { + // Check if we're on a Bukkit hybrid server + try { + Class.forName("org.bukkit.Bukkit"); + Available = true; + } catch (ClassNotFoundException e) { + Available = false; + return; + } + + // Try to hook into Vault + try { + Class vaultClass = Class.forName("net.milkbowl.vault.economy.Economy"); + economyClass = vaultClass; + + RegisteredServiceProvider rsp = Bukkit.getServicesManager() + .getRegistration(vaultClass); + + if (rsp != null) { + economy = rsp.getProvider(); + + // Cache reflection methods + getBalance = economyClass.getMethod("getBalance", String.class); + withdrawPlayer = economyClass.getMethod("withdrawPlayer", + String.class, double.class); + depositPlayer = economyClass.getMethod("depositPlayer", + String.class, double.class); + hasMethod = economyClass.getMethod("has", String.class, double.class); + format = economyClass.getMethod("format", double.class); + + Enabled = true; + LogWriter.info("VaultAPI Economy hooked successfully!"); + } + } catch (Exception e) { + LogWriter.info("VaultAPI not available: " + e.getMessage()); + Enabled = false; + } + } + + // Economy Methods + public static double getBalance(EntityPlayer player) { + if (!Enabled) return 0.0; + try { + return (Double) getBalance.invoke(economy, player.getCommandSenderName()); + } catch (Exception e) { + LogWriter.except(e); + return 0.0; + } + } + + public static boolean withdraw(EntityPlayer player, double amount) { + if (!Enabled) return false; + try { + Object response = withdrawPlayer.invoke(economy, + player.getCommandSenderName(), amount); + return (Boolean) response.getClass() + .getMethod("transactionSuccess").invoke(response); + } catch (Exception e) { + LogWriter.except(e); + return false; + } + } + + public static boolean deposit(EntityPlayer player, double amount) { + if (!Enabled) return false; + try { + Object response = depositPlayer.invoke(economy, + player.getCommandSenderName(), amount); + return (Boolean) response.getClass() + .getMethod("transactionSuccess").invoke(response); + } catch (Exception e) { + LogWriter.except(e); + return false; + } + } + + public static boolean has(EntityPlayer player, double amount) { + if (!Enabled) return false; + try { + return (Boolean) hasMethod.invoke(economy, + player.getCommandSenderName(), amount); + } catch (Exception e) { + LogWriter.except(e); + return false; + } + } + + public static String formatCurrency(double amount) { + if (!Enabled) return String.format("%.2f", amount); + try { + return (String) format.invoke(economy, amount); + } catch (Exception e) { + return String.format("%.2f", amount); + } + } +} +``` + +#### 1.2.3 Initialization Hook + +**File: `src/main/java/noppes/npcs/CustomNpcs.java`** + +Add to `load()` method after AddonManager: +```java +// Initialize VaultAPI integration (for Bukkit hybrid servers) +VaultHelper.load(); +``` + +### 1.3 Currency Controller + +**File: `src/main/java/kamkeel/npcs/controllers/CurrencyController.java`** + +```java +package kamkeel.npcs.controllers; + +import net.minecraft.entity.player.EntityPlayer; +import net.minecraft.item.ItemStack; +import net.minecraft.nbt.NBTTagCompound; +import kamkeel.npcs.compat.VaultHelper; +import noppes.npcs.NoppesUtilPlayer; + +public class CurrencyController { + private static CurrencyController instance; + + // Configuration + public boolean useVaultIfAvailable = true; + public ItemStack fallbackCurrency = null; // Item to use when Vault unavailable + public double itemToVaultRatio = 1.0; // 1 item = X vault currency + + public static CurrencyController getInstance() { + if (instance == null) { + instance = new CurrencyController(); + } + return instance; + } + + /** + * Check if Vault economy is being used + */ + public boolean isUsingVault() { + return useVaultIfAvailable && VaultHelper.Enabled; + } + + /** + * Get player's balance (Vault or item count) + */ + public double getBalance(EntityPlayer player) { + if (isUsingVault()) { + return VaultHelper.getBalance(player); + } + // Fall back to counting items + if (fallbackCurrency != null) { + return NoppesUtilPlayer.countItems(player, fallbackCurrency, false, false); + } + return 0.0; + } + + /** + * Check if player can afford amount + */ + public boolean canAfford(EntityPlayer player, double amount) { + if (isUsingVault()) { + return VaultHelper.has(player, amount); + } + return getBalance(player) >= amount; + } + + /** + * Withdraw currency from player + */ + public boolean withdraw(EntityPlayer player, double amount) { + if (isUsingVault()) { + return VaultHelper.withdraw(player, amount); + } + // Remove items + if (fallbackCurrency != null) { + ItemStack toRemove = fallbackCurrency.copy(); + toRemove.stackSize = (int) Math.ceil(amount / itemToVaultRatio); + return NoppesUtilPlayer.consumeItem(player, toRemove, false, false); + } + return false; + } + + /** + * Deposit currency to player + */ + public boolean deposit(EntityPlayer player, double amount) { + if (isUsingVault()) { + return VaultHelper.deposit(player, amount); + } + // Give items + if (fallbackCurrency != null) { + ItemStack toGive = fallbackCurrency.copy(); + toGive.stackSize = (int) Math.floor(amount / itemToVaultRatio); + return player.inventory.addItemStackToInventory(toGive); + } + return false; + } + + /** + * Format currency for display + */ + public String format(double amount) { + if (isUsingVault()) { + return VaultHelper.formatCurrency(amount); + } + return String.format("%.0f", amount); + } + + // NBT Persistence + public NBTTagCompound writeToNBT(NBTTagCompound compound) { + compound.setBoolean("UseVault", useVaultIfAvailable); + compound.setDouble("ItemRatio", itemToVaultRatio); + if (fallbackCurrency != null) { + compound.setTag("FallbackItem", fallbackCurrency.writeToNBT(new NBTTagCompound())); + } + return compound; + } + + public void readFromNBT(NBTTagCompound compound) { + useVaultIfAvailable = compound.getBoolean("UseVault"); + itemToVaultRatio = compound.getDouble("ItemRatio"); + if (compound.hasKey("FallbackItem")) { + fallbackCurrency = ItemStack.loadItemStackFromNBT( + compound.getCompoundTag("FallbackItem")); + } + } +} +``` + +### 1.4 Player Currency Data + +**File: `src/main/java/noppes/npcs/controllers/data/PlayerCurrencyData.java`** + +```java +package noppes.npcs.controllers.data; + +import net.minecraft.nbt.NBTTagCompound; +import java.util.HashMap; + +public class PlayerCurrencyData { + private final PlayerData parent; + + // Transaction history (for auditing/display) + public HashMap transactionHistory = new HashMap<>(); + public double totalEarned = 0.0; + public double totalSpent = 0.0; + + public PlayerCurrencyData(PlayerData parent) { + this.parent = parent; + } + + public void recordTransaction(double amount, boolean isEarning) { + long timestamp = System.currentTimeMillis(); + transactionHistory.put(timestamp, isEarning ? amount : -amount); + if (isEarning) { + totalEarned += amount; + } else { + totalSpent += amount; + } + // Limit history size + if (transactionHistory.size() > 100) { + // Remove oldest entries + Long oldest = transactionHistory.keySet().stream() + .min(Long::compare).orElse(null); + if (oldest != null) { + transactionHistory.remove(oldest); + } + } + } + + public void loadNBTData(NBTTagCompound compound) { + if (compound.hasKey("CurrencyData")) { + NBTTagCompound data = compound.getCompoundTag("CurrencyData"); + totalEarned = data.getDouble("TotalEarned"); + totalSpent = data.getDouble("TotalSpent"); + } + } + + public void saveNBTData(NBTTagCompound compound) { + NBTTagCompound data = new NBTTagCompound(); + data.setDouble("TotalEarned", totalEarned); + data.setDouble("TotalSpent", totalSpent); + compound.setTag("CurrencyData", data); + } +} +``` + +### 1.5 Configuration UI + +Add currency configuration to the global settings GUI: + +**File: `src/main/java/noppes/npcs/client/gui/global/GuiNPCManageCurrency.java`** + +This GUI will allow server operators to: +- Enable/disable Vault integration +- Set fallback currency item +- Configure item-to-Vault ratio +- View server economy statistics + +--- + +## Feature 2: Trader Enhancements + +### 2.1 Overview + +Enhance the existing `RoleTrader` with: +- **Stock System**: Limited inventory that depletes when players buy +- **Per-Player vs Per-Server Stock**: Configure whether stock is shared or individual +- **Stock Reset Timer**: Automatic restocking based on configurable cooldown (like quest cooldowns) +- **Currency Integration**: Use Vault currency alongside or instead of item-based trading + +### 2.2 Trader Stock Configuration + +#### 2.2.1 Stock Data Class + +**File: `src/main/java/noppes/npcs/controllers/data/TraderStock.java`** + +```java +package noppes.npcs.controllers.data; + +import net.minecraft.nbt.NBTTagCompound; +import net.minecraft.nbt.NBTTagList; +import java.util.HashMap; + +public class TraderStock { + // Stock configuration + public boolean enableStock = false; + public boolean perPlayer = false; // false = per-server, true = per-player + + // Reset configuration (mirrors Quest cooldown system) + public EnumStockReset resetType = EnumStockReset.NONE; + public long customResetTime = 0; // For MCCUSTOM/RLCUSTOM types + + // Stock quantities per slot (max stock) + public int[] maxStock = new int[18]; + + // Current stock (per-server mode) + public int[] currentStock = new int[18]; + public long lastResetTime = 0; + + // Per-player stock tracking + public HashMap playerStock = new HashMap<>(); + + public TraderStock() { + for (int i = 0; i < 18; i++) { + maxStock[i] = -1; // -1 = unlimited + currentStock[i] = -1; + } + } + + /** + * Get available stock for a slot + */ + public int getAvailableStock(int slot, String playerName) { + if (!enableStock || maxStock[slot] < 0) { + return Integer.MAX_VALUE; // Unlimited + } + + if (perPlayer) { + PlayerTraderStock pStock = playerStock.get(playerName); + if (pStock == null) { + return maxStock[slot]; // Not purchased yet + } + return pStock.getStock(slot, maxStock[slot]); + } + + return currentStock[slot]; + } + + /** + * Consume stock when purchase is made + */ + public boolean consumeStock(int slot, String playerName, int amount) { + if (!enableStock || maxStock[slot] < 0) { + return true; // Unlimited + } + + if (perPlayer) { + PlayerTraderStock pStock = playerStock.computeIfAbsent( + playerName, k -> new PlayerTraderStock()); + return pStock.consumeStock(slot, maxStock[slot], amount); + } + + if (currentStock[slot] >= amount) { + currentStock[slot] -= amount; + return true; + } + return false; + } + + /** + * Check if stock should reset + */ + public boolean shouldReset(long currentTime) { + if (resetType == EnumStockReset.NONE) { + return false; + } + + long elapsed = currentTime - lastResetTime; + long resetInterval = getResetInterval(); + + return elapsed >= resetInterval; + } + + /** + * Reset all stock to max values + */ + public void resetStock(long currentTime) { + lastResetTime = currentTime; + + for (int i = 0; i < 18; i++) { + currentStock[i] = maxStock[i]; + } + + // Clear per-player stock + playerStock.clear(); + } + + /** + * Get reset interval in milliseconds + */ + public long getResetInterval() { + switch (resetType) { + case MCDAILY: + return 24000 * 50; // 24000 ticks * 50ms + case MCWEEKLY: + return 168000 * 50; + case MCCUSTOM: + return customResetTime * 50; + case RLDAILY: + return 86400000L; // 24 hours in ms + case RLWEEKLY: + return 604800000L; // 7 days in ms + case RLCUSTOM: + return customResetTime; + default: + return Long.MAX_VALUE; + } + } + + /** + * Get time until next reset (for display) + */ + public long getTimeUntilReset(long currentTime) { + if (resetType == EnumStockReset.NONE) { + return -1; + } + long elapsed = currentTime - lastResetTime; + long interval = getResetInterval(); + return Math.max(0, interval - elapsed); + } + + // NBT Serialization + public NBTTagCompound writeToNBT(NBTTagCompound compound) { + compound.setBoolean("EnableStock", enableStock); + compound.setBoolean("PerPlayer", perPlayer); + compound.setInteger("ResetType", resetType.ordinal()); + compound.setLong("CustomResetTime", customResetTime); + compound.setIntArray("MaxStock", maxStock); + compound.setIntArray("CurrentStock", currentStock); + compound.setLong("LastResetTime", lastResetTime); + + // Save per-player stock + NBTTagList playerList = new NBTTagList(); + for (Map.Entry entry : playerStock.entrySet()) { + NBTTagCompound playerTag = new NBTTagCompound(); + playerTag.setString("Player", entry.getKey()); + entry.getValue().writeToNBT(playerTag); + playerList.appendTag(playerTag); + } + compound.setTag("PlayerStock", playerList); + + return compound; + } + + public void readFromNBT(NBTTagCompound compound) { + enableStock = compound.getBoolean("EnableStock"); + perPlayer = compound.getBoolean("PerPlayer"); + resetType = EnumStockReset.values()[compound.getInteger("ResetType")]; + customResetTime = compound.getLong("CustomResetTime"); + maxStock = compound.getIntArray("MaxStock"); + currentStock = compound.getIntArray("CurrentStock"); + lastResetTime = compound.getLong("LastResetTime"); + + // Load per-player stock + NBTTagList playerList = compound.getTagList("PlayerStock", 10); + for (int i = 0; i < playerList.tagCount(); i++) { + NBTTagCompound playerTag = playerList.getCompoundTagAt(i); + String playerName = playerTag.getString("Player"); + PlayerTraderStock pStock = new PlayerTraderStock(); + pStock.readFromNBT(playerTag); + playerStock.put(playerName, pStock); + } + } +} + +// Inner class for per-player stock tracking +class PlayerTraderStock { + public int[] purchasedAmounts = new int[18]; + public long lastPurchaseTime = 0; + + public int getStock(int slot, int maxStock) { + return Math.max(0, maxStock - purchasedAmounts[slot]); + } + + public boolean consumeStock(int slot, int maxStock, int amount) { + if (getStock(slot, maxStock) >= amount) { + purchasedAmounts[slot] += amount; + lastPurchaseTime = System.currentTimeMillis(); + return true; + } + return false; + } + + public void writeToNBT(NBTTagCompound compound) { + compound.setIntArray("Purchased", purchasedAmounts); + compound.setLong("LastPurchase", lastPurchaseTime); + } + + public void readFromNBT(NBTTagCompound compound) { + purchasedAmounts = compound.getIntArray("Purchased"); + lastPurchaseTime = compound.getLong("LastPurchase"); + } +} +``` + +#### 2.2.2 Stock Reset Enum + +**File: `src/main/java/noppes/npcs/constants/EnumStockReset.java`** + +```java +package noppes.npcs.constants; + +public enum EnumStockReset { + NONE, // Never resets + MCDAILY, // Every 24000 MC ticks (1 MC day) + MCWEEKLY, // Every 168000 MC ticks (7 MC days) + MCCUSTOM, // Custom MC tick interval + RLDAILY, // Every 24 real hours + RLWEEKLY, // Every 7 real days + RLCUSTOM // Custom real-time interval +} +``` + +### 2.3 RoleTrader Modifications + +**File: `src/main/java/noppes/npcs/roles/RoleTrader.java`** + +Add the following to `RoleTrader`: + +```java +// Add new fields +public TraderStock stock = new TraderStock(); +public boolean useCurrency = false; // Use Vault/Currency system +public double[] slotPrices = new double[18]; // Currency prices per slot + +// Modify interact() to check stock reset +@Override +public void interact(EntityPlayer player) { + // Check for stock reset before opening GUI + if (stock.enableStock) { + long currentTime = stock.resetType.name().startsWith("RL") + ? System.currentTimeMillis() + : player.worldObj.getTotalWorldTime(); + + if (stock.shouldReset(currentTime)) { + stock.resetStock(currentTime); + // Save to market if using shared market + if (!marketName.isEmpty()) { + Market.save(this, marketName); + } + } + } + + npc.say(player, npc.advanced.getInteractLine()); + NoppesUtilServer.sendOpenGui(player, EnumGuiType.PlayerTrader, npc); +} + +// Modify writeToNBT +@Override +public NBTTagCompound writeToNBT(NBTTagCompound nbttagcompound) { + // ... existing code ... + + // Add stock data + nbttagcompound.setTag("Stock", stock.writeToNBT(new NBTTagCompound())); + nbttagcompound.setBoolean("UseCurrency", useCurrency); + + // Save currency prices + NBTTagList priceList = new NBTTagList(); + for (double price : slotPrices) { + NBTTagCompound priceTag = new NBTTagCompound(); + priceTag.setDouble("Price", price); + priceList.appendTag(priceTag); + } + nbttagcompound.setTag("SlotPrices", priceList); + + return nbttagcompound; +} + +// Modify readFromNBT +@Override +public void readFromNBT(NBTTagCompound nbttagcompound) { + // ... existing code ... + + // Load stock data + if (nbttagcompound.hasKey("Stock")) { + stock.readFromNBT(nbttagcompound.getCompoundTag("Stock")); + } + useCurrency = nbttagcompound.getBoolean("UseCurrency"); + + // Load currency prices + if (nbttagcompound.hasKey("SlotPrices")) { + NBTTagList priceList = nbttagcompound.getTagList("SlotPrices", 10); + for (int i = 0; i < priceList.tagCount() && i < 18; i++) { + slotPrices[i] = priceList.getCompoundTagAt(i).getDouble("Price"); + } + } +} +``` + +### 2.4 ContainerNPCTrader Modifications + +**File: `src/main/java/noppes/npcs/containers/ContainerNPCTrader.java`** + +Modify `slotClick()` to handle stock and currency: + +```java +public ItemStack slotClick(int slotIndex, EntityPlayer player) { + RoleTrader role = (RoleTrader) npc.roleInterface; + String playerName = player.getCommandSenderName(); + + // ... existing validation ... + + // Check stock availability + if (role.stock.enableStock) { + int available = role.stock.getAvailableStock(slotIndex, playerName); + if (available <= 0) { + // Out of stock - send message to player + return null; + } + } + + // Handle currency-based purchase + if (role.useCurrency && role.slotPrices[slotIndex] > 0) { + double price = role.slotPrices[slotIndex]; + CurrencyController currency = CurrencyController.getInstance(); + + if (!currency.canAfford(player, price)) { + // Can't afford - send message + return null; + } + + // Withdraw currency + if (!currency.withdraw(player, price)) { + return null; + } + } else { + // ... existing item-based currency logic ... + } + + // Consume stock + if (role.stock.enableStock) { + role.stock.consumeStock(slotIndex, playerName, 1); + } + + // ... existing item delivery logic ... + + // Save if using market + if (!role.marketName.isEmpty()) { + Market.save(role, role.marketName); + } + + return soldItem; +} +``` + +### 2.5 Trader Setup GUI Additions + +**File: `src/main/java/noppes/npcs/client/gui/roles/GuiNpcTraderSetup.java`** + +Add new configuration options: + +```java +// Add buttons/fields for: +// - "Enable Stock" toggle +// - "Per Player" / "Per Server" radio buttons +// - "Reset Type" dropdown (None, MC Daily, MC Weekly, etc.) +// - "Custom Reset Time" field +// - "Use Currency" toggle +// - Per-slot stock quantity inputs +// - Per-slot currency price inputs + +private void initStockGui() { + addButton(new GuiNpcButton(20, x, y, 80, 20, + "Enable Stock: " + (role.stock.enableStock ? "Yes" : "No"))); + + addButton(new GuiNpcButton(21, x, y + 22, 80, 20, + role.stock.perPlayer ? "Per Player" : "Per Server")); + + String[] resetTypes = {"None", "MC Daily", "MC Weekly", "MC Custom", + "RL Daily", "RL Weekly", "RL Custom"}; + addButton(new GuiNpcButton(22, x, y + 44, 80, 20, resetTypes, + role.stock.resetType.ordinal())); + + addButton(new GuiNpcButton(23, x, y + 66, 80, 20, + "Use Currency: " + (role.useCurrency ? "Yes" : "No"))); +} +``` + +--- + +## Feature 3: Auction House + +### 3.1 Overview + +The Auction House is a global trading system where players can: +- **List items for sale** at fixed prices or as auctions with bidding +- **Browse listings** by category, search, and filter +- **Bid on auctions** with automatic outbid notifications +- **Buy instantly** for buy-it-now prices +- **Manage their listings** (cancel, modify) +- **Collect proceeds and expired items** via mailbox or direct claim + +### 3.2 Auction Data Structures + +#### 3.2.1 AuctionListing + +**File: `src/main/java/noppes/npcs/controllers/data/AuctionListing.java`** + +```java +package noppes.npcs.controllers.data; + +import net.minecraft.item.ItemStack; +import net.minecraft.nbt.NBTTagCompound; +import java.util.UUID; + +public class AuctionListing { + public int id; + public UUID sellerUUID; + public String sellerName; + public ItemStack item; + + // Pricing + public double startingPrice; + public double buyoutPrice; // 0 = no buyout + public double currentBid; + public UUID highBidderUUID; + public String highBidderName; + + // Timing + public long listingTime; + public long expirationTime; + public EnumAuctionDuration duration; + + // Status + public EnumAuctionStatus status = EnumAuctionStatus.ACTIVE; + + // Category + public EnumAuctionCategory category = EnumAuctionCategory.MISC; + + public AuctionListing() {} + + public AuctionListing(UUID seller, String sellerName, ItemStack item, + double startPrice, double buyout, EnumAuctionDuration duration) { + this.sellerUUID = seller; + this.sellerName = sellerName; + this.item = item.copy(); + this.startingPrice = startPrice; + this.buyoutPrice = buyout; + this.currentBid = startPrice; + this.duration = duration; + this.listingTime = System.currentTimeMillis(); + this.expirationTime = listingTime + duration.getMillis(); + this.category = categorizeItem(item); + } + + /** + * Check if auction has expired + */ + public boolean isExpired() { + return System.currentTimeMillis() >= expirationTime; + } + + /** + * Get time remaining in milliseconds + */ + public long getTimeRemaining() { + return Math.max(0, expirationTime - System.currentTimeMillis()); + } + + /** + * Place a bid + */ + public boolean placeBid(UUID bidder, String bidderName, double amount) { + if (status != EnumAuctionStatus.ACTIVE) return false; + if (amount <= currentBid) return false; + if (bidder.equals(sellerUUID)) return false; // Can't bid on own item + + // Minimum bid increment (5% or 1, whichever is greater) + double minIncrement = Math.max(1, currentBid * 0.05); + if (amount < currentBid + minIncrement) return false; + + highBidderUUID = bidder; + highBidderName = bidderName; + currentBid = amount; + + return true; + } + + /** + * Execute buyout + */ + public boolean buyout(UUID buyer, String buyerName) { + if (status != EnumAuctionStatus.ACTIVE) return false; + if (buyoutPrice <= 0) return false; // No buyout available + if (buyer.equals(sellerUUID)) return false; + + highBidderUUID = buyer; + highBidderName = buyerName; + currentBid = buyoutPrice; + status = EnumAuctionStatus.SOLD; + + return true; + } + + /** + * Cancel listing (seller only, before any bids) + */ + public boolean cancel(UUID requester) { + if (!requester.equals(sellerUUID)) return false; + if (highBidderUUID != null) return false; // Has bids, can't cancel + + status = EnumAuctionStatus.CANCELLED; + return true; + } + + /** + * Auto-categorize item based on type + */ + private EnumAuctionCategory categorizeItem(ItemStack item) { + // Implement item categorization logic + // Check for weapons, armor, tools, food, blocks, etc. + return EnumAuctionCategory.MISC; + } + + // NBT Serialization + public NBTTagCompound writeToNBT(NBTTagCompound compound) { + compound.setInteger("Id", id); + compound.setString("SellerUUID", sellerUUID.toString()); + compound.setString("SellerName", sellerName); + compound.setTag("Item", item.writeToNBT(new NBTTagCompound())); + compound.setDouble("StartPrice", startingPrice); + compound.setDouble("BuyoutPrice", buyoutPrice); + compound.setDouble("CurrentBid", currentBid); + if (highBidderUUID != null) { + compound.setString("BidderUUID", highBidderUUID.toString()); + compound.setString("BidderName", highBidderName); + } + compound.setLong("ListingTime", listingTime); + compound.setLong("ExpirationTime", expirationTime); + compound.setInteger("Duration", duration.ordinal()); + compound.setInteger("Status", status.ordinal()); + compound.setInteger("Category", category.ordinal()); + return compound; + } + + public void readFromNBT(NBTTagCompound compound) { + id = compound.getInteger("Id"); + sellerUUID = UUID.fromString(compound.getString("SellerUUID")); + sellerName = compound.getString("SellerName"); + item = ItemStack.loadItemStackFromNBT(compound.getCompoundTag("Item")); + startingPrice = compound.getDouble("StartPrice"); + buyoutPrice = compound.getDouble("BuyoutPrice"); + currentBid = compound.getDouble("CurrentBid"); + if (compound.hasKey("BidderUUID")) { + highBidderUUID = UUID.fromString(compound.getString("BidderUUID")); + highBidderName = compound.getString("BidderName"); + } + listingTime = compound.getLong("ListingTime"); + expirationTime = compound.getLong("ExpirationTime"); + duration = EnumAuctionDuration.values()[compound.getInteger("Duration")]; + status = EnumAuctionStatus.values()[compound.getInteger("Status")]; + category = EnumAuctionCategory.values()[compound.getInteger("Category")]; + } +} +``` + +#### 3.2.2 Supporting Enums + +**File: `src/main/java/noppes/npcs/constants/EnumAuctionDuration.java`** + +```java +package noppes.npcs.constants; + +public enum EnumAuctionDuration { + SHORT(2 * 60 * 60 * 1000L), // 2 hours + MEDIUM(12 * 60 * 60 * 1000L), // 12 hours + LONG(24 * 60 * 60 * 1000L), // 24 hours + VERY_LONG(48 * 60 * 60 * 1000L); // 48 hours + + private final long millis; + + EnumAuctionDuration(long millis) { + this.millis = millis; + } + + public long getMillis() { + return millis; + } + + public String getDisplayName() { + switch (this) { + case SHORT: return "2 Hours"; + case MEDIUM: return "12 Hours"; + case LONG: return "24 Hours"; + case VERY_LONG: return "48 Hours"; + default: return "Unknown"; + } + } +} +``` + +**File: `src/main/java/noppes/npcs/constants/EnumAuctionStatus.java`** + +```java +package noppes.npcs.constants; + +public enum EnumAuctionStatus { + ACTIVE, // Currently listed + SOLD, // Successfully sold (buyout or auction end with bids) + EXPIRED, // Ended without bids + CANCELLED, // Cancelled by seller + CLAIMED // Item/money has been claimed +} +``` + +**File: `src/main/java/noppes/npcs/constants/EnumAuctionCategory.java`** + +```java +package noppes.npcs.constants; + +public enum EnumAuctionCategory { + WEAPONS, + ARMOR, + TOOLS, + FOOD, + POTIONS, + BLOCKS, + MATERIALS, + ENCHANTED, + MISC +} +``` + +### 3.3 Auction Controller + +**File: `src/main/java/noppes/npcs/controllers/AuctionController.java`** + +```java +package noppes.npcs.controllers; + +import net.minecraft.entity.player.EntityPlayer; +import net.minecraft.item.ItemStack; +import net.minecraft.nbt.CompressedStreamTools; +import net.minecraft.nbt.NBTTagCompound; +import net.minecraft.nbt.NBTTagList; +import noppes.npcs.CustomNpcs; +import noppes.npcs.LogWriter; +import noppes.npcs.controllers.data.AuctionListing; +import noppes.npcs.constants.*; + +import java.io.File; +import java.util.*; +import java.util.concurrent.ConcurrentHashMap; +import java.util.stream.Collectors; + +public class AuctionController { + private static AuctionController instance; + + // All listings (thread-safe for async operations) + public ConcurrentHashMap listings = new ConcurrentHashMap<>(); + + // Index by seller for quick lookup + private Map> sellerIndex = new ConcurrentHashMap<>(); + + // Pending claims (seller -> items/money to claim) + public Map> pendingClaims = new ConcurrentHashMap<>(); + + private int nextId = 1; + private long lastSaveTime = 0; + private static final long SAVE_INTERVAL = 60000; // Save every minute + + // Configuration + public double listingFee = 0.0; // Fee to list item + public double saleTax = 0.05; // 5% tax on sales + public int maxListingsPerPlayer = 20; + public boolean requireAuctioneer = true; // Require Auctioneer NPC to access + + public static AuctionController getInstance() { + if (instance == null) { + instance = new AuctionController(); + instance.load(); + } + return instance; + } + + /** + * Create a new auction listing + */ + public AuctionListing createListing(EntityPlayer seller, ItemStack item, + double startPrice, double buyout, + EnumAuctionDuration duration) { + UUID sellerUUID = seller.getUniqueID(); + + // Check max listings + Set sellerListings = sellerIndex.get(sellerUUID); + if (sellerListings != null && sellerListings.size() >= maxListingsPerPlayer) { + return null; + } + + // Charge listing fee + if (listingFee > 0) { + CurrencyController currency = CurrencyController.getInstance(); + if (!currency.withdraw(seller, listingFee)) { + return null; + } + } + + // Create listing + AuctionListing listing = new AuctionListing( + sellerUUID, seller.getCommandSenderName(), + item, startPrice, buyout, duration + ); + listing.id = nextId++; + + // Add to indexes + listings.put(listing.id, listing); + sellerIndex.computeIfAbsent(sellerUUID, k -> new HashSet<>()).add(listing.id); + + // Remove item from seller inventory + item.stackSize = 0; + + scheduleSave(); + return listing; + } + + /** + * Place a bid on an auction + */ + public boolean placeBid(EntityPlayer bidder, int listingId, double amount) { + AuctionListing listing = listings.get(listingId); + if (listing == null || listing.isExpired()) return false; + + CurrencyController currency = CurrencyController.getInstance(); + + // Check if bidder can afford + if (!currency.canAfford(bidder, amount)) return false; + + // Refund previous bidder + if (listing.highBidderUUID != null) { + addClaim(listing.highBidderUUID, listing.highBidderName, + null, listing.currentBid, "Outbid refund for: " + + listing.item.getDisplayName()); + } + + // Place bid + if (!listing.placeBid(bidder.getUniqueID(), + bidder.getCommandSenderName(), amount)) { + return false; + } + + // Hold currency from bidder + currency.withdraw(bidder, amount); + + scheduleSave(); + return true; + } + + /** + * Buyout an auction + */ + public boolean buyout(EntityPlayer buyer, int listingId) { + AuctionListing listing = listings.get(listingId); + if (listing == null || listing.buyoutPrice <= 0) return false; + + CurrencyController currency = CurrencyController.getInstance(); + + // Check if buyer can afford + if (!currency.canAfford(buyer, listing.buyoutPrice)) return false; + + // Refund previous bidder if any + if (listing.highBidderUUID != null) { + addClaim(listing.highBidderUUID, listing.highBidderName, + null, listing.currentBid, "Buyout refund for: " + + listing.item.getDisplayName()); + } + + // Execute buyout + if (!listing.buyout(buyer.getUniqueID(), buyer.getCommandSenderName())) { + return false; + } + + // Withdraw from buyer + currency.withdraw(buyer, listing.buyoutPrice); + + // Calculate seller proceeds (minus tax) + double proceeds = listing.buyoutPrice * (1 - saleTax); + + // Add claims for both parties + addClaim(listing.sellerUUID, listing.sellerName, null, proceeds, + "Sale of: " + listing.item.getDisplayName()); + addClaim(buyer.getUniqueID(), buyer.getCommandSenderName(), + listing.item, 0, "Purchased: " + listing.item.getDisplayName()); + + scheduleSave(); + return true; + } + + /** + * Cancel a listing (seller only) + */ + public boolean cancelListing(EntityPlayer player, int listingId) { + AuctionListing listing = listings.get(listingId); + if (listing == null) return false; + + if (!listing.cancel(player.getUniqueID())) return false; + + // Return item to seller + addClaim(listing.sellerUUID, listing.sellerName, listing.item, 0, + "Cancelled listing: " + listing.item.getDisplayName()); + + scheduleSave(); + return true; + } + + /** + * Process expired auctions (called periodically) + */ + public void processExpiredAuctions() { + long now = System.currentTimeMillis(); + + for (AuctionListing listing : listings.values()) { + if (listing.status != EnumAuctionStatus.ACTIVE) continue; + if (!listing.isExpired()) continue; + + if (listing.highBidderUUID != null) { + // Auction successful - has bids + listing.status = EnumAuctionStatus.SOLD; + + double proceeds = listing.currentBid * (1 - saleTax); + addClaim(listing.sellerUUID, listing.sellerName, null, proceeds, + "Auction sold: " + listing.item.getDisplayName()); + addClaim(listing.highBidderUUID, listing.highBidderName, + listing.item, 0, "Won auction: " + listing.item.getDisplayName()); + } else { + // No bids - return to seller + listing.status = EnumAuctionStatus.EXPIRED; + addClaim(listing.sellerUUID, listing.sellerName, listing.item, 0, + "Expired listing: " + listing.item.getDisplayName()); + } + } + + scheduleSave(); + } + + /** + * Get active listings with optional filters + */ + public List getActiveListings(EnumAuctionCategory category, + String search, + int page, int pageSize) { + return listings.values().stream() + .filter(l -> l.status == EnumAuctionStatus.ACTIVE) + .filter(l -> !l.isExpired()) + .filter(l -> category == null || l.category == category) + .filter(l -> search == null || search.isEmpty() || + l.item.getDisplayName().toLowerCase() + .contains(search.toLowerCase())) + .sorted(Comparator.comparingLong(l -> l.expirationTime)) + .skip((long) page * pageSize) + .limit(pageSize) + .collect(Collectors.toList()); + } + + /** + * Get player's own listings + */ + public List getPlayerListings(UUID playerUUID) { + Set ids = sellerIndex.get(playerUUID); + if (ids == null) return Collections.emptyList(); + + return ids.stream() + .map(listings::get) + .filter(Objects::nonNull) + .collect(Collectors.toList()); + } + + /** + * Get pending claims for a player + */ + public List getPendingClaims(UUID playerUUID) { + return pendingClaims.getOrDefault(playerUUID, Collections.emptyList()); + } + + /** + * Claim pending items/money + */ + public boolean claim(EntityPlayer player, int claimIndex) { + List claims = pendingClaims.get(player.getUniqueID()); + if (claims == null || claimIndex >= claims.size()) return false; + + AuctionClaim claim = claims.get(claimIndex); + + // Give item or money + if (claim.item != null) { + if (!player.inventory.addItemStackToInventory(claim.item.copy())) { + return false; // Inventory full + } + } + if (claim.money > 0) { + CurrencyController.getInstance().deposit(player, claim.money); + } + + claims.remove(claimIndex); + scheduleSave(); + return true; + } + + private void addClaim(UUID playerUUID, String playerName, + ItemStack item, double money, String description) { + AuctionClaim claim = new AuctionClaim(item, money, description); + pendingClaims.computeIfAbsent(playerUUID, k -> new ArrayList<>()).add(claim); + } + + // Persistence + private void scheduleSave() { + long now = System.currentTimeMillis(); + if (now - lastSaveTime > SAVE_INTERVAL) { + save(); + lastSaveTime = now; + } + } + + public void save() { + try { + NBTTagCompound compound = new NBTTagCompound(); + compound.setInteger("NextId", nextId); + compound.setDouble("ListingFee", listingFee); + compound.setDouble("SaleTax", saleTax); + compound.setInteger("MaxListings", maxListingsPerPlayer); + + // Save listings + NBTTagList listingList = new NBTTagList(); + for (AuctionListing listing : listings.values()) { + listingList.appendTag(listing.writeToNBT(new NBTTagCompound())); + } + compound.setTag("Listings", listingList); + + // Save claims + NBTTagList claimList = new NBTTagList(); + for (Map.Entry> entry : pendingClaims.entrySet()) { + NBTTagCompound playerClaims = new NBTTagCompound(); + playerClaims.setString("UUID", entry.getKey().toString()); + NBTTagList claims = new NBTTagList(); + for (AuctionClaim claim : entry.getValue()) { + claims.appendTag(claim.writeToNBT(new NBTTagCompound())); + } + playerClaims.setTag("Claims", claims); + claimList.appendTag(playerClaims); + } + compound.setTag("PendingClaims", claimList); + + File file = new File(CustomNpcs.getWorldSaveDirectory(), "auction.dat"); + CompressedStreamTools.writeCompressed(compound, + new java.io.FileOutputStream(file)); + + } catch (Exception e) { + LogWriter.except(e); + } + } + + public void load() { + try { + File file = new File(CustomNpcs.getWorldSaveDirectory(), "auction.dat"); + if (!file.exists()) return; + + NBTTagCompound compound = CompressedStreamTools.readCompressed( + new java.io.FileInputStream(file)); + + nextId = compound.getInteger("NextId"); + listingFee = compound.getDouble("ListingFee"); + saleTax = compound.getDouble("SaleTax"); + maxListingsPerPlayer = compound.getInteger("MaxListings"); + + // Load listings + NBTTagList listingList = compound.getTagList("Listings", 10); + for (int i = 0; i < listingList.tagCount(); i++) { + AuctionListing listing = new AuctionListing(); + listing.readFromNBT(listingList.getCompoundTagAt(i)); + listings.put(listing.id, listing); + sellerIndex.computeIfAbsent(listing.sellerUUID, k -> new HashSet<>()) + .add(listing.id); + } + + // Load claims + NBTTagList claimList = compound.getTagList("PendingClaims", 10); + for (int i = 0; i < claimList.tagCount(); i++) { + NBTTagCompound playerClaims = claimList.getCompoundTagAt(i); + UUID playerUUID = UUID.fromString(playerClaims.getString("UUID")); + NBTTagList claims = playerClaims.getTagList("Claims", 10); + List claimsList = new ArrayList<>(); + for (int j = 0; j < claims.tagCount(); j++) { + AuctionClaim claim = new AuctionClaim(); + claim.readFromNBT(claims.getCompoundTagAt(j)); + claimsList.add(claim); + } + pendingClaims.put(playerUUID, claimsList); + } + + } catch (Exception e) { + LogWriter.except(e); + } + } +} + +// Claim data structure +class AuctionClaim { + public ItemStack item; + public double money; + public String description; + public long timestamp; + + public AuctionClaim() {} + + public AuctionClaim(ItemStack item, double money, String description) { + this.item = item != null ? item.copy() : null; + this.money = money; + this.description = description; + this.timestamp = System.currentTimeMillis(); + } + + public NBTTagCompound writeToNBT(NBTTagCompound compound) { + if (item != null) { + compound.setTag("Item", item.writeToNBT(new NBTTagCompound())); + } + compound.setDouble("Money", money); + compound.setString("Description", description); + compound.setLong("Timestamp", timestamp); + return compound; + } + + public void readFromNBT(NBTTagCompound compound) { + if (compound.hasKey("Item")) { + item = ItemStack.loadItemStackFromNBT(compound.getCompoundTag("Item")); + } + money = compound.getDouble("Money"); + description = compound.getString("Description"); + timestamp = compound.getLong("Timestamp"); + } +} +``` + +### 3.4 Auctioneer Role + +**File: `src/main/java/noppes/npcs/roles/RoleAuctioneer.java`** + +```java +package noppes.npcs.roles; + +import net.minecraft.entity.player.EntityPlayer; +import net.minecraft.nbt.NBTTagCompound; +import noppes.npcs.NoppesUtilServer; +import noppes.npcs.constants.EnumGuiType; +import noppes.npcs.entity.EntityNPCInterface; + +public class RoleAuctioneer extends RoleInterface { + + // Configuration + public String auctionHouseName = "Global"; // For future multi-auction support + public boolean allowSelling = true; + public boolean allowBuying = true; + public boolean showExpiredListings = true; + + // Custom messages + public String welcomeMessage = ""; + public String sellDisabledMessage = "This auctioneer does not accept listings."; + public String buyDisabledMessage = "This auctioneer does not sell items."; + + public RoleAuctioneer(EntityNPCInterface npc) { + super(npc); + } + + @Override + public NBTTagCompound writeToNBT(NBTTagCompound compound) { + compound.setString("AuctionHouse", auctionHouseName); + compound.setBoolean("AllowSelling", allowSelling); + compound.setBoolean("AllowBuying", allowBuying); + compound.setBoolean("ShowExpired", showExpiredListings); + compound.setString("WelcomeMsg", welcomeMessage); + compound.setString("SellDisabledMsg", sellDisabledMessage); + compound.setString("BuyDisabledMsg", buyDisabledMessage); + return compound; + } + + @Override + public void readFromNBT(NBTTagCompound compound) { + auctionHouseName = compound.getString("AuctionHouse"); + allowSelling = compound.getBoolean("AllowSelling"); + allowBuying = compound.getBoolean("AllowBuying"); + showExpiredListings = compound.getBoolean("ShowExpired"); + welcomeMessage = compound.getString("WelcomeMsg"); + sellDisabledMessage = compound.getString("SellDisabledMsg"); + buyDisabledMessage = compound.getString("BuyDisabledMsg"); + } + + @Override + public void interact(EntityPlayer player) { + // Show welcome message if set + if (!welcomeMessage.isEmpty()) { + npc.say(player, npc.advanced.getInteractLine()); + } + + // Open auction house GUI + NoppesUtilServer.sendOpenGui(player, EnumGuiType.PlayerAuction, npc); + } +} +``` + +### 3.5 Update EnumRoleType + +**File: `src/main/java/noppes/npcs/constants/EnumRoleType.java`** + +```java +public enum EnumRoleType { + None, + Trader, + Follower, + Bank, + Transporter, + Postman, + Companion, + Mount, + Auctioneer // Add this +} +``` + +### 3.6 Update DataAdvanced + +**File: `src/main/java/noppes/npcs/DataAdvanced.java`** + +Add to `setRole()` method: + +```java +else if (role == EnumRoleType.Auctioneer && !(npc.roleInterface instanceof RoleAuctioneer)) + npc.roleInterface = new RoleAuctioneer(npc); +``` + +### 3.7 Update EnumGuiType + +**File: `src/main/java/noppes/npcs/constants/EnumGuiType.java`** + +Add new GUI types: + +```java +// Auction House GUIs +PlayerAuction, // Main auction browse/buy interface +PlayerAuctionSell, // Create new listing +PlayerAuctionMyListings, // View own listings +PlayerAuctionClaims, // Claim items/money +AuctioneerSetup, // NPC configuration +ManageAuctions // Admin management +``` + +### 3.8 Auction GUI System + +The auction GUI system will consist of multiple interconnected screens: + +#### 3.8.1 Main Auction Browser + +**File: `src/main/java/noppes/npcs/client/gui/player/GuiAuctionBrowse.java`** + +Features: +- Category filter tabs (Weapons, Armor, Tools, etc.) +- Search bar for item names +- Sort options (Time remaining, Price, Recently listed) +- Paginated listing display +- Quick buy/bid buttons + +#### 3.8.2 Create Listing GUI + +**File: `src/main/java/noppes/npcs/client/gui/player/GuiAuctionSell.java`** + +Features: +- Item slot for the item to sell +- Starting price input +- Buyout price input (optional) +- Duration selector +- Listing fee display +- Confirm button + +#### 3.8.3 My Listings GUI + +**File: `src/main/java/noppes/npcs/client/gui/player/GuiAuctionMyListings.java`** + +Features: +- List of player's active listings +- Current bid status +- Time remaining +- Cancel button (if no bids) + +#### 3.8.4 Claims GUI + +**File: `src/main/java/noppes/npcs/client/gui/player/GuiAuctionClaims.java`** + +Features: +- List of pending claims (items won, money from sales, refunds) +- Claim button for each item +- Claim all button + +### 3.9 Network Packets + +#### 3.9.1 Auction Action Packet + +**File: `src/main/java/kamkeel/npcs/network/packets/player/AuctionActionPacket.java`** + +```java +package kamkeel.npcs.network.packets.player; + +public class AuctionActionPacket extends AbstractPacket { + + public enum Action { + CREATE_LISTING, + PLACE_BID, + BUYOUT, + CANCEL, + CLAIM, + CLAIM_ALL, + BROWSE, + MY_LISTINGS + } + + private Action action; + private int listingId; + private double amount; + private NBTTagCompound itemData; + private int duration; + private double buyoutPrice; + private int category; + private String search; + private int page; + + // Implement sendData/receiveData... +} +``` + +#### 3.9.2 Auction Sync Packet + +**File: `src/main/java/kamkeel/npcs/network/packets/data/AuctionSyncPacket.java`** + +Used to send auction listing data to clients for GUI display. + +### 3.10 Periodic Tasks + +Add to server tick handler to process expired auctions: + +**File: `src/main/java/noppes/npcs/ServerTickHandler.java`** + +```java +private int auctionCheckCounter = 0; + +@SubscribeEvent +public void onServerTick(TickEvent.ServerTickEvent event) { + // ... existing code ... + + // Check expired auctions every 5 minutes (6000 ticks) + if (++auctionCheckCounter >= 6000) { + auctionCheckCounter = 0; + AuctionController.getInstance().processExpiredAuctions(); + } +} +``` + +--- + +## Implementation Order + +The features should be implemented in this order due to dependencies: + +### Phase 1: Currency System (Foundation) +1. Add VaultAPI dependency to build files +2. Create `VaultHelper.java` with reflection-based integration +3. Create `CurrencyController.java` +4. Add initialization hook in `CustomNpcs.java` +5. Create `PlayerCurrencyData.java` and integrate with `PlayerData` +6. Create currency configuration GUI +7. Test with and without Vault present + +### Phase 2: Trader Enhancements +1. Create `EnumStockReset.java` +2. Create `TraderStock.java` +3. Modify `RoleTrader.java` to add stock and currency fields +4. Modify `ContainerNPCTrader.java` to handle stock/currency +5. Update `GuiNpcTraderSetup.java` with new options +6. Update network packets for stock synchronization +7. Test stock depletion and reset timers + +### Phase 3: Auction House +1. Create auction enums (`EnumAuctionDuration`, `EnumAuctionStatus`, `EnumAuctionCategory`) +2. Create `AuctionListing.java` and `AuctionClaim` classes +3. Create `AuctionController.java` +4. Update `EnumRoleType.java` to add Auctioneer +5. Create `RoleAuctioneer.java` +6. Update `DataAdvanced.java` for role instantiation +7. Update `EnumGuiType.java` with auction GUIs +8. Create auction containers +9. Create auction GUI classes +10. Create network packets +11. Add periodic task for expired auctions +12. Create auctioneer setup GUI +13. Comprehensive testing + +--- + +## File Summary + +### New Files to Create + +| File | Description | +|------|-------------| +| `kamkeel/npcs/compat/VaultHelper.java` | VaultAPI integration | +| `kamkeel/npcs/controllers/CurrencyController.java` | Currency management | +| `noppes/npcs/controllers/data/PlayerCurrencyData.java` | Per-player currency data | +| `noppes/npcs/controllers/data/TraderStock.java` | Trader stock configuration | +| `noppes/npcs/constants/EnumStockReset.java` | Stock reset types | +| `noppes/npcs/controllers/AuctionController.java` | Auction house management | +| `noppes/npcs/controllers/data/AuctionListing.java` | Auction listing data | +| `noppes/npcs/constants/EnumAuctionDuration.java` | Auction duration options | +| `noppes/npcs/constants/EnumAuctionStatus.java` | Auction status states | +| `noppes/npcs/constants/EnumAuctionCategory.java` | Item categories | +| `noppes/npcs/roles/RoleAuctioneer.java` | Auctioneer NPC role | +| `noppes/npcs/containers/ContainerAuction*.java` | Auction containers | +| `noppes/npcs/client/gui/player/GuiAuction*.java` | Auction GUIs | +| `noppes/npcs/client/gui/roles/GuiNpcAuctioneerSetup.java` | Auctioneer config | +| `kamkeel/npcs/network/packets/player/AuctionActionPacket.java` | Auction actions | +| `kamkeel/npcs/network/packets/data/AuctionSyncPacket.java` | Auction data sync | + +### Files to Modify + +| File | Changes | +|------|---------| +| `dependencies.gradle` | Add VaultAPI dependency | +| `repositories.gradle` | Add Vault repository | +| `CustomNpcs.java` | Initialize VaultHelper, AuctionController | +| `EnumRoleType.java` | Add Auctioneer | +| `EnumGuiType.java` | Add auction GUI types | +| `DataAdvanced.java` | Handle Auctioneer role | +| `RoleTrader.java` | Add stock and currency support | +| `ContainerNPCTrader.java` | Handle stock/currency transactions | +| `GuiNpcTraderSetup.java` | Add stock/currency UI | +| `PlayerData.java` | Add PlayerCurrencyData | +| `CommonProxy.java` | Register auction containers | +| `ServerTickHandler.java` | Add auction expiration check | +| `PacketHandler.java` | Register auction packets | + +--- + +## Testing Strategy + +### Unit Testing +- Currency operations (deposit, withdraw, balance) +- Stock depletion and reset calculations +- Auction bid validation +- Auction expiration handling + +### Integration Testing +- VaultAPI integration on hybrid servers +- Fallback to item currency when Vault unavailable +- Stock persistence across server restarts +- Auction persistence and recovery + +### User Acceptance Testing +- Complete trading flow with stock limits +- Complete auction flow (list → bid → win → claim) +- Currency display formatting +- GUI usability + +### Edge Cases +- Negative currency amounts +- Concurrent bids on same auction +- Server crash during transaction +- Player offline when auction ends +- Maximum listings per player +- Inventory full when claiming + +--- + +## API/Scripting Extensions + +Consider adding these scripting hooks: + +```java +// ICurrency interface for scripts +double getBalance(IPlayer player); +boolean withdraw(IPlayer player, double amount); +boolean deposit(IPlayer player, double amount); +String format(double amount); + +// IAuction interface for scripts +IAuctionListing createListing(IPlayer seller, IItemStack item, + double startPrice, double buyout, int durationHours); +boolean cancelListing(int listingId); +List getPlayerListings(IPlayer player); + +// Events +onAuctionCreated(IAuctionListing listing); +onAuctionBid(IAuctionListing listing, IPlayer bidder, double amount); +onAuctionSold(IAuctionListing listing, IPlayer buyer, double price); +onAuctionExpired(IAuctionListing listing); +onTraderPurchase(ITrader trader, IPlayer buyer, int slot, int stockRemaining); +onTraderStockReset(ITrader trader); +``` + +--- + +## Conclusion + +This implementation plan provides a comprehensive roadmap for the CustomNPC+ 1.11 Market Update. The three features are designed to work together seamlessly: + +1. **Currency System** provides the foundation for monetary transactions +2. **Trader Enhancements** modernize the existing trader with stock and currency support +3. **Auction House** creates a global marketplace leveraging the currency system + +The implementation follows existing codebase patterns and can be developed incrementally, with each phase building on the previous one.