Events API

Use events to react when resources in your SimpleCloud network change. Subscribe through cloudApi.event() and use the event’s stable resource ID in your callback:

Subscription subscription = cloudApi.event().server().onStateChanged(event -> {
    String serverId = event.getServerId();
    // React to the state change.
});

Keep the returned Subscription and close it when your plugin stops. The event handling guide shows the complete plugin lifecycle and how to safely interact with your server platform from a callback.

Choose an event category

Category	Subscription methods	Callback types
`group()`	`onCreated`, `onUpdated`, `onDeleted`	`GroupCreatedEvent`, `GroupUpdatedEvent`, `GroupDeletedEvent`
`server()`	`onStarted`, `onStopped`, `onStateChanged`, `onUpdated`, `onDeleted`	`ServerStartedEvent`, `ServerStoppedEvent`, `ServerStateChangedEvent`, `ServerUpdatedEvent`, `ServerDeletedEvent`
`persistentServer()`	`onCreated`, `onStarted`, `onStopped`, `onUpdated`, `onDeleted`	`PersistentServerCreatedEvent`, `PersistentServerStartedEvent`, `PersistentServerStoppedEvent`, `PersistentServerUpdatedEvent`, `PersistentServerDeletedEvent`
`blueprint()`	`onCreated`, `onUpdated`, `onDeleted`	`BlueprintCreatedEvent`, `BlueprintUpdatedEvent`, `BlueprintDeletedEvent`

Server events describe individual server instances. Persistent server events describe changes to the persistent server itself, such as it being updated or starting a server instance.

Keep state accurate

Events notify you that something changed; query APIs provide the current state. Subscriptions only receive live events, so query the resource when your plugin starts or when missing an event would make its state incorrect. Close each subscription when you no longer need it. Both close() and unsubscribe() stop future delivery and can be called more than once.

Read callback data

Every callback provides getNetworkId() and an ISO 8601 timestamp through getTimestamp(). The remaining getters depend on the event type. Prefer the stable ID getter when identifying a resource. Query the matching resource API when you need its current data; model getters such as getServer(), getGroup(), and getBlueprint() can be unavailable for an event.

Server callback getters

Callback type	Additional getters
`ServerStartedEvent`	`getServerId()`, `getServerGroupId()`, `getServer()`
`ServerStoppedEvent`	`getServerId()`, `getServerGroupId()`, `getServer()`, `getCrashed()`, `getExitCode()` (`Integer` or `null`), `getReason()` (`String` or `null`)
`ServerStateChangedEvent`	`getServerId()`, `getOldState()`, `getNewState()`, `getServer()`
`ServerUpdatedEvent`	`getServerId()`, `getServerGroupId()`, `getServer()`
`ServerDeletedEvent`	`getServerId()`, `getServerGroupId()`, `getServer()`

Group callback getters

Callback type	Additional getters
`GroupCreatedEvent`	`getServerGroupId()`, `getGroup()`
`GroupUpdatedEvent`	`getServerGroupId()`, `getGroup()`
`GroupDeletedEvent`	`getServerGroupId()`, `getName()` (`String` or `null`)

Persistent server callback getters

Callback type	Additional getters
`PersistentServerCreatedEvent`	`getPersistentServerId()`, `getName()` (`String` or `null`)
`PersistentServerStartedEvent`	`getPersistentServerId()`, `getServerId()` (`String` or `null`)
`PersistentServerStoppedEvent`	`getPersistentServerId()`, `getServerId()` (`String` or `null`)
`PersistentServerUpdatedEvent`	`getPersistentServerId()`, `getName()` (`String` or `null`)
`PersistentServerDeletedEvent`	`getPersistentServerId()`, `getName()` (`String` or `null`)

Blueprint callback getters

Callback type	Additional getters
`BlueprintCreatedEvent`	`getBlueprintId()`, `getBlueprint()`
`BlueprintUpdatedEvent`	`getBlueprintId()`, `getBlueprint()`
`BlueprintDeletedEvent`	`getBlueprintId()`, `getName()` (`String` or `null`)

Getting Started

Cloud API

Guides

REST API Reference

Choose an event category

Keep state accurate

Read callback data

​Choose an event category

​Keep state accurate

​Read callback data

Choose an event category

Keep state accurate

Read callback data