Transfer a player to another server

Use CloudPlayer.connect(...) when you already know which server the player should join. The method expects the name registered on the player’s proxy, such as lobby-1—not the server UUID returned by Server.getServerId().

Transfer the player

Look up the player by UUID, confirm they are online, and connect them to the registered server name:

PlayerTransferService.java

import app.simplecloud.api.CloudApi;
import app.simplecloud.api.player.CloudPlayer;

import java.util.UUID;
import java.util.concurrent.CompletableFuture;

public final class PlayerTransferService {
    private final CloudApi api;

    public PlayerTransferService(CloudApi api) {
        this.api = api;
    }

    public CompletableFuture<CloudPlayer.ConnectResult> transfer(
        UUID playerId,
        String registeredServerName
    ) {
        return api.player().get(playerId).thenCompose(player -> {
            if (player == null || !player.isOnline()) {
                return CompletableFuture.completedFuture(
                    CloudPlayer.ConnectResult.PLAYER_NOT_FOUND
                );
            }

            return player.connect(registeredServerName);
        });
    }
}

Call transfer(...) from your command or matchmaking flow and handle the result:

transferService.transfer(playerId, "lobby-1")
    .thenAccept(result -> {
        switch (result) {
            case SUCCESS, ALREADY_CONNECTED ->
                logger.info("Player is connected to lobby-1");
            case SERVER_NOT_FOUND ->
                logger.warning("lobby-1 is not registered on the proxy");
            case PLAYER_NOT_FOUND ->
                logger.info("Player is no longer online");
            case CONNECTION_FAILED ->
                logger.warning("Could not connect player to lobby-1");
        }
    })
    .exceptionally(error -> {
        logger.log(Level.WARNING, "Could not transfer player", error);
        return null;
    });

This guide returns PLAYER_NOT_FOUND when its lookup finds no online player. If the player disconnects after that check, connect(...) returns CONNECTION_FAILED.

Connection results

Result	Meaning
`SUCCESS`	The player connected to the destination.
`ALREADY_CONNECTED`	The player is already connected to the destination.
`SERVER_NOT_FOUND`	The supplied name is not registered on the player’s proxy.
`PLAYER_NOT_FOUND`	This guide’s lookup found no online player.
`CONNECTION_FAILED`	The proxy could not complete the connection.

If your plugin needs to find an available destination first, see Route players with autoscaling.

Getting Started

Cloud API

Guides

REST API Reference

Transfer a player to another server

Transfer the player

Connection results

​Transfer the player

​Connection results

Transfer the player

Connection results