How to set up Geyser on a BungeeCord network

On a network, install Geyser and Floodgate on the BungeeCord proxy, then install Floodgate on every backend Paper server and copy the proxy's key.pem to each. Bedrock players connect to the proxy and can move between servers like Java players.

Layout#

Do not also install Geyser on the backends. Only the proxy accepts Bedrock connections.

Before you start#

• A working BungeeCord network: proxy created from the BungeeCord template, backends on Paper, ip_forward: true in the proxy's config.yml, and bungeecord: true in each backend's spigot.yml.
• Backends with online-mode=false in server.properties (the proxy handles authentication).

1. Proxy: install Geyser and Floodgate#

1. Download the BungeeCord builds of Geyser and Floodgate from geysermc.org/download.
2. Upload both to the proxy's plugins folder and restart the proxy.
3. Set the Bedrock port in plugins/Geyser-BungeeCord/config.yml:

bedrock:
  address: 0.0.0.0
  port: 25565   # the proxy's port, or an extra allocation on the proxy

Bedrock uses UDP, so it can share the proxy's port number. See which port do Bedrock players use.

4. In the proxy's plugins/floodgate/config.yml, make sure Floodgate data is forwarded to backends:

send-floodgate-data: true

5. Restart the proxy.

2. Backends: install Floodgate#

On every Paper server behind the proxy:

1. Upload floodgate-spigot.jar to plugins/ and start the server once so it creates plugins/floodgate/.
2. Stop the server.
3. Download key.pem from the proxy's plugins/floodgate/ folder and upload it to the backend's plugins/floodgate/, replacing the generated one.
4. Start the server.

Every Floodgate install on the network must have the same key.pem. If they differ, Bedrock players are kicked with a key error.

Keep username-prefix and replace-spaces the same on all Floodgate configs too, so names are consistent.

Why Floodgate on the backends?#

The proxy authenticates Bedrock players, but each backend needs to know a player is a Bedrock player with a Floodgate UUID and name. The backend Floodgate reads the data forwarded by the proxy, which is why the key must match. It also gives plugins on each backend access to the Floodgate API.

Ports on Schokr#

Only the proxy needs to be reachable by players. If your backends are separate Schokr servers, the proxy connects to them on their own ports; players never connect to backends directly.

Testing#

1. Join from Java and switch servers to confirm the network works.
2. Join from Bedrock on the proxy address and Bedrock port.
3. Switch servers from Bedrock (for example with /server lobby).
4. Watch the backend console for any Floodgate errors on join.

Troubleshooting#

• Kicked with a Floodgate key or decryption error: key.pem mismatch. Recopy from the proxy.
• Bedrock player shows as a normal offline-mode player on the backend: Floodgate missing on that backend, or send-floodgate-data is off on the proxy.
• Cannot connect at all: see fix "Unable to connect to world".