Skip to main content
The Cloud API is a Java library for interacting with your SimpleCloud network programmatically. Use it to manage groups, servers, players, and react to events in real-time.

​
API Architecture

MethodReturnsDescription
api.group()GroupApiCreate, read, update, delete groups
api.server()ServerApiStart, stop, query servers
api.player()PlayerApiPlayer data, connections, messaging
api.event()EventApiSubscribe to real-time events

​
Event API Subcategories

MethodDescription
api.event().group()Group lifecycle events
api.event().server()Server lifecycle events
api.event().persistentServer()Persistent server events
api.event().blueprint()Blueprint lifecycle events

​
Key Features

  • Async-first design - All operations return CompletableFuture (Java) or suspend functions (Kotlin)
  • Type-safe models - Strongly typed domain objects for Groups, Servers, Players
  • Real-time events - Subscribe to changes via NATS messaging
  • Adventure integration - Players implement Adventure’s Audience for rich text messaging
  • Environment-aware - Auto-configuration from SIMPLECLOUD_* environment variables

​
Quick Example

// Initialize the API
CloudApi api = CloudApi.create();

// Get all servers in a group
api.server().getServersByGroup("lobby").thenAccept(servers -> {
    System.out.println("Lobby servers: " + servers.size());
});

// Start a new server
api.server().startServer(new StartServerRequest("group-id", "lobby"))
    .thenAccept(server -> System.out.println("Started: " + server.getServerId()));

// Send a message to a player (Adventure integration)
api.player().get(playerUUID).thenAccept(player -> {
    if (player != null) {
        player.sendMessage(Component.text("Welcome!").color(NamedTextColor.GREEN));
    }
});

// Subscribe to server events
Subscription sub = api.event().server().onStarted(event -> {
    System.out.println("Server started: " + event.getServerId());
});

​
Next Steps

Installation

Add the Cloud API to your project

Servers API

Manage server instances

Players API

Player data and messaging

Events API

React to real-time changes