> ## Documentation Index
> Fetch the complete documentation index at: https://simplecloud.app/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Events API

> Subscribe to group, server, persistent server, and blueprint events

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:

```java theme={null}
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](/docs/en/developer/guides/event-handling) 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.

<AccordionGroup>
  <Accordion title="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()`                                                                                            |
  </Accordion>

  <Accordion title="Group callback getters">
    | Callback type       | Additional getters                                     |
    | ------------------- | ------------------------------------------------------ |
    | `GroupCreatedEvent` | `getServerGroupId()`, `getGroup()`                     |
    | `GroupUpdatedEvent` | `getServerGroupId()`, `getGroup()`                     |
    | `GroupDeletedEvent` | `getServerGroupId()`, `getName()` (`String` or `null`) |
  </Accordion>

  <Accordion title="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`)     |
  </Accordion>

  <Accordion title="Blueprint callback getters">
    | Callback type           | Additional getters                                   |
    | ----------------------- | ---------------------------------------------------- |
    | `BlueprintCreatedEvent` | `getBlueprintId()`, `getBlueprint()`                 |
    | `BlueprintUpdatedEvent` | `getBlueprintId()`, `getBlueprint()`                 |
    | `BlueprintDeletedEvent` | `getBlueprintId()`, `getName()` (`String` or `null`) |
  </Accordion>
</AccordionGroup>