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

# Players API

> Spieler verwalten und Cross-Server-Nachrichten senden

Die Players API ermöglicht das Abfragen von Spielern, Transferieren zwischen Servern und Senden von Rich-Text-Nachrichten mit Adventure. Zugriff über `api.player()`.

## Spieler abrufen

```java theme={null}
// Spieler nach UUID
api.player().get(uuid)
    .thenAccept(player -> {
        if (player != null) {
            System.out.println(player.getName() + " auf " + player.getConnectedServerName());
        }
    });

// Spieler nach Username
api.player().get("Steve")
    .thenAccept(player -> {
        if (player != null) {
            System.out.println("Gefunden: " + player.getUniqueId());
        }
    });

// Alle Online-Spieler
api.player().getOnlinePlayers()
    .thenAccept(players -> players.forEach(p ->
        System.out.println(p.getName())));

// Online-Spielerzahl
api.player().getOnlinePlayerCount()
    .thenAccept(count -> System.out.println("Online: " + count));
```

## Spieler-Aktionen

### Spieler transferieren

```java theme={null}
api.player().get(uuid).thenAccept(player -> {
    if (player != null) {
        player.connect("lobby-1").thenAccept(result -> {
            switch (result) {
                case SUCCESS -> System.out.println("Transfer erfolgreich");
                case SERVER_NOT_FOUND -> System.out.println("Server existiert nicht");
                case ALREADY_CONNECTED -> System.out.println("Bereits auf diesem Server");
                case CONNECTION_FAILED -> System.out.println("Transfer fehlgeschlagen");
            }
        });
    }
});
```

### Spieler kicken

```java theme={null}
player.kick(Component.text("Server wird neugestartet")
    .color(NamedTextColor.RED));
```

## Adventure-Integration

`CloudPlayer` implementiert Adventure's `Audience` Interface:

### Nachrichten senden

```java theme={null}
// Farbiger Text
player.sendMessage(Component.text("Erfolg!")
    .color(NamedTextColor.GREEN));

// Klickbarer Text
player.sendMessage(Component.text("Hier klicken")
    .clickEvent(ClickEvent.runCommand("/help"))
    .hoverEvent(HoverEvent.showText(Component.text("/help ausführen"))));
```

### Titles senden

```java theme={null}
player.showTitle(Title.title(
    Component.text("Willkommen!").color(NamedTextColor.GOLD),
    Component.text("auf dem Server").color(NamedTextColor.GRAY),
    Title.Times.times(
        Duration.ofMillis(500),
        Duration.ofSeconds(3),
        Duration.ofMillis(500)
    )
));
```

### Action Bar senden

```java theme={null}
player.sendActionBar(Component.text("⚔ Kampfmodus aktiviert")
    .color(NamedTextColor.RED));
```

## CloudPlayer Model

<ResponseField name="uniqueId" type="UUID" required>
  Spieler-UUID.
</ResponseField>

<ResponseField name="name" type="string" required>
  Spieler-Username.
</ResponseField>

<ResponseField name="displayName" type="string">
  Anzeigename des Spielers.
</ResponseField>

<ResponseField name="connectedServerName" type="string">
  Aktueller Server-Name.
</ResponseField>

<ResponseField name="connectedProxyName" type="string">
  Verbundener Proxy-Name.
</ResponseField>

<ResponseField name="online" type="boolean" required>
  Ob der Spieler aktuell online ist.
</ResponseField>

<ResponseField name="onlineTimeSeconds" type="long" required>
  Gesamte Online-Zeit in Sekunden.
</ResponseField>

<ResponseField name="sessionId" type="string | null">
  Aktive Session-ID oder `null`, wenn sie nicht verfügbar ist.
</ResponseField>

<ResponseField name="firstSeen" type="string">
  Erster Login-Zeitpunkt im ISO-8601-Format.
</ResponseField>

<ResponseField name="lastSeen" type="string">
  Letzter Login-Zeitpunkt im ISO-8601-Format.
</ResponseField>

<ResponseField name="properties" type="object">
  Spieler-spezifische Properties.
</ResponseField>

## ConnectResult

| Wert                | Beschreibung                      |
| ------------------- | --------------------------------- |
| `SUCCESS`           | Transfer erfolgreich              |
| `SERVER_NOT_FOUND`  | Zielserver existiert nicht        |
| `ALREADY_CONNECTED` | Spieler bereits auf diesem Server |
| `PLAYER_NOT_FOUND`  | Spieler ging offline              |
| `CONNECTION_FAILED` | Transfer fehlgeschlagen           |