Codestin Search App

Initialization

Before you can use the Servers API, you need to initialize the Controller API. Please refer to the Initialization guide for more information.

After initializing the Controller API, you can use controllerApi.getServers() to access the Servers API.

Get Servers

There are multiple ways to get servers from the API:

// Get all servers
val allServers = controllerApi.getServers().getAllServers()
 
// Get server by ID
val server = controllerApi.getServers().getServerById("server-uuid")
 
// Get servers by group name
val lobbyServers = controllerApi.getServers().getServersByGroup("lobby")
 
// Get server by group name and numerical ID
val specificServer = controllerApi.getServers().getServerByNumerical("lobby", 1)
 
// Get servers by type
val proxyServers = controllerApi.getServers().getServersByType(ServerType.PROXY)

Start Servers

You can start a new server by specifying the group name and optionally a start cause:

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

Stop Servers

There are multiple ways to stop servers:

// 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
)
 
// Stop all servers in a group
controllerApi.getServers().stopServers(
    groupName = "lobby",
    stopCause = ServerStopCause.API_STOP
)
 
// Stop all servers in a group with timeout
controllerApi.getServers().stopServers(
    groupName = "lobby",
    timeoutSeconds = 60,
    stopCause = ServerStopCause.API_STOP
)

Update Servers

There are several ways to update server properties:

// Update entire server object
val updatedServer = controllerApi.getServers().updateServer(server)
 
// Update server state
val updatedServer = controllerApi.getServers().updateServerState(
    id = "server-uuid",
    state = ServerState.STARTING
)
 
// Update a single property
val updatedServer = controllerApi.getServers().updateServerProperty(
    id = "server-uuid",
    key = "maxPlayers",
    value = 200
)

Current Server Information

There are two ways to get information about the current server your code is running on:

Using the API

You can use the getCurrentServer() method to get information about the current server:

val currentServer = controllerApi.getServers().getCurrentServer()
println("Current server group: ${currentServer.group}")
println("Current server ID: ${currentServer.uniqueId}")

Using Environment Variables

SimpleCloud automatically provides environment variables that you can access without initializing the API. These variables are available in two categories:

Default Variables

The following environment variables are always available for every server:

val group = System.getenv("SIMPLECLOUD_GROUP")
val uniqueId = System.getenv("SIMPLECLOUD_UNIQUE_ID")
val numericalId = System.getenv("SIMPLECLOUD_NUMERICAL_ID")
 
val host = System.getenv("SIMPLECLOUD_HOST")
val ip = System.getenv("SIMPLECLOUD_IP")
val port = System.getenv("SIMPLECLOUD_PORT")
 
val type = System.getenv("SIMPLECLOUD_TYPE")
val maxPlayers = System.getenv("SIMPLECLOUD_MAX_PLAYERS")
val maxMemory = System.getenv("SIMPLECLOUD_MAX_MEMORY")
val minMemory = System.getenv("SIMPLECLOUD_MIN_MEMORY")
val createdAt = System.getenv("SIMPLECLOUD_CREATED_AT")

Custom Properties

Any custom properties defined in your group configuration are automatically available as environment variables. The property names are:

Prefixed with SIMPLECLOUD_
Converted to uppercase
Have dashes (-) replaced with underscores (_)

For example:

// In your group configuration
val group = Group(
    name = "lobby",
    properties = mapOf(
        "game-mode" to "ADVENTURE",
        "isLobby" to "true",
        "max_rounds" to "5"
    )
)
 
// In your server code
val gameMode = System.getenv("SIMPLECLOUD_GAME_MODE")     // Returns "ADVENTURE"
val isLobby = System.getenv("SIMPLECLOUD_ISLOBBY")        // Returns "true"
val maxRounds = System.getenv("SIMPLECLOUD_MAX_ROUNDS")   // Returns "5"

Servers API

On this page