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

# Groups API

> Server-Gruppen programmatisch verwalten

Die Groups API ermöglicht das Erstellen, Abfragen, Aktualisieren und Löschen von Server-Gruppen. Zugriff über `api.group()`.

## Gruppen abrufen

```java theme={null}
// Alle Gruppen abrufen
api.group().getAllGroups()
    .thenAccept(groups -> groups.forEach(g -> System.out.println(g.getName())));

// Gruppe nach Namen
api.group().getGroupByName("lobby")
    .thenAccept(group -> System.out.println(group.getId()));

// Gruppe nach ID
api.group().getGroupById("group-uuid")
    .thenAccept(group -> System.out.println(group.getName()));
```

## Gruppe erstellen

```java theme={null}
CreateGroupRequest request = CreateGroupRequest.builder()
    .name("bedwars")
    .type(GroupServerType.SERVER)
    .minMemory(512)
    .maxMemory(1024)
    .maxPlayers(16)
    .minOnlineCount(1)
    .maxOnlineCount(10)
    .build();

api.group().createGroup(request)
    .thenAccept(group -> System.out.println("Erstellt: " + group.getId()));
```

## Gruppe aktualisieren

```java theme={null}
UpdateGroupRequest update = UpdateGroupRequest.builder()
    .maxPlayers(32)
    .maxOnlineCount(20)
    .build();

api.group().updateGroup("group-uuid", update)
    .thenAccept(group -> System.out.println("Aktualisiert: " + group.getName()));
```

## Gruppe löschen

```java theme={null}
api.group().deleteGroup("group-uuid")
    .thenAccept(success -> System.out.println("Gelöscht: " + success));
```

<Warning>
  Das Löschen einer Gruppe stoppt laufende Server nicht. Stoppe Server zuerst wenn nötig.
</Warning>

## Gruppen-Properties

Gruppen unterstützen eigene Key-Value-Properties für Metadaten:

```java theme={null}
// Properties hinzufügen oder aktualisieren (merged mit bestehenden)
Map<String, String> props = Map.of(
    "gameMode", "ADVENTURE",
    "region", "eu-west"
);
api.group().updateGroupProperties("group-uuid", props);

// Bestimmte Properties entfernen
api.group().deleteGroupProperties("group-uuid", List.of("region"));
```

Properties sind in Servern als Umgebungsvariablen mit `SIMPLECLOUD_` Präfix verfügbar.

## Group Model

| Property         | Typ                   | Beschreibung             |
| ---------------- | --------------------- | ------------------------ |
| `id`             | `String`              | Eindeutige Kennung       |
| `name`           | `String`              | Gruppenname              |
| `type`           | `GroupServerType`     | `SERVER` oder `PROXY`    |
| `minMemory`      | `int`                 | Minimaler Speicher (MB)  |
| `maxMemory`      | `int`                 | Maximaler Speicher (MB)  |
| `maxPlayers`     | `int`                 | Spielerlimit pro Server  |
| `minOnlineCount` | `int`                 | Minimale laufende Server |
| `maxOnlineCount` | `int`                 | Maximale erlaubte Server |
| `properties`     | `Map<String, String>` | Eigene Metadaten         |

## Server-Start-Warteschlange

Gruppen mit dem Skalierungsmodus `SERVERS` unterstützen eine manuelle Start-Warteschlange. Anstatt einen Server sofort zu starten, kannst du eine Start-Anfrage in die Warteschlange einreihen, die der Reconciler beim nächsten Tick verarbeitet. Dies ist nützlich, wenn du genau kontrollieren möchtest, wann neue Server erstellt werden, während das `max_servers`-Limit der Gruppe eingehalten wird.

<Info>
  Die Start-Warteschlange ist nur für Gruppen mit dem Skalierungsmodus `SERVERS` verfügbar. Gruppen mit dem Modus `SLOTS` unterstützen keine Warteschlangen-Starts.
</Info>

### Server-Start einreihen

Du kannst einen Start über die Gruppen-ID oder den Gruppennamen (oder beides) einreihen:

```java theme={null}
// Start nach Gruppenname einreihen
api.group().queueServerStart("lobby")
    .thenAccept(response -> System.out.println(
        "Eingereiht: " + response.getQueuedStarts()));

// Start nach Gruppen-ID einreihen
api.group().queueServerStart("group-uuid")
    .thenAccept(response -> System.out.println(
        "Eingereiht: " + response.getQueuedStarts()));
```

Der Reconciler verarbeitet eingereihte Starts beim nächsten Reconciliation-Tick und versucht, einen Server zuzuweisen. Wenn die Gruppe ihr `max_servers`-Limit erreicht hat, wird der eingereihte Start als `failed` mit einem Grund markiert.

### Eingereihte Starts auflisten

```java theme={null}
api.group().listQueuedStarts()
    .thenAccept(response -> {
        System.out.println("Wartend: " + response.getQueuedStarts());
        System.out.println("Fehlgeschlagen: " + response.getFailedStarts());
        response.getItems().forEach(entry ->
            System.out.println(entry.getServerGroupName() + ": " +
                entry.getQueuedStarts() + " wartend"));
    });
```

### Eingereihte Starts löschen

Alle ausstehenden und fehlgeschlagenen Starts einer bestimmten Gruppe entfernen:

```java theme={null}
api.group().clearQueuedStarts("group-uuid")
    .thenAccept(response -> System.out.println(
        "Warteschlange geleert für: " + response.getServerGroupName()));
```

### Start-Warteschlangen-Eintrag

| Property         | Typ       | Beschreibung                               |
| ---------------- | --------- | ------------------------------------------ |
| `id`             | `String`  | Eindeutige Kennung des eingereihten Starts |
| `created_at`     | `String`  | Zeitstempel der Einreihung (ISO 8601)      |
| `status`         | `String`  | `pending` oder `failed`                    |
| `failure_reason` | `String?` | Grund des Fehlschlags, falls zutreffend    |

<Warning>
  Fehlgeschlagene Starts werden nach 1 Stunde automatisch bereinigt. Verwende den List-Endpunkt, um auf Fehler zu prüfen und bei Bedarf neu einzureihen.
</Warning>

## GroupServerType

| Wert     | Beschreibung                        |
| -------- | ----------------------------------- |
| `SERVER` | Game-Server (Paper, Spigot, etc.)   |
| `PROXY`  | Proxy-Server (Velocity, BungeeCord) |