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.

Overview

The Player Droplet API allows you to:

Manage players across your entire network
Track player states and properties
Send rich text messages and effects
Handle player connections and transfers
Integrate with Adventure API for rich content

Getting Started

1. Add the Dependency

Loading dependency information...

2. Choose Your Language

While our API is primarily written in Kotlin, we support multiple languages through our Protocol Buffer specifications:

Java (Native support)
Kotlin (Native support)
TypeScript
Go
Rust
Other languages supported by Protocol Buffers

3. Initialize the API

// For Minecraft servers (uses environment variables)
val playerApi = PlayerApi.createCoroutineApi()

// For external applications (provide token directly)
val playerApi = PlayerApi.createCoroutineApi("your-auth-token")

4. Authentication

The API uses token-based authentication:

Minecraft Servers: Token is automatically provided via CONTROLLER_SECRET environment variable
External Applications: Use the master token from /components/.secrets/auth.secret

Player Management

The API provides comprehensive methods to manage players across your network.

Query Players

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

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

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

// Get online player count
val count = playerApi.getOnlinePlayerCount()
println("Online players: $count")

Player Actions

// Connect player to a server
val result = playerApi.connectPlayer(uniqueId, serverName)
println("Connection result: $result")

// Check if player is online
val isOnline = playerApi.isOnline(uniqueId)
println("Player online: $isOnline")

// Update player's server
val success = playerApi.updateServer(uniqueId, serverName)
println("Server update success: $success")

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

Adventure Integration

The API provides rich content delivery through Adventure API integration.

Messages and Titles

// Send a simple message
player.sendMessage(Component.text("Hello, world!"))

// Send formatted message
player.sendMessage(
    Component.text()
        .content("Welcome to the server!")
        .color(NamedTextColor.GOLD)
        .decoration(TextDecoration.BOLD, true)
        .build()
)

// Send interactive message
player.sendMessage(
    Component.text()
        .content("Click here!")
        .color(NamedTextColor.AQUA)
        .clickEvent(ClickEvent.openUrl("https://example.com"))
        .hoverEvent(HoverEvent.showText(Component.text("Visit website")))
        .build()
)

// Show title with subtitle
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)
    )
))

// Show action bar
player.sendActionBar(
    Component.text()
        .content("+100 Experience")
        .color(NamedTextColor.GREEN)
        .build()
)

Sound Effects

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

// Play positioned sound
player.playSound(
    Sound.sound(
        Key.key("block.note_block.pling"),
        Sound.Source.BLOCK,
        1.0f,
        1.0f
    ),
    x = 0.0,
    y = 64.0,
    z = 0.0
)

Player Properties

The API provides access to various player properties and statistics.

Basic Properties

Property	Type	Description
uniqueId	`UUID`	Player's unique identifier
name	`String`	Player's username
displayName	`String?`	Custom display name (if set)
firstLogin	`Long`	Timestamp of first network join
lastLogin	`Long`	Timestamp of most recent join
onlineTime	`Long`	Total time spent on network (ms)
sessionTime	`Long`	Current session duration (ms)

Connection Properties

Property	Type	Description
connectedServerName	`String?`	Current server name
connectedProxyName	`String?`	Current proxy name
clientLanguage	`String`	Player's client language setting
numericalClientVersion	`Int`	Minecraft protocol version
onlineMode	`Boolean`	Whether authenticated with Mojang
online	`Boolean`	Current online status