Skip to main content

Documentation Index

Fetch the complete documentation index at: https://new-docs.simplecloud.app/llms.txt

Use this file to discover all available pages before exploring further.

The Players API lets you query players, transfer them between servers, and send rich-text messages using Adventure. Access it via api.player().

​
Get Players

// Get player by UUID
api.player().get(uuid)
    .thenAccept(player -> {
        if (player != null) {
            System.out.println(player.getName() + " on " + player.getConnectedServerName());
        }
    });

// Get player by username
api.player().get("Steve")
    .thenAccept(player -> { ... });

// Get all online players
api.player().getOnlinePlayers()
    .thenAccept(players -> players.forEach(p ->
        System.out.println(p.getName())));

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

​
Player Actions

​
Transfer Player

api.player().get(uuid).thenAccept(player -> {
    if (player != null) {
        player.connect("lobby-1").thenAccept(result -> {
            switch (result) {
                case SUCCESS -> System.out.println("Transferred!");
                case SERVER_NOT_FOUND -> System.out.println("Server doesn't exist");
                case ALREADY_CONNECTED -> System.out.println("Already on that server");
                case CONNECTION_FAILED -> System.out.println("Connection failed");
            }
        });
    }
});

​
Kick Player

player.kick(Component.text("Server restarting")
    .color(NamedTextColor.RED));

​
Adventure Integration

CloudPlayer implements Adventure’s Audience interface, giving you access to all Adventure messaging features:

​
Send Messages

// Plain text
player.sendMessage(Component.text("Hello!"));

// Colored text
player.sendMessage(Component.text("Success!")
    .color(NamedTextColor.GREEN));

// Styled text
player.sendMessage(Component.text("Important")
    .color(NamedTextColor.GOLD)
    .decorate(TextDecoration.BOLD));

// Clickable text
player.sendMessage(Component.text("Click here")
    .clickEvent(ClickEvent.runCommand("/help"))
    .hoverEvent(HoverEvent.showText(Component.text("Run /help"))));

​
Send Titles

player.showTitle(Title.title(
    Component.text("Welcome!").color(NamedTextColor.GOLD),
    Component.text("to the server").color(NamedTextColor.GRAY),
    Title.Times.times(
        Duration.ofMillis(500),   // fade in
        Duration.ofSeconds(3),    // stay
        Duration.ofMillis(500)    // fade out
    )
));

​
Send Action Bar

player.sendActionBar(Component.text("⚔ Combat Mode Enabled")
    .color(NamedTextColor.RED));

​
Play Sounds

player.playSound(Sound.sound(
    Key.key("entity.experience_orb.pickup"),
    Sound.Source.PLAYER,
    1.0f,  // volume
    1.0f   // pitch
));

​
Boss Bars

BossBar bar = BossBar.bossBar(
    Component.text("Event Progress"),
    0.5f,  // progress (0.0 to 1.0)
    BossBar.Color.PURPLE,
    BossBar.Overlay.PROGRESS
);

player.showBossBar(bar);

// Update progress
bar.progress(0.75f);

// Remove when done
player.hideBossBar(bar);

player.sendPlayerListHeaderAndFooter(
    Component.text("My Server").color(NamedTextColor.GOLD),
    Component.text("play.example.com").color(NamedTextColor.GRAY)
);
For more detailed examples in both Java and Kotlin, see Adventure Integration.

​
CloudPlayer Model

PropertyTypeDescription
uniqueIdUUIDPlayer’s UUID
nameStringPlayer’s username
displayNameStringPlayer’s display name
connectedServerNameStringCurrent server name
connectedProxyNameStringConnected proxy name
onlinebooleanWhether the player is currently online
onlineTimeSecondslongAccumulated online time in seconds
sessionIdStringActive session ID, null if unavailable
firstSeenStringFirst login timestamp (ISO-8601)
lastSeenStringLast login timestamp (ISO-8601)
propertiesMap<String, String>Player’s properties

​
ConnectResult

ValueDescription
SUCCESSTransfer successful
SERVER_NOT_FOUNDTarget server doesn’t exist
ALREADY_CONNECTEDPlayer already on that server
PLAYER_NOT_FOUNDPlayer went offline
CONNECTION_FAILEDTransfer failed

​
Broadcast to All Players

api.player().getOnlinePlayers().thenAccept(players -> {
    Component message = Component.text("[Announcement] ")
        .color(NamedTextColor.GOLD)
        .append(Component.text("Server restarting in 5 minutes")
            .color(NamedTextColor.WHITE));

    players.forEach(player -> player.sendMessage(message));
});