Minecraft Java + Bedrock LAN server

This directory is set up for a LAN-only Paper Minecraft Java server with:

• Geyser-Spigot for Bedrock Edition clients
• ViaVersion and ViaBackwards for Paper/Geyser Java protocol gaps during version rollouts
• offline LAN authentication so local Bedrock clients can join without Xbox login
• Java on TCP 25565
• Bedrock on UDP 19132

Setup

./setup.sh

The setup script downloads the latest stable Paper build and Geyser-Spigot. It also creates server.properties. Geyser creates its own config on first launch; start.sh tunes it for LAN play whenever that file is present.

The published repo intentionally contains only scripts, safe examples, and patch source. Downloaded jars, live server state, generated Paper configs, worlds, logs, and server.properties are local runtime output and ignored.

This is intentionally configured for a trusted home LAN:

• online-mode=false
• allow-flight=true
• Geyser java.auth-type: offline
• Geyser validate-bedrock-login: false

That lets local Bedrock clients join without Xbox login, but names are not authenticated. Do not expose this server to the public internet.

Floodgate is intentionally disabled for this mode because it expects Bedrock identity data that is absent when Xbox authentication is disabled.

The local Geyser jar is also patched for this LAN server. The patch allows two Bedrock clients with the same underlying Bedrock/Xbox identity to connect at the same time, assigns unique Java-safe names for blank or duplicate LAN Bedrock names while preferring the name set in the Bedrock client interface, and includes a small Paper 26.2 compatibility fix for Geyser's Spigot command reflection. This is only appropriate for a trusted LAN.

The patches are reproducible from source:

./scripts/patch-geyser-allow-duplicate-xuid.sh

setup.sh runs that patch automatically after downloading Geyser. It also installs ViaVersion and ViaBackwards because Geyser can lag a Paper Java protocol version during Minecraft rollouts. Geyser is configured to connect to Java through 127.0.0.1:25565 instead of its direct in-process connection so the Via plugins can translate that protocol. Replacement classes live under scripts/patched-geyser-src/.

Safe example configs are included at:

• server.properties.example
• examples/geyser-config.example.yml

Before the server can run, read the Minecraft EULA:

https://aka.ms/MinecraftEULA

Then change this line in eula.txt:

eula=true

Start

./start.sh

Upgrade

./upgrade.sh

The upgrade script downloads the latest stable Paper build, latest Geyser-Spigot build, and latest ViaVersion/ViaBackwards builds, verifies published checksums where available, backs up the existing jars under .upgrade-backups/, reapplies the local Geyser patches, and updates server-version.txt. Restart the server after upgrading.

To target a specific Minecraft version or Paper channel:

MINECRAFT_VERSION=26.1.2 ./upgrade.sh
PAPER_CHANNEL=ALPHA ./upgrade.sh

Memory can be adjusted with environment variables:

JAVA_XMS=1G JAVA_XMX=4G ./start.sh

Connecting on LAN

Java Edition clients connect to:

<server-lan-ip>:25565

Bedrock Edition clients should see the server in the Friends tab as a LAN game. If it does not appear automatically, add it manually:

Address: <server-lan-ip>
Port:    19132

Make sure your local firewall allows incoming TCP 25565 and UDP 19132.

You can also verify the Bedrock LAN/status listener from this machine:

./scripts/check-bedrock-lan.py

To test LAN-style broadcast discovery from this machine:

./scripts/check-bedrock-lan.py 255.255.255.255 --broadcast

When the server is running, this should print a Bedrock LAN/status listener responded line followed by the Bedrock server advertisement.