公开 API

JoyMart 在启动时会向 Bukkit ServicesManager 注册 GameBoxAPI，供其他插件调用。下面介绍三种获取方式、常用方法、自定义事件、缓存与性能以及构建依赖。

获取 API

其他插件可通过三种方式获取 GameBoxAPI：

java

// 方式 1：静态单例（最快）
GameBoxAPI api = GameBoxAPI.getInstance();

// 方式 2：ServicesManager（推荐，解耦）
GameBoxAPI api = Bukkit.getServicesManager().load(GameBoxAPI.class);

// 方式 3：直接拿主类
GameBox plugin = GameBoxAPI.getPlugin();
GameBoxAPI api = plugin.getApi();

getPlugin() 静态方法

GameBoxAPI.getPlugin() 返回 GameBox 主类实例（me.nikl.gamebox.GameBox），可直接访问主类上的方法。

常用方法

java

// 代币
int balance = api.getTokens(uuid);
api.setTokens(uuid, 1000);   // 直接设置代币余额（下限 0）
api.addTokens(uuid, 100);
api.removeTokens(uuid, 50);
boolean ok = api.payIfCanAfford(uuid, 30);

// 高分
long hs = api.getHighScore(uuid, "2048");
api.setHighScore(uuid, "2048", 9999L);  // 强制设置个人高分（不写入全局排行榜）
int rank = api.submitScore("2048", uuid, "Steve", 1234L);
List<TopList.Entry> top = api.getTopList("2048", 10);
api.resetHighScores("2048");

// 玩家数据
api.savePlayer(uuid);        // 立即保存单个玩家数据（仅当数据已变化）

// 状态
boolean inMenu = api.isInGameBox(uuid);
boolean inGame = api.isInGame(uuid);
boolean in2048 = api.isInGame(uuid, "2048");
boolean enabled = api.isGameEnabled("2048");      // 某内置游戏 id 是否已启用
Set<String> games = api.getEnabledGameIds();
Set<String> all = api.getRegisteredGameIds();     // 所有已注册游戏 id（含未启用）

// 操作
api.openMainMenu(player);
api.openTopList(player, "2048");
api.enterGameBox(player);
api.leaveGameBox(player);
api.saveAll();
api.reload();

完整方法签名

完整方法签名见仓库中的 GameBoxAPI.java。

自定义事件

JoyMart 触发两个 Bukkit 事件，其他插件可监听：

java

@EventHandler
public void onEnter(EnterGameBoxEvent e) {
    Player p = e.getPlayer();
    // ...
}

@EventHandler
public void onLeave(LeftGameBoxEvent e) {
    Player p = e.getPlayer();
    // ...
}

事件类位于 me.nikl.gamebox.events 包。

缓存与性能

GBPlayer 在玩家加入时一次性加载到内存，之后所有读写都走缓存，只在 autoSaveInterval（默认 300 秒）或玩家退出时落库，避免每次操作查 DB。
GBPlayer.isDirty() 标记机制：只有真正变化过的玩家才会被写入。
TopListPage 高分榜 GUI 带 30 秒 TTL 缓存，新纪录产生时自动失效，避免重复查全表。
MySQL 模式 使用 HikariCP 连接池（默认 10 连接），跨服安全。

构建依赖

类型	依赖
provided	PaperAPI、Vault、PlaceholderAPI
运行时软依赖（仅检测存在性，无需编译期）	CalendarEvents
compile (shade, 重定位到 `me.nikl.gamebox.common.*`)	bstats-bukkit、HikariCP、slf4j-nop、ACF (Paper)、ExpiringMap、jsr305

完整依赖

完整依赖见仓库中的 pom.xml。

License

见仓库中的 LICENSE。

公开 API ​

获取 API ​

常用方法 ​

自定义事件 ​

缓存与性能 ​

构建依赖 ​

License ​

公开 API

获取 API

常用方法

自定义事件

缓存与性能

构建依赖

License