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

# Events API

> Subscribe to real-time events from your cloud network

The Events API lets you react to changes in your network in real-time. Access it via `api.event()`.

## Event Categories

| Method                           | Events                                 |
| -------------------------------- | -------------------------------------- |
| `api.event().group()`            | Group created, updated, deleted        |
| `api.event().server()`           | Server started, stopped, state changed |
| `api.event().persistentServer()` | Persistent server events               |
| `api.event().blueprint()`        | Blueprint created, updated, deleted    |

## Server Events

Server events fire for both group-based servers and persistent servers. When a persistent server triggers the event, `persistentServerId` is populated and `groupName` is empty. When a group server triggers the event, `groupName` is populated and `persistentServerId` is empty.

### Server Started

```java theme={null}
Subscription sub = api.event().server().onStarted(event -> {
    System.out.println("Server started: " + event.getServerId());

    // Check whether this is a group or persistent server
    if (event.getPersistentServerId() != null && !event.getPersistentServerId().isEmpty()) {
        System.out.println("Persistent server: " + event.getPersistentServerId());
    } else {
        System.out.println("Group: " + event.getGroupName());
    }
});
```

### Server Stopped

```java theme={null}
api.event().server().onStopped(event -> {
    System.out.println("Server stopped: " + event.getServerId());
});
```

### Server State Changed

```java theme={null}
api.event().server().onStateChanged(event -> {
    System.out.println(event.getServerId() + ": " +
        event.getOldState() + " → " + event.getNewState());
});
```

### Server Updated

```java theme={null}
api.event().server().onUpdated(event -> {
    System.out.println("Server updated: " + event.getServerId());
});
```

### Server Deleted

```java theme={null}
api.event().server().onDeleted(event -> {
    System.out.println("Server deleted: " + event.getServerId());
});
```

## Group Events

### Group Created

```java theme={null}
api.event().group().onCreated(event -> {
    System.out.println("Group created: " + event.getServerGroupId());
});
```

### Group Updated

```java theme={null}
api.event().group().onUpdated(event -> {
    System.out.println("Group updated: " + event.getServerGroupId());
});
```

### Group Deleted

```java theme={null}
api.event().group().onDeleted(event -> {
    System.out.println("Group deleted: " + event.getServerGroupId());
});
```

## Persistent Server Events

```java theme={null}
// Created
api.event().persistentServer().onCreated(event -> { ... });

// Started
api.event().persistentServer().onStarted(event -> { ... });

// Stopped
api.event().persistentServer().onStopped(event -> { ... });

// Updated
api.event().persistentServer().onUpdated(event -> { ... });

// Deleted
api.event().persistentServer().onDeleted(event -> { ... });
```

## Blueprint Events

```java theme={null}
// Created
api.event().blueprint().onCreated(event -> { ... });

// Updated
api.event().blueprint().onUpdated(event -> { ... });

// Deleted
api.event().blueprint().onDeleted(event -> { ... });
```

## Managing Subscriptions

Subscriptions implement `AutoCloseable`. Always clean them up when done:

### Manual Cleanup

```java theme={null}
Subscription sub = api.event().server().onStarted(event -> { ... });

// Later, when shutting down
sub.close();
```

### Try-with-Resources

```java theme={null}
try (Subscription sub = api.event().server().onStarted(event -> { ... })) {
    // Subscription active within this block
    Thread.sleep(60000);
} // Automatically closed
```

### Plugin Lifecycle

```java theme={null}
public class MyPlugin extends JavaPlugin {
    private final List<Subscription> subscriptions = new ArrayList<>();
    private CloudApi api;

    @Override
    public void onEnable() {
        api = CloudApi.create();

        subscriptions.add(api.event().server().onStarted(this::handleServerStart));
        subscriptions.add(api.event().server().onStopped(this::handleServerStop));
    }

    @Override
    public void onDisable() {
        subscriptions.forEach(Subscription::close);
    }

    private void handleServerStart(ServerStartedEvent event) {
        getLogger().info("Server started: " + event.getServerId());
    }

    private void handleServerStop(ServerStoppedEvent event) {
        getLogger().info("Server stopped: " + event.getServerId());
    }
}
```

## Event Reference

### Server Events

| Event                     | Properties                                    |
| ------------------------- | --------------------------------------------- |
| `ServerStartedEvent`      | `serverId`, `groupName`, `persistentServerId` |
| `ServerStoppedEvent`      | `serverId`, `groupName`, `persistentServerId` |
| `ServerStateChangedEvent` | `serverId`, `oldState`, `newState`            |
| `ServerUpdatedEvent`      | `serverId`                                    |
| `ServerDeletedEvent`      | `serverId`                                    |

<Note>
  `ServerStartedEvent` and `ServerStoppedEvent` fire for both group servers and persistent servers. For persistent servers, `persistentServerId` is set and `groupName` is empty. For group servers, `groupName` is set and `persistentServerId` is empty.
</Note>

### Group Events

| Event               | Properties      |
| ------------------- | --------------- |
| `GroupCreatedEvent` | `serverGroupId` |
| `GroupUpdatedEvent` | `serverGroupId` |
| `GroupDeletedEvent` | `serverGroupId` |

### Persistent Server Events

| Event                          | Properties |
| ------------------------------ | ---------- |
| `PersistentServerCreatedEvent` | `serverId` |
| `PersistentServerStartedEvent` | `serverId` |
| `PersistentServerStoppedEvent` | `serverId` |
| `PersistentServerUpdatedEvent` | `serverId` |
| `PersistentServerDeletedEvent` | `serverId` |

### Blueprint Events

| Event                   | Properties    |
| ----------------------- | ------------- |
| `BlueprintCreatedEvent` | `blueprintId` |
| `BlueprintUpdatedEvent` | `blueprintId` |
| `BlueprintDeletedEvent` | `blueprintId` |