Public API

JoyMart exposes a public API for other plugins. The main class is me.nikl.gamebox.GameBox.

Public API (for other plugins)

JoyMart registers GameBoxAPI with the Bukkit ServicesManager on startup. Other plugins can obtain it via three methods:

// Method 1: static singleton (fastest)
GameBoxAPI api = GameBoxAPI.getInstance();

// Method 2: ServicesManager (recommended, decoupled)
GameBoxAPI api = Bukkit.getServicesManager().load(GameBoxAPI.class);

// Method 3: directly from the main class
GameBox plugin = GameBoxAPI.getPlugin();
GameBoxAPI api = plugin.getApi();

getPlugin() static method

GameBoxAPI.getPlugin() returns the GameBox main class instance (me.nikl.gamebox.GameBox), giving direct access to methods on the main class.

Common methods:

// Tokens
int balance = api.getTokens(uuid);
api.setTokens(uuid, 1000);   // Set a player's token balance (clamped to >= 0)
api.addTokens(uuid, 100);
api.removeTokens(uuid, 50);
boolean ok = api.payIfCanAfford(uuid, 30);

// High scores
long hs = api.getHighScore(uuid, "2048");
api.setHighScore(uuid, "2048", 9999L);  // Force-set a player's high score (does not write to the global leaderboard)
int rank = api.submitScore("2048", uuid, "Steve", 1234L);
List<TopList.Entry> top = api.getTopList("2048", 10);
api.resetHighScores("2048");

// Player data
api.savePlayer(uuid);        // Force-save a single player's data now (only if dirty)

// State
boolean inMenu = api.isInGameBox(uuid);
boolean inGame = api.isInGame(uuid);
boolean in2048 = api.isInGame(uuid, "2048");
boolean enabled = api.isGameEnabled("2048");      // Whether a built-in game id is enabled
Set<String> games = api.getEnabledGameIds();
Set<String> all = api.getRegisteredGameIds();     // All registered game ids (enabled or not)

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

See GameBoxAPI.java for the full method signatures.

Custom Events

JoyMart fires two Bukkit events that other plugins can listen to:

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

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

The event classes are in the me.nikl.gamebox.events package.

TIP

You can also run console commands on enter/leave without writing code — configure the commands.onEnter / commands.onLeave lists in config.yml.

Caching & Performance

• GBPlayer is loaded into memory once on join; all subsequent reads/writes go through the cache and only flush to the DB on autoSaveInterval (default 300s) or player quit — avoiding per-operation DB lookups.
• GBPlayer.isDirty() flag mechanism: only players whose data actually changed get written.
• TopListPage high-score GUI has a 30-second TTL cache, automatically invalidated on new records, to avoid repeatedly scanning the full table.
• MySQL mode uses a HikariCP connection pool (default 10 connections) — cross-server safe.

TIP

The autoSaveInterval and MySQL pool settings live in the storage block of config.yml. See Data Storage for the full backend overview.

Build Dependencies

Type	Dependency
provided	PaperAPI, Vault, PlaceholderAPI
Soft-depend at runtime (existence detection only, no compile-time needed)	CalendarEvents
compile (shade, relocated to me.nikl.gamebox.common.*)	bstats-bukkit, HikariCP, slf4j-nop, ACF (Paper), ExpiringMap, jsr305

See pom.xml for the full dependency list.

License

See LICENSE.