Developer API - SnHub Docs

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

The API ships from SnHub 1.1.0 on, with API version 1.0.0.

Only com.sn.hub.api is a stable, kept contract. Everything else in the jar is obfuscated and internal. Do not call it, and never use com.sn.hub.api.impl directly.

Getting the jar

Download the latest release jar.

Install it into your local Maven repository:

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

Depend on it with provided scope. Never shade it.

<dependency>
    <groupId>com.sn</groupId>
    <artifactId>SnHub</artifactId>
    <version><version></version>
    <scope>provided</scope>
</dependency>

Quick start

Declare the dependency in your plugin.yml:

depend: [SnHub]      # or softdepend if optional

Resolve the API when you need it:

SnHubAPI api = SnHubProvider.get();
if (api != null) {
    // use the api
}

Resolve the reference when you need it. Do not cache it across a SnHub reload or disable.

Master switch

API events can be disabled by the server owner with api-events.enabled: false in config.yml. Cancellable hooks then report "not cancelled" and gameplay proceeds. The query service stays available either way.

Events

Cancellable events fire on the main thread, right before SnHub changes state. Cancelling aborts the action.

Event	Fired when	Cancel effect
`PvpModeEnterEvent`	The PvP sword countdown finished and the player is about to enter PvP mode	The player stays in normal mode, gets no PvP gear and keeps the hub hotbar
`HubItemUseEvent`	A player is about to use a hub item whose effect SnHub runs itself	Nothing happens and the item cooldown is not armed
`PlayerVisibilityToggleEvent`	A player is about to hide or show the other players with the toggle item	Visibility, the toggle item and its cooldown stay as they were

Payloads:

PvpModeEnterEvent: getPlayer().
HubItemUseEvent: getPlayer(), getItemId() (the items.yml id), getSlot() (0 to 8 for the hotbar, 40 for the off hand).
PlayerVisibilityToggleEvent: getPlayer(), isHiding() (the state about to be set).

HubItemUseEvent fires for these item ids:

Item id	Use
`ender-butt`	The right click that throws the rideable pearl
`bow-teleport`	The bow shot. Cancelling cancels the shot
`visibility-shown`, `visibility-hidden`	The right click on the hide-players toggle

Items whose click actions live in items.yml (the server selector, the hub selector, the rules book and your own items) run through SnLib and fire no HubItemUseEvent. The PvP sword is held, not used: PvpModeEnterEvent covers it.

Events only fire for a use that really happens. A click refused by SnHub (wrong world or mode, missing permission, running cooldown) fires nothing. A toggle click fires HubItemUseEvent first, then PlayerVisibilityToggleEvent when the first one was not cancelled.

Listen like any Bukkit event:

@EventHandler
public void on(PvpModeEnterEvent event) {
    if (isInQueue(event.getPlayer())) {
        event.setCancelled(true);
    }
}

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

Query service

Every method is synchronous and reads in-memory state. Call them on the main thread.

Method	Returns	Notes
`getPlayerState(UUID)`	`Optional<HubPlayerView>`	`mode()` (`NORMAL`, `PVP` or `BUILD`) and `hidingPlayers()`. Empty for offline players
`isInPvp(UUID)`	`boolean`	True while the player is in PvP mode. False for offline players
`getSpawn()`	`Optional<Location>`	A copy of the hub spawn. Empty when none is set or its world is not loaded
`getServerId()`	`Optional<String>`	This hub's network id. Empty until `server-id: auto` is detected
`getLiveHubs()`	`List<HubView>`	Live hubs of the last network poll: `id()`, `online()`, `max()`, `lastSeen()`. Empty when the network is inactive
`getServerCount(String)`	`int`	Last known player count of a proxy server. `-1` when unknown
`getApiVersion()`	`String`	The API contract version

Views never update. Call the method again to read fresh state.

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.