ZyAuctions API

ZyAuctions exposes a small synchronous API and six events. Between them you can read the whole auction house, create and settle listings on a player's behalf, and hook anything that happens.

The shape of it

if (!ZyAuctions.available()) return;
ZyAuctionsApi auctions = ZyAuctions.get();

// Reads are cheap and safe from any thread.
List<Listing> cheapSwords = auctions.listings(ListingQuery.builder()
        .category(Category.WEAPONS)
        .search("sword")
        .sort(SortOrder.PRICE_LOW)
        .build());

// Anything that moves items or money is main-thread and synchronous.
PurchaseResult result = auctions.buy(player, cheapSwords.getFirst().id());
if (result.successful()) {
    getLogger().info(player.getName() + " paid " + result.pricePaid());
}

Two rules that shape everything

Reads are snapshots. A Listing you are holding never changes. Somebody bidding on it produces a new one; yours still says what it said. If you need current state, look it up again — that is a map read, not a query.

Mutations are main-thread and synchronous. Anything that moves an item or an amount of money completes before it returns, and throws IllegalStateException if you call it from the wrong thread. There is no callback to wait for and no future to unwrap.

Persistence is the only asynchronous part, and it is behind the API — a successful result means the change is live, not that it has reached the disk.

Versioning

The API module is versioned separately from the plugin and follows semver. Breaking changes require a major bump and never land in a patch release; anything on its way out is deprecated for at least two minor releases first, with the replacement named in the Javadoc.

com.zephrynis.zyauctions.api and its subpackages are the API. Everything else in com.zephrynis.zyauctions is internal and will change without warning, whatever its visibility modifier says.