RondoAPI

priv.seventeen.artist.rondo.api.RondoAPI 是 Rondo 的公开 API 门面。

货币注册表

getCurrency

fun getCurrency(id: String): Currency?

按 ID 获取货币定义；不存在时返回 null。

getAllCurrencies

fun getAllCurrencies(): List<Currency>

返回全部货币。

getAllCurrencyIds

fun getAllCurrencyIds(): Set<String>

返回规范小写的货币 ID。结果是调用时的快照，不会随之后的配置重载变化。

isCurrencyRegistered

fun isCurrencyRegistered(id: String): Boolean

余额操作

getBalance

fun getBalance(player: UUID, currencyId: String): BigDecimal

同步查询在线或离线玩家的权威余额，会访问 SQLite/MySQL。只读快照不参与该方法的最终结果；货币未注册时返回 BigDecimal.ZERO。

peekEconomySnapshot

fun peekEconomySnapshot(
    player: UUID
): PlayerEconomySnapshot?

只读内存，不执行数据库 I/O；没有缓存时返回 null。null 明确表示“当前没有快照”，不表示玩家余额为零或默认余额。

getEconomySnapshot

fun getEconomySnapshot(
    player: UUID
): CompletableFuture<PlayerEconomySnapshot>

已有快照时 Future 立即完成，否则在后台一次性加载玩家的全部货币。同一玩家的并发加载会合并；存储失败时 Future 异常完成，不会返回 null 或伪造默认余额。

Future 的回调可能在 Rondo 异步任务线程执行。回调中操作玩家、世界、实体或背包前必须切回合法的 Bukkit 线程。

快照提供：

class PlayerEconomySnapshot {
    val playerUuid: UUID
    val currencies: Map<String, CurrencyEconomySnapshot>
    val revision: Long
    val updatedAtEpochMillis: Long
 
    fun getCurrency(currencyId: String): CurrencyEconomySnapshot?
    fun getBalance(currencyId: String): BigDecimal?
}
 
data class CurrencyEconomySnapshot(
    val balance: BigDecimal,
    val totalEarned: BigDecimal,
    val totalSpent: BigDecimal
)

revision 只表示当前 Rondo 进程内的快照发布顺序，不是跨服数据库版本号，也不能用于数据库乐观锁。

hasBalance

fun hasBalance(
    player: UUID,
    currencyId: String,
    amount: BigDecimal
): Boolean

检查余额是否充足。货币未注册、金额为负数或金额超出存储范围时返回 false。

deposit

fun deposit(
    player: UUID,
    currencyId: String,
    amount: BigDecimal,
    source: String
): Boolean

存入正数金额。金额会按货币的 decimal-places 四舍五入，并受余额上限和数据库精度限制。

withdraw

fun withdraw(
    player: UUID,
    currencyId: String,
    amount: BigDecimal,
    source: String
): Boolean

扣除正数金额，失败时返回 false。

setBalance

fun setBalance(
    player: UUID,
    currencyId: String,
    amount: BigDecimal,
    source: String
): Boolean

直接设置余额。

转账

fun transfer(
    from: UUID,
    to: UUID,
    currencyId: String,
    amount: BigDecimal
): TransferResult

data class TransferResult(
    val success: Boolean,
    val message: String,
    val taxAmount: BigDecimal = BigDecimal.ZERO
)

转账会自动计算税额。失败原因可从 message 读取。

发送方扣款（含税）和接收方入账会在同一个存储事务内完成；接收方超过余额上限时操作失败。

兑换

fun exchange(
    player: UUID,
    ruleId: String,
    targetAmount: BigDecimal
): ExchangeResult

data class ExchangeResult(
    val success: Boolean,
    val message: String,
    val fromAmount: BigDecimal = BigDecimal.ZERO,
    val toAmount: BigDecimal = BigDecimal.ZERO
)

targetAmount 是希望获得的目标货币数量。

源余额、目标余额和周期兑换额度会在同一个存储事务内提交。

排行榜

fun getRanking(
    currencyId: String,
    page: Int,
    pageSize: Int = 10
): List<RankingEntry>

page 从 1 开始，pageSize 允许 1..100。

fun getPlayerRank(
    player: UUID,
    currencyId: String
): Int?

未上榜时返回 null。

流水日志

fun getLog(
    player: UUID,
    currencyId: String?,
    page: Int,
    pageSize: Int = 10
): List<TransactionLog>

currencyId 传 null 表示查询全部货币。

返回与异常

业务失败返回 false 或 success=false。
数据库连接失败时可能抛出异常。
API 返回成功时，余额已经提交到 SQLite/MySQL；不存在退出时再保存的可写内存账户。
权威余额与资金操作是同步接口，不要在主线程批量调用。
peekEconomySnapshot 是 nullable 的非阻塞内存探测。
getEconomySnapshot 返回 Future，负责处理缓存命中或异步加载。
快照只用于展示与高频读取，不作为资金事务的最终判断依据。
经济事件的同步/异步状态与调用线程一致。
跨服模式以共享 MySQL 为权威账本，Redis 只负责发布缓存失效通知。

RondoAPI

On this page