Add Velocity proxy support for Minecraft 1.20.2+ configuration phase

[StarWeizz]

Fix Velocity Proxy Support for Minecraft 1.20.2+ Configuration Phase

Summary

This PR fixes bot disconnections when connecting through Velocity proxy servers with Minecraft 1.20.2+ versions. The issue occurred during server transfers when the bot sent gameplay packets (movement, physics) during the configuration phase, causing the server to kick the bot with error: "Disconnected, while in configuration phase".

Fixes #3764

Problem Description

Background

Minecraft 1.20.2 introduced a new "configuration phase" that occurs:

• During initial login
• During server transfers via Velocity proxy
• When changing resource packs

During this phase:

• Only configuration packets are allowed (registry_data, resource_pack, finish_configuration, etc.)
• Gameplay packets are NOT allowed (movement, position, look, etc.)
• Sending gameplay packets causes immediate disconnection

What Was Broken

Mineflayer was sending physics/movement packets during the configuration phase, causing:

1. Server kicks with error: "Disconnected, while in configuration phase server_resource_pack"
2. Failed transfers between Velocity backend servers
3. Resource pack deadlocks - server waiting for SUCCESSFULLY_LOADED before sending finish_configuration

Solution

1. New Velocity Plugin (lib/plugins/velocity.js)

A new plugin that:

• Tracks configuration phase state via bot.inConfigurationPhase flag
• Detects configuration phase through multiple events:
  • start_configuration (1.20.2+)
  • select_known_packs (1.21+)
  • registry_data (1.20.2+)
  • transfer (1.20.5+)
• Disables physics during configuration to prevent movement packets
• Automatically accepts resource packs during configuration phase (sends ACCEPTED + SUCCESSFULLY_LOADED immediately)
• Re-enables physics after configuration completes (after finish_configuration)
• Emits events for tracking: bot.on('configurationPhase', (phase) => {})

2. Physics Plugin Modification (lib/plugins/physics.js)

Added checks to prevent sending movement packets during configuration:

• sendPacketPosition() - Returns early if bot.inConfigurationPhase
• sendPacketLook() - Returns early if bot.inConfigurationPhase
• sendPacketPositionAndLook() - Returns early if bot.inConfigurationPhase
• updatePosition() - Returns early if bot.inConfigurationPhase

3. Loader Update (lib/loader.js)

Added velocity plugin to internal plugins list, loaded before physics plugin (order matters).

4. Example (examples/velocity_transfer.js)

New example demonstrating Velocity proxy connection and server transfer handling.

Technical Details

Configuration Phase Flow

1. Server sends: start_configuration or transfer
   ↓
2. Bot enters configuration phase
   - Sets bot.inConfigurationPhase = true
   - Disables physics (blocks movement packets)
   - Emits 'configurationPhase' event with 'start'
   ↓
3. Server sends: registry_data, resource_pack, etc.
   ↓
4. Bot handles configuration packets
   - Automatically accepts resource packs (ACCEPTED + SUCCESSFULLY_LOADED)
   ↓
5. Server sends: finish_configuration
   ↓
6. Bot acknowledges and exits configuration phase
   - Sends finish_configuration acknowledgment
   - Sets bot.inConfigurationPhase = false
   - Re-enables physics after 2s delay
   - Emits 'configurationPhase' event with 'end'

Resource Pack Handling

The plugin uses prependListener to intercept resource pack events before the resource_pack plugin processes them. This ensures:

• Packets are sent with correct UUID from raw packet data
• No race conditions with event handlers
• Immediate ACCEPTED + SUCCESSFULLY_LOADED response (required for server to continue)

Why Automatic Resource Pack Acceptance?

During Velocity transfers, resource packs must be accepted immediately or the configuration phase hangs indefinitely. The server waits for SUCCESSFULLY_LOADED before sending finish_configuration. Users can still manually handle resource packs outside of configuration phase.

Testing

Tested Scenarios

✅ Velocity proxy connection (1.21.8)
✅ Server transfers between backend servers
✅ Resource pack acceptance during transfers
✅ Multiple consecutive transfers
✅ Physics re-enabling after transfer
✅ Fallback to spawn/login events if finish_configuration doesn't fire

Test Servers

• Velocity proxy with multiple backend servers (1.20.2 - 1.21.8)
• Backend servers with mandatory resource packs
• Backend servers with custom NBT tags

How to Test

# Run the example
node examples/velocity_transfer.js <velocity-host> <velocity-port> <username>

# Expected behavior:
# 1. Bot connects to Velocity proxy
# 2. Bot logs in successfully
# 3. Bot spawns on backend server
# 4. Use server transfer command (e.g., /server hub)
# 5. Bot enters configuration phase (logged)
# 6. Bot accepts resource pack automatically
# 7. Bot exits configuration phase (logged)
# 8. Bot spawns on new backend server

Breaking Changes

None. This is a purely additive change:

• New plugin that can be disabled: plugins: { velocity: false }
• Existing bots continue to work as before
• Only affects behavior during configuration phase (which was broken before)

Backward Compatibility

• ✅ Works with Minecraft 1.20.2+ (configuration phase versions)
• ✅ Compatible with older versions (plugin does nothing if configuration phase never triggered)
• ✅ Existing resource pack handling still works outside configuration phase
• ✅ Users can still manually call bot.acceptResourcePack() for normal gameplay

Additional Notes

Why a New Plugin?

The configuration phase handling requires:

1. State tracking across multiple plugins (physics, resource_pack)
2. Packet interception before other plugins
3. Event coordination (disable/enable physics)

A dedicated plugin is cleaner than modifying multiple existing plugins.

Plugin Load Order

The velocity plugin must load before physics plugin because:

• Physics plugin needs bot.inConfigurationPhase flag
• Load order in loader.js ensures correct initialization

Files Changed

• ✨ lib/plugins/velocity.js - New plugin (180 lines)
• 🔧 lib/plugins/physics.js - Added configuration phase checks (4 locations)
• 🔧 lib/loader.js - Added velocity to plugins list (1 line)
• 📚 examples/velocity_transfer.js - New example (55 lines)

Credits

Based on investigation of issue #3764 and testing with Velocity proxy servers.