API für Spieler

Spieler suchen

Die Beispiele verwenden den unter Installation erstellten gemeinsamen CloudApi-Client und gehören in die Methoden deines Plugins. Wenn du die UUID eines Spielers kennst, verwende sie statt des Benutzernamens, da sich dieser ändern kann. Suche einen Spieler anhand seiner UUID und prüfe, ob er online ist, bevor du auf seinen aktuellen Server zugreifst:

api.player().get(playerId).thenAccept(player -> {
    if (player == null || !player.isOnline()) {
        logger.info("Spieler ist offline");
        return;
    }

    String serverName = player.getConnectedServerName();
    logger.info(serverName == null
        ? "Spieler ist nur mit einem Proxy verbunden"
        : "Spieler ist auf " + serverName);
});

get(UUID) gibt null zurück, wenn SimpleCloud keinen gespeicherten Spieler mit dieser UUID kennt. Du kannst einen Spieler auch anhand seines Benutzernamens suchen; dabei wird die Groß- und Kleinschreibung nicht berücksichtigt:

api.player().get("Steve");

Ein CloudPlayer enthält den Zustand zum Zeitpunkt der Abfrage. Rufe den Spieler erneut ab, wenn eine spätere Aktion von seiner aktuellen Präsenz abhängt.

Spieler auflisten, die online sind

Rufe die Liste der Spieler ab, die online sind, wenn du die Spieler selbst benötigst, oder frage nur ihre Anzahl ab:

api.player().getOnlinePlayers();
api.player().getOnlinePlayerCount();

Wenn kein Spieler online ist, ist die Liste leer und die Anzahl 0.

Spielerdaten prüfen

Methode	Wert
`getUniqueId()`	Spieler-UUID
`getName()`	Benutzername
`getDisplayName()`	Gespeicherter Anzeigename
`isOnline()`	Ob der Spieler zum Zeitpunkt der Abfrage online war
`getConnectedProxyName()`	Name des verbundenen Proxys oder `null`
`getConnectedServerName()`	Name des registrierten Backend-Servers oder `null`
`getSessionId()`	Aktive Sitzungs-ID oder `null`
`getFirstSeen()`	Zeitstempel der ersten Sichtung im ISO-8601-Format oder `null`
`getLastSeen()`	Zeitstempel der letzten Sichtung im ISO-8601-Format oder `null`
`getOnlineTimeSeconds()`	Kumulierte Onlinezeit
`getProperties()`	Unveränderliche benutzerdefinierte Eigenschaften oder eine leere Map

Spieler verbinden

Rufe connect(...) mit dem auf dem Proxy des Spielers registrierten Servernamen auf, zum Beispiel lobby-1. Übergib nicht die Server-UUID. Zum Verbinden von Spielern muss der Provider simplecloud-api auf dem Velocity- oder BungeeCord-Proxy installiert sein.

Ergebnis	Bedeutung
`SUCCESS`	Der Spieler wurde mit dem Zielserver verbunden.
`SERVER_NOT_FOUND`	Der Proxy kennt den Namen des Zielservers nicht.
`ALREADY_CONNECTED`	Der Spieler ist bereits mit dem Zielserver verbunden.
`PLAYER_NOT_FOUND`	Wird derzeit nicht von `connect(...)` zurückgegeben; der Leitfaden zum Verschieben von Spielern verwendet es, wenn seine Spielersuche keinen Spieler findet, der online ist.
`CONNECTION_FAILED`	Die Verbindung konnte nicht hergestellt werden, beispielsweise weil der Spieler nicht mehr verfügbar ist.

Unter Spieler auf einen anderen Server verschieben findest du einen vollständigen Ablauf zum Verschieben eines Spielers.

Spieler kicken

Übergib eine Adventure-Komponente mit dem Grund, der dem Spieler angezeigt wird:

player.kick(Component.text("Der Server startet neu"));

Zum Kicken von Spielern muss der Provider simplecloud-api auf dem Velocity- oder BungeeCord-Proxy installiert sein.

Adventure-Inhalte senden

CloudPlayer implementiert Audience von Adventure. Du kannst daher Nachrichten, Actionbars, Titel, Sounds, Bossbars, Bücher sowie Kopf- und Fußzeilen der Spielerliste senden.

player.sendMessage(Component.text("Willkommen!"));
player.sendActionBar(Component.text("Kampfmodus aktiviert"));
player.showTitle(Title.title(
    Component.text("Willkommen"),
    Component.text("auf dem Server")
));

Für entfernte Adventure-Inhalte muss der Provider simplecloud-api auf dem Paper- oder Folia-Server des Spielers installiert sein.

Onlinezeit und Eigenschaften verwalten

Spielereigenschaften speichern benutzerdefinierte Zeichenketten für deine Plugins.

Aufgabe	Methode
Onlinezeit auslesen	`getOnlineTimeSeconds(playerId)`
Onlinezeit festlegen	`setOnlineTimeSeconds(playerId, seconds)`
Onlinezeit zurücksetzen	`resetOnlineTime(playerId)`
Zeit hinzufügen oder entfernen	`addOnlineTimeSeconds(playerId, seconds)` oder `removeOnlineTimeSeconds(playerId, seconds)`
Eine Eigenschaft festlegen	`updatePlayerProperty(playerId, key, value)`
Mehrere Eigenschaften festlegen	`updatePlayerProperties(playerId, properties)`
Eine Eigenschaft löschen	`deletePlayerProperty(playerId, key)`
Mehrere Eigenschaften löschen	`deletePlayerProperties(playerId, keys)`

Die Onlinezeit muss zwischen 0 und Integer.MAX_VALUE Sekunden liegen. Die Methoden zum Addieren und Subtrahieren lesen den aktuellen Wert, bevor sie das Ergebnis schreiben. Parallele Änderungen können sich deshalb gegenseitig überschreiben. Aktualisierungen von Eigenschaften führen die übergebenen Werte mit der vorhandenen Map zusammen; Löschmethoden entfernen nur die angegebenen Schlüssel. Die zusammengeführten Eigenschaften dürfen als JSON höchstens 4 KB groß sein.

Getting Started

Cloud API

Guides

Spieler suchen

Spieler auflisten, die online sind

Spielerdaten prüfen

Spieler verbinden

Spieler kicken

Adventure-Inhalte senden

Onlinezeit und Eigenschaften verwalten

​Spieler suchen

​Spieler auflisten, die online sind

​Spielerdaten prüfen

​Spieler verbinden

​Spieler kicken

​Adventure-Inhalte senden

​Onlinezeit und Eigenschaften verwalten

Spieler suchen

Spieler auflisten, die online sind

Spielerdaten prüfen

Spieler verbinden

Spieler kicken

Adventure-Inhalte senden

Onlinezeit und Eigenschaften verwalten