The Persistent Servers API manages long-lived server configurations through api.persistentServer(). Persistent servers keep their identity across restarts and can be assigned to a specific serverhost.
Get Persistent Servers
// Get all persistent servers
api.persistentServer().getAllPersistentServers()
.thenAccept(servers -> servers.forEach(server ->
System.out.println(server.getName())));
// Get persistent servers with filters
PersistentServerQuery query = PersistentServerQuery.create()
.filterByActive(true)
.filterByTags("survival")
.limit(20);
api.persistentServer().getAllPersistentServers(query)
.thenAccept(servers -> System.out.println("Matches: " + servers.size()));
// Get by ID or name
api.persistentServer().getPersistentServerById("persistent-server-uuid")
.thenAccept(server -> System.out.println(server.getName()));
api.persistentServer().getPersistentServerByName("survival")
.thenAccept(server -> System.out.println(server.getPersistentServerId()));
Create Persistent Server
CreatePersistentServerRequest request = CreatePersistentServerRequest.builder()
.name("survival")
.type(GroupServerType.SERVER)
.minMemory(1024)
.maxMemory(4096)
.maxPlayers(80)
.active(true)
.priority(100)
.serverhostId("serverhost-1")
.tags(List.of("survival", "public"))
.properties(Map.of("world", "main"))
.build();
api.persistentServer().createPersistentServer(request)
.thenAccept(server -> System.out.println("Created: " + server.getPersistentServerId()));
Update Persistent Server
UpdatePersistentServerRequest update = UpdatePersistentServerRequest.builder()
.maxPlayers(100)
.active(true)
.priority(200)
.build();
api.persistentServer().updatePersistentServer("persistent-server-uuid", update)
.thenAccept(server -> System.out.println("Updated: " + server.getName()));
Delete Persistent Server
api.persistentServer().deletePersistentServer("persistent-server-uuid")
.thenRun(() -> System.out.println("Deleted persistent server"));
Persistent Server Properties
api.persistentServer()
.updatePersistentServerProperties("persistent-server-uuid", Map.of(
"world", "main",
"difficulty", "hard"
))
.thenAccept(properties -> System.out.println("Properties: " + properties));
api.persistentServer()
.deletePersistentServerProperties("persistent-server-uuid", List.of("difficulty"));
PersistentServerQuery
| Filter | Method | Description |
|---|
| Tags | filterByTags(String... tags) | Match persistent servers with any of the given tags |
| Active status | filterByActive(boolean active) | Match active or inactive persistent servers |
| Serverhost | filterByServerhostId(String serverhostId) | Match persistent servers assigned to one serverhost |
| Limit | limit(int limit) | Limit the number of returned results |
PersistentServer Model
PersistentServer extends ServerBase, so it includes the shared configuration fields used by groups and persistent servers.
Unique persistent server ID.
Human-readable server name.
Persistent server type. Use SERVER for game servers or PROXY for proxy servers.
Whether SimpleCloud should keep the persistent server running.
Priority used by scheduling and ordering logic.
Player count of the running instance, or 0 if no instance exists.
Blueprint or image source configuration.
Tags used for filtering and organization.
Creation timestamp in ISO 8601 format.
Last update timestamp in ISO 8601 format.
Running instances created from persistent servers still appear in api.server() and expose server.getPersistentServerId() plus server.getPersistentServer().
