MD Files for Future

This commit is contained in:
Kam committed 2026-02-04 16:35:56 -05:00
1 parent 83b86a4538
commit ed386677ee
7 files changed
+417 -1053

No files matched your search

-729
View File
@@ -1,729 +0,0 @@
# CustomNPC+ 1.11 Market Update - Implementation Plan
## Overview
The 1.11 Market Update introduces a comprehensive economy system for CustomNPC+:
1. **Currency System** - Built-in CNPC+ currency with optional Vault integration
2. **Trader Enhancements** - Stock system, currency-based trades, reset timers
3. **Auction House** - Global auction system with bidding, buyout, and claims
---
## 1. Currency System
### Status: COMPLETE ✅
The currency system provides a unified economy for CNPC+ features.
### Features
- **Built-in CNPC+ Currency** - Stored in PlayerData, persists across profile slots
- **Vault Integration** - Optional, when enabled all operations use Vault instead
- **Scripting API** - Full access via `IPlayer` methods
- **Unified Usage** - Both Trader and Auction systems use `PlayerCurrencyData` which auto-delegates to Vault
### Vault Integration Flow
```
┌─────────────────────────────────────────────────────────────────┐
│ PlayerCurrencyData │
│ │
│ shouldUseVault() = ConfigMarket.UseVault && VaultUtil.isEnabled()│
│ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ All methods check shouldUseVault() first: │ │
│ │ - getBalance() → VaultUtil.getBalance() or local balance │ │
│ │ - withdraw() → VaultUtil.withdrawMoney() or local │ │
│ │ - deposit() → VaultUtil.addMoney() or local │ │
│ │ - canAfford() → VaultUtil.has() or local check │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
│ Used by: ContainerNPCTrader, AuctionController │
└─────────────────────────────────────────────────────────────────┘
```
### Key Files
| File | Purpose |
|------|---------|
| `PlayerTradeData.java` | Per-player trade data (currency + auction claims), Vault delegation |
| `IPlayerTradeData.java` | API interface for trade operations (currency + claims) |
| `ConfigMarket.java` | Currency configuration (UseVault, CurrencyName, StartingBalance, MaxBalance) |
| `VaultUtil.java` | Vault API integration via reflection |
### Configuration (ConfigMarket.java)
```
Market.Currency:
- Use Vault: false
- Currency Name: "Coins"
- Starting Balance: 0
- Max Balance: 2147483647
```
### Scripting API (IPlayer)
```javascript
player.getCurrencyBalance() // Get balance
player.setCurrencyBalance(amount) // Set balance
player.depositCurrency(amount) // Add currency (returns success)
player.withdrawCurrency(amount) // Remove currency (returns success)
player.canAffordCurrency(amount) // Check if can afford
player.isUsingVaultCurrency() // Check if Vault is active
player.getFormattedCurrencyBalance() // Get formatted string
// Via IPlayerData
player.getData().getTradeData() // Get IPlayerTradeData interface
```
---
## 2. Trader Enhancements
### Status: COMPLETE ✅
---
### 2.1 Stock System - COMPLETE ✅
Traders can have limited stock that resets on configurable schedules.
#### Stock Modes
| Mode | Description | Status |
|------|-------------|--------|
| **Global** | All players share the same stock pool | ✅ Working |
| **Per-Player** | Each player has their own stock counts | ✅ Working |
#### Stock Reset Types (EnumStockReset)
| Type | Description | Status |
|------|-------------|--------|
| `NONE` | Stock never resets | ✅ Working |
| `MCDAILY` | Resets every MC day (24000 ticks) | ✅ Working |
| `MCWEEKLY` | Resets every 7 MC days (168000 ticks) | ✅ Working |
| `MCCUSTOM` | Custom MC tick interval | ✅ Working |
| `RLDAILY` | Resets every 24 real-life hours | ✅ Working |
| `RLWEEKLY` | Resets every 7 real-life days | ✅ Working |
| `RLCUSTOM` | Custom real-time interval | ✅ Working |
#### Stock UI Features - COMPLETE ✅
| Feature | Status | Notes |
|---------|--------|-------|
| Stock count per item | ✅ | Shows to right of output slot |
| Out of stock indicator | ✅ | Dark overlay + red count |
| Reset timer countdown | ✅ | Real-time client-side countdown in top-right |
| "Reopen Trader" message | ✅ | Shows when countdown reaches 0 |
| Admin stock configuration | ✅ | SubGuiNpcTraderStock |
| Per-slot stock limits | ✅ | SubGuiNpcTraderStockSlots |
| Reset stock button | ✅ | With confirmation dialog |
| Reset cooldown button | ✅ | With confirmation dialog |
---
### 2.2 Trader Currency Support - COMPLETE ✅
Trades can require BOTH items AND currency (additive costs). Uses `PlayerCurrencyData` which auto-delegates to Vault when enabled.
#### Trade Entry Structure
Each trade slot can have:
- **Sold Item** - What the player receives ✅
- **Currency 1** - First item cost (existing) ✅
- **Currency 2** - Second item cost (existing) ✅
- **Currency Cost** - CNPC+ Currency / Vault cost ✅ NEW
#### Implementation Details
- Currency cost stored as `long[] currencyCost[18]` in RoleTrader
- Uses `data.tradeData.getBalance()` and `data.tradeData.withdraw()`
- Automatically uses Vault when `ConfigMarket.UseVault` is enabled
- NBT serialization for persistence ✅
---
### 2.3 Player Trader GUI - COMPLETE ✅
#### Display Features
| Element | Position | Status |
|---------|----------|--------|
| "Trader" label | Top-left | ✅ |
| Reset countdown | Top-right | ✅ Real-time ticking |
| Stock count | Right of each trade | ✅ Green/Red |
| Player balance | Bottom-right | ✅ |
| Status message | Bottom-left | ✅ On hover |
---
### 2.4 Multi-Player Sync - COMPLETE ✅
MarketRegistry provides linked market synchronization across all NPCs sharing the same market.
---
### 2.5 Scripting API - COMPLETE ✅
Full API available via `IRoleTrader` interface.
---
## 3. Auction House System
### Status: COMPLETE ✅
### 3.1 Architecture Overview
```
┌─────────────────────────────────────────────────────────────────┐
│ AuctionController │
│ - Manages auction listings with player indices │
│ - Handles listing/bidding/buyout logic │
│ - Uses ConcurrentHashMap for thread-safety (no locks) │
│ - Async saves on CNPC+ thread every 30 seconds │
│ - 30-second update cycle for processing ended auctions │
└─────────────────────────────────────────────────────────────────┘
│
Uses PlayerCurrencyData (Vault-aware)
│
┌─────────────────────────────────────────────────────────────────┐
│ PlayerTradeData │
│ - Combined currency + auction claims (shared across profiles) │
│ - Currency: Vault integration with local fallback │
│ - Claims: Thread-safe CopyOnWriteArrayList for async additions │
│ - Expired claims processed on login │
│ - Notifications sent immediately to online players │
└─────────────────────────────────────────────────────────────────┘
```
### 3.2 Vault Integration
The Auction system uses `PlayerCurrencyData` for all currency operations:
- `AuctionController.createListing()` → `currencyData.withdraw(fee)`
- `AuctionController.placeBid()` → `currencyData.withdraw(bidAmount)`
- `AuctionController.buyout()` → `currencyData.withdraw(buyoutPrice)`
- `AuctionController.claimCurrency()` → `currencyData.deposit(amount)`
**When Vault is enabled** (`ConfigMarket.UseVault = true`):
- All operations automatically use Vault economy
- No code changes required - `PlayerCurrencyData` handles delegation
### 3.3 GUI Structure
```
GuiAuctionInterface (Base GUI - opened via Auctioneer NPC)
│
├── GuiAuctionListing (Browse auctions - PAGE_LISTINGS)
│ - 9x5 grid of auction items
│ - Filter button with tooltip showing current settings
│ - Click item → Opens GuiAuctionBidding
│ - Pagination with up/down arrows
│
├── GuiAuctionSell (Create new listing - PAGE_SELL)
│ - Sell slot for item to auction (cloned from inventory)
│ - Click inventory: left=add stack, right=add 1
│ - Click sell slot: left=clear, right=remove 1
│ - Starting price + buyout price text fields
│ - Allow Buyout toggle button
│ - Listing fee display
│ - Confirm button with coin icon
│
├── GuiAuctionTrades (My Trades - PAGE_CLAIMS)
│ - 9x5 grid showing: active listings, active bids, claims
│ - Blue tint: active listings/bids
│ - Green tint: claimable items
│ - Red tint: refunds
│ - Confirmation system for cancel/claim operations
│
├── GuiAuctionBidding (View listing details)
│ - Item display slot
│ - Auction info (seller, price, time, bids)
│ - Bid button → SubGuiAuctionBid
│ - Buy Now button → SubGuiAuctionBuyNow
│ - Own listings: buttons hidden, view-only
│
├── SubGuiAuctionBid (Bid confirmation popup)
│ - Shows minimum bid, player balance
│ - Bid amount input field
│ - Place Bid / Cancel buttons
│
├── SubGuiAuctionBuyNow (Buyout confirmation popup)
│ - Shows buyout price, player balance
│ - Yes / Cancel buttons
│
└── SubGuiAuctionSearch (Filter popup)
- Search text input
- Apply/Cancel buttons
```
### 3.4 Client Config Sync
The client uses `AuctionClientConfig` to cache server settings:
- Synced via `LoginPacket` on player join
- Client never uses `ConfigMarket` directly for display
- Ensures server authority over fees, currency name, etc.
```java
// Server sends config in LoginPacket
AuctionClientConfig.writeToNBT(compound); // Server side
// Client receives and caches
AuctionClientConfig.readFromNBT(compound); // Client side
// Client GUI uses cached values
AuctionClientConfig.getListingFee();
AuctionClientConfig.getCurrencyName();
AuctionClientConfig.getMinBidIncrement();
```
### 3.5 Data Structures
#### AuctionListing
```java
public class AuctionListing {
String id; // Unique listing ID (UUID-based)
UUID sellerUUID; // Seller's UUID
String sellerName; // Seller's display name
ItemStack item; // Item being sold
long startingPrice; // Minimum starting bid
long buyoutPrice; // Instant buy price (0 = no buyout)
long currentBid; // Current highest bid
UUID highBidderUUID; // Current high bidder (null if no bids)
String highBidderName; // High bidder display name
int bidCount; // Number of bids placed
long createdTime; // When listing was created
long endTime; // When auction ends
EnumAuctionStatus status; // ACTIVE, ENDED, CANCELLED, CLAIMED
}
```
#### AuctionClaim
```java
public class AuctionClaim {
String id; // Unique claim ID
UUID playerUUID; // Player who can claim
String listingId; // Related auction listing
EnumClaimType type; // ITEM, CURRENCY, REFUND
ItemStack item; // Item to claim (if type = ITEM)
long currency; // Currency to claim (if type = CURRENCY/REFUND)
long createdTime; // When claim was created
boolean claimed; // Whether claimed
}
```
### 3.6 Security Features
All actions are validated server-side:
| Check | Location | Description |
|-------|----------|-------------|
| Own item bid prevention | `placeBid()` | `listing.isSeller(playerUUID)` check |
| Own item buyout prevention | `buyout()` | `listing.isSeller(playerUUID)` check |
| Auction expiry check | `placeBid()/buyout()` | Double-check inside write lock |
| Currency validation | All actions | Verify balance before operations |
| Claim ownership | `claimItem()/claimCurrency()` | `claim.isForPlayer(playerUUID)` check |
| Blacklist check | `createListing()` | `AuctionBlacklist.isBlacklistedForPlayer()` check |
| Bound item check | `createListing()` | Auto-blocks Soulbound/Profile-Slotbound items |
### 3.7 Snipe Protection
When a bid is placed with less than `SnipeProtectionMinutes` remaining:
- Extend the auction end time TO `SnipeProtectionMinutes` from now
- Never extend beyond `SnipeProtectionMinutes`
- Default: 2 minutes
Example: Auction ends in 30 seconds, someone bids → Timer resets to 2:00
---
### 3.8 Item Blacklist System
Prevents specific items from being listed on the auction house.
#### Blacklist Types
| Type | Description | Example |
|------|-------------|---------|
| **Items** | Block specific items by registry name | `minecraft:diamond_sword` |
| **Wildcards** | Block items matching pattern | `minecraft:diamond*` |
| **Mods** | Block all items from a mod | `customnpcs` |
| **NBT Tags** | Block items with specific NBT | `ench` (enchanted items) |
#### Auto-Blocked Items (Always Blocked)
These items are **always** blocked regardless of blacklist settings:
- **Soulbound Items** - Items with `cnpc_soulbind` requirement
- **Profile-Slotbound Items** - Items with `cnpc_profile_slot` requirement
The system checks for these under `RPGCore/Requirements` in the item's NBT.
#### Bypass Permission
Players with OP status or the `customnpcs.auction.blacklist.bypass` permission can list blacklisted items.
#### Configuration
```
Market.Auction.Blacklist:
Enabled: true
BlacklistedItems: ["minecraft:barrier", "minecraft:command_block*"]
BlacklistedMods: []
BlacklistedNBTTags: []
```
#### Commands
| Command | Description |
|---------|-------------|
| `/cnpc auction blacklist add <item\|mod\|nbt> <value>` | Add to blacklist (runtime only) |
| `/cnpc auction blacklist remove <item\|mod\|nbt> <value>` | Remove from blacklist (runtime only) |
| `/cnpc auction blacklist list [item\|mod\|nbt]` | List blacklisted entries |
| `/cnpc auction blacklist reload` | Reload blacklist from config |
| `/cnpc auction blacklist check` | Check if held item is blacklisted |
---
## 4. AuctionController Performance & Thread Safety
### 4.1 Threading Model
```
┌─────────────────────────────────────────────────────────────────┐
│ AuctionController │
│ │
│ ┌─────────────────────┐ ┌─────────────────┐ ┌───────────────┐ │
│ │ ConcurrentHashMap │ │ AtomicBoolean │ │ CNPC+ Thread │ │
│ │ (listings, indices) │ │ dirty, saving │ │ (async saves) │ │
│ └─────────────────────┘ └─────────────────┘ └───────────────┘ │
│ │
│ All operations use ConcurrentHashMap - no explicit locking │
│ Minecraft is single-threaded for gameplay - inherent safety │
│ Async saves snapshot data before writing to disk │
└─────────────────────────────────────────────────────────────────┘
│
┌─────────────────────────────────────────────────────────────────┐
│ PlayerTradeData │
│ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ Currency: long balance (or Vault delegation) │ │
│ │ Claims: CopyOnWriteArrayList<AuctionClaim> │ │
│ │ - Thread-safe for concurrent read/write │ │
│ │ - Claims can be added from CNPC+ thread for offline players │ │
│ │ - Stored in PlayerData (persisted with player, not auctions) │ │
│ └─────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
```
### 4.2 Player Indices for O(1) Lookups
| Index | Type | Purpose |
|-------|------|---------|
| `playerListingIds` | `Map<UUID, Set<String>>` | Active listings by seller |
| `playerBidIds` | `Map<UUID, Set<String>>` | Listings where player has active bid |
**Claims are now stored in PlayerData:**
- `PlayerTradeData.claims` - CopyOnWriteArrayList per player
- Accessed via `PlayerData.get(player).tradeData`
- Shared across all profile slots (combined with currency)
**Performance Impact:**
- `getPlayerListingCount()`: O(n) → O(1)
- `getPlayerActiveListings()`: O(n) → O(k) where k = player's listings
- `getPlayerActiveBids()`: O(n) → O(k)
- `getPlayerClaims()`: Direct access to player's claims list
### 4.3 Update Intervals
| Operation | Interval | Rationale |
|-----------|----------|-----------|
| Process ended auctions | 30 seconds (600 ticks) | Reduces server load |
| Save auction data | 30 seconds (600 ticks) | Batches writes, reduces I/O |
| Process expired claims | On player login | Per-player, not global tick |
### 4.4 Data Safety
1. **Currency Deduction** - Withdraw before updating listing
2. **Previous Bidder Refund** - Store info before modification
3. **Concurrent Saves** - `AtomicBoolean` prevents duplicates
4. **Offline Player Claims** - Loaded async on CNPC+ thread, saved to PlayerData
5. **Claim Migration** - Old claims in auction.dat migrated to PlayerData on load
### 4.5 Server Shutdown Handling
On `FMLServerStoppedEvent`:
1. `AuctionController.save()` called synchronously
2. Uses CNPC+ thread (single-threaded executor)
3. All pending saves complete before shutdown
---
## 5. File Structure
### New Files Created
```
constants/
EnumAuctionStatus.java ✅
EnumAuctionSort.java ✅
EnumClaimType.java ✅
EnumNotificationType.java ✅
controllers/
AuctionController.java ✅ (with threading, indices, Vault support)
AuctionConfigSync.java ✅ (server-side config sync utility)
controllers/data/
AuctionListing.java ✅
AuctionClaim.java ✅
AuctionFilter.java ✅
AuctionBlacklist.java ✅ (item blacklist checking + bypass)
PlayerTradeData.java ✅ (currency + claims storage per player)
roles/
RoleAuctioneer.java ✅
containers/
ContainerAuction.java ✅
ContainerAuctionListing.java ✅
ContainerAuctionBidding.java ✅
ContainerAuctionTrades.java ✅
ContainerAuctionSell.java ✅
InventoryAuctionDisplay.java ✅
SlotAuctionDisplay.java ✅
client/
AuctionClientConfig.java ✅ (client-side config cache)
client/gui/player/
GuiAuctionInterface.java ✅
GuiAuctionListing.java ✅
GuiAuctionSell.java ✅
GuiAuctionTrades.java ✅
GuiAuctionBidding.java ✅
SubGuiAuctionSearch.java ✅
SubGuiAuctionBid.java ✅
SubGuiAuctionBuyNow.java ✅
AuctionTooltipHandler.java ✅
client/gui/util/
GuiAuctionNavButton.java ✅
network/packets/player/
AuctionActionPacket.java ✅
```
### New Commands
```
command/
AuctionCommand.java ✅ /cnpc auction with list, view, open, blacklist
command/auction/
BlacklistSubCommand.java ✅ /cnpc auction blacklist subcommands
```
### Files Modified
```
CustomNpcs.java ✅ Initialize AuctionController, save on shutdown
EnumRoleType.java ✅ Added Auctioneer
EnumGuiType.java ✅ Added PlayerAuction, PlayerAuctionSell, PlayerAuctionTrades, PlayerAuctionBidding
EnumPlayerPacket.java ✅ Added AuctionData, AuctionAction
CommonProxy.java ✅ Handle auction container types
ClientProxy.java ✅ Handle auction GUI types
DataAdvanced.java ✅ Handle Auctioneer role
ConfigMarket.java ✅ Added Auction section
LoginPacket.java ✅ Sync auction config to client
PlayerData.java ✅ Added tradeData field (currency + claims, shared across profiles)
en_US.lang ✅ Added auction lang keys
```
---
## 6. Configuration
### ConfigMarket.java Structure
```java
// =========================================
// Currency (Market.Currency)
// =========================================
public static boolean UseVault = false; // Use Vault economy
public static String CurrencyName = "Coins"; // Display name
public static long StartingBalance = 0; // New player balance
public static long MaxBalance = Long.MAX_VALUE; // Balance cap
// =========================================
// Auction (Market.Auction)
// =========================================
public static final int MAX_TRADE_SLOTS = 45; // 9x5 grid maximum
public static final int MIN_TRADE_SLOTS = 1; // Minimum allowed
public static boolean AuctionEnabled = true;
public static int AuctionDurationHours = 24; // Auction length (hours)
public static long ListingFee = 10; // Fee to create listing
public static long MinimumListingPrice = 1; // Minimum starting price
public static double SalesTaxPercent = 0.05; // 5% tax on sales
public static int DefaultMaxTrades = 8; // Per player (listings + bids + claims)
public static int SnipeProtectionMinutes = 2; // Anti-snipe timer
public static int ClaimExpirationDays = 20; // Days before unclaimed deleted
public static double MinBidIncrementPercent = 0.05; // 5% minimum bid increase
// =========================================
// Auction Logging
// =========================================
public static boolean AuctionLoggingEnabled = false;
public static boolean LogAuctionCreated = true;
public static boolean LogAuctionBid = true;
public static boolean LogAuctionBuyout = true;
public static boolean LogAuctionSold = true;
public static boolean LogAuctionExpired = true;
public static boolean LogAuctionCancelled = true;
public static boolean LogAuctionClaimed = true;
// =========================================
// Auction Blacklist (Market.Auction.Blacklist)
// =========================================
public static boolean BlacklistEnabled = true;
public static String[] BlacklistedItems = {}; // Registry names (supports wildcards)
public static String[] BlacklistedMods = {}; // Mod IDs to block entirely
public static String[] BlacklistedNBTTags = {}; // NBT tag keys to block
```
### Auction Permissions
| Permission | Description |
|------------|-------------|
| `customnpcs.auction.trades.*` | Unlimited trade slots (up to 45) |
| `customnpcs.auction.trades.X` | Exactly X trade slots (where X is 1-45) |
| `customnpcs.auction.blacklist.bypass` | Bypass item blacklist restrictions |
**Trade Slot Permissions:**
- Default is 8 trade slots
- Permissions only **increase** the limit (permissions below 8 are ignored)
- Maximum is capped at 45 (9x5 grid)
- Trade slots = Active Listings + Active Bids + Pending Claims
**Blacklist Bypass:**
- OP players or those with `customnpcs.auction.blacklist.bypass` can list blacklisted items
- Soulbound and Profile-Slotbound items are **always** blocked (no bypass)
---
## 7. Commands
### `/cnpc auction` Command
Allows interaction with the Auction House without needing an Auctioneer NPC.
| Subcommand | Usage | Permission | Description |
|------------|-------|------------|-------------|
| `list` | `/cnpc auction list [page]` | OP | View active auctions in chat |
| `view` | `/cnpc auction view <player>` | OP | View a player's auction activity |
| `open` | `/cnpc auction open` | Any | Opens the Auction House GUI |
**Examples:**
```
/cnpc auction list - Show first page of active auctions
/cnpc auction list 2 - Show page 2 of auctions
/cnpc auction view Steve - Show Steve's listings, bids, and claims
/cnpc auction open - Open the full Auction House GUI
```
### `/cnpc auction blacklist` Command
Manage the auction item blacklist (runtime changes, not persisted to config).
| Subcommand | Usage | Permission | Description |
|------------|-------|------------|-------------|
| `add` | `/cnpc auction blacklist add <item\|mod\|nbt> <value>` | OP | Add to blacklist |
| `remove` | `/cnpc auction blacklist remove <item\|mod\|nbt> <value>` | OP | Remove from blacklist |
| `list` | `/cnpc auction blacklist list [item\|mod\|nbt]` | OP | List blacklisted entries |
| `reload` | `/cnpc auction blacklist reload` | OP | Reload from config |
| `check` | `/cnpc auction blacklist check` | Any | Check if held item is blacklisted |
**Examples:**
```
/cnpc auction blacklist add item minecraft:diamond_sword
/cnpc auction blacklist add item minecraft:diamond* (wildcard)
/cnpc auction blacklist add mod industrialcraft2
/cnpc auction blacklist add nbt ench
/cnpc auction blacklist remove item minecraft:diamond_sword
/cnpc auction blacklist list item
/cnpc auction blacklist check (checks held item)
```
---
## 8. Implementation Status
### Phase 1: Currency System - COMPLETE ✅
### Phase 2: Trader Enhancements - COMPLETE ✅
### Phase 3: Auction Core - COMPLETE ✅
### Phase 4: Auction GUI - COMPLETE ✅
### Phase 5: Auction Network - COMPLETE ✅
### Phase 6: Performance & Safety - COMPLETE ✅
1. ~~Threading model with ReentrantReadWriteLock~~
2. ~~Player indices for O(1) lookups~~
3. ~~20-second update cycle~~
4. ~~Async saves on CNPC+ thread~~
5. ~~Race condition prevention~~
6. ~~Server shutdown handling~~
7. ~~Own listing view (buttons hidden)~~
8. ~~Server-side security checks~~
### Remaining Work
- [ ] **GuiManageAuction (Admin GUI)** - Admin interface to view all auctions, cancel listings, manage claims
- [ ] Additional testing
### Implemented Since Initial Plan
- [x] **`/auction` Command** - Console/player command with subcommands:
- `/auction list [page]` - View active auctions from command line
- `/auction view <player>` - View a player's auction activity (listings, bids, claims)
- `/auction open` - Open Auction House GUI without needing an Auctioneer NPC
- [x] **Permission system integration** - Per-player trade slot limits via `customnpcs.auction.trades.X` permissions
- Default: 8 trade slots
- Maximum: 45 (9x5 grid)
- Synced to client when viewing My Trades
- Cached on login for performance
- [x] **Minimum Listing Price** - Configurable minimum starting price (default: 1)
- [x] **Buyout enabled by default** - Buyout toggle is ON by default when creating listings
- [x] **Search by seller** - Filter can now search by item name OR seller name
- [x] **Rebid prevention** - Players cannot rebid on auctions where they're already the highest bidder
- [x] **Buyout price difference** - When buying out an auction you're bidding on, only pay the difference
- [x] **Immediate claim cleanup** - Claims are removed from storage immediately when claimed
- [x] **Listing cleanup** - Ended listings are removed when all related claims are processed
- [x] **Live notifications** - Notifications sent immediately to online players instead of queued
- [x] **Login claim summary** - Shows detailed claim summary on login (X items and Y currency to claim)
- [x] **PlayerTradeData** - Merged currency + claims into single class (shared across profiles)
- [x] **No locking system** - Pure ConcurrentHashMap for better performance
- [x] **30-second intervals** - Combined process/save cycle for simplicity
- [x] **Async offline player claims** - Claims added to offline players via CNPC+ thread
- [x] **Claim migration** - Old claims in auction.dat automatically migrated to PlayerData
- [x] **Item Blacklist System** - Block items by registry name, mod, NBT tag, or wildcard pattern
- Auto-blocks Soulbound and Profile-Slotbound items (checks `RPGCore/Requirements`)
- Per-player bypass via `customnpcs.auction.blacklist.bypass` permission
- Runtime add/remove commands (not persisted to config)
- Check command to test held item
---
## 9. Design Decisions
| Decision | Choice | Rationale |
|----------|--------|-----------|
| Claims Storage | In PlayerData, not auction.dat | Claims persist with player, reduces auction.dat size, allows offline claim addition |
| Thread Safety | ConcurrentHashMap (no locks) | Minecraft is single-threaded for gameplay; locks add overhead without benefit |
| Vault Integration | Via PlayerCurrencyData | Single point of delegation, reused by Trader & Auction |
| Update Interval | 30 seconds | Performance vs responsiveness tradeoff |
| Player Indices | ConcurrentHashMap + Sets | O(1) lookups, thread-safe |
| Async Saves | CNPC+ Thread | Doesn't block server tick |
| Offline Claims | Load PlayerData async, add claim, save | Claims can be added to offline players without blocking |
| Config Sync | LoginPacket → AuctionClientConfig | Client never accesses server config directly |
| Item Blacklist | Static utility class | Simple, fast checks without instantiation; auto-blocks bound items |
| Bound Item Detection | Check `RPGCore/Requirements` NBT path | Uses AttributeItemUtil constants for consistency |
---
## 10. Future Considerations (Not in 1.11)
- Category-based filtering (by item type, mod, etc.)
- Auction history/statistics tracking
- Auction house tax sink (currency removed from economy)
- Reserve prices (hidden minimum price)
- Private auctions (invite-only)
- Watchlist/favorites system
- Price history graphs
+144
View File
@@ -0,0 +1,144 @@
# CNPC+ 1.11 Ability System Beta
🟡 **In Testing**
## Features: ⚒️
- **Phase-Based Execution:**
> All abilities follow a Wind-up → Active → Completion flow. Wind-up lets players react, Active deals the effect.
- **Melee Abilities:**
> - **Slam** - Leap and AOE on impact.
> - **Heavy Hit** - Single powerful strike with bonus knockback.
> - **Cutter** - Slashing cone arc attack.
> - **Shockwave** - AOE burst radiating from the caster.
- **Energy Orbs:**
> - **Orb** - Homing energy sphere.
> - **Dual Orb** - Two simultaneous homing orbs.
> - **Orb Barrage** - Rapid volley of orbs in sequence.
- **Energy Discs:**
> - **Disc** - Spinning flat projectile with optional boomerang.
> - **Dual Disc** - Two simultaneous discs.
- **Energy Beams:**
> - **Beam** - Sustained homing beam from caster to target.
> - **Dual Beam** - Two simultaneous beams.
- **Laser Shot:**
> Instant-fire projectile with no homing. Pure aim.
- **Projectile:**
> Standard projectile using classic Minecraft physics.
- **Movement Abilities:**
> - **Charge** - Rush forward in a line, damaging everything in path.
> - **Dash** - Quick directional movement without damage.
> - **Teleport** - Instant relocation to the target.
- **AOE Abilities:**
> - **Sweeper** - Wide rotational sweep around the caster.
> - **Vortex** - Pulls entities inward while dealing damage.
- **Telegraph System:**
> Visual ground indicators during wind-up. Supports Circle, Ring, Line, Cone, and Point shapes with color customization and warning phase transitions.
- **Energy Projectile Customization:**
> Modular data system for all energy projectiles: Anchor Point, Display Colors, Homing, Combat Stats, and Lifespan.
- **Ability Effects:**
> Abilities can apply potion effects on hit: Slowness, Weakness, Poison, Wither, Blindness, Nausea, Hunger, Mining Fatigue.
- **Ability Conditions:**
> Condition system controlling when abilities can execute based on target state and custom predicates.
- **Interruptible Wind-ups:**
> Abilities can be interrupted by damage during wind-up, forcing a configurable Dazed recovery state.
- **Movement & Rotation Locking:**
> Lock caster movement, rotation, or both during Wind-up, Active, or both phases.
- **Animation & Sound Integration:**
> Wind-up and Active animations with optional duration sync. Custom sound events per phase.
- **Player Abilities:**
> Players can unlock abilities, select one at a time, and share a universal cooldown.
- **Ability Preview:**
> Live preview in the ability editor GUI. Test telegraphs, animations, and projectiles on a dummy NPC.
- **Scripting API:**
> Full event support: Start, Execute, Interrupt, Complete, Hit (modifiable damage/knockback), and Tick events. Start, Execute, and Hit are cancelable.
- **Ability Commands:**
> `/kam ability list`, `types`, `info`, `delete`, `reload` for managing custom abilities.
**Extras**
- Global ability presets that update everywhere when edited.
- Weighted ability selection for NPC random usage.
- Configurable min/max range per ability.
- Reusable telegraph presets shared across abilities.
+199
View File
@@ -0,0 +1,199 @@
# ⚔️ CustomNPC+ 1.11 - Abilities ⚔️
---
The **Ability Update** introduces a full combat ability system to CNPC+! Give your NPCs powerful attacks with **visual telegraphs**, launch **energy projectiles** that home in on targets, and let players unlock abilities of their own!
---
## How Abilities Work 🎯
Every ability follows a **phase-based execution flow** that gives combat a readable, strategic feel.
**Phases:**
- **Wind-up** - The ability charges. Telegraphs appear, animations play, and observant players can react
- **Active** - The ability fires. Damage is dealt, projectiles launch, effects apply
- **Dazed** - Optional recovery state if the ability is interrupted during wind-up
**Core Configuration:**
- **Cooldown** - Time before the ability can be used again
- **Targeting Mode** - Aggro Target, Self, AOE on Self, or AOE on Target
- **Range** - Configurable min and max range for activation
- **Lock Movement** - Lock the caster's movement, rotation, or both during any phase
- **Interruptible** - Allow damage to interrupt wind-up and force a dazed state
- **Weight** - Priority weighting for NPC random ability selection
> Abilities support both **inline configuration** on individual NPCs and **global presets** that update everywhere when edited.
---
## Melee Abilities 🗡️
Close-range attacks that hit hard and punish positioning.
- **Slam** - Leap toward the target in an arc, dealing AOE damage on impact. Configurable radius, knockback, and leap height
- **Heavy Hit** - A single powerful melee strike with bonus knockback
- **Cutter** - A slashing arc attack in a cone. Configurable angle and reach
- **Shockwave** - An AOE burst radiating outward from the caster
> All melee abilities support configurable **damage**, **knockback**, and **potion effects** on hit.
---
## Energy Projectiles ✨
A brand new projectile system built from the ground up with full visual customization.
### Orbs
Homing energy spheres that track their target through the air.
- **Orb** - A single homing projectile
- **Dual Orb** - Fires two orbs simultaneously
- **Orb Barrage** - Fires a volley of orbs in rapid sequence
### Discs
Flat spinning projectiles with optional **boomerang** behavior.
- **Disc** - A single spinning disc with configurable radius and thickness
- **Dual Disc** - Fires two discs simultaneously
### Beams
Sustained energy beams that connect the caster to their target.
- **Beam** - A homing beam with configurable width and head size. Locks the caster in place during channeling
- **Dual Beam** - Fires two beams simultaneously
### Laser Shot
An **instant-fire** projectile with configurable width and speed. No homing — pure aim.
### Projectile
A standard projectile using classic Minecraft physics for a more traditional ranged attack.
### Energy Configuration
Every energy projectile shares a **modular data system** for deep customization:
- **Anchor Point** - Choose where the projectile spawns: Right Hand, Left Hand, Front, Center, Chest, or Above Head
- **Display** - Set core color, edge color, glow effect, transparency, and size
- **Homing** - Toggle homing, adjust turn rate and max tracking range
- **Combat** - Damage, knockback, vertical knockback, hit cooldown, and optional AOE splash
- **Lifespan** - Projectile speed, max age, and max travel distance
---
## Movement Abilities 💨
Abilities that reposition the caster in combat.
- **Charge** - Rush forward in a line, damaging all entities in the path. Configurable speed, hit width, and knockback
- **Dash** - A quick directional movement without dealing damage
- **Teleport** - Instantly relocate to the target's position
> **Charge** locks direction during wind-up, so the telegraph accurately shows the attack path.
---
## AOE Abilities 🌀
Area control abilities that dominate space.
- **Sweeper** - A wide rotational sweep attack around the caster with configurable radius and rotation speed
- **Vortex** - Creates a pulling force that drags nearby entities toward the center while dealing damage
---
## Telegraph System 📍
**Telegraphs** are visual ground indicators that warn players before an ability lands. They appear during the wind-up phase and disappear when the ability fires.
**Shapes:**
- **Circle** - Filled circle with configurable radius
- **Ring** - Donut shape with inner and outer radius
- **Line** - Rectangle along the attack direction
- **Cone** - Fan/wedge shape with configurable angle
- **Point** - Single point indicator
**Features:**
- **Color Customization** - Set ARGB colors for both the telegraph and its warning phase
- **Warning Phase** - Color shifts in the final ticks before the ability fires
- **Entity Tracking** - Telegraphs can follow a moving entity or stay at a fixed position
- **Smooth Interpolation** - Position updates are interpolated for clean visuals
> Telegraphs are saved as **reusable presets** and can be shared across multiple abilities.
---
## Animations & Sound 🎬
Abilities integrate directly with the animation and sound systems.
- **Wind-up Animation** - Plays during the charging phase
- **Active Animation** - Plays when the ability fires
- **Animation Sync** - Optionally sync wind-up duration to match animation length exactly
- **Sound Events** - Assign custom sounds to both wind-up and active phases
- **Phase Colors** - Visual color feedback on the caster during wind-up and active
> Many ability types include **built-in animation names** that work automatically when matching animations exist.
---
## Effects & Conditions ⚡
### Potion Effects
Abilities can apply **potion effects** to any entity they hit. Each effect has configurable type, duration, and amplifier.
**Available Effects:**
Slowness, Weakness, Poison, Wither, Blindness, Nausea, Hunger, Mining Fatigue
### Conditions
Abilities support a **condition system** that controls when they can be used. Conditions are evaluated before execution and can require specific target states, ranges, or custom predicates.
---
## Player Abilities 🧑
Players can unlock and use abilities too!
- **Unlock System** - Players receive abilities via scripting or commands
- **Ability Selection** - Choose one ability at a time from your unlocked list
- **Universal Cooldown** - Shared cooldown across all player abilities
---
## Scripting API 📜
Full scripting support for ability lifecycle events:
- **StartEvent** *(Cancelable)* - Fired when wind-up begins
- **ExecuteEvent** *(Cancelable)* - Fired when the ability activates
- **InterruptEvent** - Fired when wind-up is interrupted by damage
- **CompleteEvent** - Fired when the ability finishes
- **HitEvent** *(Cancelable)* - Fired on each entity hit. Damage and knockback values can be modified
- **TickEvent** - Fired every tick with current phase and tick count
> Scripts can cancel, modify damage, and react to every phase of ability execution.
---
## Ability Preview 🔎
The ability editor includes a **live preview system**. Test your telegraph shapes, animations, and projectile visuals directly in the GUI on a dummy NPC — no world effects applied.
---
## Ability Commands 💬
- `/kam ability list` - List all custom abilities
- `/kam ability types` - List all registered ability types
- `/kam ability info <name|uuid>` - View ability details
- `/kam ability delete <uuid>` - Delete a custom ability
- `/kam ability reload` - Reload abilities from disk
---
-301
View File
@@ -1,301 +0,0 @@
# Ability System Review - CustomNPC+
A comprehensive technical review of the Ability System identifying bugs, logic issues, incomplete features, and inconsistencies.
---
## Critical Issues
### 1. Cooldown Uses Mixed Time Systems
**Status:** FIXED
**Files:**
- `Ability.java` - Removed cooldown tracking (cooldownEndTime, startCooldown(), isOnCooldown(), canUse())
- `DataAbilities.java` - Now sole owner of cooldown management using world time
**Solution:** Removed all cooldown tracking from `Ability.java`. Cooldowns are now managed exclusively by `DataAbilities` using `world.getTotalWorldTime()` for consistency.
---
### 2. AbilityHeal - Heal Over Time Completely Broken
**Status:** FIXED
**File:** `AbilityHeal.java`
**Solution:** Refactored to separate ally-finding from healing. The `findAlliesInRadius()` method is now called regardless of `instantHeal` flag, populating the list for HoT to use. Added heal particles during HoT ticks.
---
### 3. AbilityGuard - Counter Integration Missing
**Status:** FIXED
**Files:**
- `DataAbilities.java:onDamage()` - Added integration to call `AbilityGuard.onDamageTaken()`
- `DataAbilities.java:getGuardDamageReduction()` - Added helper method for damage reduction
**Solution:** `DataAbilities.onDamage()` now checks if current ability is an `AbilityGuard` and calls `onDamageTaken()` when the NPC is hit while guarding.
---
## High Priority Issues
### 4. knockbackUp Stored But Never Applied
**Status:** FIXED
**File:** `Ability.java`
**Solution:** Updated `applyNpcKnockback()` to accept a `knockbackUp` parameter and use it instead of hardcoded `0.1D`. Both `applyAbilityDamage()` and `applyAbilityDamageWithDirection()` now pass the knockbackUp value from the HitEvent.
---
### 5. Targeting Modes Not Implemented
**Status:** FIXED (Removed)
**File:** `TargetingMode.java`
**Solution:** Removed the unused targeting modes (`RANDOM_ENEMY`, `LOWEST_HP`, `HIGHEST_THREAT`) from the enum. Only the implemented modes remain: `AGGRO_TARGET`, `SELF`, `AOE_SELF`, `AOE_TARGET`.
---
### 6. Damage Source Inconsistency
**Status:** FIXED
**File:** `Ability.java`
**Solution:** Standardized both `applyAbilityDamage()` and `applyAbilityDamageWithDirection()` to use `NpcDamageSource("mob", npc)` for consistent damage source handling.
---
## Incomplete Features
### 7. AbilityProjectile - No Actual Projectile
**Status:** CONFIRMED - INCOMPLETE
**File:** `AbilityProjectile.java:88`
```java
// TODO: Use custom EntityAbilityProjectile for actual tracking
applyAbilityDamageWithDirection(npc, target, damage, knockback, dx, dz);
```
**Current behavior:**
- `speed`, `homing`, `homingStrength` fields exist but are unused
- No projectile entity is spawned
- Damage is instant, just with particle cosmetics
---
### 8. AbilityOrb - No Visual Orb Rendering
**Status:** CONFIRMED - INCOMPLETE
**File:** `AbilityOrb.java:117-179`
**Problem:** The orb tracks position (`orbX`, `orbY`, `orbZ`) with runtime getters but nothing renders it client-side. Players only see particle effects on hit, not the flying orb itself.
---
### 9. AbilityBeam - No Visual Beam Rendering
**Status:** CONFIRMED - INCOMPLETE
**File:** `AbilityBeam.java:213-220`
**Problem:** Only spawns flame particles along the path. No actual beam entity or proper beam visual. The `lockOnTarget` telegraph during active phase isn't visually communicated.
---
## Medium Priority Issues
### 10. Hazard/Trap Telegraph Offset Mismatch
**Status:** CONFIRMED
**Files:**
- `AbilityHazard.java:119-147, 201-248`
- `AbilityTrap.java:109-138, 166-205`
**Problem:** Telegraph is created at target position, but actual effect applies random offset:
```java
// createTelegraph() - No offset applied, shows at target position
// onExecute() - Random offset applied AFTER telegraph locks
double[] pos = calculateOffsetPosition(telegraph.getX(), telegraph.getY(), telegraph.getZ());
zoneX = pos[0]; // Actual effect position differs from telegraph
```
**Impact:** Players see telegraph at one location, damage happens elsewhere. Misleading visual feedback.
**Fix:** Either apply offset during telegraph creation, or update telegraph position in `onExecute()`.
---
### 11. AbilityCharge Telegraph Direction Timing
**Status:** CONFIRMED - MINOR
**File:** `AbilityCharge.java:91, 254-286`
**Problem:** Telegraph created at tick 0, direction locked at tick 1:
```java
// Telegraph created during setup (tick 0) with current target direction
// Line 91: Direction locked at tick 1
if (tick == 1) {
lockChargeDirection(npc, target);
}
```
**Impact:** If target moves between tick 0-1, telegraph direction won't match actual charge.
---
### 12. AbilitySlam - activeTicks May End Before Landing
**Status:** CONFIRMED - MINOR
**File:** `AbilitySlam.java:52-53, 230-250`
**Problem:** `activeTicks = 60` is fixed, but if NPC takes longer to land, ability transitions to RECOVERY without `onLanding()` being called.
**Secondary issue:** If NPC lands early (tick 15), active phase continues until tick 60 doing nothing - wasted ticks.
---
### 13. FOLLOW Mode Telegraph Not Updated
**Status:** CONFIRMED
**Files:** `AbilityHazard.java:139-146`, `AbilityVortex.java`
**Problem:** For `FOLLOW_TARGET` mode, telegraph locks position on execute, but the actual hazard zone follows the target. Visual mismatch between warning and danger.
---
## Redundancies
### 14. Duplicate findGroundLevel() Methods
**Status:** FIXED
**Files:**
- `Ability.java` - Made `findGroundLevel()` public static
- `TelegraphInstance.java` - Now uses `Ability.findGroundLevel()`
---
### 15. Duplicate calculateOffsetPosition() Methods
**Status:** FIXED
**Files:**
- `Ability.java` - Added shared static `calculateOffsetPosition()` method
- `AbilityTrap.java` - Removed duplicate, uses `Ability.calculateOffsetPosition()`
- `AbilityHazard.java` - Removed duplicate, uses `Ability.calculateOffsetPosition()`
---
### 16. Unused applyKnockback in AbilityOrb
**Status:** FIXED
**File:** `AbilityOrb.java`
Removed the unused `applyKnockback()` method.
---
### 17. Duplicate Reset/Interrupt Cleanup
**Status:** NOT FIXED (Low Priority)
**Multiple ability files**
Most abilities override both `reset()` and `onInterrupt()` with duplicate cleanup code. Pattern should have `onInterrupt()` call `reset()` or use shared cleanup method.
---
## Minor Issues & Inconsistencies
### 18. Field Naming Confusion
- `AbilityHazard`: `damagePerSecond` with `damageInterval` - name suggests per-second but applied every N ticks
- `AbilityCharge`: `hitWidth` stored as `hitRadius` in older NBT (backward compat exists)
### 19. AbilityVortex Entity Lookup Performance
**File:** `AbilityVortex.java:201-212`
Iterates through ALL loaded entities every tick to find pulled entities by UUID. Should cache entity references or use entity IDs.
### 20. Telegraph Yaw Rotation
**File:** `TelegraphRenderer.java:95`
Uses `GL11.glRotatef(-instance.getYaw(), 0, 1, 0)` - negative yaw. Should verify this matches Minecraft's yaw conventions.
### 21. Missing Null Checks
Various locations where `target` could be null but is used without defensive checks:
- `AbilityProjectile.java:73`
- `AbilityOrb.java:138-171`
---
## Missing Features (Enhancement Requests)
These are not bugs but notable missing functionality:
1. **No Ability Chaining/Combo System** - No way to trigger abilities from other abilities
2. **No Cooldown Reduction on Hit** - Can't reduce cooldowns based on successful hits
3. **No Multi-Target Hit Limit** - AOE abilities hit unlimited targets (unlike Vortex's `maxTargets`)
4. **No Damage Type Configuration** - All abilities use mob/melee damage, no magic/fire/etc options
5. **No Target Validation During Execution** - If target dies/despawns mid-ability, behavior varies
---
## Priority Summary
| Priority | Issue | Status |
|----------|-------|--------|
| **CRITICAL** | Cooldown time system mismatch | FIXED |
| **CRITICAL** | AbilityHeal HoT broken | FIXED |
| **CRITICAL** | AbilityGuard counter not integrated | FIXED |
| **HIGH** | knockbackUp ignored | FIXED |
| **HIGH** | Targeting modes unimplemented | FIXED (Removed) |
| **HIGH** | Damage source inconsistency | FIXED |
| **MEDIUM** | Projectile/Orb/Beam no visuals | Not Fixed |
| **MEDIUM** | Hazard/Trap telegraph offset | Not Fixed |
| **LOW** | Charge telegraph timing | Not Fixed |
| **LOW** | Slam activeTicks timing | Not Fixed |
| **LOW** | Code redundancies | FIXED |
---
## Remaining Issues
The following issues were not addressed in this fix round:
1. **Projectile/Orb/Beam Visual Rendering** - These abilities still only use particles, no actual entity rendering
2. **Hazard/Trap Telegraph Offset Mismatch** - Telegraph shows at target, effect spawns with offset
3. **Charge Telegraph Direction Timing** - Minor visual mismatch between tick 0-1
4. **Slam activeTicks Timing** - Fixed at 60 ticks regardless of landing time
---
## Changes Made
### Ability.java
- Removed `cooldownEndTime` transient field
- Removed `startCooldown()`, `isOnCooldown()`, `canUse()` methods (cooldown managed by DataAbilities)
- Updated `tick()` to not call startCooldown (DataAbilities handles it)
- Updated `reset()` to not reset cooldownEndTime
- Made `findGroundLevel()` public static for shared use
- Added static `calculateOffsetPosition()` utility method
- Fixed `applyNpcKnockback()` to accept and use knockbackUp parameter
- Standardized damage source to `NpcDamageSource("mob", npc)` in both damage methods
- Removed deprecated getters/setters (telegraphColor, castSound, animationId)
### IAbility.java (API)
- Removed `isOnCooldown()` method from interface
### DataAbilities.java
- Added AbilityGuard import
- Added guard counter integration in `onDamage()`
- Added `getGuardDamageReduction()` helper method
- Removed deprecated `isMovementBlocked()` method
- Updated knockbackUp javadoc (no longer deprecated)
### CombatHandler.java
- Renamed `isMovementBlocked()` to `isAbilityControllingMovement()`
### TargetingMode.java
- Removed unused modes: `RANDOM_ENEMY`, `LOWEST_HP`, `HIGHEST_THREAT`
### AbilityHeal.java
- Fixed HoT by separating `findAlliesInRadius()` from healing logic
- Allies are now found in `onExecute()` regardless of instantHeal flag
- Added heal particles during HoT ticks
### AbilityHazard.java
- Removed duplicate `calculateOffsetPosition()`, uses `Ability.calculateOffsetPosition()`
- Removed deprecated `getDamagePerTick()`/`setDamagePerTick()` methods
### AbilityTrap.java
- Removed duplicate `calculateOffsetPosition()`, uses `Ability.calculateOffsetPosition()`
### AbilityOrb.java
- Removed unused `applyKnockback()` method
### TelegraphInstance.java
- Removed duplicate `findGroundLevel()`, uses `Ability.findGroundLevel()`
+57
View File
@@ -0,0 +1,57 @@
# CNPC+ 1.11 Beta - Market Update
🟡 **In Testing**
## Features: ⚒️
- **Built-in Currency System:**
> Fully configurable economy currency used across all Market features. Profile persistent across character slots with Vault support for Bukkit-compatible plugins.
- **Auction House:**
> Global player marketplace for listing items, bidding, and instant buyouts. Auctions last 24 hours by default.
- **Auction Bidding & Snipe Protection:**
> Competitive bidding with a 5% minimum bid increment. Snipe Protection extends auctions on last-second bids. Outbid players are automatically refunded.
- **Buyout System:**
> Instant purchase at the seller's Buyout Price. Highest bidder only pays the difference between their bid and the buyout.
- **My Trades:**
> Single screen for managing Active Listings, Active Bids, and Pending Claims. Players can cancel listings with a 10% penalty if bids exist.
- **Auction Notifications:**
> Real-time notifications for sales, outbids, and wins. Offline players receive a claim summary on login.
- **Trade Slots:**
> Limited slots (default 8, max 45) shared across listings, bids, and claims. Configurable via permissions.
- **Claim Expiration:**
> Uncollected claims expire after 20 days.
- **Item Blacklist:**
> Block items by registry name, wildcard pattern, mod, or NBT tag. Soulbound and Profile-Slotbound items are always blocked automatically.
- **Listing Fee & Sales Tax:**
> Configurable listing fee charged on creation and sales tax taken from successful sales.
- **Search & Sorting:**
> Search by item name or seller. Sort by newest, ending soon, price, or most bids.
- **Trader Stock System:**
> Limited stock with Global or Per-Player modes. Restock timers for MC Daily/Weekly, RL Daily/Weekly, or Custom intervals.
- **Trader Currency Trades:**
> Trades can require currency on top of item costs.
- **Auctioneer NPC Role:**
> New role that opens the Auction House on interaction. No configuration needed.
- **Auction Commands:**
> `/kam auction open` for players. Admin commands for listing view and player activity inspection.
**Extras**
- Auction logging for server admins (tracks creates, bids, buyouts, sales, expirations, cancellations, claims).
- Lifetime currency tracking per player (total earned and spent).
- Configurable starting balance and max balance cap.
- Blacklist bypass permission for admins.
+17 -23
View File
@@ -10,9 +10,10 @@ The **Market Update** brings a complete economy system to CNPC+! Create bustling
CNPC+ now has a **built-in currency** used across all Market features!
- **Fully Configurable** - Name it Coins, Gold, Credits, whatever fits your world
- **Fully Configurable** - Name it Coins, Gold, Credits, whatever fits your world. Set a starting balance and max balance cap to shape your economy
- **Profile Persistent** - Currency carries across all your character slots
- **Vault Support** - CNPC+ integrates seamlessly with Bukkit-compatible economy plugins if Vault is installed
- **Vault Support** - Integrates seamlessly with Bukkit-compatible economy plugins if Vault is installed. Falls back to built-in currency otherwise
- **Lifetime Tracking** - Tracks total earned and spent per player
> Full Scripting API support for currency operations on players.
@@ -20,17 +21,17 @@ CNPC+ now has a **built-in currency** used across all Market features!
## Auction House 🏛️
A **global player marketplace** where players can list items, bid against each other, and purchase instantly!
A **global player marketplace** where players can list items, bid against each other, and purchase instantly! Search for items by name or seller, and sort by newest, ending soon, price, or most bids.
### Selling
List any item with a **Starting Price** for competitive bidding. Set an optional **Buyout Price** for players who want to skip the wait and buy immediately.
List any item with a **Starting Price** for competitive bidding. Set an optional **Buyout Price** for players who want to skip the wait and buy immediately. Auctions last **24 hours** by default.
> A configurable **Listing Fee** is charged when creating auctions, and a **Sales Tax** is taken from successful sales.
### Bidding
Compete for items by placing bids! **Snipe Protection** extends auctions when last-second bids come in, giving everyone a fair shot. If you get outbid, your currency is **automatically refunded**.
Compete for items by placing bids! Each bid must be at least **5%** higher than the current bid. **Snipe Protection** extends auctions when last-second bids come in, giving everyone a fair shot. If you get outbid, your currency is **automatically refunded**.
### Buyout
@@ -44,7 +45,9 @@ One screen to manage all your auction activity:
- **Active Bids** - Auctions you're competing in
- **Ready to Claim** - Won items and currency waiting for pickup
> Players can **cancel** their own listings. Items are returned as a claim.
Players can **cancel** their own listings -- items are returned as a claim. If there are active bids on the listing, a **10% cancellation penalty** is charged.
> Claims expire after **20 days**. Make sure to collect your items and currency before they're gone!
### Notifications
@@ -52,7 +55,7 @@ Get notified immediately when your item sells, when you're outbid, or when you w
### Trade Slots
Each player has a limited number of **Trade Slots** (default 8). Trade Slots are shared between Active Listings, Active Bids, and Pending Claims.
Every player gets a limited number of **Trade Slots** (default 8). Slots are shared across Active Listings, Active Bids, **and** Pending Claims -- so uncollected claims take up space. Pick up your claims to free slots for new listings and bids!
> Server owners can grant players more slots via permissions up to a maximum of 45.
@@ -68,14 +71,9 @@ Server owners have full control over what items can be listed on the Auction Hou
- **Mod** - Block all items from a specific mod
- **NBT Tag** - Block items containing certain NBT data
> **Soulbound** and **Profile-Slotbound** items are always blocked automatically. Bound items cannot be traded!
> **Soulbound** and **Profile-Slotbound** items are always blocked automatically, regardless of blacklist settings. Bound items cannot be traded!
**Blacklist Commands:**
- `/kam auction blacklist add <item|mod|nbt> <value>` - Add entry
- `/kam auction blacklist remove <item|mod|nbt> <value>` - Remove entry
- `/kam auction blacklist list` - View all blacklisted entries
- `/kam auction blacklist check` - Check if your held item is blacklisted
- `/kam auction blacklist reload` - Reload from config
Manage the blacklist in-game with `/kam auction blacklist` commands, or configure it directly in the config file.
---
@@ -94,14 +92,10 @@ Traders now support **limited stock** with automatic restocking!
- **RL Daily / Weekly** - Restock based on real-life time
- **Custom** - Set your own interval in MC ticks or real-time
**Visual Feedback:**
- Stock count displayed next to each trade
- **Out of Stock** overlay when unavailable
- Live **countdown timer** until next restock
Stock counts, out-of-stock status, and restock timers are all visible directly in the trade interface.
> Admins can manually reset stock or cooldowns via the Trader GUI.
### Currency Trades
Trades can now require **currency on top of items**. Combine material costs with coin costs for balanced economy progression!
@@ -110,10 +104,9 @@ Trades can now require **currency on top of items**. Combine material costs with
## Auctioneer Role 🧑‍💼
New NPC role for the Auction House! Set the role on any NPC and players can access the full Auction House by interacting with them.
> No configuration needed
New NPC role for the Auction House! Set the role on any NPC and players can access the full Auction House by interacting with them -- no extra configuration needed. The role respects the global Auction Enabled setting.
### Auction Command
### Auction Commands
Players can also access the Auction House via command:
@@ -123,5 +116,6 @@ Players can also access the Auction House via command:
- `/kam auction list [page]` - View active auctions in chat
- `/kam auction view <player>` - View a player's auction activity
---
> Server owners can enable **auction logging** to track all auction activity (creates, bids, buyouts, sales, expirations, cancellations, and claims).
---
Binary file not shown.

Before

Width:  |  Height:  |  Size: 884 KiB