How Geyser Works

Geyser is a protocol translator. It runs alongside your Java server (as a plugin or standalone proxy) and listens for Bedrock connections on a UDP port. When a Bedrock player connects, Geyser translates their Bedrock protocol packets into Java protocol packets the server understands, and vice versa.

The result: Bedrock players appear on your Java server as if they were Java players, sharing the same world, chat, and gameplay.

Installing Geyser as a Plugin

The simplest setup runs Geyser as a plugin on your Paper or Spigot server.

1. Download the Geyser plugin (Geyser-Spigot.jar) from geysermc.org/download.
2. Upload it to your plugins/ folder via the File Manager or SFTP.
3. Restart the server.
4. Geyser generates a config at plugins/Geyser-Spigot/config.yml on first load.

Out of the box, Geyser is configured to listen on UDP 19132, the standard Bedrock port. On our plans that exact port is usually not available, so you point Geyser at a port you actually own: grab an extra UDP allocation from the panel Network tab and set it in plugins/Geyser-Spigot/config.yml under bedrock: > port:. Bedrock players then connect to your server's IP on that port.

Installing Floodgate (Recommended)

By default, Geyser requires Bedrock players to own a Java account to authenticate. Floodgate removes that requirement, letting Bedrock players join with just their Bedrock account.

1. Download Floodgate (floodgate-spigot.jar) from geysermc.org/download.
2. Upload it to plugins/ alongside Geyser.
3. In plugins/Geyser-Spigot/config.yml, set the auth type to floodgate: ``yaml remote: auth-type: floodgate ``
4. Restart.

With Floodgate, Bedrock players are prefixed with a dot (.) in their username by default to avoid collisions with Java usernames. You can customize this prefix in the Floodgate config.

Verifying Cross-Play

After installing Geyser (and optionally Floodgate) and restarting:

1. From a Bedrock client, add a server with your Java server's IP and the Geyser port you configured.
2. Connect.
3. The Bedrock player should appear in-world alongside Java players.

If the connection fails, check the server console for Geyser startup messages and any errors.

Port Considerations

• Java players connect on your server's Java port (TCP), the one shown at the top of the panel page. The game default is 25565, but on our plans the assigned port is often different
• Bedrock players connect on the Geyser port (UDP), the extra allocation you set in Geyser's config
• Both ports must exist in the panel Network tab. If you need an additional allocation for Geyser, request one there or open a ticket

Limitations of Cross-Play

Geyser does an impressive job, but the two editions are not identical:

• Some Java mechanics do not translate perfectly to Bedrock controls
• Bedrock UI for certain inventory-heavy interactions can be awkward
• Heavily modded Java servers (Forge/Fabric) generally do not work with Geyser, since Bedrock clients cannot load Java mods. Geyser is best paired with Paper/Spigot plugin servers
• Some plugins that rely on Java-specific client behavior may behave oddly for Bedrock players

For a vanilla-plus survival server running Paper and quality-of-life plugins, Geyser works very well. For a 300-mod Forge pack, cross-play is not realistic.

Common Issues

• Bedrock players cannot connect: Geyser not installed, the server is not Paper/Spigot, or the wrong port. Confirm Geyser loaded in the console and that the UDP port in Geyser's config matches an allocation in the Network tab.
• "Could not authenticate": Bedrock player does not own a Java account and Floodgate is not installed or configured. Install Floodgate and set auth-type: floodgate.
• Bedrock player names look odd (leading dot): That is Floodgate's default prefix to prevent username collisions. Customize or remove it in the Floodgate config if you prefer.
• Geyser works but mods are missing for Bedrock: Expected. Bedrock clients cannot load Java mods. Use a plugin server, not a modded one, for cross-play.

What to Read Next

• Java: Plugins since Geyser pairs with a Paper/Spigot plugin server
• Bedrock if you decide to run a standalone Bedrock server instead
• Performance and Backups for keeping the combined server healthy