> ## 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.

# Cloud API

> Baue Integrationen mit SimpleCloud über unsere Java/Kotlin API

Die Cloud API ist eine Java-Bibliothek zur programmatischen Interaktion mit deinem SimpleCloud-Netzwerk. Verwende sie zum Verwalten von Gruppen, laufenden Servern, Persistent Servern, Spielern, Cache-Zustand und Events in Echtzeit.

## API-Architektur

| Methode                  | Gibt zurück           | Beschreibung                                                  |
| ------------------------ | --------------------- | ------------------------------------------------------------- |
| `api.group()`            | `GroupApi`            | Gruppen erstellen, lesen, aktualisieren, löschen              |
| `api.server()`           | `ServerApi`           | Laufende Server abfragen, stoppen und aktualisieren           |
| `api.persistentServer()` | `PersistentServerApi` | Persistent Server erstellen, lesen, aktualisieren, löschen    |
| `api.player()`           | `PlayerApi`           | Spielerdaten, Verbindungen, Messaging                         |
| `api.event()`            | `EventApi`            | Echtzeit-Events abonnieren                                    |
| `api.cache()`            | `QueryCache`          | Lokale Query-Cache-Eintraege ansehen, invalidieren und leeren |

### Event API Unterkategorien

| Methode                          | Beschreibung               |
| -------------------------------- | -------------------------- |
| `api.event().group()`            | Gruppen-Lifecycle-Events   |
| `api.event().server()`           | Server-Lifecycle-Events    |
| `api.event().persistentServer()` | Persistente Server-Events  |
| `api.event().blueprint()`        | Blueprint-Lifecycle-Events |

## Wichtige Features

* **Async-first Design** - Alle Operationen geben `CompletableFuture` (Java) oder Suspend-Funktionen (Kotlin) zurück
* **Typsichere Modelle** - Stark typisierte Domain-Objekte für Gruppen, Server, Spieler
* **Echtzeit-Events** - Änderungen über NATS-Messaging abonnieren
* **Adventure-Integration** - Spieler implementieren Adventure's `Audience` für Rich-Text-Messaging
* **Persistent-Server-Support** - Lang laufende Server über `api.persistentServer()` verwalten
* **Query Cache** - Stale-while-revalidate Cache mit automatischer Event-Invalidierung
* **Umgebungs-bewusst** - Auto-Konfiguration aus `SIMPLECLOUD_*` Umgebungsvariablen

## Schnellbeispiel

<Tabs>
  <Tab title="Java">
    ```java theme={null}
    // API initialisieren
    CloudApi api = CloudApi.create();

    // Alle Server in einer Gruppe abrufen
    api.server().getServersByGroup("lobby").thenAccept(servers -> {
        System.out.println("Lobby-Server: " + servers.size());
    });

    // Serverstart für eine Gruppe anfordern
    api.group().getGroupByName("lobby")
        .thenCompose(group -> api.group().requestServerStart(group))
        .thenRun(() -> System.out.println("Start-Anfrage akzeptiert"));

    // Nachricht an Spieler senden (Adventure-Integration)
    api.player().get(playerUUID).thenAccept(player -> {
        if (player != null) {
            player.sendMessage(Component.text("Willkommen!").color(NamedTextColor.GREEN));
        }
    });

    // Server-Events abonnieren
    Subscription sub = api.event().server().onStarted(event -> {
        System.out.println("Server gestartet: " + event.getServerId());
    });
    ```
  </Tab>

  <Tab title="Kotlin">
    ```kotlin theme={null}
    // API initialisieren
    val api = CloudApi.create()

    // Alle Server in einer Gruppe abrufen
    val servers = api.server().getServersByGroup("lobby").await()
    println("Lobby-Server: ${servers.size}")

    // Serverstart für eine Gruppe anfordern
    val group = api.group().getGroupByName("lobby").await()
    api.group().requestServerStart(group).await()
    println("Start-Anfrage akzeptiert")

    // Nachricht an Spieler senden (Adventure-Integration)
    api.player().get(playerUUID).await()?.let { player ->
        player.sendMessage(Component.text("Willkommen!").color(NamedTextColor.GREEN))
    }

    // Server-Events abonnieren
    val sub = api.event().server().onStarted { event ->
        println("Server gestartet: ${event.serverId}")
    }
    ```
  </Tab>
</Tabs>

## Nächste Schritte

<CardGroup cols={2}>
  <Card title="Installation" icon="download" href="/docs/de/developer/installation">
    Cloud API zu deinem Projekt hinzufügen
  </Card>

  <Card title="Servers API" icon="server" href="/docs/de/developer/api/servers">
    Server-Instanzen verwalten
  </Card>

  <Card title="Persistent Servers API" icon="hard-drive" href="/docs/de/developer/api/persistent-servers">
    Lang laufende Server verwalten
  </Card>

  <Card title="Players API" icon="users" href="/docs/de/developer/api/players">
    Spielerdaten und Messaging
  </Card>

  <Card title="Events API" icon="bell" href="/docs/de/developer/api/events">
    Auf Echtzeit-Änderungen reagieren
  </Card>
</CardGroup>