Auction and Currency API

This commit is contained in:
Kam committed 2026-01-24 15:11:38 -05:00
1 parent c8a2fb9824
commit 2e5d86993c
6 files changed
+383 -4

No files matched your search

+7
View File
@@ -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).
@@ -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();
}
@@ -26,7 +26,7 @@ public interface IPlayerData {
IPlayerMailData getMailData();
IPlayerCurrencyData getCurrencyData();
IPlayerTradeData getTradeData();
void save();
}
@@ -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);
}
@@ -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();
}
@@ -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();
}