API 概览

Rondo 提供 Java/Kotlin API，可查询货币、读写余额、转账、兑换、读取排行榜与流水，并监听可取消的 Bukkit 事件。

引入依赖

Gradle Kotlin DSL

repositories {
    maven("https://repo.arcartx.com/repository/maven-public/")
}
 
val rondoVersion = "<与服务端 JAR 相同的已发布版本>"
 
dependencies {
    compileOnly("priv.seventeen.artist:rondo:$rondoVersion")
}

将 rondoVersion 替换为服务器安装的 Rondo 版本。

plugin.yml

depend: [Rondo]

可选依赖使用：

softdepend: [Rondo]

使用 softdepend 时，请先检查 Rondo 是否已启用。

核心入口

import priv.seventeen.artist.rondo.api.RondoAPI

快速示例

import priv.seventeen.artist.rondo.api.RondoAPI
import java.math.BigDecimal
 
val currencyIds: Set<String> = RondoAPI.getAllCurrencyIds()
val balance = RondoAPI.getBalance(player.uniqueId, "gold")
 
// UI、HUD 等高频展示：只读内存探测，未命中时返回 null
val snapshot = RondoAPI.peekEconomySnapshot(player.uniqueId)
val displayBalance = snapshot?.getBalance("gold")
 
// 缓存未命中时异步加载，Future 成功时一定包含快照
RondoAPI.getEconomySnapshot(player.uniqueId).thenAccept { loaded ->
    val loadedBalance = loaded.getBalance("gold")
}
 
val charged = RondoAPI.withdraw(
    player.uniqueId,
    "gold",
    BigDecimal("100.00"),
    "my_plugin:shop"
)
 
if (!charged) {
    player.sendMessage("余额不足或操作被拒绝")
}

重要约定

货币 ID 不区分大小写，注册表返回规范小写 ID。
金额使用 BigDecimal，最多保留 4 位小数。
source 建议使用 插件名:功能，长度为 1–128 个字符。
权威余额查询和资金操作是同步接口，可能执行 SQLite/MySQL I/O。
每次成功的资金操作都已经在数据库事务中提交；Rondo 没有待保存的内存余额。
peekEconomySnapshot 只读内存且允许返回 null，适合每 tick 的 UI/HUD 探测。
getEconomySnapshot 返回 CompletableFuture；已有缓存时立即完成，未命中时异步加载全部货币。
快照只用于展示，不能用来判断扣款是否成功。
getEconomySnapshot 的异步回调可能在 Rondo 任务线程执行，调用 Bukkit 主线程 API 前需要切回主线程。
资金操作会在调用线程触发可取消事件。
业务校验失败返回 false 或失败结果；存储故障可能抛出异常。

不要在主线程批量查询或修改离线玩家余额。

API 概览

引入依赖

Gradle Kotlin DSL

plugin.yml

核心入口

快速示例

重要约定

On this page