Player Droplet API

The Player Droplet API provides comprehensive player management and interaction capabilities across your SimpleCloud network, featuring both Future and Coroutine-based implementations.

Installation

Loading dependency information...

Authentication If you're using our Player Droplet API in a Minecraft server, the token is automatically provided via environment variables. For external applications, you'll need to use the master authentication token. You can find the master token in /components/.secrets/auth.secret in your SimpleCloud directory.

// Uses CONTROLLER_SECRET from environment
val playerApi = PlayerApi.createCoroutineApi()

Other Programming Languages

Our Player Droplet API is primarily written in Kotlin, but we also have Proto Definitions available for other languages. You can find the definitions in the buf.build/simplecloud/proto-specs repository.

It provides support for all kinds of languages, including:

Java
TypeScript
Go
Rust
Other languages supported by Protocol Buffers

API Initialization

val playerApi = PlayerApi.createCoroutineApi()

Player Management

getOfflinePlayer

Retrieves player data regardless of online status.

val player = playerApi.getOfflinePlayer(name)
println("Player ${player.getName()} first joined at ${player.getFirstLogin()}")

getOnlinePlayer

Retrieves data for currently online players.

val player = playerApi.getOnlinePlayer(name)
println("Player ${player.getName()} is on server ${player.getConnectedServerName()}")

getOnlinePlayers

Retrieves a list of all currently online players.

val players = playerApi.getOnlinePlayers()
players.forEach { player ->
    println("${player.getName()} on ${player.getConnectedServerName()}")
}

getOnlinePlayerCount

Returns the total number of online players.

val count = playerApi.getOnlinePlayerCount()
println("Online players: $count")

connectPlayer

Connects a player to a specific server.

val result = playerApi.connectPlayer(uniqueId, serverName)
println("Connection result: $result")

isOnline

Checks if a player is currently online.

val isOnline = playerApi.isOnline(uniqueId)
println("Player online: $isOnline")

updateServer

Updates a player's current server information.

val success = playerApi.updateServer(uniqueId, serverName)
println("Server update success: $success")

Player Properties

getUniqueId

Returns the player's unique identifier.

val uuid = player.getUniqueId()
println("Player UUID: $uuid")

getName

Returns the player's username.

val name = player.getName()
println("Player name: $name")

getDisplayName

Returns the player's custom display name, if set.

val displayName = player.getDisplayName()
println("Display name: $displayName")

getFirstLogin

Returns the timestamp of the player's first login.

val firstLogin = player.getFirstLogin()
println("First joined: ${Date(firstLogin)}")

getLastLogin

Returns the timestamp of the player's most recent login.

val lastLogin = player.getLastLogin()
println("Last login: ${Date(lastLogin)}")

getOnlineTime

Returns the player's total time spent on the network.

val onlineTime = player.getOnlineTime()
println("Total online time: ${TimeUnit.MILLISECONDS.toHours(onlineTime)} hours")

getSessionTime

Returns the duration of the player's current session.

val sessionTime = player.getSessionTime()
println("Current session: ${TimeUnit.MILLISECONDS.toMinutes(sessionTime)} minutes")

getConnectedServerName

Returns the name of the server the player is currently connected to.

val serverName = player.getConnectedServerName()
println("Connected to server: ${serverName ?: "None"}")

getConnectedProxyName

Returns the name of the proxy server the player is connected through.

val proxyName = player.getConnectedProxyName()
println("Connected via proxy: $proxyName")

isOnline

Returns whether the player is currently online.

val online = player.isOnline()
println("Player online: $online")

kick

Kicks the player from the network with a specified reason.

player.kick(Component.text("Maintenance mode activated")
    .color(NamedTextColor.RED))

Adventure Integration

Sending Messages

Send rich text messages to players.

player.sendMessage(Component.text("Hello, world!"))

Titles

Display titles and subtitles to players.

player.showTitle(Title.title(
    Component.text("Welcome!").color(NamedTextColor.GOLD),
    Component.text("Enjoy your stay").color(NamedTextColor.YELLOW),
    Title.Times.of(
        Duration.ofSeconds(1),
        Duration.ofSeconds(3),
        Duration.ofSeconds(1)
    )
))

Sound Effects

Play sounds to players.

player.playSound(
    Sound.sound(
        Key.key("entity.player.levelup"),
        Sound.Source.MASTER,
        1.0f,
        1.0f
    )
)