开发者 API

其他插件可以通过 StarAuctionAPI 读取市集上的商品、查询还没寄给玩家的笔数、帮玩家打开市集或星月邮箱，并用四个事件拦截或记录上架、购买、出价与成交。

类	包	用途
`StarAuctionAPI`	`dev.starplugins.auction.api`	入口：读取商品、待寄笔数、打开市集 / 星月邮箱
`AuctionListEvent`	`dev.starplugins.auction.api`	玩家上架前触发，可以取消
`AuctionPurchaseEvent`	`dev.starplugins.auction.api`	玩家购买一口价商品、付款前触发，可以取消
`AuctionBidEvent`	`dev.starplugins.auction.api`	玩家出价、付款前触发，可以取消
`AuctionTradeEvent`	`dev.starplugins.auction.api`	成交后触发
`Listing`	`dev.starplugins.auction.data`	一件商品（只读的 record）

引入

把 StarAuction 的 jar 加进编译依赖（只在编译时使用，不要打包进你的插件），例如 Gradle：

dependencies {
    compileOnly files('libs/StarAuction.jar')   // 资源中心下载的星月市集 jar
}

plugin.yml 加上软依赖，确保星月市集先载入（没装也能正常启动）：

softdepend: [StarAuction]

快速开始

import dev.starplugins.auction.api.StarAuctionAPI;
import dev.starplugins.auction.data.Listing;

if (StarAuctionAPI.ready()) {
    List<Listing> mine = StarAuctionAPI.listings(player.getUniqueId());
    player.sendMessage("你有 " + mine.size() + " 件商品在市集上");
    StarAuctionAPI.open(player);
}

先检查 ready()

星月市集没安装、被停用、授权还没验证通过、或开服后还在载入商品时，ready() 返回 false。这时读取方法返回空列表 / 0，open 返回 false。

StarAuctionAPI

全部都是静态方法。

方法	返回	说明
`ready()`	`boolean`	市集现在能不能用
`active()`	`List<Listing>`	全服所有上架中的商品（跨服时包含所有共用数据库的子服），按最新上架排序
`listings(UUID owner)`	`List<Listing>`	某位玩家上架中的商品
`stashCount(UUID owner)`	`int`	市集还没寄到这位玩家星月邮箱的笔数（物品 + 款项；读取快取，可能稍有延迟，第一次查询时可能是 `0`）。1.1.0 起东西几秒内就会寄出，平常是 `0`；想知道邮箱里还没领的，用星月邮箱的 `StarMailAPI.unclaimed(uuid)`
`open(Player player)`	`boolean`	帮玩家打开市集（能显示时打开云界面市集，否则箱子菜单）。会排到玩家所在的线程执行
`openStash(Player player)`	`boolean`	帮玩家打开星月邮箱（1.1.0 起领取箱由星月邮箱取代；会先把还没寄出的东西再寄一次）

读取方法直接读内存中的市集，不查数据库，可以在任何线程调用、频繁调用。
返回的列表是复制品，修改它不会影响市集。
API 目前不提供「替玩家上架 / 购买」的方法：所有交易都要经过玩家自己的付款与物品检查。
市集寄出的邮件 source 是 starauction：想在玩家领取时做点什么，可以监听星月邮箱的 MailClaimEvent 并检查 source()。

Listing

dev.starplugins.auction.data.Listing 是一个 Java record，以下方法都可以直接调用：

方法	类型	说明
`id()`	`long`	商品编号（玩家看到的 `#编号`）
`type()`	`Listing.Type`	`SELL` 一口价 / `AUCTION` 拍卖 / `BUY` 收购单
`status()`	`Listing.Status`	`ACTIVE` 上架中 / `SOLD` 卖完或成交 / `EXPIRED` 到期 / `CANCELLED` 卖家下架 / `REMOVED` 管理员下架
`owner()` / `ownerName()`	`UUID` / `String`	卖家（收购单是收购方）
`item()`	`String`	物品数据（数量 1 的物品，Paper 完整物品数据的 Base64）。用 `ItemStack.deserializeBytes(Base64.getDecoder().decode(item()))` 还原
`itemKey()`	`String`	同一种物品的指纹（物品数据完全相同 → 相同）
`material()`	`String`	材质名称，例如 `DIAMOND`
`search()` / `category()`	`String`	搜索用的小写文字 / 所属分类 ID（逗号分隔）
`amount()`	`int`	剩余数量（拍卖是整批数量；收购单是还要收几个）
`initialAmount()`	`int`	上架时的数量
`price()`	`double`	一口价与收购单：单价；拍卖：起拍价（整批）
`partial()`	`boolean`	一口价能不能零买
`currency()`	`String`	货币 ID
`bid()` / `bidder()` / `bidderName()` / `bids()`		拍卖：目前最高出价 / 出价者 UUID / 名字 / 出价次数
`buyout()` / `reserve()`	`double`	拍卖的一口价 / 保留价（`0` = 没设）
`fee()`	`double`	已付的上架手续费
`taxRate()`	`double`	成交时的交易税率（`0.05` = 5%），上架时决定
`created()` / `expires()` / `ended()`	`long`	上架 / 到期 / 结束时间（毫秒时间戳，`ended` 未结束时是 `0`）
`server()`	`String`	上架的子服 ID
`version()`	`int`	每次变动 +1
`active(long now)`	`boolean`	现在是否上架中且未到期
`total()`	`double`	一口价：剩下的总价；拍卖：目前价格（没人出价时是起拍价）；收购单：剩下的预付款
`hasBids()`	`boolean`	拍卖是否已经有人出价

事件

AuctionListEvent

玩家上架之前（扣手续费之前）触发，在玩家所在的线程。取消后不会上架，玩家放进去的物品退回。

方法	说明
`getPlayer()`	上架的玩家
`getType()`	`Listing.Type`
`getItem()`	物品（数量 1，复制品）
`getAmount()`	数量
`getPrice()`	一口价与收购单是单价，拍卖是起拍价
`getCurrency()`	货币 ID
`isCancelled()` / `setCancelled(boolean)`	取消

@EventHandler
public void onList(AuctionListEvent e) {
    if (e.getType() == Listing.Type.AUCTION && !e.getPlayer().hasPermission("myserver.auction")) {
        e.setCancelled(true);
        e.getPlayer().sendMessage("只有正式会员可以开拍卖");
    }
}

AuctionPurchaseEvent

玩家购买一口价商品、付款之前触发。取消后不会扣钱。

方法	说明
`getPlayer()`	买家
`getListing()`	商品（玩家看到的样子）
`getAmount()`	购买数量
`getCost()`	要付的金额
`isCancelled()` / `setCancelled(boolean)`	取消

AuctionBidEvent

玩家出价、付款之前触发（一口价买下拍卖也是出价）。取消后不会扣钱。

方法	说明
`getPlayer()`	出价者
`getListing()`	拍卖（玩家看到的样子）
`getAmount()`	出价金额（达到一口价时就是一口价）
`isCancelled()` / `setCancelled(boolean)`	取消

AuctionTradeEvent

成交之后（数据库已经确认）触发，在主线程（Folia 是全局线程）。只用来通知，不能取消。

方法	说明
`getListing()`	成交后的商品
`getBuyer()`	买方 UUID：一口价是买家、拍卖是得标者、收购单是发布收购单的人
`getAmount()`	成交数量
`getTotal()`	买方付的金额（扣税前）

一口价购买、拍卖一口价买下、卖给收购单：在发生交易的那个子服触发。
拍卖到期成交：在结算那场拍卖的子服触发（跨服时是最先处理到的那个子服）。
所以跨服时，每一笔成交只会在一个子服触发一次。想在所有子服都知道，请自己转发。

@EventHandler
public void onTrade(AuctionTradeEvent e) {
    Listing l = e.getListing();
    getLogger().info("#" + l.id() + " " + l.material() + " ×" + e.getAmount()
        + " 成交 " + e.getTotal() + " " + l.currency());
}

事件只在本服触发

AuctionListEvent、AuctionPurchaseEvent、AuctionBidEvent 在玩家执行操作的子服触发；别的子服的操作不会在你这个子服触发事件。

引入​

快速开始​

StarAuctionAPI​

Listing​

事件​

AuctionListEvent​

AuctionPurchaseEvent​

AuctionBidEvent​

AuctionTradeEvent​

引入