VelocityUUIDRouter

VelocityUUIDRouter is a Velocity plugin for mixed Java/offline authentication setups.

It lets Java premium players authenticate through Mojang and receive their online UUID, while non-premium Java players can still join with offline UUIDs. Bedrock players connecting through Geyser/Floodgate are detected and left untouched so Floodgate can handle their login flow.

What It Does

• Detects premium Java usernames with Minecraft Services.
• Forces premium Java players into Velocity online authentication.
• Allows non-premium Java players with offline UUIDs.
• Keeps UUID mode session-wide, matching how Velocity handles player identity.
• Logs UUID mode decisions for configured premium servers.
• Provides admin commands to reload config, inspect status, and view connected player UUID modes.
• Avoids modifying Bedrock/Geyser/Floodgate login handling.

Requirements

• Velocity 3.x, built against 3.5.0-SNAPSHOT
• Velocity should be configured with:

online-mode = false

• Java 21 for building
• Optional: Geyser/Floodgate for Bedrock support

Configuration

The plugin creates this file on first startup:

plugins/velocityuuidrouter/config.yml

Default config:

# WIP: premiumServers is currently used for logging only.
# Non-premium players are not blocked or redirected.
premiumServers: []

lookupCacheMinutes: 60
lookupFailureMode: offline
logPremiumDecisions: true

Example:

# WIP: premiumServers is currently used for logging only.
# Non-premium players are not blocked or redirected.
premiumServers:
  - lobby
  - survival

lookupCacheMinutes: 60
lookupFailureMode: offline
logPremiumDecisions: true

premiumServers must use server names from velocity.toml. Matching is case-insensitive.

Commands

Main command:

/velocityuuidrouter

Alias:

/vur

Subcommands:

/vur status
/vur players
/vur reload

Permissions:

velocityuuidrouter.status
velocityuuidrouter.players
velocityuuidrouter.reload

Building

Clone the project, then run:

./gradlew build

The jar will be created at:

build/libs/VelocityUUIDRouter-1.0.0.jar

To run tests only:

./gradlew test

To build only the jar:

./gradlew jar

Gradle is configured to use a Java 21 toolchain.

WIP

• Per server UUID management
• More configurable premium-server behavior
• Better runtime diagnostics for Geyser/Floodgate edge cases

Important Limitations

Velocity establishes a player UUID during login. Clean per-server UUID switching after login is not currently supported by Velocity, so UUID mode is session-wide.

License

This project is intended to be forkable and redistributable with credit to the original creator, RealDoc06.