React to server availability

Listen for available servers

The listener uses the CloudApi client your plugin already owns and notifies your application code when a server becomes available:

ServerAvailabilityListener.java

package com.example;

import app.simplecloud.api.CloudApi;
import app.simplecloud.api.event.Subscription;
import app.simplecloud.api.server.ServerState;

public final class ServerAvailabilityListener implements AutoCloseable {
    private final Subscription subscription;

    public ServerAvailabilityListener(
        CloudApi cloudApi,
        Runnable onServerAvailable
    ) {
        subscription = cloudApi.event().server().onStateChanged(event -> {
            if (event.getNewState() == ServerState.AVAILABLE) {
                onServerAvailable.run();
            }
        });
    }

    @Override
    public void close() {
        subscription.close();
    }
}

Create the listener when your plugin starts and connect it to the work that is waiting for an available server:

serverAvailability = new ServerAvailabilityListener(
    cloudApi,
    () -> matchmaking.refreshAvailableServers()
);

Treat the callback as a signal to retry waiting work or refresh the destinations known to your routing system.

Events only report changes that happen after you subscribe. If your plugin also needs the current state when it starts, load it separately through the Servers API.

If the callback changes Bukkit, Folia, Velocity, or BungeeCord state, schedule that platform-specific work through the platform’s scheduler.

Close the listener

Close the listener when your plugin stops, before closing the shared CloudApi client:

if (serverAvailability != null) {
    serverAvailability.close();
}

This stops future callbacks. The listener does not close the shared CloudApi client.

See the Events API reference for the other event categories and callback types.

Getting Started

Cloud API

Guides

REST API Reference

React to server availability

Listen for available servers

Close the listener

​Listen for available servers

​Close the listener

Listen for available servers

Close the listener