Nimbus SDK

compileOnly(files("libs/nimbus-sdk.jar"))

@Override
public void onEnable() {
    Nimbus.init();
}

@Override
public void onDisable() {
    Nimbus.shutdown();
}

Nimbus.init("http://127.0.0.1:8080", "your-api-token");

// Identity
String name = Nimbus.name();           // "BedWars-1"
String group = Nimbus.group();         // "BedWars"
boolean managed = Nimbus.isManaged();  // true

// Custom state
Nimbus.setState("INGAME");
Nimbus.clearState();

// Routing
Nimbus.route("Steve", "BedWars", RoutingStrategy.LEAST_PLAYERS);
NimbusService best = Nimbus.bestServer("BedWars", RoutingStrategy.FILL_FIRST);

// Queries (from cache, instant)
List<NimbusService> servers = Nimbus.services("BedWars");
List<NimbusService> routable = Nimbus.routable("BedWars");
int players = Nimbus.players("BedWars");
int total = Nimbus.players();

// Events
Nimbus.on(ServiceReadyEvent.class, e -> { ... });
Nimbus.onChange("BedWars", services -> { ... });

// Messaging
Nimbus.message("Lobby-1", "game_ended", Map.of("winner", "Steve"));

// Tab names
Nimbus.setTabName(player.getUniqueId(), "<red>[RED] {player}");
Nimbus.clearTabName(player.getUniqueId());

// Direct access
NimbusClient client = Nimbus.client();
ServiceCache cache = Nimbus.cache();

// Game lifecycle example:
public class BedWarsGame {

    public void onGameStart() {
        Nimbus.setState("INGAME");  // Stop sending new players here
    }

    public void onGameEnd() {
        Nimbus.setState("ENDING");  // Still not routable during cleanup

        // Route all players to a new BedWars game
        for (Player player : getPlayers()) {
            Nimbus.route(player.getName(), "BedWars", RoutingStrategy.FILL_FIRST);
        }
    }

    public void onCleanupComplete() {
        Nimbus.clearState();  // Server is routable again
    }
}

// Send player to the server with the fewest players (spread evenly)
Nimbus.route("Steve", "BedWars", RoutingStrategy.LEAST_PLAYERS);

// Send player to the fullest server (pack tightly, better game feel)
Nimbus.route("Steve", "BedWars", RoutingStrategy.FILL_FIRST);

// Send player to a random server
Nimbus.route("Steve", "BedWars", RoutingStrategy.RANDOM);

Nimbus.route("Steve", "BedWars", RoutingStrategy.LEAST_PLAYERS)
    .thenAccept(service -> {
        if (service != null) {
            System.out.println("Sent Steve to " + service.getName());
        } else {
            System.out.println("No BedWars server available!");
        }
    });

NimbusService best = Nimbus.bestServer("BedWars", RoutingStrategy.LEAST_PLAYERS);
if (best != null) {
    Nimbus.client().sendPlayer("Steve", best.getName());
}

ServiceRouter router = Nimbus.router();

// Only route to servers with fewer than 15 players
router.routePlayer("Steve", "BedWars", RoutingStrategy.FILL_FIRST,
    service -> service.getPlayerCount() < 15);

// Find best across all groups
router.findBestGlobal(RoutingStrategy.LEAST_PLAYERS,
    service -> service.getGroupName().startsWith("Game"));

ServiceCache cache = Nimbus.cache();

// Query (instant, from cache)
List<NimbusService> all = cache.getAll();
List<NimbusService> bedwars = cache.getByGroup("BedWars");
List<NimbusService> routable = cache.getRoutable("BedWars");
int total = cache.getTotalPlayers();
List<String> groups = cache.getGroupNames();

// React to changes
cache.onChange("BedWars", services -> {
    // Called when any BedWars service starts, stops, or changes state
    updateSigns(services);
});

cache.onAnyChange(services -> {
    // Called on any service change
    updateScoreboard(services);
});

// React to player count changes
Nimbus.onPlayers("BedWars", (group, count) -> {
    updateHologram("BedWars: " + count + " playing");
});

PlayerTracker tracker = new PlayerTracker(Nimbus.client(), 2); // poll every 2 seconds
tracker.start();

tracker.onPlayerCountChange("BedWars", (group, count) -> {
    updateHologram("BedWars: " + count + " playing");
});

tracker.onTotalPlayersChange(total -> {
    updateScoreboard("Online: " + total);
});

int count = tracker.getPlayerCount("BedWars");
int serviceCount = tracker.getServicePlayerCount("BedWars-1"); // player count for a specific service
int total = tracker.getTotalPlayers();

Nimbus.reportPlayerCount();

import dev.nimbuspowered.nimbus.sdk.event.*;

Nimbus.on(ServiceReadyEvent.class, event -> {
    System.out.println(event.getServiceName() + " is ready!");
});

Nimbus.on(CustomStateChangedEvent.class, event -> {
    System.out.println(event.getServiceName() + ": "
        + event.getOldState() + " -> " + event.getNewState());
});

Nimbus.on(ScaleUpEvent.class, event -> {
    System.out.println("Scaling up " + event.getGroupName()
        + ": " + event.getCurrentInstances() + " -> " + event.getTargetInstances());
});

Nimbus.on(PlayerConnectedEvent.class, event -> {
    System.out.println(event.getPlayerName() + " joined " + event.getServiceName());
});

Nimbus.on("GROUP_CREATED", event -> {
    String groupName = event.get("group");
    System.out.println("New group: " + groupName);
});

// Called when BedWars services change (start, stop, state change)
Nimbus.onChange("BedWars", services -> {
    int available = (int) services.stream()
        .filter(NimbusService::isRoutable)
        .count();
    System.out.println(available + " BedWars servers available");
});

// Send a message to a specific service
Nimbus.message("Lobby-1", "game_ended", Map.of(
    "winner", "Steve",
    "map", "Castle",
    "duration", "340"
));

// Send without data
Nimbus.message("Lobby-1", "restart_warning");

Nimbus.on(ServiceMessageEvent.class, event -> {
    if ("game_ended".equals(event.getChannel())) {
        String winner = event.getData().get("winner");
        announceWinner(winner);
    }
});

NimbusDisplay display = Nimbus.client().getDisplay("BedWars").join();

String line1 = display.getSignLine1();         // "&1&l★ BedWars ★"
String state = display.resolveState("INGAME"); // "In Game" (from display config)

NimbusService service = Nimbus.cache().get("BedWars-1");

service.getName();         // "BedWars-1"
service.getGroupName();    // "BedWars"
service.getPort();         // 30001
service.getState();        // "READY"
service.getCustomState();  // "INGAME" or null
service.getPlayerCount();  // 12
service.getStartedAt();    // ISO timestamp
service.getUptime();       // "2h 15m"
service.isReady();         // true if state == "READY"
service.isRoutable();      // true if READY and no custom state