Developer API

SnKoths exposes a public developer API for other plugins: custom Bukkit events and a read-only query service. The API lives in the com.sn.koths.api package inside the plugin jar. There is no separate artifact.

Only com.sn.koths.api is a stable, kept contract. Everything else in the jar is obfuscated and internal. Do not call it.

Getting the jar

Download the latest release jar.

Install it into your local Maven repository:

mvn install:install-file -Dfile=SnKoths-<version>.jar -DgroupId=com.sn \
  -DartifactId=SnKoths -Dversion=<version> -Dpackaging=jar

Depend on it with provided scope. Never shade it.

Quick start

Declare the dependency in your plugin.yml:

depend: [SnKoths]      # or softdepend if optional

Resolve the API when you need it:

SnKothsAPI api = SnKothsProvider.get();
if (api != null) {
    // use the api
}

Resolve the reference when you need it. Do not cache it across a SnKoths reload.

Master switch

API events can be disabled by the server owner with api-events.enabled: false in config.yml. The query service stays available either way.

Events

Cancellable events fire before the action. Cancelling aborts it.

Event	Fired when	Cancel effect
`KothStartEvent`	A koth is about to start, from a command, a schedule or a starter item. Carries the koth and the source (`COMMAND`, `SCHEDULE`, `STARTER`).	The koth does not start. A redeemed starter item is handed back.

Notification events fire after the fact. They cannot be cancelled.

Event	Fired when	Thread
`KothEndEvent`	A koth ended. Carries the koth, the reason (`WIN`, `TIMEOUT_NO_WINNER`, `STOPPED`, `SHUTDOWN`), the winner, the SCORE ranking, the zone seconds per player and the duration.	Main

Listen like any Bukkit event:

@EventHandler
public void on(KothStartEvent event) {
    if (event.getKoth().id().equals("castle")) {
        event.setCancelled(true);
    }
}

Event payloads are read-only. Cancellation is the only change a listener can make.

Query service

Every method reads in-memory state. Call them on the main thread. Every returned view is an immutable snapshot.

Method	Returns	Notes
`getKoths()`	`List<KothView>`	Every loaded koth definition, running or not.
`getKoth(id)`	`KothView` or `null`	The definition of one koth.
`isActive(id)`	`boolean`	Whether the koth is running now.
`getActiveKoths()`	`List<KothStateView>`	Runtime state of every running koth, in start order.
`getActiveKoth(id)`	`KothStateView` or `null`	Runtime state of one running koth.
`getTopPlayers(limit)`	`List<LeaderboardEntryView>`	Cached all-time top players by wins.
`getTopTeams(limit)`	`List<LeaderboardEntryView>`	Cached all-time top teams by wins.
`getStats(uuid)`	`KothStatsView` or `null`	Cached stats of an online player, `null` while offline or loading.
`getApiVersion()`	`String`	The API contract version.

Versioning

Call getApiVersion() for the API contract version. It is independent of the plugin version. Additions bump the minor component. Existing members are never removed or changed. Deprecated members keep working.