货币系统 API

Malkuth 支持自定义货币系统，允许第三方插件注册自己的货币类型并与商城集成。

方法一览

方法	返回值	说明
registerCurrency(id: String, currency: ShopSerializer.CustomCurrency)	Unit	注册自定义货币
getCurrencyBalance(player: Player, shopId: String)	Number	获取玩家在指定商店使用的货币余额，商店不存在时返回 -1
hasCurrency(player: Player, shopId: String, price: Number)	Boolean	检查玩家是否有足够的货币

CustomCurrency 结构

ShopSerializer.CustomCurrency 是自定义货币的数据类，定义了货币的 PAPI 占位符和 Kether 动作：

import kim.hhhhhy.malkuth.internal.data.serialize.shop.ShopSerializer

data class CustomCurrency(
    /** PAPI 占位符，用于查询余额 */
    val placeholder: String,
    /** 给予货币的 Kether 动作（可选） */
    val giveAction: String?,
    /** 扣除货币的 Kether 动作（可选） */
    val takeAction: String?,
    /** 余额不足时执行的 Kether 动作（可选） */
    val denyAction: String?
)

注册自定义货币

import kim.hhhhhy.malkuth.internal.data.serialize.shop.ShopSerializer.CustomCurrency

// 注册自定义货币
Malkuth.api.registerCurrency("points", CustomCurrency(
    placeholder = "%mypoints_balance%",
    giveAction = "mypoints give {{ amount }}",
    takeAction = "mypoints take {{ amount }}",
    denyAction = "tell inline \"积分不足\""
))

查询余额

val api = Malkuth.api

// 获取玩家在商店使用的货币余额
val balance = api.getCurrencyBalance(player, "main_shop")
player.sendMessage("你的余额: $balance")

// 检查是否足够购买
if (api.hasCurrency(player, "main_shop", 100.0)) {
    player.sendMessage("余额充足")
} else {
    player.sendMessage("余额不足")
}

在商店配置中使用自定义货币

注册完成后，可以在商店配置文件中通过货币 ID 引用：

shop:
  id: "points_shop"
  name: "积分商店"
  currency: "points"  # 使用注册的货币 ID
  goods:
    - id: "diamond"
      price: 500  # 500 积分

多货币费用明细

普通商品与购物车流程不会把多种货币压成一个余额数字。源码中的 CurrencyCost 位于 internal/data/serialize/shop/CurrencyCost.kt：

data class CurrencyCost(
    val currencyKey: String,
    val unitPrice: Double,
    val totalPrice: Double
)

CurrencySelectionMode 支持 SINGLE / MULTIPLE。CurrencyCostPlan 负责选择支付项、按数量计算费用并格式化摘要：single 只保留选中的一项，multiple 按配置顺序保留全部项。PlayerPoints 的实际扣款金额会按其整数 API 向上取整；事件和退款应以 totalPrice 明细为准。

拍卖行使用相同的货币后端，但其动态价格由拍卖记录决定，配置写法见站内的“拍卖行模式”页面。

提示

自定义货币注册应在插件启用阶段（onEnable）完成，确保在 Malkuth 加载商店配置之前注册。建议在 plugin.yml 中将 Malkuth 设为前置依赖。