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

> Look up players, inspect presence, transfer or kick them, and manage player data

Use `api.player()` to find players and inspect their network presence. Prefer UUID lookup when you already know the player's UUID because usernames can change.

## Look up a player

Look up a player by UUID and check whether they are online before using their current server:

```java theme={null}
api.player().get(playerId).thenAccept(player -> {
    if (player == null || !player.isOnline()) {
        logger.info("Player is offline");
        return;
    }

    String serverName = player.getConnectedServerName();
    logger.info(serverName == null
        ? "Player is connected through a proxy"
        : "Player is on " + serverName);
});
```

`get(UUID)` returns `null` when SimpleCloud has no stored player with that UUID. You can also look up a player by their case-insensitive username:

```java theme={null}
api.player().get("Steve");
```

A `CloudPlayer` contains the state recorded when you queried it. Fetch the player again when a later action depends on their current presence.

## List online players

Use the online player list when you need the players themselves, or request only the count:

```java theme={null}
api.player().getOnlinePlayers();
api.player().getOnlinePlayerCount();
```

The list is empty and the count is `0` when no players are online.

## Inspect player data

| Method                     | Value                                        |
| -------------------------- | -------------------------------------------- |
| `getUniqueId()`            | Player UUID                                  |
| `getName()`                | Username                                     |
| `getDisplayName()`         | Stored display name                          |
| `isOnline()`               | Whether the player was online when queried   |
| `getConnectedProxyName()`  | Connected proxy name, or `null`              |
| `getConnectedServerName()` | Registered backend server name, or `null`    |
| `getSessionId()`           | Active session ID, or `null`                 |
| `getFirstSeen()`           | First-seen ISO-8601 timestamp, or `null`     |
| `getLastSeen()`            | Last-seen ISO-8601 timestamp, or `null`      |
| `getOnlineTimeSeconds()`   | Accumulated online time                      |
| `getProperties()`          | Immutable custom properties, or an empty map |

## Connect a player

Call `connect(...)` with the server name registered on the player's proxy, such as `lobby-1`. Do not pass the server UUID.

Connecting players requires the `simplecloud-api` provider on the Velocity or BungeeCord proxy.

| Result              | Meaning                                                                                                             |
| ------------------- | ------------------------------------------------------------------------------------------------------------------- |
| `SUCCESS`           | The player connected to the target server.                                                                          |
| `SERVER_NOT_FOUND`  | The proxy does not know the target server name.                                                                     |
| `ALREADY_CONNECTED` | The player is already connected to the target server.                                                               |
| `PLAYER_NOT_FOUND`  | Not currently returned by `connect(...)`; the transfer guide uses it when its player lookup finds no online player. |
| `CONNECTION_FAILED` | The connection could not be completed, including when the player is no longer available.                            |

See [Transfer a player to another server](/docs/en/developer/guides/player-transfer) for a complete transfer workflow.

## Kick a player

Pass an Adventure component as the reason shown to the player:

```java theme={null}
player.kick(Component.text("Server restarting"));
```

Kicking players requires the `simplecloud-api` provider on the Velocity or BungeeCord proxy.

## Send Adventure content

`CloudPlayer` implements Adventure's `Audience`, so you can send messages, action bars, titles, sounds, boss bars, books, and player-list headers and footers.

```java theme={null}
player.sendMessage(Component.text("Welcome!"));
player.sendActionBar(Component.text("Combat mode enabled"));
player.showTitle(Title.title(
    Component.text("Welcome"),
    Component.text("to the server")
));
```

Remote Adventure content requires the `simplecloud-api` provider on the player's Paper or Folia server.

## Manage online time and properties

Player properties store custom string values for your plugins.

| Task                      | Method                                                                                    |
| ------------------------- | ----------------------------------------------------------------------------------------- |
| Read online time          | `getOnlineTimeSeconds(playerId)`                                                          |
| Set online time           | `setOnlineTimeSeconds(playerId, seconds)`                                                 |
| Reset online time         | `resetOnlineTime(playerId)`                                                               |
| Add or remove time        | `addOnlineTimeSeconds(playerId, seconds)` or `removeOnlineTimeSeconds(playerId, seconds)` |
| Set one property          | `updatePlayerProperty(playerId, key, value)`                                              |
| Set several properties    | `updatePlayerProperties(playerId, properties)`                                            |
| Delete one property       | `deletePlayerProperty(playerId, key)`                                                     |
| Delete several properties | `deletePlayerProperties(playerId, keys)`                                                  |

Online time must be between `0` and `Integer.MAX_VALUE` seconds. Property updates merge the supplied values with the existing map; delete methods remove only the specified keys.