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.

Overview

The Controller API allows you to:

Create and manage server groups
Start and stop servers
Monitor server states
Configure server properties
Handle real-time events

Getting Started

1. Add the Dependency

Loading dependency information...

The API is currently available as a snapshot version. Once we release our first stable version, it will be published to Maven Central.

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 controllerApi = Controller.createCoroutineApi()

// For external applications (provide token directly)
val controllerApi = Controller.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

Group Management

Groups are templates for server instances. They define the configuration that new servers will use when started.

Create a Group

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)

Get Groups

// Get a specific group
val lobbyGroup = controllerApi.getGroups().getGroupByName("lobby")

// Get all groups
val allGroups = controllerApi.getGroups().getAllGroups()

// Get groups by type
val serverGroups = controllerApi.getGroups().getGroupsByType(ServerType.SERVER)

Update & Delete Groups

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

// Delete a group
controllerApi.getGroups().deleteGroup("lobby")

Server Management

Servers are instances created from group templates. The API provides comprehensive control over server lifecycle and properties.

Start & Stop Servers

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

// Stop a server by ID
controllerApi.getServers().stopServer(
id = "server-uuid",
stopCause = ServerStopCause.API_STOP
)

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

Query Servers

// Get all servers
val allServers = controllerApi.getServers().getAllServers()

// Get a specific server by ID
val server = controllerApi.getServers().getServerById("server-uuid")

// Get servers by group
val lobbyServers = controllerApi.getServers().getServersByGroup("lobby")

// Get a server by numerical ID
val specificServer = controllerApi.getServers().getServerByNumerical("lobby", 1)

// Get servers by type
val serverServers = controllerApi.getServers().getServersByType(ServerType.SERVER)

Update Server Properties

// Update server state
controllerApi.getServers().updateServerState(
    id = "server-uuid",
    state = ServerState.AVAILABLE
)

// Update custom property
controllerApi.getServers().updateServerProperty(
id = "server-uuid",
key = "gameMode",
value = "CAPTURE_THE_FLAG"
)

Data Models

Group 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

Property	Type	Description
uniqueId	`string`	Unique identifier
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