Difference between revisions of "Minecraft Forge Handshake"

From wiki.vg
Jump to navigation Jump to search
(Add packet 3.)
(Document the FML2 handshake protocol for Minecraft 1.13+)
 
(14 intermediate revisions by 4 users not shown)
Line 1: Line 1:
−
{{Box|
+
This page documents the current '''[https://minecraftforge.net/ Minecraft Forge] protocol''', including how to connect to servers running Minecraft Forge and what changes it makes to the vanilla protocol.
−
BORDER = #FFCC00|
 
−
BACKGROUND = #FFFF00|
 
−
WIDTH = 100%|
 
−
ICON = |
 
−
HEADING = Work in progress! |
 
−
CONTENT = 
 
−
This page is a work in progress, and may be missing information.
 
−
}}
 
  
−
Documentation of the [http://www.minecraftforum.net/forums/mapping-and-modding/minecraft-mods/2520465 World Downloader mod]'s plugin channel configuration system.
+
= FML protocol (1.7 - 1.12) =
  
−
See [https://github.com/Pokechu22/WorldDownloader/blob/master/src/wdl/WDLPluginChannels.java here].
+
Largely based off of [https://github.com/ORelio/Minecraft-Console-Client/pull/100 Pokechu22's work on getting Minecraft Console Client to connect to Forge servers], this section describes the FML protocol used for Minecraft 1.7.X to 1.12.X.
  
−
== Note ==
+
== Changes to [[Server List Ping]] ==
  
−
All types here are as specified by Java's [http://docs.oracle.com/javase/7/docs/api/java/io/DataOutputStream.html <code>DataOutputStream</code>] and can be read using a [http://docs.oracle.com/javase/7/docs/api/java/io/DataInputStream.html <code>DataInputStream</code>], unless otherwise noted.
+
When forge is installed, the [[Server List Ping]] changes with additional mod information:
  
−
== <code>WDL|INIT</code> ==
+
<syntaxhighlight lang="javascript">
 +
{
 +
    "description": "A Minecraft Server",
 +
    "players": {
 +
        "max": 20,
 +
        "online": 0
 +
    },
 +
    "version": {
 +
        "name": "1.8",
 +
        "protocol": 47
 +
    },
 +
    "modinfo": {
 +
        "type": "FML",
 +
        "modList": [
 +
            {
 +
                "modid": "mcp",
 +
                "version": "9.05"
 +
            },
 +
            {
 +
                "modid": "FML",
 +
                "version": "8.0.99.99"
 +
            },
 +
            {
 +
                "modid": "Forge",
 +
                "version": "11.14.3.1512"
 +
            },
 +
            {
 +
                "modid": "rpcraft",
 +
                "version": "Beta 1.3 - 1.8.0"
 +
            }
 +
        ]
 +
    }
 +
}
 +
</syntaxhighlight>
  
−
<code>WDL|INIT</code> is sent to show that World Downloader is ready to receive new permissions.  Don't send permissions until this is received - it may still be saving from another part of the map or another sever where it has permission, and revoking permission in the middle is a Bad Thing&trade;.
+
So, to test whether forge is installed, look for the <code>modinfo</code> key and then a <code>type</code> of <code>FML</code>
 +
 
 +
The <code>modList</code> contains each installed mod's version and ID.
 +
 
 +
{{warning|The key <code>modList</code> has a capital 'L', unlike any other key in the ping result!}}
 +
 
 +
This is injected in [https://github.com/MinecraftForge/MinecraftForge/blob/ebe9b6d4cbc4a5281c386994f1fbda04df5d2e1f/patches/minecraft/net/minecraft/network/ServerStatusResponse.java.patch#L45 ServerStatusResponse] by calling [https://github.com/MinecraftForge/MinecraftForge/blob/ebe9b6d4cbc4a5281c386994f1fbda04df5d2e1f/src/main/java/net/minecraftforge/fml/common/network/internal/FMLNetworkHandler.java#L197-L211 FMLNetworkHandler.enhanceStatusQuery()].
 +
 
 +
== Connection to a forge server ==
 +
 
 +
Attempting to connect to a forge server without making any changes results in getting immediately disconnected with the message "<code>This server requires FML/Forge to be installed. Contact your server admin for more details.</code>".  This message is displayed in [https://github.com/MinecraftForge/MinecraftForge/blob/ebe9b6d4cbc4a5281c386994f1fbda04df5d2e1f/src/main/java/net/minecraftforge/fml/common/FMLCommonHandler.java#L653-L661 FMLCommonHandler] and is [https://github.com/MinecraftForge/MinecraftForge/blob/ebe9b6d4cbc4a5281c386994f1fbda04df5d2e1f/patches/minecraft/net/minecraft/network/handshake/client/C00Handshake.java.patch#L35 injected] in a modified [[Protocol#Handshake|0x00 Handshake packet]].
 +
 
 +
If <code>\0FML\0</code> is added to the end of the server's address (where <code>\0</code> is a [[Wikipedia:null character]]) (again, in the 0x00 handshake packet), the server will not immediately reject you.  However, you still will not complete the connection.
 +
 
 +
This occurs because Minecraft Forge has an additional set of handshakes (for determining mods and block IDs), that must be completed before the server allows logging in.
 +
 
 +
== Forge handshake ==
 +
 
 +
Forge's handshake occurs in the middle of the [[Protocol FAQ#What's the normal login sequence for a client?|normal login sequence]], right after [[Protocol#Login Success|0x02 Login Success]] is received by the client.
 +
 
 +
In addition to the [[Debugging|normal packet debugging]] for the server, if <code>-Dfml.debugNetworkHandshake=true</code> is passed to the forge server, some more information about the current handshake status will be outputted.
 +
 
 +
{{Need Info|Why does it send the CompleteHandshake packet to itself?  How does it keep synchronized (especially near the end with the ACKs)?}}
 +
 
 +
* '''S→C''': [[Plugin channel#REGISTER|<code>REGISTER</code>]] forge's plugin channels: FML|HS, FML, FML|MP, FML, FORGE (yes, FML is there twice; technically, it does not need to be there twice but that is the way that Forge sends it and sending it that way will act more similar to forge)
 +
* '''S→C''': A ServerHello packet is sent on <code>FML|HS</code> including the player's dimension (0 if it's the first login)
 +
* '''C→S''': <code>REGISTER</code> the plugin channels: FML|HS, FML, FML|MP, FML, FORGE.
 +
* '''C→S''': A ClientHello packet is sent on the <code>FML|HS</code> channel.
 +
* '''C→S''': A ModList packet is sent.
 +
* Server checks that the mod list is compatible.  If incompatible, the player is [[Protocol#Disconnect|disconnected]] with an explanatory message.  Otherwise, continue.
 +
* '''S→C''': A ModList packet is sent.
 +
* Client checks that the mod list is compatible.  If incompatible, it disconnects.  Otherwise, continue.
 +
* '''C→S''': A HandshakeAck packet is sent, with the phase being <code>WAITINGSERVERDATA</code> (2).
 +
* '''S→C''': A series of RegistryData packets is sent, with hasMore being true for all packets except the last.
 +
* Client reads and stores each RegistryData, continuing reading until hasMore is false.  Once hasMore is false, it checks whether it has all of the needed blocks/items.  If it does not, it disconnects.  Otherwise, continue.
 +
* '''C→S''': A HandshakeAck packet is sent with phase being <code>WAITINGSERVERCOMPLETE</code> (3).
 +
* '''S→C''': A HandshakeAck packet is sent with phase being <code>WAITINGCACK</code> (2).
 +
* '''C→S''': A HandshakeAck packet is sent with phase being <code>PENDINGCOMPLETE</code> (4).
 +
* '''S→C''': A HandshakeAck packet is sent with phase being <code>COMPLETE</code> (3).
 +
* The server sends a "CompleteHandshake" packet '''to itself'''.  (Not sure why)
 +
* '''C→S''': A HandshakeAck packet is sent with phase being <code>COMPLETE</code> (5).
 +
* The client sends a "CompleteHandshake" packet '''to itself'''.  (Not sure why)
 +
 
 +
== Definitions ==
 +
 
 +
Minecraft Forge uses an additional type not covered in [[data types]] for some things -- a varshort.  This is essentially the same as a regular short, except that if the top byte (what is normally sign) is set, it is followed by an additional byte.  This allows forge to retain backwards compatibility but extend the length of certain numbers -- the varshort is only used in places where, in vanilla Minecraft, the sign bit would not have been set.  It is implemented in [https://github.com/MinecraftForge/MinecraftForge/blob/ebe9b6d4cbc4a5281c386994f1fbda04df5d2e1f/src/main/java/net/minecraftforge/fml/common/network/ByteBufUtils.java#L58-L89 ByteBufUtils].
 +
 
 +
Discriminator bytes are the way that Minecraft Forge allows sending multiple messages on one [[plugin channel]].  They aren't part of the original specification, but a similar concept is used with the [https://wiki.vg/index.php?title=Plugin_channels&oldid=14089#MC.7CAdvCmd <code>MC|AdvCdm</code> plugin channel] (used for command blocks).  That packet decides whether a block location is being sent or an entity ID (minecart command blocks) is being sent based off of the value of the first byte in the packet.
 +
 
 +
In the same way, forge uses the first byte of the plugin message to specify which packet to use.  It uses [https://github.com/MinecraftForge/MinecraftForge/blob/ebe9b6d4cbc4a5281c386994f1fbda04df5d2e1f/src/main/java/net/minecraftforge/fml/common/network/FMLIndexedMessageToMessageCodec.java FMLIndexedMessageToMessageCodec] to automatically switch the value.
 +
 
 +
Discriminator bytes change depending on the channel: 0 for <code>FML|HS</code> means something different from 0 for <code>FML</code>.
 +
 
 +
== <code>FML|HS</code> Packet structure ==
 +
 
 +
<code>FML|HS</code> is used to perform the handshake.  Discriminator bytes are found in [https://github.com/MinecraftForge/MinecraftForge/blob/ebe9b6d4cbc4a5281c386994f1fbda04df5d2e1f/src/main/java/net/minecraftforge/fml/common/network/handshake/FMLHandshakeCodec.java FMLHandshakeCodec].
 +
 
 +
=== [https://github.com/MinecraftForge/MinecraftForge/blob/ebe9b6d4cbc4a5281c386994f1fbda04df5d2e1f/src/main/java/net/minecraftforge/fml/common/network/handshake/FMLHandshakeMessage.java#L33-L76 ServerHello] ===
 +
 
 +
Starts the handshake.
  
 
{| class="wikitable"
 
{| class="wikitable"
 +
! Channel
 
  ! Bound To
 
  ! Bound To
 
  ! Field Name
 
  ! Field Name
Line 27: Line 112:
 
  ! Notes
 
  ! Notes
 
  |-
 
  |-
−
  | rowspan="2" | Server
+
|rowspan="3"| <code>FML|HS</code>
 +
|rowspan="3"| Client
 +
| Discriminator
 +
| Byte
 +
| Always 0 for ServerHello
 +
|-
 +
| FML protocol Version
 +
| Byte
 +
| Determined from [https://github.com/MinecraftForge/MinecraftForge/blob/ebe9b6d4cbc4a5281c386994f1fbda04df5d2e1f/src/main/java/net/minecraftforge/fml/common/network/NetworkRegistry.java#L67-L69 NetworkRegistery].  Currently <code>2</code>.
 +
|-
 +
| Override dimension
 +
| Optional Int
 +
| Only sent if protocol version is greater than 1.
 +
|}
 +
 
 +
=== [https://github.com/MinecraftForge/MinecraftForge/blob/ebe9b6d4cbc4a5281c386994f1fbda04df5d2e1f/src/main/java/net/minecraftforge/fml/common/network/handshake/FMLHandshakeMessage.java#L77-L95 ClientHello] ===
 +
 
 +
Response from the client to the ServerHello packet.
 +
 
 +
{| class="wikitable"
 +
! Channel
 +
! Bound To
 +
! Field Name
 +
! Field Type
 +
! Notes
 +
|-
 +
|rowspan="2"| <code>FML|HS</code>
 +
  |rowspan="2"| Server
 +
| Discriminator
 +
| Byte
 +
| Always 1 for ClientHello.
 +
|-
 +
| FML protocol Version
 +
| Byte
 +
| Determined from [https://github.com/MinecraftForge/MinecraftForge/blob/ebe9b6d4cbc4a5281c386994f1fbda04df5d2e1f/src/main/java/net/minecraftforge/fml/common/network/NetworkRegistry.java#L67-L69 NetworkRegistery].  Currently <code>2</code>.
 +
|}
 +
 
 +
=== [https://github.com/MinecraftForge/MinecraftForge/blob/ebe9b6d4cbc4a5281c386994f1fbda04df5d2e1f/src/main/java/net/minecraftforge/fml/common/network/handshake/FMLHandshakeMessage.java#L96-L152 ModList] ===
 +
 
 +
Contains a list of all mods installed on the server or client.  Sent from the client to the server first, and then the server responds with its mod list.  The server's mod list matches the one sent in the ping.
 +
 
 +
{| class="wikitable"
 +
! Channel
 +
! Bound To
 +
!colspan="2"| Field Name
 +
!colspan="2"| Field Type
 +
! Notes
 +
|-
 +
|rowspan="4"| <code>FML|HS</code>
 +
|rowspan="4"| Both
 +
|colspan="2"| Discriminator
 +
|colspan="2"| Byte
 +
| Always 2 for ModList
 +
|-
 +
|colspan="2"| Number of mods
 +
|colspan="2"| Varint
 +
| Number of mods below
 +
|-
 +
|rowspan="2"| Mods
 +
| Mod name
 +
|rowspan="2"| Array
 +
| String
 +
| Name of the mod
 +
|-
 
  | Mod version
 
  | Mod version
−
  | UTF8 string
+
  | String
−
  | This is a byte array; the remainder of the packet is this value (there is no length specified).  In some older versions of the mod, this is not present and the length of the packet is 0.
+
  | Version of the mod
 
  |}
 
  |}
  
−
== <code>WDL|CONTROL</code> ==
+
=== [https://github.com/MinecraftForge/MinecraftForge/blob/6e90348dc546164b21735aefd83ed0bac0d8283c/src/main/java/net/minecraftforge/fml/common/network/handshake/FMLHandshakeMessage.java#L154-L240 RegistryData] ===
  
−
This channel is sent from the server to the client to specify various permissions.  It uses a 4-byte integer at the start to indicate a section.  There is no required order, but it is conventional to put them in numerical order.
+
{{Need Info|Explain exactly what registries are, and figure out what Substitutions and Dummies are}}
  
−
In all cases unless otherwise indicated, if a packet is not sent its values are treated as 'true'.
+
The server sends several of this packet, one for each registry.  It'll keep sending them until the hasMore value is no longer true.
  
−
=== Default values ===
+
{| class="wikitable"
 +
! Channel
 +
! Bound To
 +
!colspan="2"| Field Name
 +
!colspan="2"| Field Type
 +
! Notes
 +
|-
 +
|rowspan="10"| <code>FML|HS</code>
 +
|rowspan="10"| Both
 +
|colspan="2"| Discriminator
 +
|colspan="2"| Byte
 +
| Always 3 for RegistryData.
 +
|-
 +
|colspan="2"| Has more
 +
|colspan="2"| Boolean
 +
| Marks whether another RegistryData packet will be sent after this.
 +
|-
 +
|colspan="2"| Name
 +
|colspan="2"| String
 +
| Name of the registry for this packet
 +
|-
 +
|colspan="2"| Number of ids
 +
|colspan="2"| Varint
 +
| Number of ids sent below
 +
|-
 +
|rowspan="2"| Ids
 +
| Name
 +
|rowspan="2"| Array
 +
| String
 +
| Name of the thing
 +
|-
 +
| Id
 +
| Varint
 +
| Numerical id of the thing
 +
|-
 +
|colspan="2"| Number of substitutions
 +
|colspan="2"| Varint
 +
| Number of substitutions sent below
 +
|-
 +
|colspan="2"| Substitutions
 +
|colspan="2"| Array of strings
 +
| Each substitution
 +
|-
 +
|colspan="2"| Number of dummies
 +
|colspan="2"| Varint
 +
| Number of dummies in the array below.  '''May not be present in older versions of forge'''; check if there still is data remaining in the packet before continuing to read data.
 +
|-
 +
|colspan="2"| Dummies
 +
|colspan="2"| Array of strings
 +
| Each dummy?
 +
|}
  
−
Specifies the default value used for permissions not sent.
+
=== [https://github.com/MinecraftForge/MinecraftForge/blob/ebe9b6d4cbc4a5281c386994f1fbda04df5d2e1f/src/main/java/net/minecraftforge/fml/common/network/handshake/FMLHandshakeMessage.java#L241-L264 HandshakeAck] ===
  
−
Note that sending this packet does not actually ''change'' the value for other packets; it instead specifies an internal fallback.  Thus, this packet can be sent at any time to change this default without needing to resend other packets.
+
Confirms that the client is able to use the settings sent previously.
  
 
{| class="wikitable"
 
{| class="wikitable"
Line 52: Line 250:
 
  ! Notes
 
  ! Notes
 
  |-
 
  |-
−
  | rowspan="2" | <code>WDL|CONTROL</code>
+
  |rowspan="2"| <code>FML|HS</code>
−
  | rowspan="2" | Client
+
  |rowspan="2"| Both
 
  | Discriminator
 
  | Discriminator
−
  | Integer
+
  | Byte
−
  | Set to 0 to indicate this packet.
+
  | Always -1 (255) for HandshakeAck
 +
|-
 +
| Phase
 +
| Byte
 +
| The current phase, which is the ordinal (0-indexed) in the [https://github.com/MinecraftForge/MinecraftForge/blob/ebe9b6d4cbc4a5281c386994f1fbda04df5d2e1f/src/main/java/net/minecraftforge/fml/common/network/handshake/FMLHandshakeClientState.java FMLHandshakeClientState] or [https://github.com/MinecraftForge/MinecraftForge/blob/ebe9b6d4cbc4a5281c386994f1fbda04df5d2e1f/src/main/java/net/minecraftforge/fml/common/network/handshake/FMLHandshakeServerState.java FMLHandshakeServerState] enums (if the server is sending it, it is in the ServerState enum, and if the client is sending it, it is the ClientState enum).
 +
|}
 +
 
 +
=== [https://github.com/MinecraftForge/MinecraftForge/blob/ebe9b6d4cbc4a5281c386994f1fbda04df5d2e1f/src/main/java/net/minecraftforge/fml/common/network/handshake/FMLHandshakeMessage.java#L265-L267 HandshakeReset] ===
 +
 
 +
Causes the client to recomplete the entire handshake from the start.  There is no payload beyond the discriminator byte.
 +
 
 +
The normal forge server does not ever use this packet, but it is used [https://github.com/SpigotMC/BungeeCord/blob/aaddc9fcfdcada8d19ab115f2dcc8aed413a9206/proxy/src/main/java/net/md_5/bungee/ServerConnector.java#L126-L138 when connecting through a BungeeCord instance], specifically when transitioning from a vanilla server to a modded one or from a modded server to another modded server.
 +
 
 +
{| class="wikitable"
 +
! Channel
 +
! Bound To
 +
! Field Name
 +
! Field Type
 +
! Notes
 
  |-
 
  |-
−
  | Default value
+
  |rowspan="1"| <code>FML|HS</code>
−
  | Boolean
+
|rowspan="1"| Client
−
  | True to enable all functions not otherwise specified, false to disable them.
+
| Discriminator
 +
  | Byte
 +
  | Always -2 (254) for HandshakeReset
 
  |}
 
  |}
  
−
=== Basic data ===
+
== <code>FML|MP</code> and multipart packets ==
  
−
Sets some of the standard properties.
+
Forge supports splitting large clientbound plugin message packets into smaller multipart packets.  This functionality does not <!-- appear to --> exist serverbound. <!-- which seems odd, given that the clientbound packet has a max size of 1 megabyte while the serverbound one is much smaller --> This system is available in all versions. <!-- or at least in 1.7.10 and above -->
 +
 
 +
This system starts by [https://github.com/MinecraftForge/MinecraftForge/blob/16bfd8cef1d12ee9ca0de1122addaf9916767ae9/src/main/java/net/minecraftforge/fml/common/network/internal/FMLProxyPacket.java#L164-L167 sending] an <code>FML|MP</code> packet to indicate what the actual packet is (note that this is within the plugin message itself):
  
 
{| class="wikitable"
 
{| class="wikitable"
Line 74: Line 294:
 
  ! Notes
 
  ! Notes
 
  |-
 
  |-
−
  | rowspan="7" | <code>WDL|CONTROL</code>
+
  |rowspan="3"| <code>FML|MP</code>
 +
|rowspan="3"| Client
 +
| Channel
 +
| String (20)
 +
| The wrapped channel
 +
|-
 +
| Parts
 +
| Unsigned byte
 +
| Total number of parts (equal to <code>ceil(dataLength / (double)(1048495))</code>
 +
|-
 +
| Length
 +
| Int
 +
| Total length of wrapped data
 +
|}
 +
 
 +
This is [https://github.com/MinecraftForge/MinecraftForge/blob/16bfd8cef1d12ee9ca0de1122addaf9916767ae9/src/main/java/net/minecraftforge/fml/common/network/internal/FMLProxyPacket.java#L173-L178 followed] by a series of additional <code>FML|MP</code> packets which write the payload.  Each packet is prefixed with the part number as an unsigned byte (starting at 0), followed by the rest of the packet containing up to 1048495 bytes of the actual message.  Each packet must be sent in order.
 +
 
 +
Up to 52424750 <!-- (0x100000 - 0x50 - 1) * 255 - the -1 is different from what FML actually checks, but matches what it seems to encode --> bytes (~52 megabytes) may be sent through this system.
 +
 
 +
== Differences from Forge 1.7.10 ==
 +
 
 +
Forge for Minecraft 1.8 made some changes from the 1.7.10 version.
 +
 
 +
The most important thing to keep track of isn't (entirely) a forge change.  In 1.7.10, [http://wiki.vg/index.php?title=Protocol&oldid=6003#Plugin_Message_2 plugin channel packets] are length prefixed, while in 1.8 they are not.  However, forge makes [https://github.com/MinecraftForge/MinecraftForge/blob/605457deecba2144d69113d3c9ce6589021f542b/fml/patches/minecraft/net/minecraft/network/play/server/S3FPacketCustomPayload.java.patch some more changes] to the server to client packet (but not the client to server packet): Rather than using a short for the length, a varshort is used.  Due to the way that varshorts work, this is backwards compatible, but if this is not accounted for you may receive forge packets that seem corrupted as there is an extra byte that appears seemingly randomly.
 +
 
 +
{{Warning|While it may seem like you can get away with not handling varshorts, on servers with lots of mods (EG FTB), this will appear.}}
 +
 
 +
Additionally, in 1.7.10 the registries packet is instead "ModIdData":
 +
 
 +
=== [https://github.com/MinecraftForge/MinecraftForge/blob/ebe9b6d4cbc4a5281c386994f1fbda04df5d2e1f/src/main/java/net/minecraftforge/fml/common/network/handshake/FMLHandshakeMessage.java#L154-L240 ModIdData] ===
 +
 
 +
Contains numeric ID mapping for blocks and items.
 +
 
 +
{{Need Info|Again, what are blockSubstitutions and itemSubstitutions?}}
 +
 
 +
{| class="wikitable"
 +
! Channel
 +
! Bound to
 +
! colspan="2"|Name
 +
! colspan="2"|Type
 +
! Notes
 +
|-
 +
| rowspan="8"|<code>FML|HS</code>
 +
| rowspan="8"|Client
 +
| colspan="2"|Discriminator
 +
| colspan="2"|Byte
 +
| Always 3 for ModIdData
 +
|-
 +
| colspan="2"|Mapping length
 +
| colspan="2"|VarInt
 +
| Length of the following mapping
 +
|-
 +
| rowspan="2"|Mapping
 +
| Name
 +
| rowspan="2"|Array
 +
| String
 +
| Name of the block/item. Prefixed with a [https://github.com/MinecraftForge/MinecraftForge/blob/1.7.10/fml/src/main/java/cpw/mods/fml/common/registry/GameData.java#L763-L766 discriminator byte], 01 = block, 02 = item.
 +
|-
 +
| ID
 +
| VarInt
 +
| Numeric ID of the item.
 +
|-
 +
| colspan="2"|Block substitutions length
 +
| colspan="2"|VarInt
 +
| Length of the following array
 +
|-
 +
| colspan="2"|Block substitutions
 +
| colspan="2"|Array of strings
 +
| Block substitutions
 +
|-
 +
| colspan="2"|Item substitutions length
 +
| colspan="2"|VarInt
 +
| Length of the following array
 +
|-
 +
| colspan="2"|Item substitutions
 +
| colspan="2"|Array of strings
 +
| Item substitutions
 +
|}
 +
 
 +
= FML2 protocol (1.13 - Current) =
 +
 
 +
This section is also mostly based off [https://github.com/ORelio/Minecraft-Console-Client/commit/a28409043ca66f811103e2cd57a6b8130baf7768#diff-8ecd732a672d36828f2451352c312eb7R243 research on making Minecraft Console Client join 1.13+ Forge servers]. As a result, it only describes the necessary steps for joining a Forge server, but not all its network protocol.
 +
 
 +
== Changes to [[Server List Ping]] ==
 +
 
 +
When forge is installed, the [[Server List Ping]] changes with additional mod information. Example for 1.13.2:
 +
 
 +
<syntaxhighlight lang="javascript">
 +
{
 +
  "description": {
 +
    "text": "A Minecraft Server"
 +
  },
 +
  "players": {
 +
    "max": 20,
 +
    "online": 0
 +
  },
 +
  "version": {
 +
    "name": "1.13.2",
 +
    "protocol": 404
 +
  },
 +
  "forgeData": {
 +
    "channels": [
 +
      {
 +
        "res": "ironchest:main_channel",
 +
        "version": "1",
 +
        "required": false
 +
      }
 +
    ],
 +
    "mods": [
 +
      {
 +
        "modId": "forge",
 +
        "modmarker": "ANY"
 +
      },
 +
      {
 +
        "modId": "ironchest",
 +
        "modmarker": "1.13.2-8.0.2"
 +
      }
 +
    ],
 +
    "fmlNetworkVersion": 2
 +
  }
 +
}
 +
</syntaxhighlight>
 +
 
 +
{{warning|The key <code>modId</code> has a capital 'I', unlike <code>modid</code> pre-1.13}} for the previous FML protocol.
 +
 
 +
== Changes to [[Protocol#Handshake|Handshake]] packet ==
 +
 
 +
Forge adds a marker to the <code>Server Address</code> field of the [[Protocol#Handshake|Handshake]] packet: <code>\0FML2\0</code> is added to the end of the server's address, where <code>\0</code> is a [https://en.wikipedia.org/wiki/Null_character null character]. Unless the Forge server has no mods installed, attempting to connect to a Forge server without making any changes results in getting immediately disconnected with the message <code>This server has mods that require Forge to be installed on the client. Contact your server admin for more details.</code>. Inferring the correct marker to use is possible by examining the Server List Ping response from the server. FML2 will set the <code>forgeData</code> > <code>fmlNetworkVersion</code> to <code>2</code>.
 +
 
 +
''References:''
 +
* [https://github.com/MinecraftForge/MinecraftForge/blob/638d1d31deabd8a83cf4b84496549703bc527ab4/src/main/java/net/minecraftforge/fml/network/FMLNetworkConstants.java#L37 FMLNetworkConstants.java]: <code>FML2</code> marker
 +
* [https://github.com/MinecraftForge/MinecraftForge/blob/638d1d31deabd8a83cf4b84496549703bc527ab4/src/main/java/net/minecraftforge/fml/network/NetworkHooks.java#L57 NetworkHooks.java]: Get marker from server IP
 +
* [https://github.com/MinecraftForge/MinecraftForge/blob/638d1d31deabd8a83cf4b84496549703bc527ab4/src/main/java/net/minecraftforge/fml/network/FMLHandshakeHandler.java#L116 FMLHandshakeHandler.java]: Get connection type from maker
 +
* [https://github.com/MinecraftForge/MinecraftForge/blob/fe43088c96cf65c6793260eae96416871a9eb8f2/src/main/java/net/minecraftforge/fml/server/ServerLifecycleHooks.java#L165 ServerLifecycleHooks.java]: Reject vanilla clients on mising marker
 +
 
 +
== Handshake Protocol ==
 +
 
 +
After receiving the [[Protocol#Login_Start|Login Start]] packet, the Forge server communicates with the Forge client using [[Protocol#Login_Plugin_Request|Login Plugin Request]] and [[Protocol#Login_Plugin_Response|Login Plugin Response]] packets before allowing the vanilla login phase to proceed as usual. Each packet must be understood and replied accordingly by the client, or the login attempt is rejected with a [[Protocol#Disconnect_.28login.29|Disconnect (Login)]] packet.
 +
 
 +
=== Login Wrapper ===
 +
 
 +
As per [https://github.com/MinecraftForge/MinecraftForge/blob/638d1d31deabd8a83cf4b84496549703bc527ab4/src/main/java/net/minecraftforge/fml/network/FMLLoginWrapper.java FMLLoginWrapper.java], the [[Protocol#Login_Plugin_Request|Login Plugin Request]] and [[Protocol#Login_Plugin_Response|Login Plugin Response]] are formatted as follows:
 +
 
 +
* <code>Channel</code> is <code>fml:loginwrapper</code>
 +
* <code>Data</code> has the following layout:
 +
 
 +
{| class="wikitable"
 +
! Field Name
 +
! Field Type
 +
! Notes
 +
|-
 +
| Channel
 +
| Identifier
 +
| Name of the plugin channel. <code>fml:handshake</code> for FML handshake.
 +
|-
 +
| Inner Packet
 +
| [[Protocol#Packet_format|Packet]]
 +
| Same layout as vanilla packets. Forge [https://github.com/MinecraftForge/MinecraftForge/blob/638d1d31deabd8a83cf4b84496549703bc527ab4/src/main/java/net/minecraftforge/fml/network/FMLLoginWrapper.java#L59 uses Minecraft's PacketBuffer class] to decode the packet.
 +
|}
 +
 
 +
=== Handshake Channel ===
 +
 
 +
Packets exchanged on the <code>fml:handshake</code> channel are described below. As per [[Protocol#Login_Plugin_Request|Login Plugin Request]] and [[Protocol#Login_Plugin_Response|Login Plugin Response]] requirements, each request sent by the server expects exactly one packet back from the client, wrapped as described in [[Minecraft_Forge_Handshake#Login Wrapper|Login Wrapper]]. The client can only respond to requests from the server. The FML handshake completes successfully once the client has correctly responded to all requests from the server.
 +
 
 +
''References:''
 +
 
 +
* [https://github.com/MinecraftForge/MinecraftForge/blob/fe43088c96cf65c6793260eae96416871a9eb8f2/src/main/java/net/minecraftforge/fml/network/NetworkInitialization.java NetworkInitialization.java]: Packet IDs
 +
* [https://github.com/MinecraftForge/MinecraftForge/blob/fe43088c96cf65c6793260eae96416871a9eb8f2/src/main/java/net/minecraftforge/fml/network/FMLHandshakeMessages.java FMLHandshakeMessages.java]: Packet layouts
 +
* [https://github.com/MinecraftForge/MinecraftForge/blob/fe43088c96cf65c6793260eae96416871a9eb8f2/src/main/java/net/minecraftforge/fml/network/FMLHandshakeHandler.java FMLHandshakeHandler.java]: Packet handling code
 +
 
 +
==== [https://github.com/MinecraftForge/MinecraftForge/blob/fe43088c96cf65c6793260eae96416871a9eb8f2/src/main/java/net/minecraftforge/fml/network/FMLHandshakeMessages.java#L63 Mod List] ====
 +
 
 +
Advertises the list of Mods, [[Plugin channel]] and Registries on the Forge server.
 +
 
 +
{| class="wikitable"
 +
! Packet ID
 +
! Bound To
 +
! colspan="2" | Field Name
 +
! colspan="2" | Field Type
 +
! Notes
 +
|-
 +
| rowspan="7" | 1
 
  | rowspan="7" | Client
 
  | rowspan="7" | Client
−
  | Discriminator
+
  | colspan="2" | Mod Count
−
  | Integer
+
| colspan="2" | VarInt
−
  | Set to 1 to indicate this packet.
+
| Length of the Mods array
 +
|-
 +
| colspan="2" | Mod Names
 +
  | colspan="2" | Array of String
 +
  | List of Mods installed on the Server
 
  |-
 
  |-
−
  | General download enabled
+
  | colspan="2" | Channel Count
−
  | Boolean
+
  | colspan="2" | VarInt
−
  | True to enable all downloading in all chunks, false to disable it.
+
  | Length of the Channels array
 
  |-
 
  |-
−
  | Save radius
+
  | rowspan="2" | Channels
−
  | Integer
+
  | Name
−
  | The distance from the player chunks can be saved from. -1 to allow all distances. This is a square distance, not a circle or a diamond.  '''Only applies if chunk caching is disabled'''.
+
  | rowspan="2" | Array
 +
  | Identifier
 +
  | Name of the [[Plugin channel]]
 
  |-
 
  |-
−
  | Chunk caching enabled
+
  | Marker
−
  | Boolean
+
  | String
−
  | Can chunks be saved as the player moves about.  If false, then they can only save within the area indicated by save radius; if true they can save everywhere.  However, regardless of this value, if general download is disabled, they cannot download.
+
  | Version of the [[Plugin channel]]
 
  |-
 
  |-
−
  | Entity saving enabled
+
  | colspan="2" | Registry Count
−
  | Boolean
+
  | colspan="2" | VarInt
−
  | True to allow the mod to save entities, false to force entities to be removed from the world.  This only applies to chunks that can be saved.
+
  | Length of the Registries array
 
  |-
 
  |-
−
  | Tile entity saving enabled
+
  | colspan="2" | Registries
−
  | Boolean
+
  | colspan="2" | Array of Identifier
−
  | True to allow the mod to save tile entities, false to force tile entities to be removed from the world.  This only applies to chunks that can be saved.
+
  | List of Registries on the Server
 
  |-
 
  |-
−
| Container saving enabled
 
−
| Boolean
 
−
| True to allow the mod to save containers (a subset of tile entities that require manual interaction to be saved, mainly chests).  This only applies if tile entities are allowed to be saved and only applies in chunks that can be saved.
 
 
  |}
 
  |}
  
−
=== Entity track distances ===
+
The client is supposed to check the list of mods against its own list, and [https://github.com/MinecraftForge/MinecraftForge/blob/fe43088c96cf65c6793260eae96416871a9eb8f2/src/main/java/net/minecraftforge/fml/network/FMLHandshakeHandler.java#L178 abort login if a mismatch is detected]. Otherwise, it should reply with [[Minecraft_Forge_Handshake#Mod_List_Reply|Mod List Reply]] to continue the handshake process.
  
−
Used to specify any custom entity track distances on the server, because they may change on spigot servers.  More info on why this is needed on [https://github.com/Pokechu22/WorldDownloader/wiki/Entities-GUI#what-are-track-distances the project wiki].
+
==== [https://github.com/MinecraftForge/MinecraftForge/blob/fe43088c96cf65c6793260eae96416871a9eb8f2/src/main/java/net/minecraftforge/fml/network/FMLHandshakeMessages.java#L131 Mod List Reply] ====
  
−
The client is free to ignore these values, and will use sane defaults based off of whether the server's brand includes "spigot" if they are not sent.  However, by default these values are used.
+
Advertises the list of Mods, [[Plugin channels]] and Registries on the Forge client, in reply to [[Minecraft_Forge_Handshake#Mod_List|Mod List]].
  
 
{| class="wikitable"
 
{| class="wikitable"
−
  ! Channel
+
  ! Packet ID
 
  ! Bound To
 
  ! Bound To
 
  ! colspan="2" | Field Name
 
  ! colspan="2" | Field Name
Line 118: Line 522:
 
  ! Notes
 
  ! Notes
 
  |-
 
  |-
−
  | rowspan="4" | <code>WDL|CONTROL</code>
+
  | rowspan="8" | 2
−
  | rowspan="4" | Client
+
  | rowspan="8" | Server
−
  | colspan="2" | Discriminator
+
  | colspan="2" | Mod Count
−
  | colspan="2" | Integer
+
  | colspan="2" | VarInt
−
  | Set to 2 to indicate this packet.
+
  | Length of the Mods array
 +
|-
 +
| colspan="2" | Mod Names
 +
| colspan="2" | Array of String
 +
| List of Mods installed on the Server
 
  |-
 
  |-
−
  | colspan="2" | Number of ranges
+
  | colspan="2" | Channel Count
−
  | colspan="2" | Integer
+
  | colspan="2" | VarInt
−
  | Size of the following array.
+
  | Length of the Channels array
 
  |-
 
  |-
−
  | rowspan="2" | Values
+
  | rowspan="2" | Channels
−
  | Entity name
+
  | Name
 
  | rowspan="2" | Array
 
  | rowspan="2" | Array
 +
| Identifier
 +
| Name of the [[Plugin channel]]
 +
|-
 +
| Marker
 
  | String
 
  | String
−
  | The name of the entity, as used in the savegame ID.
+
  | Version of the [[Plugin channel]]
 +
|-
 +
| colspan="2" | Registry Count
 +
| colspan="2" | VarInt
 +
| Length of the Registries array
 +
|-
 +
| rowspan="2" | Registries
 +
| Name
 +
| rowspan="2" | Array
 +
| Identifier
 +
| Name of the registry
 
  |-
 
  |-
−
  | Track distance
+
  | Marker
−
  | Integer
+
  | String
−
  | The track distance of the entity, in blocks.
+
  | Version of the registry
 
  |}
 
  |}
  
−
=== Permission request info ===
+
Compared to [[Minecraft_Forge_Handshake#Mod_List|Mod List]], this packet also includes a Marker for each Registry. As of MC 1.16, the Forge server [https://github.com/MinecraftForge/MinecraftForge/blob/fe43088c96cf65c6793260eae96416871a9eb8f2/src/main/java/net/minecraftforge/fml/network/FMLHandshakeHandler.java#L202 only checks the contents of the mod list], so a client just wanting to pass the server-side check can reply with the data provided by the server and leave an empty string in the Registry Marker field.
 +
 
 +
==== [https://github.com/MinecraftForge/MinecraftForge/blob/fe43088c96cf65c6793260eae96416871a9eb8f2/src/main/java/net/minecraftforge/fml/network/FMLHandshakeMessages.java#L212 Server Registry] ====
  
−
Information used with permission requests.
+
Advertises a registry to the client. The Forge server will send one request/packet per registry.
 +
 
 +
{{Need Info|The [https://github.com/MinecraftForge/MinecraftForge/blob/fe43088c96cf65c6793260eae96416871a9eb8f2/src/main/java/net/minecraftforge/registries/ForgeRegistry.java#L812 Forge Snapshot] data format is not documented yet. }}
  
 
{| class="wikitable"
 
{| class="wikitable"
−
  ! Channel
+
  ! Packet ID
−
  ! Bound to
+
  ! Bound To
 
  ! Field Name
 
  ! Field Name
 
  ! Field Type
 
  ! Field Type
 
  ! Notes
 
  ! Notes
 
  |-
 
  |-
−
  | rowspan="3" | <code>WDL|CONTROL</code>
+
  | rowspan="3" | 3
 
  | rowspan="3" | Client
 
  | rowspan="3" | Client
−
  | Discriminator
+
  | Registry Name
−
  | Integer
+
  | Identifier
−
  | Set to 3 to indicate this packet.
+
  | Name of the registry
 
  |-
 
  |-
−
  | Requests enabled
+
  | Snapshot Present
 
  | Boolean
 
  | Boolean
−
  | Whether requests work on this server.  In '''all cases''' this should be true unless you have an out of date plugin... in which case you probably wouldn't be sending this anyways.
+
  | Indicates if a Snapshot is present
 +
|-
 +
| Snapshot
 +
| [https://github.com/MinecraftForge/MinecraftForge/blob/fe43088c96cf65c6793260eae96416871a9eb8f2/src/main/java/net/minecraftforge/registries/ForgeRegistry.java#L812 Forge Snapshot]
 +
| Snapshot of the registry
 +
  |}
 +
 
 +
A client is expected to process the registry and reply with an [[Minecraft_Forge_Handshake#Acknowledgement|Acknowledgement]] packet.
 +
 
 +
==== [https://github.com/MinecraftForge/MinecraftForge/blob/fe43088c96cf65c6793260eae96416871a9eb8f2/src/main/java/net/minecraftforge/fml/network/FMLHandshakeMessages.java#L252 Configuration Data] ====
 +
 
 +
Advertises configuration data to the client.
 +
 
 +
{| class="wikitable"
 +
! Packet ID
 +
! Bound To
 +
! Field Name
 +
! Field Type
 +
! Notes
 
  |-
 
  |-
−
  | Request message
+
  | rowspan="2" | 4
 +
| rowspan="2" | Client
 +
| File Name
 
  | String
 
  | String
−
  | A message displayed to players on the permissions and permissions request screen. You can use this to display rules relating to use of the mod, or explain how you want it to be used, or what info to include in the request, etc.
+
  | Name of the configuration file
 +
|-
 +
| Data
 +
| Array of Bytes
 +
| File contents (may be a String)
 +
|}
 +
 
 +
A client is expected to process the configuration data and reply with an [[Minecraft_Forge_Handshake#Acknowledgement|Acknowledgement]] packet.
 +
 
 +
==== [https://github.com/MinecraftForge/MinecraftForge/blob/fe43088c96cf65c6793260eae96416871a9eb8f2/src/main/java/net/minecraftforge/fml/network/FMLHandshakeMessages.java#L202 Acknowledgement] ====
 +
 
 +
Acknowledges a [[Minecraft_Forge_Handshake#Server_Registry|Server Registry]] or [[Minecraft_Forge_Handshake#Configuration_Data|Configuration Data]] packet.
 +
 
 +
{| class="wikitable"
 +
! Packet ID
 +
! Bound To
 +
! Field Name
 +
! Field Type
 +
! Notes
 +
|-
 +
| 99
 +
| Server
 +
|
 +
|
 +
|
 
  |}
 
  |}
  
−
== <code>WDL|REQUEST</code> ==
+
This is a dummy packet sent back when no reply payload is required, as each request sent by the server expects a packet back from the client.
  
−
Used for permission requests.
+
[[Category:Protocol Details]]
 +
[[Category:Minecraft Modern]]

Latest revision as of 19:07, 13 August 2020

This page documents the current Minecraft Forge protocol, including how to connect to servers running Minecraft Forge and what changes it makes to the vanilla protocol.

FML protocol (1.7 - 1.12)

Largely based off of Pokechu22's work on getting Minecraft Console Client to connect to Forge servers, this section describes the FML protocol used for Minecraft 1.7.X to 1.12.X.

Changes to Server List Ping

When forge is installed, the Server List Ping changes with additional mod information: 

{
    "description": "A Minecraft Server",
    "players": {
        "max": 20,
        "online": 0
    },
    "version": {
        "name": "1.8",
        "protocol": 47
    },
    "modinfo": {
        "type": "FML",
        "modList": [
            {
                "modid": "mcp",
                "version": "9.05"
            },
            {
                "modid": "FML",
                "version": "8.0.99.99"
            },
            {
                "modid": "Forge",
                "version": "11.14.3.1512"
            },
            {
                "modid": "rpcraft",
                "version": "Beta 1.3 - 1.8.0"
            }
        ]
    }
}

So, to test whether forge is installed, look for the modinfo key and then a type of FML

The modList contains each installed mod's version and ID.

Warning.png The key modList has a capital 'L', unlike any other key in the ping result!

This is injected in ServerStatusResponse by calling FMLNetworkHandler.enhanceStatusQuery().

Connection to a forge server

Attempting to connect to a forge server without making any changes results in getting immediately disconnected with the message "This server requires FML/Forge to be installed. Contact your server admin for more details.". This message is displayed in FMLCommonHandler and is injected in a modified 0x00 Handshake packet.

If \0FML\0 is added to the end of the server's address (where \0 is a Wikipedia:null character) (again, in the 0x00 handshake packet), the server will not immediately reject you. However, you still will not complete the connection.

This occurs because Minecraft Forge has an additional set of handshakes (for determining mods and block IDs), that must be completed before the server allows logging in.

Forge handshake

Forge's handshake occurs in the middle of the normal login sequence, right after 0x02 Login Success is received by the client.

In addition to the normal packet debugging for the server, if -Dfml.debugNetworkHandshake=true is passed to the forge server, some more information about the current handshake status will be outputted.

Huh.png The following information needs to be added to this page:
Why does it send the CompleteHandshake packet to itself? How does it keep synchronized (especially near the end with the ACKs)?
  • S→C: REGISTER forge's plugin channels: FML|HS, FML, FML|MP, FML, FORGE (yes, FML is there twice; technically, it does not need to be there twice but that is the way that Forge sends it and sending it that way will act more similar to forge)
  • S→C: A ServerHello packet is sent on FML|HS including the player's dimension (0 if it's the first login)
  • C→S: REGISTER the plugin channels: FML|HS, FML, FML|MP, FML, FORGE.
  • C→S: A ClientHello packet is sent on the FML|HS channel.
  • C→S: A ModList packet is sent.
  • Server checks that the mod list is compatible. If incompatible, the player is disconnected with an explanatory message. Otherwise, continue.
  • S→C: A ModList packet is sent.
  • Client checks that the mod list is compatible. If incompatible, it disconnects. Otherwise, continue.
  • C→S: A HandshakeAck packet is sent, with the phase being WAITINGSERVERDATA (2).
  • S→C: A series of RegistryData packets is sent, with hasMore being true for all packets except the last.
  • Client reads and stores each RegistryData, continuing reading until hasMore is false. Once hasMore is false, it checks whether it has all of the needed blocks/items. If it does not, it disconnects. Otherwise, continue.
  • C→S: A HandshakeAck packet is sent with phase being WAITINGSERVERCOMPLETE (3).
  • S→C: A HandshakeAck packet is sent with phase being WAITINGCACK (2).
  • C→S: A HandshakeAck packet is sent with phase being PENDINGCOMPLETE (4).
  • S→C: A HandshakeAck packet is sent with phase being COMPLETE (3).
  • The server sends a "CompleteHandshake" packet to itself. (Not sure why)
  • C→S: A HandshakeAck packet is sent with phase being COMPLETE (5).
  • The client sends a "CompleteHandshake" packet to itself. (Not sure why)

Definitions

Minecraft Forge uses an additional type not covered in data types for some things -- a varshort. This is essentially the same as a regular short, except that if the top byte (what is normally sign) is set, it is followed by an additional byte. This allows forge to retain backwards compatibility but extend the length of certain numbers -- the varshort is only used in places where, in vanilla Minecraft, the sign bit would not have been set. It is implemented in ByteBufUtils.

Discriminator bytes are the way that Minecraft Forge allows sending multiple messages on one plugin channel. They aren't part of the original specification, but a similar concept is used with the MC|AdvCdm plugin channel (used for command blocks). That packet decides whether a block location is being sent or an entity ID (minecart command blocks) is being sent based off of the value of the first byte in the packet.

In the same way, forge uses the first byte of the plugin message to specify which packet to use. It uses FMLIndexedMessageToMessageCodec to automatically switch the value.

Discriminator bytes change depending on the channel: 0 for FML|HS means something different from 0 for FML.

FML|HS Packet structure

FML|HS is used to perform the handshake. Discriminator bytes are found in FMLHandshakeCodec.

ServerHello

Starts the handshake.

Channel Bound To Field Name Field Type Notes
FML|HS Client Discriminator Byte Always 0 for ServerHello
FML protocol Version Byte Determined from NetworkRegistery. Currently 2.
Override dimension Optional Int Only sent if protocol version is greater than 1.

ClientHello

Response from the client to the ServerHello packet.

Channel Bound To Field Name Field Type Notes
FML|HS Server Discriminator Byte Always 1 for ClientHello.
FML protocol Version Byte Determined from NetworkRegistery. Currently 2.

ModList

Contains a list of all mods installed on the server or client. Sent from the client to the server first, and then the server responds with its mod list. The server's mod list matches the one sent in the ping.

Channel Bound To Field Name Field Type Notes
FML|HS Both Discriminator Byte Always 2 for ModList
Number of mods Varint Number of mods below
Mods Mod name Array String Name of the mod
Mod version String Version of the mod

RegistryData

Huh.png The following information needs to be added to this page:
Explain exactly what registries are, and figure out what Substitutions and Dummies are

The server sends several of this packet, one for each registry. It'll keep sending them until the hasMore value is no longer true.

Channel Bound To Field Name Field Type Notes
FML|HS Both Discriminator Byte Always 3 for RegistryData.
Has more Boolean Marks whether another RegistryData packet will be sent after this.
Name String Name of the registry for this packet
Number of ids Varint Number of ids sent below
Ids Name Array String Name of the thing
Id Varint Numerical id of the thing
Number of substitutions Varint Number of substitutions sent below
Substitutions Array of strings Each substitution
Number of dummies Varint Number of dummies in the array below. May not be present in older versions of forge; check if there still is data remaining in the packet before continuing to read data.
Dummies Array of strings Each dummy?

HandshakeAck

Confirms that the client is able to use the settings sent previously.

Channel Bound To Field Name Field Type Notes
FML|HS Both Discriminator Byte Always -1 (255) for HandshakeAck
Phase Byte The current phase, which is the ordinal (0-indexed) in the FMLHandshakeClientState or FMLHandshakeServerState enums (if the server is sending it, it is in the ServerState enum, and if the client is sending it, it is the ClientState enum).

HandshakeReset

Causes the client to recomplete the entire handshake from the start. There is no payload beyond the discriminator byte.

The normal forge server does not ever use this packet, but it is used when connecting through a BungeeCord instance, specifically when transitioning from a vanilla server to a modded one or from a modded server to another modded server.

Channel Bound To Field Name Field Type Notes
FML|HS Client Discriminator Byte Always -2 (254) for HandshakeReset

FML|MP and multipart packets

Forge supports splitting large clientbound plugin message packets into smaller multipart packets. This functionality does not exist serverbound. This system is available in all versions.

This system starts by sending an FML|MP packet to indicate what the actual packet is (note that this is within the plugin message itself):

Channel Bound To Field Name Field Type Notes
FML|MP Client Channel String (20) The wrapped channel
Parts Unsigned byte Total number of parts (equal to ceil(dataLength / (double)(1048495))
Length Int Total length of wrapped data

This is followed by a series of additional FML|MP packets which write the payload. Each packet is prefixed with the part number as an unsigned byte (starting at 0), followed by the rest of the packet containing up to 1048495 bytes of the actual message. Each packet must be sent in order.

Up to 52424750 bytes (~52 megabytes) may be sent through this system.

Differences from Forge 1.7.10

Forge for Minecraft 1.8 made some changes from the 1.7.10 version.

The most important thing to keep track of isn't (entirely) a forge change. In 1.7.10, plugin channel packets are length prefixed, while in 1.8 they are not. However, forge makes some more changes to the server to client packet (but not the client to server packet): Rather than using a short for the length, a varshort is used. Due to the way that varshorts work, this is backwards compatible, but if this is not accounted for you may receive forge packets that seem corrupted as there is an extra byte that appears seemingly randomly.

Warning.png While it may seem like you can get away with not handling varshorts, on servers with lots of mods (EG FTB), this will appear.

Additionally, in 1.7.10 the registries packet is instead "ModIdData":

ModIdData

Contains numeric ID mapping for blocks and items.

Huh.png The following information needs to be added to this page:
Again, what are blockSubstitutions and itemSubstitutions?
Channel Bound to Name Type Notes
FML|HS Client Discriminator Byte Always 3 for ModIdData
Mapping length VarInt Length of the following mapping
Mapping Name Array String Name of the block/item. Prefixed with a discriminator byte, 01 = block, 02 = item.
ID VarInt Numeric ID of the item.
Block substitutions length VarInt Length of the following array
Block substitutions Array of strings Block substitutions
Item substitutions length VarInt Length of the following array
Item substitutions Array of strings Item substitutions

FML2 protocol (1.13 - Current)

This section is also mostly based off research on making Minecraft Console Client join 1.13+ Forge servers. As a result, it only describes the necessary steps for joining a Forge server, but not all its network protocol.

Changes to Server List Ping

When forge is installed, the Server List Ping changes with additional mod information. Example for 1.13.2: 

{
  "description": {
    "text": "A Minecraft Server"
  },
  "players": {
    "max": 20,
    "online": 0
  },
  "version": {
    "name": "1.13.2",
    "protocol": 404
  },
  "forgeData": {
    "channels": [
      {
        "res": "ironchest:main_channel",
        "version": "1",
        "required": false
      }
    ],
    "mods": [
      {
        "modId": "forge",
        "modmarker": "ANY"
      },
      {
        "modId": "ironchest",
        "modmarker": "1.13.2-8.0.2"
      }
    ],
    "fmlNetworkVersion": 2
  }
}

Warning.png The key modId has a capital 'I', unlike modid pre-1.13 for the previous FML protocol.

Changes to Handshake packet

Forge adds a marker to the Server Address field of the Handshake packet: \0FML2\0 is added to the end of the server's address, where \0 is a null character. Unless the Forge server has no mods installed, attempting to connect to a Forge server without making any changes results in getting immediately disconnected with the message This server has mods that require Forge to be installed on the client. Contact your server admin for more details.. Inferring the correct marker to use is possible by examining the Server List Ping response from the server. FML2 will set the forgeData > fmlNetworkVersion to 2.

References:

Handshake Protocol

After receiving the Login Start packet, the Forge server communicates with the Forge client using Login Plugin Request and Login Plugin Response packets before allowing the vanilla login phase to proceed as usual. Each packet must be understood and replied accordingly by the client, or the login attempt is rejected with a Disconnect (Login) packet.

Login Wrapper

As per FMLLoginWrapper.java, the Login Plugin Request and Login Plugin Response are formatted as follows:

  • Channel is fml:loginwrapper
  • Data has the following layout:
Field Name Field Type Notes
Channel Identifier Name of the plugin channel. fml:handshake for FML handshake.
Inner Packet Packet Same layout as vanilla packets. Forge uses Minecraft's PacketBuffer class to decode the packet.

Handshake Channel

Packets exchanged on the fml:handshake channel are described below. As per Login Plugin Request and Login Plugin Response requirements, each request sent by the server expects exactly one packet back from the client, wrapped as described in Login Wrapper. The client can only respond to requests from the server. The FML handshake completes successfully once the client has correctly responded to all requests from the server.

References:

Mod List

Advertises the list of Mods, Plugin channel and Registries on the Forge server.

Packet ID Bound To Field Name Field Type Notes
1 Client Mod Count VarInt Length of the Mods array
Mod Names Array of String List of Mods installed on the Server
Channel Count VarInt Length of the Channels array
Channels Name Array Identifier Name of the Plugin channel
Marker String Version of the Plugin channel
Registry Count VarInt Length of the Registries array
Registries Array of Identifier List of Registries on the Server

The client is supposed to check the list of mods against its own list, and abort login if a mismatch is detected. Otherwise, it should reply with Mod List Reply to continue the handshake process.

Mod List Reply

Advertises the list of Mods, Plugin channels and Registries on the Forge client, in reply to Mod List.

Packet ID Bound To Field Name Field Type Notes
2 Server Mod Count VarInt Length of the Mods array
Mod Names Array of String List of Mods installed on the Server
Channel Count VarInt Length of the Channels array
Channels Name Array Identifier Name of the Plugin channel
Marker String Version of the Plugin channel
Registry Count VarInt Length of the Registries array
Registries Name Array Identifier Name of the registry
Marker String Version of the registry

Compared to Mod List, this packet also includes a Marker for each Registry. As of MC 1.16, the Forge server only checks the contents of the mod list, so a client just wanting to pass the server-side check can reply with the data provided by the server and leave an empty string in the Registry Marker field.

Server Registry

Advertises a registry to the client. The Forge server will send one request/packet per registry.

Huh.png The following information needs to be added to this page:
The Forge Snapshot data format is not documented yet.
Packet ID Bound To Field Name Field Type Notes
3 Client Registry Name Identifier Name of the registry
Snapshot Present Boolean Indicates if a Snapshot is present
Snapshot Forge Snapshot Snapshot of the registry

A client is expected to process the registry and reply with an Acknowledgement packet.

Configuration Data

Advertises configuration data to the client.

Packet ID Bound To Field Name Field Type Notes
4 Client File Name String Name of the configuration file
Data Array of Bytes File contents (may be a String)

A client is expected to process the configuration data and reply with an Acknowledgement packet.

Acknowledgement

Acknowledges a Server Registry or Configuration Data packet.

Packet ID Bound To Field Name Field Type Notes
99 Server

This is a dummy packet sent back when no reply payload is required, as each request sent by the server expects a packet back from the client.

Retrieved from "https://wiki.vg/index.php?title=Minecraft_Forge_Handshake&oldid=15987"