Plugin channels

Plugin channels allow client mods and server plugins to communicate without cluttering up chat. This post by Dinnerbone is a good introduction and basic documentation.

Reserved channels

REGISTER

Two-way

Allows the client or server to register for one or more custom channels, indicating that data should be sent on those channels if the receiving end supports it too. Payload is a null (0x00) separated list of strings.

UNREGISTER

Two-way

Allows the client or server to unregister from one or more custom channels, indicating that the receiving end should stop sending data on those channels. Payload is a null-separated list of strings. This is only useful if plugins are disabled/unloaded while the client is connected.

Channels internal to Minecraft

Since 1.3, Minecraft itself uses several plugin channels to implement new features. These internal channel names are prefixed by MC|. They are not formally registered using the REGISTER channel. The vanilla Minecraft server will send these packets regardless, and the vanilla client will accept them.

MC|AdvCmd

Client to server

Sets the contents of a command block or command block Minecart. The Notchain client only uses this for command block minecarts and uses MC|AutoCmd for blocks, but the Notchian server still accepts it for either.

In 1.8 and earlier the name of this channel was incorrectly spelled as MC|AdvCdm. This was fixed in snapshot 15w34a.

The packet starts with a single byte, which determines the type of thing being edited (block or minecart). If it is 0, then it is a block and the location is 3 ints; if it is 1, then it is a minecart and the location is the entity's EID as an int.

type = 0

Type	Field Name	Field Type	Notes
0x00	X	Int
	Y	Int
	Z	Int
	Command	String
	Track Output	Boolean

type = 1

Type	Field Name	Field Type	Notes
0x01	Entity ID	Int
	Command	String
	Track Output	Boolean

MC|AutoCmd

Client to server

Sets command block contents. This can only be used to edit command blocks; command block minecarts cannot be used with it. To edit a command block minecart, use MC|AdvCmd.

Field Name	Field Type	Notes
X	Int
Y	Int
Z	Int
Command	String
Track output	Boolean	If false, the output of the previous command will not be stored within the command block.
Mode	String enum	One of "SEQUENCE", "AUTO", and "REDSTONE"
Is conditional	Boolean
Automatic	Boolean

MC|BEdit

Client to server

When a player edits an unsigned book.

This payload is simply a set of bytes corresponding to a Slot.

The NBT section of the Slot contains

TAG_Compound(''): 1 entry
{
  TAG_List('pages'): 2 entries
  {
    TAG_String(0): 'Something on Page 1'
    TAG_String(1): 'Something on Page 2'
  }
}

MC|BOpen

Server to client

When a player right clicks with a signed book. This tells the client to open the book GUI.

The payload is a VarInt enum for the selected hand: 0 for the main hand, 1 for the offhand.

MC|BSign

Client to server

When a player signs a book.

This payload is simply a set of bytes corresponding to a Slot.

The Item ID in the Slot should be a Written Book

The NBT section of the Slot contains

TAG_Compound(''): 3 entires
{
  TAG_String('author'): 'Steve'
  TAG_String('title'): 'A Wonderful Book'
  TAG_List('pages'): 2 entries
  {
    TAG_String(0): 'Something on Page 1'
    TAG_String(1): 'Something on Page 2'
  }
}

MC|Beacon

Client to server

Two integers corresponding to the 2 effects a user wishes to have active.

MC|Brand

Two-way

Announces the server and client implementation name right after a player has logged in. For the Notchian client and server server, this is "vanilla" (which is chosen using the Function net.minecraft.client.ClientBrandRetriever.getClientModName()) (encoded as a protocol string: a UTF-8 string with the length prefixed as a VarInt).

These brands are used in crash reports and a few other locations; it's recommended that custom clients and servers use changed brands for the purpose of identification (for the Notchian client, the class used to get the brand is one of the few non-obfuscated classes). The brand is not processed in any other way, and Notchian clients will connect to servers with changed brands with no issue (the brand is not used to validate).

The Notchian server sends a MC|Brand packet right after it sends a Join Game packet, and the Notchian client sends it right after receiving a Join Game packet. However, some modified clients and servers will not send this packet (or will take longer to send it than normal), so it is important to not crash if the brand has not been sent. Additionally, the brand may change at any time (for instance, if connected through a BungeeCord instance, you may switch from a server with one brand to a server with another brand without receiving a Join Game packet).

MC|DebugPath

Server to client

What appears to be the purpose of MC|DebugPath as seen in the snapshot 16w14a announcement. This is not found in the normal game.

Never sent, but does something with pathfinding debugging. The client reads the data and stores it, but its renderer cannot be enabled without modifications.

Name	Type	Notes
Unknown 1	Int	Used as a key in the mapping that stores this data; might be an entity ID?
Unknown 2	Float	Appears to be the "radius" of the squares for each pathpoint
Entity	PathEntity	See below

PathEntity structure:

Name	Type	Notes
Current path index	Int	Index in the points array that the entity is currently targeting. That point is rendered red; the others are rendered blue.
Target	PathPoint	Rendered as a green cube
Number of points	Int	Number of elements in the following array
Points array	Array of PathPoint	The actual points on the path
Open set length	Int	Number of elements in the following array
Open set	Array of PathPoint	Displayed in blue
Closed set length	Int	Number of elements in the following array
Closed set	Array of PathPoint	Displayed in red

PathPoint structure:

Name	Type	Notes
X	Int
Y	Int
Z	Int
Distance from origin	Float
Cost	Float
Cost malus	Float	Number that is rendered
Has been visited	Boolean
Node type	Int enum	See below
Distance to target	Float

Values for node type:

• 0: BLOCKED
• 1: OPEN
• 2: WALKABLE
• 3: TRAPDOOR
• 4: FENCE
• 5: LAVA
• 6: WATER
• 7: RAIL
• 8: DANGER_FIRE
• 9: DAMAGE_FIRE
• 10: DANGER_CACTUS
• 11: DAMAGE_CACTUS
• 12: DANGER_OTHER
• 13: DAMAGE_OTHER
• 14: DOOR_OPEN
• 15: DOOR_WOOD_CLOSED
• 16: DOOR_IRON_CLOSED

MC|DebugNeighborsUpdate

Server to client

Never sent, but used to debug block updates. Does not render without modifying the client.

This channel is invalid, as its name is longer than the max length (23 > 20).

Name	Type	Notes
Time	VarLong	World timestamp at which the update occurred. 200 ticks after this timestamp, the given update stops rendering.
Location	Position	Location of the block that updated.

MC|ItemName

Client to server

Sent as a player is renaming an item in an anvil (each keypress in the anvil UI sends a new MC|ItemName packet). If the new name is empty, then the item loses its custom name (this is different from setting the custom name to the normal name of the item). The item name may be no longer than 35 characters, and if it is longer than that, then the rename is silently ignored.

Field name	Field type	Notes
Item name	String	The new name of the item

MC|PickItem

Client to server

Used to swap out an empty space on the hotbar with the item in the given inventory slot. The Notchain client uses this for pick block functionality (middle click) to retrieve items from the inventory.

Payload is a single varint, which is the slot in the inventory to grab from.

The server will first search the player's hotbar for an empty slot, starting from the current slot and looping around to the slot before it. If there are no empty slots, it will start a second search from the current slot and find the first slot that does not contain an enchanted item. If there still are no slots that meet that criteria, then the server will use the currently selected slot.

After finding the appropriate slot, the server swaps the items and then send 3 packets:

• Set Slot, with window ID set to -2 and slot set to the newly chosen slot and the item set to the item that is now in that slot (which was previously at the slot the client requested)
• Set Slot, with window ID set to -2 and slot set to the slot the player requested, with the item that is now in that slot and was previously on the hotbar slot
• Held Item Change, with the slot set to the newly chosen slot.

MC|PingHost

Client to server

Sent after a Server list ping in Minecraft 1.6. More information on Server List Ping#1.6. In 1.7 and above, the Request (Status, 0x00, serverbound) packet is instead sent before the ping.

Since this plugin channel is only sent for the legacy server list ping, it uses the older packet structure.

MC|StopSound

Server to client

Used to implement the /stopsound command. Stops a sound that is currently playing on the client.

Field name	Field type	Notes
Sound category	String	Should be one of the sound categories used in Named Sound Effect, but if it's invalid or empty then it is (intentionally) treated as all sound categories.
Sound name	String	A sound effect name. If left empty, all sounds are stopped.

Emptiness of sound category or sound name can be combined, IE a empty sound name but a set sound category will stop all sounds in the given category.

MC|Struct

Client to server

Sets information about the Structure block.

Field Name	Field Type	Notes
X	Int	Tile entity location
Y	Int	Tile entity location
Z	Int	Tile entity location
Action	Byte	An additional action to perform beyond simply saving the given data; see below
Mode	String enum	One of "SAVE", "LOAD", "CORNER", "DATA".
Name	String
Offset X	Int	Between -32 and 32
Offset Y	Int	Between -32 and 32
Offset Z	Int	Between -32 and 32
Size X	Int	Between 0 and 32
Size Y	Int	Between 0 and 32
Size Z	Int	Between 0 and 32
Mirror	String enum	One of "NONE", "LEFT_RIGHT", "FRONT_BACK".
Rotation	String enum	One of "NONE", "CLOCKWISE_90", "CLOCKWISE_180", "COUNTERCLOCKWISE_90".
Metadata	String
Ignore entities	Boolean
Show air	Boolean
Show bounding box	Boolean
Integrity	Float	Between 0 and 1
Seed	VarLong

Possible actions:

• 2 - Save the structure
• 3 - Load the structure
• 4 - Detect size

All other values are ignored. The Notchian client uses 1 to indicate no special action should be taken (i.e. the done button).

MC|TrList

Server to client

The list of trades a villager NPC is offering.

Field Name		Field Type		Notes
Window ID		Int		The ID of the window that is open; this is an int rather than a byte.
Size		Byte		The number of trades in the following array
Trades	Input item 1	Array	Slot	The first item the villager is buying
	Output item		Slot	The item the villager is selling
	Has second item		Boolean	Whether there is a second item
	Input item 2		Optional slot	The second item the villager is buying; only present if they have a second item.
	Trade disabled		Boolean	True if the trade is disabled; false if the trade is enabled.
	Number of tool uses		Int	May actually be the number of times this trade has been used; MCP may be misleading me
	Maximum number of trade uses		Int	Number of times this trade can be used

MC|TrSel

Client to server

When a player selects a specific trade offered by a villager NPC. It contains a single int id corresponding to the selected slot int the players current (trading) inventory.

Notable community plugin channels

Channels listed in this section are not used by the vanilla Minecraft client or server. This is just a likely-incomplete list of channels used by mods/plugins popular within the Minecraft community.

BungeeCord

See here

FML|HS, FML

Main article: Minecraft Forge Handshake

Used by Minecraft Forge to negotiate required mods, among other things. FML|HS FML

ML|OpenTE

Server to client

Used by ModLoader to support custom GUI windows. Does not use the REGISTER channel.

WECUI

Main article: /WorldEditCUI

Used by the server-side WorldEdit and the client-side WorldEditCUI to coordinate selections.

WDL|INIT, WDL|CONTROL, WDL|REQUEST

Main article: /World downloader

Used by the client-side World Downloader mod to get permission information and perform permission requests.