Transfer a player to another server

Transfer the player

Before you begin, install the Cloud API, require the simplecloud-api platform plugin, and create one shared CloudApi client. Install simplecloud-api on every proxy that may handle the player because that proxy performs the transfer. Pass the registered server name, such as lobby-1, rather than the UUID returned by Server.getServerId(). 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;
import java.util.logging.Level;
import java.util.logging.Logger;

public final class PlayerTransferService {
    private final CloudApi api;
    private final Logger logger;

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

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

    public void transferToLobby(UUID playerId) {
        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;
            });
    }
}

Create one PlayerTransferService from your plugin’s shared CloudApi and logger. Call transferToLobby(...) from your command or matchmaking flow. The service 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`	The 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