Velocity modern player information forwarding

When working on the fallback server for Nucleoid, one of the required features was to implement Velocity's modern player information forwarding, to allow skins to correctly load in on the fallback server. To do this, I first needed to find information about how the protocol worked, and I struggled to find any official documentation, and so I've summarised my understanding of how it works here.

Initial connection

When the Minecraft client connects to a server, it begins in the handshake state, and immediately sends a packet to the server, specifying its protocol version and the next state it would like to switch to, which can be either status or login. For the purposes of implementing player information forwarding, the status state is not important.

Login phase

When connecting to an online-mode server, the login phase usually involves some cryptography and exchanges with Mojang's servers in order to authenticate the user and enable encryption of the protocol, and this is the point where information such as skin data is loaded by the server. However, when using a proxy like Velocity, the connection between the proxy and the backend server is not encrypted, and the connection is made as if it is to an offline-mode server, which does not involve any communication with Mojang, as the proxy has already performed these steps with the client. This means that the backend server has no access to the player data that velocity obtained, and so a protocol for player information forwarding is required.

Modern player information forwarding

Velocity implements two methods for forwarding player information, the legacy BungeeCord protocol (which is considered insecure), and the newer 'modern forwarding'.

Modern information forwarding makes use of the Login Plugin Request/Response packets during the login phase in order to send the data in a vanilla-compatible way.

To perform modern information forwarding, the backend server must send a Login Plugin Request packet before the Login Success packet, with the channel set to velocity:player_info, and the following payload:

Field Type Value
Protocol version byte 1 for MODERN_FORWARDING_DEFAULT (up to MC 1.18), 2 for MODERN_FORWARDING_WITH_KEY (MC 1.19+)

The velocity proxy should then respond with a corresponding Login Plugin Response, which will contain the player information.

The structure of the packet is the following:

Field Type Description
Signature byte[32] See the Validation section below
Version varint The version of the forwarding protocol the server is using. See above
Client Address String[32767] The IP address of the connecting client, in textual representation
Player ID UUID The Mojang UUID of the connecting player
Username String[16] The Mojang username of the connecting player
Properties Property[] A length (as a varint) prefixed array of Properties (see below)

If the returned version is 2 (MODERN_FORWARDING_WITH_KEY), the following fields are added to the response:

Field Type Description
Public key expiry long The expiry of the players chat signing key
Public key byte[512] The encoded RSA public key used by the client to sign messages
Public key signature byte[4096] The Mojang-provided signature of the key


Each element in the properties array is a structure like this:

Field Type Description
Name String[32767] The name of the property
Value String[32767] The value of the property
Has signature boolean Whether or not a signature follows
Signature String[32767] The signature for this property

These fields correspond to the way texture data is returned from the Mojang API during regular auth.


One of the major improvements of modern information forwarding is that the data is signed using a key shared between the proxy and backend server, which prevents somebody from impersonating the proxy if the server is accidentally exposed to the public internet.

The signature is implemented using a HMAC with SHA256 as the hash function. It is calculated from the remaining content of the payload after the signature field, and if it is invalid, then the client should be disconnected immediately.


These notes are mostly based on study of the code for the FabricProxy-Lite mod, along with some cross checking with the implementation in the actual Velocity code.