Skip to main content

Documentation Index

Fetch the complete documentation index at: https://new-docs.simplecloud.app/llms.txt

Use this file to discover all available pages before exploring further.

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());
});

// Request a new server start for a group
api.group().getGroupByName("lobby")
    .thenCompose(group -> {
        if (group == null) {
            return CompletableFuture.failedFuture(
                new IllegalArgumentException("Group not found: lobby"));
        }
        return api.group().requestServerStart(group);
    })
    .thenRun(() -> System.out.println("Start request accepted for lobby"));

// 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