Skip to content

Server

This page explains how servers are represented and used within the core system.

What is a server?

Each server in the network is represented by a PixelServer object.

A PixelServer contains basic information such as:

  • unique id
  • name / display name
  • category and sub category
  • required rank
  • slot limits
  • enabled state

Most of these fields are managed internally.\ In most cases, you do not need to modify them manually.

Server Categories

Every server belongs to a ServerCategory and optionally a SubServerCategory.

Categories define the type of server, for example:

  • CityBuild
  • Dungeon
  • Event

Sub categories can further specify a server (e.g. different game modes or instances).

Switching servers

You can let players switch servers using:

player.connect(targetServer, (result, error) -> {
  if (!result) {
    player.sendServerConnectError(error);
  }
});

ServerSwitchData

You can pass additional data when switching servers using ServerSwitchData.

This allows you to:

  • define a reason
  • set a target location
  • pass custom data (must be serializable)

Example:

ServerSwitchData data = new ServerSwitchData("MyFeature:Teleport");
player.connect(targetServer, (result, error) -> {
  if (!result) {
    player.sendServerConnectError(error);
  }
}, data);

This data can be accessed on the target server (with the PlayerJoinLocationEvent).

Important checks before switching

Before switching a player, always ensure:

  • player.isSwitchingServer() → player is not already switching
  • player.getAllowServerSwitch() → switching is allowed

Or simply use:

  • player.isAllowedToSwitchServer()

This method already includes:

  • switching state
  • permission checks
  • server availability
  • slot checks

ServerHandler

You can access server-related logic via:

ServerHandler serverHandler = BukkitCoreLibrary.getServerHandler();

Common methods

  • getCurrentServer() → current server instance
  • getCurrentServerCategory() → category of current server
  • getServerById(int) → get server by id
  • getServer(String) → get server by name
  • getServerByDisplayName(String) → get server by display name

Server selection helpers

The core provides helper methods for selecting servers:

  • getFriendliestServer(player, subCategory)\ → server with most friends or best fit
  • getLowestPopulatedServer(subCategory)\ → server with lowest player count

These methods handle common selection logic for you.

Notes

  • Servers are connected via Velocity (multi-proxy setup). You usually do not need to interact with this directly.
  • Always use the core API (PixelServer, ServerHandler) instead of handling server logic manually.
  • For advanced logic, check the ServerAware system.