Controller API

The Controller API is the central interface for managing your SimpleCloud infrastructure. It provides comprehensive control over server groups, individual servers, and real-time event handling through our Protocol Buffer based controllerApi.

Installation

Loading dependency information...

As soon as we release our first stable version, we'll publish the Maven package to Maven Central. Until then, you can use the snapshots repository to access the latest features.

Authentication

If you're using our Controller 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 controllerApi = ControllercontrollerApi.createCoroutineApi()

Other Programming Languages

Our Controller 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

createGroup

Creates a new server group template.

val group = Group(
    name = "lobby",
    type = ServerType.SERVER,
    minMemory = 512,
    maxMemory = 1024,
    startPort = 25565,
    minOnlineCount = 1,
    maxOnlineCount = 5,
    maxPlayers = 100,
    newServerPlayerRatio = 50,
    properties = mapOf("gamemode" to "LOBBY")
)

val createdGroup = controllerApi.getGroups().createGroup(group)

getGroupByName

Retrieves a specific group by its name.

val lobbyGroup = controllerApi.getGroups().getGroupByName("lobby")

getAllGroups

Retrieves all configured groups.

val allGroups = controllerApi.getGroups().getAllGroups()

getGroupsByType

Retrieves all groups of a specific type.

val serverGroups = controllerApi.getGroups().getGroupsByType(ServerType.SERVER)

updateGroup

Updates an existing group's configuration.

val updatedGroup = existingGroup.copy(
    maxPlayers = 200,
    maxMemory = 2048
)
controllerApi.getGroups().updateGroup(updatedGroup)

deleteGroup

Removes a server group.

controllerApi.getGroups().deleteGroup("lobby")

startServer

Starts a new server instance from a group template.

val server = controllerApi.getServers().startServer(
    groupName = "lobby",
    startCause = ServerStartCause.API_START
)

getAllServers

Retrieves all running servers.

val allServers = controllerApi.getServers().getAllServers()

getServerById

Retrieves a specific server by its unique ID.

val server = controllerApi.getServers().getServerById("0f0c2d1a-d7d5-4c7f-b7a9-c0e8e9b5a6b8")

getServersByGroup

Retrieves all servers belonging to a specific group.

val lobbyServers = controllerApi.getServers().getServersByGroup("lobby")

getServerByNumerical

Retrieves a specific server by its group name and numerical ID.

val specificServer = controllerApi.getServers().getServerByNumerical("lobby", 1)

getServersByType

Retrieves all servers of a specific type.

val serverServers = controllerApi.getServers().getServersByType(ServerType.SERVER)

updateServerState

Updates the state of a server.

controllerApi.getServers().updateServerState(
    id = "0f0c2d1a-d7d5-4c7f-b7a9-c0e8e9b5a6b8",
    state = ServerState.AVAILABLE
)

updateServerProperty

Updates a custom property of a server.

controllerApi.getServers().updateServerProperty(
    id = "0f0c2d1a-d7d5-4c7f-b7a9-c0e8e9b5a6b8",
    key = "gameMode",
    value = "CAPTURE_THE_FLAG"
)

stopServer

Stops a running server instance.

// Stop by ID
controllerApi.getServers().stopServer(
    id = "0f0c2d1a-d7d5-4c7f-b7a9-c0e8e9b5a6b8",
    stopCause = ServerStopCause.API_STOP
)

// Stop by group and numerical ID
controllerApi.getServers().stopServer(
    groupName = "lobby",
    numericalId = 1,
    stopCause = ServerStopCause.API_STOP
)

Data Models

Group Properties

The Group class represents a server group template with the following properties:

Property	Type	Description
name	`string`	Unique identifier for the group
type	`enum`	Server type (UNKNOWN_SERVER, SERVER, PROXY)
minMemory	`long`	Minimum RAM allocation in MB
maxMemory	`long`	Maximum RAM allocation in MB
startPort	`long`	Base port number for new servers
minOnlineCount	`long`	Minimum number of servers to keep running
maxOnlineCount	`long`	Maximum number of servers allowed
maxPlayers	`long`	Maximum players per server
newServerPlayerRatio	`long`	Player count threshold for starting new servers (-1 to disable)
properties	`Map<String, String>`	Custom key-value properties

Server Properties

The Server class represents a running server instance with the following properties:

Property	Type	Description
uniqueId	`string`	Unique identifier (e.g., "0f0c2d1a-d7d5-4c7f-b7a9-c0e8e9b5a6b8")
type	`enum`	Server type (UNKNOWN_SERVER, SERVER, PROXY)
group	`string`	Parent group name
host	`string`	Host machine identifier
numericalId	`int`	Numerical ID within group
ip	`string`	Server IP address
port	`long`	Server port
minMemory	`long`	Minimum RAM allocation in MB
maxMemory	`long`	Maximum RAM allocation in MB
maxPlayers	`long`	Maximum allowed players
playerCount	`long`	Current player count
properties	`Map<String, String>`	Custom key-value properties
state	`enum`	Server state (UNKNOWN_STATE, PREPARING, STARTING, AVAILABLE, INGAME, STOPPING)
createdAt	`LocalDateTime`	Creation timestamp
updatedAt	`LocalDateTime`	Last update timestamp