API für Serverinstanzen

Verfügbare Kapazität finden

Die Beispiele verwenden den unter Installation erstellten gemeinsamen CloudApi-Client und gehören in die Methoden deines Plugins. Mit ServerQuery kannst du Instanzen nach Quelle, Zustand, Host oder numerischer ID suchen. Dieses Beispiel berechnet die gemeldeten freien Plätze aller spielbereiten Lobby-Server:

ServerQuery query = ServerQuery.create()
    .filterByServerGroupName("lobby")
    .filterByState(ServerState.AVAILABLE, ServerState.INGAME);

api.server().getAllServers(query)
    .thenApply(servers -> servers.stream()
        .filter(server -> server.getPlayerCount() != null)
        .mapToInt(server -> Math.max(
            0,
            server.getMaxPlayers() - server.getPlayerCount()
        ))
        .sum())
    .thenAccept(capacity ->
        System.out.println("Lobby-Kapazität: " + capacity));

Das Ergebnis ist eine Momentaufnahme und keine Reservierung. Wenn du damit auswählst, mit welchem Server ein Spieler verbunden werden soll, behalte die Routing-Regeln in deiner Anwendung und verarbeite das Verbindungsergebnis. Unter Spieler mit Autoscaling weiterleiten findest du einen vollständigen Routing-Ablauf. Rufe getAllServers() ohne Abfrage auf, um alle Instanzen zurückzugeben, oder verwende getServersByGroup("lobby") als Kurzform für einen Gruppennamen. Listenmethoden geben eine leere Liste zurück, wenn nichts übereinstimmt.

Filter von ServerQuery

Wiederholte Aufrufe eines Filters für mehrere Werte fügen der Abfrage weitere Werte hinzu.

ServerQuery

Stimmt mit einer oder mehreren Gruppen-IDs überein.

ServerQuery

Stimmt mit einem oder mehreren Lebenszykluszuständen überein.

ServerQuery

Stimmt mit Instanzen überein, die auf einem bestimmten Serverhost laufen.

ServerQuery

Stimmt mit der Instanz eines bestimmten persistenten Servers überein.

ServerQuery

Stimmt mit Quellen des Typs SERVER oder PROXY überein.

ServerQuery

Stimmt mit einem oder mehreren Namen von Gruppen oder persistenten Servern überein.

ServerQuery

Stimmt mit Quellen überein, die mindestens einen der angegebenen Tags besitzen.

ServerQuery

Stimmt mit einer oder mehreren numerischen IDs überein.

ServerQuery

Sortiert nach created_at, updated_at, numerical_id oder state.

ServerQuery

Verwendet asc oder desc.

Einzelnen Server suchen

Suche eine Instanz anhand ihrer eindeutigen ID oder anhand ihres Gruppennamens und ihrer numerischen ID:

api.server().getServerById("server-uuid")
    .thenAccept(server -> System.out.println(server.getState()));

api.server().getServerByNumericalId("lobby", 1)
    .thenAccept(server -> System.out.println(server.getServerId()));

Das zurückgegebene Future schlägt fehl, wenn kein passender Server vorhanden ist.

Aktuellen Server abrufen

Code, der innerhalb eines von SimpleCloud verwalteten Servers ausgeführt wird, kann seine eigene Instanz ermitteln:

api.server().getCurrentServer()
    .thenAccept(server -> System.out.println(server.getServerId()));

getCurrentServer() verwendet die Umgebungsvariable SIMPLECLOUD_UNIQUE_ID. Das zurückgegebene Future schlägt fehl, wenn der aktuelle Prozess keiner Instanz zugeordnet ist.

Auf die zugehörige Konfiguration zugreifen

Jede Instanz gehört entweder zu einer Gruppe oder zu einem persistenten Server. getServerBase() stellt deren gemeinsame Konfiguration bereit; getGroup() und getPersistentServer() geben Zugriff auf quellenspezifische Felder. Um zu ändern, wie Instanzen erstellt werden, aktualisiere stattdessen die zugehörige Gruppe oder den zugehörigen persistenten Server.

api.server().getServerById("server-uuid")
    .thenAccept(server -> {
        if (server.isFromGroup()) {
            System.out.println("Gruppe: " + server.getGroup().getName());
        } else {
            System.out.println(
                "Persistent server: " +
                server.getPersistentServer().getName()
            );
        }

        System.out.println(
            "Configured slots: " + server.getServerBase().getMaxPlayers()
        );
    });

Für eine Instanz ist nur eine der Methoden getGroup() und getPersistentServer() verfügbar. Vermeide die veraltete Methode getServerGroup(), die bei Instanzen persistenter Server eine Exception auslöst.

Instanz aktualisieren

UpdateServerRequest ändert nur die von dir festgelegten Felder:

UpdateServerRequest update = UpdateServerRequest.builder()
    .maxPlayers(64)
    .maxMemory(2048)
    .build();

api.server().updateServer("server-uuid", update)
    .thenAccept(server ->
        System.out.println("Aktualisierte Plätze: " + server.getMaxPlayers()));

Der Builder unterstützt state, properties, minMemory, maxMemory und maxPlayers. Änderungen gelten für diese Instanz, nicht für ihre zugehörige Konfiguration. playerCount ist eine vom Serverhost gemeldete Laufzeit-Beobachtung. Die HTTP-API behandelt das Feld als schreibgeschützt und weist es in Update-Anfragen als unbekannt zurück. Die Plattform meldet normalerweise state. Lege diesen Wert nur fest, wenn deine Integration für diese Meldung zuständig ist.

Instanzeigenschaften verwalten

Eigenschaften verknüpfen Anwendungsdaten mit einer einzelnen Instanz. Aktualisierungen werden mit der vorhandenen Map zusammengeführt.

api.server().updateServerProperties(
    "server-uuid",
    Map.of("gameMode", "competitive", "map", "castle")
);

api.server().deleteServerProperty("server-uuid", "map");

Verwende updateServerProperty, um einen einzelnen Schlüssel festzulegen, und deleteServerProperties, um mehrere Schlüssel zu entfernen. Jede Methode gibt die daraus resultierende Eigenschafts-Map zurück.

Instanz stoppen

api.server().stopServer("server-uuid")
    .thenRun(() -> System.out.println("Stopp eingeleitet"));

Das Future wird abgeschlossen, wenn SimpleCloud den Stopp einleitet, nicht erst nach Abschluss der Bereinigung. Verwende Events für Serverzustände, wenn dein Plugin die späteren Übergänge im Lebenszyklus beobachten muss.

Das Stoppen einer Instanz deaktiviert weder ihre Gruppe noch ihren persistenten Server. SimpleCloud kann eine Ersatzinstanz erstellen, um die Quellkonfiguration einzuhalten. Ändere diese Konfiguration zuerst, wenn der Server offline bleiben muss.

Servermodell

string

erforderlich

Eindeutige Instanz-ID.

integer

erforderlich

Numerische ID innerhalb der Quellgruppe oder des persistenten Servers.

string | null

ID der Quellgruppe oder null bei einer Instanz eines persistenten Servers.

string | null

ID des persistenten Quellservers oder null bei einer Gruppeninstanz.

string

erforderlich

Serverhost, auf dem die Instanz läuft.

string

erforderlich

Netzwerk, zu dem die Instanz gehört.

string | null

Zugewiesene IP-Adresse oder null, solange keine verfügbar ist.

integer | null

Zugewiesener Port oder null, solange keiner verfügbar ist.

integer

erforderlich

Minimaler Arbeitsspeicher in MB.

integer

erforderlich

Maximaler Arbeitsspeicher in MB.

number | null

Aktuelle CPU-Auslastung in Prozent oder null, wenn sie nicht verfügbar ist.

number | null

Aktuelle Arbeitsspeichernutzung in MB oder null, wenn sie nicht verfügbar ist.

integer | null

Aktuelle Anzahl verbundener Spieler oder null, wenn sie nicht verfügbar ist.

integer

erforderlich

Spielerlimit der Instanz.

ServerState

erforderlich

Aktueller Lebenszykluszustand.

string

erforderlich

Erstellungszeitpunkt im ISO-8601-Format.

string

erforderlich

Zeitpunkt der letzten Aktualisierung im ISO-8601-Format.

string | null

Zeitstempel der letzten Aktivität im ISO-8601-Format oder null, wenn er nicht verfügbar ist.

Map<String, Object> | null

Instanzeigenschaften oder null, wenn keine verfügbar sind.

Blueprint | null

Reservierter Accessor. Die aktuelle Implementierung gibt null zurück; verwende stattdessen die Quellkonfiguration.

ServerBase

erforderlich

Gemeinsame Konfiguration der Quellgruppe oder des persistenten Servers.

Group | null

Quellgruppe oder null bei einer Instanz eines persistenten Servers.

PersistentServer | null

Persistenter Quellserver oder null bei einer Gruppeninstanz.

Serverzustände

Zustand	Bedeutung
`UNKNOWN_STATE`	Unbekannt oder nicht angegeben.
`PREPARING`	SimpleCloud bereitet die Instanz vor.
`STARTING`	Der Serverprozess wird gestartet.
`AVAILABLE`	Bereit, Verbindungen anzunehmen.
`INGAME`	Wird mit aktiven Spielern ausgeführt.
`STOPPING`	Das Herunterfahren läuft.
`CLEANUP`	Der Prozess wurde beendet und die Bereinigung läuft.

Getting Started

Cloud API

Guides

API für Serverinstanzen

Verfügbare Kapazität finden

Einzelnen Server suchen

Aktuellen Server abrufen

Auf die zugehörige Konfiguration zugreifen

Instanz aktualisieren

Instanzeigenschaften verwalten

Instanz stoppen

Servermodell

Serverzustände

​Verfügbare Kapazität finden

​Einzelnen Server suchen

​Aktuellen Server abrufen

​Auf die zugehörige Konfiguration zugreifen

​Instanz aktualisieren

​Instanzeigenschaften verwalten

​Instanz stoppen

​Servermodell

​Serverzustände

Verfügbare Kapazität finden

Einzelnen Server suchen

Aktuellen Server abrufen

Auf die zugehörige Konfiguration zugreifen

Instanz aktualisieren

Instanzeigenschaften verwalten

Instanz stoppen

Servermodell

Serverzustände