Floodgate Plugin: Bedrock Auth on Java Servers

What is Floodgate?

Floodgate is a companion plugin for GeyserMC that allows Bedrock players to join Java servers using only their Xbox Live (Microsoft) account, without needing to own or link a Java Edition account. This dramatically lowers the barrier for Bedrock players to join your community.

Without Floodgate, GeyserMC requires each Bedrock player to have a linked Java account. Floodgate removes this requirement by handling authentication through Microsoft/Xbox Live directly.

How It Works

When a Bedrock player connects through GeyserMC with Floodgate:

1. The player authenticates with their Microsoft/Xbox Live account (the standard Bedrock authentication).
2. GeyserMC passes the authentication data to Floodgate.
3. Floodgate creates a unique player profile on the Java server for the Bedrock player.
4. The player joins the server with a name prefix (configurable, usually a dot or asterisk) to distinguish them from Java players.

Each Bedrock player gets a consistent UUID derived from their Xbox Live account, so their inventory, permissions, and stats persist between sessions.

Installation

1. Make sure GeyserMC is already installed and working on your server.
2. Download the Floodgate plugin for your server platform (Spigot, Paper, Velocity, BungeeCord).
3. Place the Floodgate .jar file in your server's plugins folder.
4. Restart the server.
5. Floodgate generates its configuration at plugins/floodgate/config.yml.

GeyserMC Configuration

After installing Floodgate, update the GeyserMC config.yml:

remote:
  auth-type: floodgate

Change auth-type from "online" to "floodgate". Restart the server for the change to take effect.

Floodgate Configuration

The main Floodgate configuration file (config.yml) has these important settings:

username-prefix: "."
replace-spaces: true
disconnect:
  invalid-xbox-username: "Your Xbox username is invalid."

Key settings:

• username-prefix - A prefix added to Bedrock player names to prevent name conflicts with Java players. Common choices are "." (dot), "*", or "+" followed by the player name. For example, a player named "Steve" on Bedrock would appear as ".Steve" on the server.
• replace-spaces - Xbox gamertags can contain spaces, but Java names cannot. When true, spaces are replaced with underscores.

Linking Accounts

Players who own both Bedrock and Java Edition may want to link their accounts so they appear as the same player regardless of which edition they use. Floodgate supports linking through the Global Linking system or a local linking database.

To link accounts locally:

1. The player logs in from their Java account and runs a link command.
2. The player logs in from their Bedrock account and confirms the link.
3. Once linked, the Bedrock player uses the same UUID and data as their Java profile.

Plugin Compatibility

Most Java plugins work fine with Floodgate players. However, some plugins may have issues:

• Plugins that check player names may not handle the prefix correctly. Well-maintained plugins usually support Floodgate.
• Permission plugins like LuckPerms work with Floodgate UUIDs without issues.
• Economy plugins generally work since they use UUIDs rather than player names.
• Custom form/GUI plugins designed for Java may not display correctly for Bedrock players. Use GeyserMC's built-in form API instead.

Security Considerations

Floodgate authenticates players through Microsoft's Xbox Live system, which is a secure authentication method. However, some considerations:

• Keep your Floodgate key file (key.pem) secure. This file is used to verify the authenticity of Bedrock connections.
• Do not share the key.pem between servers unless you understand the implications.
• Use a unique username prefix to prevent impersonation of Java players by Bedrock players.
• Regularly update both GeyserMC and Floodgate to get security patches.

Troubleshooting

• If Bedrock players get "Unable to connect to world," verify that auth-type is set to "floodgate" in GeyserMC config.
• If the server shows authentication errors, regenerate the Floodgate key by deleting key.pem and restarting.
• If player data is lost between sessions, check that the UUID is consistent. Floodgate uses a deterministic UUID based on the Xbox Live account.
• If plugins misbehave with Floodgate players, check the plugin's documentation for Floodgate/GeyserMC support.