Quickstart

Install the connector on a server you already run, paste your key, and get network-wide identity, chat and punishments.

Hive is one plugin and one API key. There’s no backend to run: you install the connector on servers you already operate, and the hub handles identity, chat, presence, punishments and matchmaking across all of them.

1. Install the connector

Download HiveCore.jar from the dashboard and drop it in plugins/. Start the server once to generate the config, then paste the key your dashboard issued for this server.

config.yml

# plugins/HiveCore/config.yml
hive-api-url: https://hive.beehivesys.net

# Paste the secret from the dashboard EXACTLY as shown, with nothing added.
# The hub hashes the whole string, so prefixing it (server-id, a label, quotes
# you retyped) changes the hash and you get: 401 invalid api key.
api-key: "cH7kQ2mR..."
server-id: lobby-1

# How this server is grouped and found by the matchmaker.
server-type: lobby

# What the hub advertises for this box. Behind a proxy, set these to the
# proxy's public endpoint - players never reach the backend directly.
#public-host: play.example.com
#public-port: 25565

If the key is missing or still a placeholder, the connector logs a clear error and leaves Hive’s features off. Your server still boots normally. Restart with a real key and the box registers itself: it appears in your dashboard’s server list and in findServer results.

You can also supply the key as the HIVE_API_KEY environment variable instead of putting it in the file, which is usually what you want in a container.

That’s the whole install. Global chat, network tab list, punishment enforcement and cross-server identity are on by default and need no code.

If the hub is unreachable, your server keeps running

Hive fails open by design. This is the part worth knowing before you install anything:

Players still join. The punishment check has a short timeout; if the hub doesn’t answer, the join is allowed rather than blocked.
Player data degrades to defaults instead of failing the login.
Chat and tab list fall back to server-local and resume when the hub returns.
Registration retries in the background; nothing needs restarting.

A hub outage costs you Hive’s features, never your server. Nothing about your existing world, plugins or players depends on us being up.

2. Build a plugin against it (optional)

Only needed if you’re writing your own game logic. The connector ships the API you compile against, published anonymously to maven.beehivesys.net/public.

build.gradle.kts

repositories {
  mavenCentral()
  maven { url = uri("https://repo.papermc.io/repository/maven-public/") }
  maven { url = uri("https://maven.beehivesys.net/public") }
}

dependencies {
  // The installed HiveCore plugin provides these classes at runtime,
  // so your jar bundles nothing of Hive's.
  compileOnly("net.beehivesys.hive:hive-minecraft:1.3.2")
}

Add depend: [HiveCore] to your plugin.yml so Paper loads the connector first, then reach the client through it.

Bootstrap.java

// The installed connector already announced this box to the network.
// Reach the SDK through it - do not construct a second client.
HiveSdk hive = HiveCore.get().sdk();

3. Route a player

Ask the network for a server with capacity and send the player there. Every call is async and returns a CompletableFuture; routing is capacity-aware, so you never overfill a box.

Queue.java

public void join(Player player) {
  hive.matchmaking()
      .findServer(player.getUniqueId(), player.getName(), "skywars")
      .thenAccept(result -> {
        if (result.isSuccess()) {
          // getMatchedServer() hands back a ServerInfo; transfer() wants its id.
          hive.transfer().transfer(player.getUniqueId(),
              result.getMatchedServer().getServerId(), null);
        } else {
          // result.getResult() says why: ALL_SERVERS_FULL, NO_SERVERS_AVAILABLE, ...
        }
      });
}

Next steps

Server registry - heartbeats, presence and transfers.
Matchmaking - queues and capacity-aware routing.
Player data - profiles, currencies and leaderboards.
Punishments - network-wide bans, mutes and kicks.

The full plugin-facing API reference, with a Java SDK sample on every operation, is at hive.beehivesys.net/api.