Introduction
The problem: Minecraft exists in two parallel versions that cannot natively connect to each other.
- Java Edition: PC (Windows, Mac, Linux), the historical version, large plugin/mod ecosystem
- Bedrock Edition: Windows 10/11, mobile, Xbox, PlayStation, Switch
GeyserMC is a proxy that translates Bedrock packets to Java and vice versa in real time. Floodgate complements Geyser by allowing Bedrock players to connect to your Java server without needing a Java license.
Prerequisites
- A working Minecraft Java server (Paper/Spigot recommended)
- Java 1.17+
- Access to the
plugins/folder - Port 19132/UDP open (default Bedrock port)
- Recommended prior guide: VeryCloud Minecraft Migration
Step 1: Choose installation method
GeyserMC can run in 3 modes:
A. Plugin (recommended)
Installed directly in the Java server's plugins/ folder. Simplest and most used mode. Choose this unless you have a specific reason.
B. Standalone
GeyserMC runs in its own process. Useful if you have multiple Java servers behind a proxy (Velocity).
C. Proxy plugin
For BungeeCord or Velocity frontend.
This guide covers Plugin mode.
Step 2: Download Geyser and Floodgate
On the Java server, go to the plugins/ folder:
cd /home/minecraft/server/plugins
Download the latest versions:
wget https://download.geysermc.org/v2/projects/geyser/versions/latest/builds/latest/downloads/spigot -O Geyser-Spigot.jar
wget https://download.geysermc.org/v2/projects/floodgate/versions/latest/builds/latest/downloads/spigot -O floodgate-spigot.jar
If you're on Paper, the same JARs work (Spigot = Paper compatible).
Step 3: Start the server
Start the Java server so Geyser generates its config:
cd ~/server
./start.sh
In the logs you'll see:
[Geyser-Spigot] Loading Geyser
[Geyser-Spigot] ******************************************
[Geyser-Spigot] Loading Geyser version 2.x.x
[Geyser-Spigot] Started Geyser on 0.0.0.0:19132
And:
[floodgate] Floodgate has finished loading!
Stop the server (stop) to configure.
Step 4: Configure Geyser
nano ~/server/plugins/Geyser-Spigot/config.yml
Key parameters:
bedrock:
address: 0.0.0.0
port: 19132
clone-remote-port: false
motd1: "VeryCloud Cross-play"
motd2: "Java + Bedrock"
server-name: "VeryCloud"
compression-level: 6
enable-proxy-protocol: false
remote:
address: auto
port: 25565
auth-type: floodgate # IMPORTANT: goes through Floodgate
# Bedrock players can connect without Java account
floodgate-key-file: key.pem
# Optimizations
command-suggestions: true
passthrough-motd: false
passthrough-player-counts: true
Important: auth-type: floodgate is what enables connection without a Java license. Without Floodgate, use auth-type: online (players must have a Microsoft/Java account).
Step 5: Configure Floodgate
nano ~/server/plugins/floodgate/config.yml
Important parameters:
# Prefix for Bedrock player names (to distinguish them)
username-prefix: "." # A Bedrock player "Steve" will appear as ".Steve"
# Replace spaces in names (Bedrock allows spaces, Java doesn't)
replace-spaces: true
# Disable if you want real Bedrock names without prefix
# (but possible conflicts with Java players of the same name)
Step 6: Open port 19132
sudo ufw allow 19132/udp
On Netrix (VeryCloud), also open UDP port 19132 in the customer area.
Step 7: Start and test
cd ~/server
./start.sh
Test from Java
Connect as usual: IP:25565. Everything should work unchanged.
Test from Bedrock
On Minecraft Bedrock (Windows 10 PC, console, mobile):
- Play → Servers → Add Server
- Server Name: VeryCloud
- Server Address: your IP or domain
- Port: 19132 (default)
- Save and Join
You arrive in-game as .YourUsername (with the . prefix).
Step 8: Linking Java and Bedrock accounts
If a player owns both versions, they can link their accounts to share inventory/skin.
On the server, after starting (as a Java admin):
/linkaccount BedrockPlayer
The Bedrock player must then type the displayed command in their chat to confirm.
Step 9: Skins and UI
Geyser automatically downloads Bedrock skins and displays them correctly to Java players. To allow the reverse:
nano ~/server/plugins/Geyser-Spigot/config.yml
allow-third-party-capes: true
allow-third-party-ears: true
show-cooldown: title
Step 10: Optimize for public servers
Bedrock-compatible plugins
Not all Java plugins are Bedrock-equivalent. Prefer:
- PlaceholderAPI: for displaying custom info
- ProtocolLib: used by Geyser
- LuckPerms: identical Java/Bedrock permissions
- EssentialsX: basic commands
Avoid plugins relying on Java-only blocks/items (custom maps, custom blocks, some GUIs).
Bedrock custom items
For custom items visible on Bedrock side, use Geyser CustomItems via resource packs. Documentation: https://wiki.geysermc.org/geyser/custom-items
Troubleshooting
Bedrock doesn't connect
Check:
sudo netstat -ulnp | grep 19132
Must show Geyser listening on 19132. If not:
- Check Geyser logs
- Check UFW (
sudo ufw status) - Check VeryCloud Netrix
"Outdated client" on Bedrock
Geyser supports a specific Bedrock version. If your Minecraft Bedrock is newer than Geyser, update Geyser:
cd ~/server/plugins
wget https://download.geysermc.org/v2/projects/geyser/versions/latest/builds/latest/downloads/spigot -O Geyser-Spigot.jar
# Then restart server
"Authentication failed" without Floodgate
If using auth-type: online, Bedrock players must link their Microsoft Bedrock account to a Microsoft Java account. Too complex for most players.
→ Use auth-type: floodgate (recommended).
Lag or Bedrock teleports
Bedrock sends more position updates than Java. Increase Bedrock view-distance:
bedrock:
view-distance: 10
Useful commands
# Hot-reload Geyser
/geyser reload
# Force save skins
/geyser dumpcache
# Link a Bedrock account to Java
/linkaccount BedrockUsername
# Unlink
/unlinkaccount
# View all connected Bedrock players
/geyser players
# Test if a player name is Bedrock
/floodgate isFloodgateUser <name>
# Update Geyser and Floodgate
cd ~/server/plugins
wget -O Geyser-Spigot.jar https://download.geysermc.org/v2/projects/geyser/versions/latest/builds/latest/downloads/spigot
wget -O floodgate-spigot.jar https://download.geysermc.org/v2/projects/floodgate/versions/latest/builds/latest/downloads/spigot
Conclusion
Your Minecraft server is now cross-play. You potentially reach double the audience: Java PC players + Bedrock console/mobile players. It's a game-changer for public servers and mixed communities.
Going further:
- Create resource packs specifically for Bedrock to reproduce your custom items
- Use ViaVersion to also support Java clients of different versions
- Set up a lobby with sub-servers (survival, creative, mini-games) via Velocity
Resources
- Official GeyserMC site: https://geysermc.org
- Documentation: https://wiki.geysermc.org
- Geyser GitHub: https://github.com/GeyserMC/Geyser
- Floodgate GitHub: https://github.com/GeyserMC/Floodgate
- VeryCloud guide — Minecraft Migration:
/docs/article/migrate-minecraft