From 2e5d86993cd47e6df4572323514d4fe2166c570c Mon Sep 17 00:00:00 2001 From: Kam Date: Sat, 24 Jan 2026 15:11:38 -0500 Subject: [PATCH] Auction and Currency API --- java/noppes/npcs/api/AbstractNpcAPI.java | 7 + .../npcs/api/handler/IAuctionHandler.java | 129 ++++++++++++++++++ java/noppes/npcs/api/handler/IPlayerData.java | 2 +- ...urrencyData.java => IPlayerTradeData.java} | 30 +++- .../npcs/api/handler/data/IAuctionClaim.java | 99 ++++++++++++++ .../api/handler/data/IAuctionListing.java | 120 ++++++++++++++++ 6 files changed, 383 insertions(+), 4 deletions(-) create mode 100644 java/noppes/npcs/api/handler/IAuctionHandler.java rename java/noppes/npcs/api/handler/{IPlayerCurrencyData.java => IPlayerTradeData.java} (66%) create mode 100644 java/noppes/npcs/api/handler/data/IAuctionClaim.java create mode 100644 java/noppes/npcs/api/handler/data/IAuctionListing.java diff --git a/java/noppes/npcs/api/AbstractNpcAPI.java b/java/noppes/npcs/api/AbstractNpcAPI.java index f5dab48..585ccf2 100644 --- a/java/noppes/npcs/api/AbstractNpcAPI.java +++ b/java/noppes/npcs/api/AbstractNpcAPI.java @@ -19,6 +19,7 @@ import noppes.npcs.api.gui.ICustomGui; import noppes.npcs.api.handler.IAbilityHandler; import noppes.npcs.api.handler.IActionManager; import noppes.npcs.api.handler.IAnimationHandler; +import noppes.npcs.api.handler.IAuctionHandler; import noppes.npcs.api.handler.ICloneHandler; import noppes.npcs.api.handler.ICustomEffectHandler; import noppes.npcs.api.handler.IDialogHandler; @@ -180,6 +181,12 @@ public abstract class AbstractNpcAPI { public abstract ITelegraphHandler getTelegraphs(); + /** + * Get the auction handler for managing auctions via scripts. + * @return The auction handler, or null if auctions are disabled + */ + public abstract IAuctionHandler getAuctions(); + /** * Create a telegraph directly. * Convenience method equivalent to getTelegraphs().create(type). diff --git a/java/noppes/npcs/api/handler/IAuctionHandler.java b/java/noppes/npcs/api/handler/IAuctionHandler.java new file mode 100644 index 0000000..eaf8816 --- /dev/null +++ b/java/noppes/npcs/api/handler/IAuctionHandler.java @@ -0,0 +1,129 @@ +package noppes.npcs.api.handler; + +import noppes.npcs.api.entity.IPlayer; +import noppes.npcs.api.handler.data.IAuctionListing; +import noppes.npcs.api.item.IItemStack; + +/** + * Handler for the Auction system. + * Access via API.getAuctions() + */ +public interface IAuctionHandler { + + /** + * Check if the auction system is enabled. + */ + boolean isEnabled(); + + /** + * Get all active listings. + */ + IAuctionListing[] getActiveListings(); + + /** + * Get a specific listing by ID. + * @param listingId The listing ID + * @return The listing, or null if not found + */ + IAuctionListing getListing(String listingId); + + /** + * Get all active listings by a specific seller. + * @param sellerUUID The seller's UUID as a string + */ + IAuctionListing[] getListingsBySeller(String sellerUUID); + + /** + * Get all listings where a player is the current high bidder. + * @param bidderUUID The bidder's UUID as a string + */ + IAuctionListing[] getListingsByBidder(String bidderUUID); + + /** + * Get total count of active listings. + */ + int getActiveListingCount(); + + /** + * Create a new listing. + * @param player The seller + * @param item The item to sell + * @param startingPrice The starting bid price + * @param buyoutPrice The buyout price (0 for no buyout) + * @return The created listing, or null if failed + */ + IAuctionListing createListing(IPlayer player, IItemStack item, long startingPrice, long buyoutPrice); + + /** + * Place a bid on a listing. + * @param listingId The listing ID + * @param player The bidder + * @param amount The bid amount + * @return null on success, error message on failure + */ + String placeBid(String listingId, IPlayer player, long amount); + + /** + * Buyout a listing instantly. + * @param listingId The listing ID + * @param player The buyer + * @return null on success, error message on failure + */ + String buyout(String listingId, IPlayer player); + + /** + * Cancel a listing (seller only, unless admin). + * @param listingId The listing ID + * @param player The player cancelling + * @param isAdmin Whether to bypass ownership check + * @return null on success, error message on failure + */ + String cancelListing(String listingId, IPlayer player, boolean isAdmin); + + /** + * Get the listing fee amount. + */ + long getListingFee(); + + /** + * Get the sales tax percentage (0.0 to 1.0). + */ + double getSalesTaxPercent(); + + /** + * Get the minimum bid increment percentage (0.0 to 1.0). + */ + double getMinBidIncrementPercent(); + + /** + * Get the auction duration in hours. + */ + int getAuctionDurationHours(); + + /** + * Get the snipe protection time in minutes. + */ + int getSnipeProtectionMinutes(); + + /** + * Get the currency name used by the auction system. + */ + String getCurrencyName(); + + /** + * Get the minimum listing price. + */ + long getMinimumListingPrice(); + + /** + * Search listings by item name or seller name. + * @param searchText The search text + * @return Matching active listings + */ + IAuctionListing[] searchListings(String searchText); + + /** + * Force save auction data. + */ + void save(); +} diff --git a/java/noppes/npcs/api/handler/IPlayerData.java b/java/noppes/npcs/api/handler/IPlayerData.java index 9382a69..5118815 100644 --- a/java/noppes/npcs/api/handler/IPlayerData.java +++ b/java/noppes/npcs/api/handler/IPlayerData.java @@ -26,7 +26,7 @@ public interface IPlayerData { IPlayerMailData getMailData(); - IPlayerCurrencyData getCurrencyData(); + IPlayerTradeData getTradeData(); void save(); } diff --git a/java/noppes/npcs/api/handler/IPlayerCurrencyData.java b/java/noppes/npcs/api/handler/IPlayerTradeData.java similarity index 66% rename from java/noppes/npcs/api/handler/IPlayerCurrencyData.java rename to java/noppes/npcs/api/handler/IPlayerTradeData.java index 0b9c84b..a9b560c 100644 --- a/java/noppes/npcs/api/handler/IPlayerCurrencyData.java +++ b/java/noppes/npcs/api/handler/IPlayerTradeData.java @@ -1,11 +1,13 @@ package noppes.npcs.api.handler; +import noppes.npcs.api.handler.data.IAuctionClaim; + /** - * Interface for player currency data. - * Note: If Vault integration is enabled in config, these operations + * Interface for player trade data (currency and auction claims). + * Note: If Vault integration is enabled in config, currency operations * will use the Vault economy instead of CNPC+ built-in currency. */ -public interface IPlayerCurrencyData { +public interface IPlayerTradeData { /** * Get the current balance @@ -64,4 +66,26 @@ public interface IPlayerCurrencyData { * @return true if Vault is handling currency, false if using CNPC+ built-in */ boolean isUsingVault(); + + /** + * Get the number of pending auction claims + */ + int getClaimCount(); + + /** + * Check if player has any pending auction claims + */ + boolean hasClaims(); + + /** + * Get all pending auction claims for this player. + */ + IAuctionClaim[] getClaims(); + + /** + * Get a specific claim by ID. + * @param claimId The claim ID + * @return The claim, or null if not found + */ + IAuctionClaim getClaim(String claimId); } diff --git a/java/noppes/npcs/api/handler/data/IAuctionClaim.java b/java/noppes/npcs/api/handler/data/IAuctionClaim.java new file mode 100644 index 0000000..8d7c3f1 --- /dev/null +++ b/java/noppes/npcs/api/handler/data/IAuctionClaim.java @@ -0,0 +1,99 @@ +package noppes.npcs.api.handler.data; + +import noppes.npcs.api.item.IItemStack; + +/** + * Represents an auction claim (item or currency to be collected). + */ +public interface IAuctionClaim { + + /** + * Get the unique claim ID. + */ + String getId(); + + /** + * Get the player's UUID who can claim this. + */ + String getPlayerUUID(); + + /** + * Get the player's display name. + */ + String getPlayerName(); + + /** + * Get the related listing ID. + */ + String getListingId(); + + /** + * Get the claim type. + * @return 0 = Item, 1 = Currency (sale proceeds), 2 = Refund (outbid) + */ + int getType(); + + /** + * Check if this is an item claim. + */ + boolean isItemClaim(); + + /** + * Check if this is a currency claim (sale proceeds or refund). + */ + boolean isCurrencyClaim(); + + /** + * Check if this is a refund claim (outbid). + */ + boolean isRefundClaim(); + + /** + * Get the item to claim (for item claims only). + * @return The item, or null for currency claims + */ + IItemStack getItem(); + + /** + * Get the item display name (for currency/refund claims tooltip). + */ + String getItemName(); + + /** + * Get the currency amount (for currency/refund claims). + */ + long getCurrency(); + + /** + * Get the other player's name involved. + * For currency claims: the buyer's name. + * For refund claims: the player who outbid. + */ + String getOtherPlayerName(); + + /** + * Get when this claim was created (Unix timestamp in ms). + */ + long getCreatedTime(); + + /** + * Check if this claim has been claimed. + */ + boolean isClaimed(); + + /** + * Check if this is a returned item (expired/cancelled listing) vs won item. + * Only relevant for item claims. + */ + boolean isReturnedItem(); + + /** + * Get days until this claim expires. + */ + long getDaysUntilExpiration(); + + /** + * Check if this claim has expired. + */ + boolean isExpired(); +} diff --git a/java/noppes/npcs/api/handler/data/IAuctionListing.java b/java/noppes/npcs/api/handler/data/IAuctionListing.java new file mode 100644 index 0000000..65e766e --- /dev/null +++ b/java/noppes/npcs/api/handler/data/IAuctionListing.java @@ -0,0 +1,120 @@ +package noppes.npcs.api.handler.data; + +import noppes.npcs.api.item.IItemStack; + +/** + * Represents an auction listing. + */ +public interface IAuctionListing { + + /** + * Get the unique listing ID. + */ + String getId(); + + /** + * Get the seller's UUID as a string. + */ + String getSellerUUID(); + + /** + * Get the seller's display name. + */ + String getSellerName(); + + /** + * Get the item being sold. + */ + IItemStack getItem(); + + /** + * Get the starting price. + */ + long getStartingPrice(); + + /** + * Get the buyout price (0 if no buyout). + */ + long getBuyoutPrice(); + + /** + * Check if this listing has a buyout option. + */ + boolean hasBuyout(); + + /** + * Get the current highest bid. + */ + long getCurrentBid(); + + /** + * Get the high bidder's UUID as a string (null if no bids). + */ + String getHighBidderUUID(); + + /** + * Get the high bidder's display name (null if no bids). + */ + String getHighBidderName(); + + /** + * Check if there are any bids on this listing. + */ + boolean hasBids(); + + /** + * Get the total number of bids placed. + */ + int getBidCount(); + + /** + * Get when the listing was created (Unix timestamp in ms). + */ + long getCreatedTime(); + + /** + * Get when the auction ends (Unix timestamp in ms). + */ + long getEndTime(); + + /** + * Get the remaining time in milliseconds. + */ + long getRemainingTime(); + + /** + * Check if the auction has expired. + */ + boolean isExpired(); + + /** + * Check if the auction is still active (can be bid on). + */ + boolean isActive(); + + /** + * Get the auction status. + * @return 0 = Active, 1 = Ended, 2 = Cancelled, 3 = Claimed + */ + int getStatus(); + + /** + * Get the minimum bid amount (current bid + increment). + */ + long getMinimumBid(); + + /** + * Check if a player UUID is the seller. + */ + boolean isSeller(String playerUUID); + + /** + * Check if a player UUID is the current high bidder. + */ + boolean isHighBidder(String playerUUID); + + /** + * Get the remaining time formatted as a string (e.g., "2h 30m"). + */ + String getRemainingTimeFormatted(); +}