Players API

Look up a player

The examples use the shared CloudApi client created in Installation and belong inside your plugin’s methods. Prefer a player’s UUID when you know it because usernames can change. Look up a player by UUID and check whether they are online before using their current server:

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:

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:

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 for a complete transfer workflow.

Kick a player

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

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.

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. The add and remove helpers read the current value before writing the result, so concurrent changes can overwrite one another. Property updates merge the supplied values with the existing map, while delete methods remove only the specified keys. The merged properties must fit within 4 KB when encoded as JSON.

Getting Started

Cloud API

Guides

REST API Reference

Look up a player

List online players

Inspect player data

Connect a player

Kick a player

Send Adventure content

Manage online time and properties

​Look up a player

​List online players

​Inspect player data

​Connect a player

​Kick a player

​Send Adventure content

​Manage online time and properties

Look up a player

List online players

Inspect player data

Connect a player

Kick a player

Send Adventure content

Manage online time and properties