Developer API - SnAutoRestart Docs

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

Only com.sn.autorestart.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=SnAutoRestart-<version>.jar -DgroupId=com.sn \
  -DartifactId=SnAutoRestart -Dversion=<version> -Dpackaging=jar

Depend on it with provided scope. Never shade it.

Quick start

Declare the dependency in your plugin.yml:

depend: [SnAutoRestart]      # or softdepend if optional

Resolve the API when you need it:

SnAutoRestartAPI api = SnAutoRestartProvider.get();
if (api != null) {
    // use the api
}

Resolve the reference when you need it. Do not cache it across a SnAutoRestart 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 on the main thread, right before an admin command changes state. Cancelling aborts the action and the sender is told another plugin blocked it.

Event	Fired when	Cancel effect
`RestartForceEvent`	`/snautorestart restart [time]` passed validation and a forced countdown is about to start	No countdown starts; a running countdown is left untouched
`RestartCancelEvent`	`/snautorestart cancel` is about to cancel the running countdown	The countdown keeps running; nothing is released or broadcast
`LockdownToggleEvent`	`/snautorestart lockdown <on\|off>` is about to change the manual lockdown	The manual lockdown stays as it is

Payloads:

RestartForceEvent: getSender(), getSeconds() (countdown length), isReplacingCountdown().
RestartCancelEvent: getSender(), getCause() (SCHEDULED or FORCED), getSecondsLeft().
LockdownToggleEvent: getSender(), isEnabling().

Countdowns started by the restart schedule fire no event. The restart lockdown a countdown turns on and off fires no event either. Only admin commands do.

Listen like any Bukkit event:

@EventHandler
public void on(RestartForceEvent event) {
    if (eventInProgress()) {
        event.setCancelled(true);
    }
}

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

Query service

Every method reads in-memory state and is safe to call from any thread.

Method	Returns	Notes
`isCountdownActive()`	`boolean`	True while a scheduled or forced countdown runs
`getCountdown()`	`Optional<CountdownView>`	Snapshot of the running countdown: `cause()`, `endsAt()`, `totalSeconds()`, `secondsLeft()`. Empty while idle
`getNextRestart()`	`Optional<Instant>`	End of the running countdown, else the next scheduled restart. Empty when neither exists
`isLockdownActive()`	`boolean`	True while the manual or the restart lockdown is on
`isManualLockdownActive()`	`boolean`	True while the manual lockdown (`/snautorestart lockdown on`) is on
`isJoinLocked()`	`boolean`	True while logins are refused, before a restart or right after boot
`getApiVersion()`	`String`	The API contract version

A CountdownView never updates. Call getCountdown() again to read the time left later.

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.