Malkuth API 概述

Malkuth 是一个全功能商城系统，提供完整的开发者 API，允许第三方插件与商城进行深度集成。

获取 API 实例

所有 API 方法通过 MalkuthAPI 接口暴露，入口为 Malkuth.api：

import kim.hhhhhy.malkuth.common.api.MalkuthAPI

val api: MalkuthAPI = Malkuth.api

依赖配置

从售后群获取 Malkuth-api.jar 文件，放入项目的 libs/ 目录：

Gradle (Kotlin DSL)

dependencies {
    compileOnly(files("libs/Malkuth-api.jar"))
}

Maven

<dependency>
    <groupId>kim.hhhhhy</groupId>
    <artifactId>malkuth-api</artifactId>
    <version>最新版本</version>
    <scope>system</scope>
    <systemPath>${project.basedir}/libs/Malkuth-api.jar</systemPath>
</dependency>

plugin.yml

depend: [Malkuth]
# 或软依赖
softdepend: [Malkuth]

API 模块一览

模块	说明	文档
商城核心	商店/商品查询、开启商店、购买记录、收藏、拍卖、仓库	Shop API
货币系统	自定义货币注册与余额查询	Currency API
物品源	自定义物品源注册与解析，33 个固定 + 1 个条件物品源	Item Source
事件系统	34 个事件，覆盖购买/回收/出售/赠送/拍卖/全球市场/全球求购等全流程	Events

包结构

kim.hhhhhy.malkuth.common.api
├── MalkuthAPI              // 核心 API 接口
├── item
│   ├── MalkuthItem         // 物品源管理
│   ├── ItemSource          // 物品源接口
│   └── BuildSourceItem     // 物品构建结果
├── event
│   ├── PlayerOpenShopEvent
│   ├── PlayerPurchaseEvent
│   └── ...                 // 共 34 个事件
└── data
    ├── TransactionRecord   // 交易记录 DTO
    ├── AuctionRecord       // 拍卖记录 DTO
    └── FavoriteRecord      // 收藏记录 DTO

备注

自定义货币类 CustomCurrency 位于 kim.hhhhhy.malkuth.internal.data.serialize.shop.ShopSerializer 内部，不存在独立的 currency 子包。

线程安全

Malkuth API 的大部分方法需要在主线程调用（涉及玩家操作的方法）。查询类方法（如 getShop、getTransactions）可在异步线程安全调用。