Servers API

A server is one running instance created from a group or persistent server. Use api.server() to inspect and manage that instance. To change how servers are created, update the owning group or persistent server instead.

Find available capacity

Use ServerQuery to find instances by source, state, host, or numerical ID. This example calculates the reported free slots across playable lobby servers:

ServerQuery query = ServerQuery.create()
    .filterByServerGroupName("lobby")
    .filterByState(ServerState.AVAILABLE, ServerState.INGAME);

api.server().getAllServers(query)
    .thenApply(servers -> servers.stream()
        .filter(server -> server.getPlayerCount() != null)
        .mapToInt(server -> Math.max(
            0,
            server.getMaxPlayers() - server.getPlayerCount()
        ))
        .sum())
    .thenAccept(capacity ->
        System.out.println("Lobby capacity: " + capacity));

The result is a snapshot, not a reservation. If you use it to choose where a player should connect, keep the routing policy in your application and handle the connection result. See Route players with autoscaling for a complete routing workflow. Call getAllServers() without a query to return every instance, or use getServersByGroup("lobby") as a group-name shortcut. List methods return an empty list when nothing matches.

ServerQuery filters

Repeated calls to a multi-value filter add values to the query.

ServerQuery

Match one or more group IDs.

ServerQuery

Match one or more lifecycle states.

ServerQuery

Match instances running on one serverhost.

ServerQuery

Match the instance of one persistent server.

ServerQuery

Match SERVER or PROXY sources.

ServerQuery

Match one or more group or persistent server names.

ServerQuery

Match sources with any supplied tag.

ServerQuery

Match one or more numerical IDs.

ServerQuery

Sort by created_at, updated_at, numerical_id, or state.

ServerQuery

Use asc or desc.

Find one server

Look up an instance by its unique ID, or by its group name and numerical ID:

api.server().getServerById("server-uuid")
    .thenAccept(server -> System.out.println(server.getState()));

api.server().getServerByNumericalId("lobby", 1)
    .thenAccept(server -> System.out.println(server.getServerId()));

These lookups complete exceptionally when no matching server exists.

Get the current server

Code running inside a SimpleCloud-managed server can resolve its own instance:

api.server().getCurrentServer()
    .thenAccept(server -> System.out.println(server.getServerId()));

getCurrentServer() uses the SIMPLECLOUD_UNIQUE_ID environment variable and completes exceptionally when the current process is not associated with an instance.

Access the owning configuration

Every instance belongs to either a group or a persistent server. getServerBase() provides their shared configuration, while getGroup() and getPersistentServer() expose source-specific fields.

api.server().getServerById("server-uuid")
    .thenAccept(server -> {
        if (server.isFromGroup()) {
            System.out.println("Group: " + server.getGroup().getName());
        } else {
            System.out.println(
                "Persistent server: " +
                server.getPersistentServer().getName()
            );
        }

        System.out.println(
            "Configured slots: " + server.getServerBase().getMaxPlayers()
        );
    });

Only one of getGroup() and getPersistentServer() is available for an instance. Avoid the deprecated getServerGroup(), which throws for persistent server instances.

Update an instance

UpdateServerRequest changes only the fields you set:

UpdateServerRequest update = UpdateServerRequest.builder()
    .maxPlayers(64)
    .maxMemory(2048)
    .build();

api.server().updateServer("server-uuid", update)
    .thenAccept(server ->
        System.out.println("Updated slots: " + server.getMaxPlayers()));

The builder supports playerCount, state, properties, minMemory, maxMemory, and maxPlayers. Changes apply to this instance, not its owning configuration. The platform normally reports state and playerCount; only set them when your integration owns that reporting.

Manage instance properties

Properties attach application data to one instance. Updates merge with the existing map.

api.server().updateServerProperties(
    "server-uuid",
    Map.of("gameMode", "competitive", "map", "castle")
);

api.server().deleteServerProperty("server-uuid", "map");

Use updateServerProperty to set one key and deleteServerProperties to remove several keys. Each method returns the resulting property map.

Stop an instance

api.server().stopServer("server-uuid")
    .thenRun(() -> System.out.println("Shutdown initiated"));

The future completes when SimpleCloud initiates the stop, not when cleanup finishes. Use server state events if your plugin must observe the later lifecycle transitions.

Stopping an instance does not disable its group or persistent server. SimpleCloud may create a replacement to maintain the source configuration. Change that configuration first when the server must stay offline.

Server model

string

required

Unique instance ID.

integer

required

Numerical ID within the source group or persistent server.

string | null

Source group ID, or null for a persistent server instance.

string | null

Source persistent server ID, or null for a group instance.

string

required

Serverhost running the instance.

string

required

Network that owns the instance.

string | null

Assigned IP address, or null before one is available.

integer | null

Assigned port, or null before one is available.

integer

required

Minimum memory in MB.

integer

required

Maximum memory in MB.

number | null

Current CPU usage percentage, or null when unavailable.

number | null

Current memory usage in MB, or null when unavailable.

integer | null

Current connected player count, or null when unavailable.

integer

required

Player limit for the instance.

ServerState

required

Current lifecycle state.

string

required

Creation timestamp in ISO 8601 format.

string

required

Last update timestamp in ISO 8601 format.

string | null

Last activity timestamp in ISO 8601 format, or null when unavailable.

Map<String, Object> | null

Instance properties, or null when none are available.

Blueprint | null

Reserved accessor. The current implementation returns null; use the source configuration instead.

ServerBase

required

Shared configuration from the source group or persistent server.

Group | null

Source group, or null for a persistent server instance.

PersistentServer | null

Source persistent server, or null for a group instance.

Server states

State	Meaning
`UNKNOWN_STATE`	Unknown or unspecified.
`PREPARING`	SimpleCloud is preparing the instance.
`STARTING`	The server process is starting.
`AVAILABLE`	Ready to accept connections.
`INGAME`	Running with active players.
`STOPPING`	Shutdown is in progress.
`CLEANUP`	The process has stopped and cleanup is in progress.

Getting Started

Cloud API

Guides

REST API Reference

Find available capacity

Find one server

Get the current server

Access the owning configuration

Update an instance

Manage instance properties

Stop an instance

Server model

Server states

​Find available capacity

​Find one server

​Get the current server

​Access the owning configuration

​Update an instance

​Manage instance properties

​Stop an instance

​Server model

​Server states

Find available capacity

Find one server

Get the current server

Access the owning configuration

Update an instance

Manage instance properties

Stop an instance

Server model

Server states