Groups API

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

Gruppen abrufen

// Alle Gruppen abrufen
api.group().getAllGroups()
    .thenAccept(groups -> groups.forEach(g -> System.out.println(g.getName())));

// Gruppen mit Filtern abrufen
GroupQuery query = GroupQuery.create()
    .filterByName("lobby")
    .filterByType(GroupServerType.SERVER);

api.group().getAllGroups(query)
    .thenAccept(groups -> groups.forEach(group ->
        System.out.println(group.getServerGroupId())));

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

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

Gruppe erstellen

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.getServerGroupId()));

Gruppe aktualisieren

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

api.group().deleteGroup("group-uuid")
    .thenRun(() -> System.out.println("Gelöscht: group-uuid"));

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

Gruppen-Properties

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

// Properties hinzufügen oder aktualisieren (merged mit bestehenden)
Map<String, Object> 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

string

erforderlich

Eindeutige Server-Gruppen-ID.

string

erforderlich

Gruppenname.

GroupServerType

erforderlich

Gruppentyp. Nutze SERVER für Spielserver oder PROXY für Proxy-Server.

integer

erforderlich

Minimaler Speicher in MB.

integer

erforderlich

Maximaler Speicher in MB.

integer

erforderlich

Spielerlimit pro Server.

integer

erforderlich

Minimale Anzahl laufender Server.

integer

erforderlich

Maximale Anzahl erlaubter Server.

object

erforderlich

Eigene Metadaten, die Server der Gruppe übernehmen.

ScalingConfig

erforderlich

Auto-Scaling-Einstellungen.

DeploymentConfig

erforderlich

Host-Deployment-Einstellungen.

SourceConfig

erforderlich

Blueprint- oder Image-Quelle, aus der Server erstellt werden.

ScalingConfig

integer

erforderlich

Minimale Anzahl laufender Server.

integer

erforderlich

Maximale Anzahl erlaubter Server.

ScalingMode

erforderlich

Scaling-Strategie. Nutze SLOTS für freie Spielerplätze oder SERVERS für serverbasierte Skalierung.

integer

Freie Slots, die bei SLOTS-Scaling verfügbar bleiben sollen.

number

Scale-up-Schwelle zwischen 0 und 1.

ScaleDownConfig

erforderlich

Einstellungen für das Herunterskalieren.

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.

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

Server-Start einreihen

Du kannst einen Start über die Gruppen-ID einreihen oder zuerst die Gruppe per Name auflösen:

// Start nach Gruppen-ID einreihen
api.group().requestServerStart("group-uuid")
    .thenRun(() -> System.out.println("Start-Anfrage angenommen"));

// Start nach Gruppenname einreihen
api.group().getGroupByName("lobby")
    .thenCompose(group -> {
        if (group == null) {
            return CompletableFuture.failedFuture(
                new IllegalArgumentException("Gruppe nicht gefunden: lobby"));
        }
        return api.group().requestServerStart(group);
    })
    .thenRun(() -> System.out.println("Start-Anfrage für lobby angenommen"));

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

api.group().getServerStartQueue()
    .thenAccept(queue -> {
        System.out.println("Gruppen mit Queue-Daten: " + queue.getCount());
        System.out.println("Wartend: " + queue.getQueuedStarts());
        System.out.println("Fehlgeschlagen: " + queue.getFailedStarts());

        GroupStartQueueEntry lobby = queue.findByServerGroupName("lobby");
        if (lobby != null) {
            System.out.println("Lobby-Starts: " + lobby.getTotalStarts());
        }
    });

Eingereihte Starts löschen

Alle ausstehenden und fehlgeschlagenen Starts einer bestimmten Gruppe entfernen:

api.group().clearServerStartQueue("group-uuid")
    .thenRun(() -> System.out.println("Warteschlange für group-uuid geleert"));

Start-Warteschlangen-Übersicht

getServerStartQueue() gibt eine GroupStartQueue zurück.

integer

erforderlich

Anzahl der Gruppen mit Queue-Daten.

integer

erforderlich

Anzahl wartender Starts über alle Gruppen.

integer

erforderlich

Anzahl fehlgeschlagener Starts über alle Gruppen.

integer

erforderlich

Gesamtzahl aller Queue-Einträge.

List<GroupStartQueueEntry>

erforderlich

Queue-Daten nach Server-Gruppe gruppiert.

Queue-Eintrag pro Gruppe

string | null

Server-Gruppen-ID.

string | null

Server-Gruppenname.

integer

erforderlich

Anzahl wartender Starts für die Gruppe.

integer

erforderlich

Anzahl fehlgeschlagener Starts für die Gruppe.

integer

erforderlich

Gesamtzahl der Queue-Einträge für die Gruppe.

List<GroupStartQueueItem>

erforderlich

Persistierte Start-Anfragen für die Gruppe.

Queue-Item

string

erforderlich

Eindeutige Kennung des eingereihten Starts.

string | null

Zeitstempel der Einreihung im ISO-8601-Format.

GroupStartQueueItemStatus

erforderlich

Status des Queue-Items. Mögliche Werte sind PENDING, FAILED und UNKNOWN.

string | null

Grund des Fehlschlags, falls zutreffend.

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

GroupServerType

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

Getting Started

Cloud API

Guides

Gruppen abrufen

Gruppe erstellen

Gruppe aktualisieren

Gruppe löschen

Gruppen-Properties

Group Model

ScalingConfig

Server-Start-Warteschlange

Server-Start einreihen

Eingereihte Starts auflisten

Eingereihte Starts löschen

Start-Warteschlangen-Übersicht

Queue-Eintrag pro Gruppe

Queue-Item

GroupServerType

​Gruppen abrufen

​Gruppe erstellen

​Gruppe aktualisieren

​Gruppe löschen

​Gruppen-Properties

​Group Model

​ScalingConfig

​Server-Start-Warteschlange

​Server-Start einreihen

​Eingereihte Starts auflisten

​Eingereihte Starts löschen

​Start-Warteschlangen-Übersicht

​Queue-Eintrag pro Gruppe

​Queue-Item

​GroupServerType

Gruppen abrufen

Gruppe erstellen

Gruppe aktualisieren

Gruppe löschen

Gruppen-Properties

Group Model

ScalingConfig

Server-Start-Warteschlange

Server-Start einreihen

Eingereihte Starts auflisten

Eingereihte Starts löschen

Start-Warteschlangen-Übersicht

Queue-Eintrag pro Gruppe

Queue-Item

GroupServerType