Players API

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:

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. Property updates merge the supplied values with the existing map; delete methods remove only the specified keys.

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