Difference between revisions of "Plugin channels"

From wiki.vg
Jump to navigation Jump to search
(→‎MC|AutoCmd: Link to MC|AdvCmd)
Line 13: Line 13:
  
 
== Channels internal to Minecraft ==
 
== Channels internal to Minecraft ==
As of 1.3, Minecraft itself started using plugin channels to implement new features. These internal channel names are prefixed by <code>MC|</code>. 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.
+
Since 1.3, Minecraft itself uses several plugin channels to implement new features. These internal channel names are prefixed by <code>MC|</code>. 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.
  
 
=== <code>MC|AdvCmd</code> ===
 
=== <code>MC|AdvCmd</code> ===
Line 78: Line 78:
 
| Automatic || Boolean ||
 
| Automatic || Boolean ||
 
|}
 
|}
 
=== <code>MC|Beacon</code> ===
 
''Client to server''
 
 
Two integers corresponding to the 2 effects a user wishes to have active.
 
  
 
=== <code>MC|BEdit</code> ===
 
=== <code>MC|BEdit</code> ===
Line 102: Line 97:
 
   }
 
   }
 
</code>
 
</code>
 +
 +
=== <code>MC|BOpen</code> ===
 +
''Server to client''
 +
 +
When a player right clicks with a signed book. This tells the client to open the book GUI.
 +
This payload is empty.
  
 
=== <code>MC|BSign</code> ===
 
=== <code>MC|BSign</code> ===
Line 126: Line 127:
 
</code>
 
</code>
  
=== <code>MC|BOpen</code> ===
+
=== <code>MC|Beacon</code> ===
 +
''Client to server''
 +
 
 +
Two integers corresponding to the 2 effects a user wishes to have active.
 +
 
 +
=== <code>MC|Brand</code> ===
 +
''Two-way''
 +
 
 +
Announces the server and client implementation name right after a player has logged in. For the Notchain client and server server, this is "vanilla" (encoded as a [[Data Types|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).
 +
 
 +
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.
 +
 
 +
=== <code>MC|DebugPath</code> ===
 
''Server to client''
 
''Server to client''
  
When a player right clicks with a signed book. This tells the client to open the book GUI.
+
Never sent, but does something with pathfinding debugging. The client reads the data and stores it, but does not render anything with it.
This payload is empty.
+
 
 +
{|class="wikitable"
 +
! Name
 +
! Type
 +
! Notes
 +
|-
 +
| ?
 +
| Int
 +
|
 +
|-
 +
| ?
 +
| Float
 +
| ?
 +
|-
 +
| Entity
 +
| PathEntity
 +
| See below
 +
|}
 +
 
 +
PathEntity structure:
 +
 
 +
{| class="wikitable"
 +
! Name
 +
! Type
 +
! Notes
 +
|-
 +
| Path index
 +
| Int
 +
|
 +
|-
 +
| ?
 +
| PathPoint
 +
|
 +
|-
 +
|}
 +
 
 +
PathPoint structure:
 +
 
 +
{| class="wikitable"
 +
! Name
 +
! Type
 +
! Notes
 +
|-
 +
| ?
 +
| Float
 +
|
 +
|-
 +
| ?
 +
| Float
 +
|
 +
|-
 +
| ?
 +
| Float
 +
|
 +
|-
 +
| 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
  
 
=== <code>MC|ItemName</code> ===
 
=== <code>MC|ItemName</code> ===
Line 136: Line 237:
  
 
When a player uses an anvil to name an item. The payload is just a string: the item's new name.
 
When a player uses an anvil to name an item. The payload is just a string: the item's new name.
 +
 +
=== <code>MC|PickItem</code> ===
 +
''Client to server''
 +
 +
Swaps out an item at the given inventory index(?) with an item on the hotbar.  The server sends back several packets.  TODO: Document them.
 +
 +
Payload is a single varint.
 +
 +
=== <code>MC|PingHost</code> ===
 +
''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 [[Protocol#Request|Request]] ([[Protocol#Status|Status]], 0x00, serverbound) packet is instead sent ''before'' the ping.
 +
 +
{{Warning|Since this plugin channel is only sent for the legacy server list ping, it uses the older packet structure.}}}
  
 
=== <code>MC|Struct</code> ===
 
=== <code>MC|Struct</code> ===
Line 199: Line 314:
 
* 3 - Load the structure
 
* 3 - Load the structure
 
* 4 - Detect size
 
* 4 - Detect size
 
=== <code>MC|PickItem</code> ===
 
''Client to server''
 
 
Swaps out an item at the given inventory index(?) with an item on the hotbar.  The server sends back several packets.  TODO: Document them.
 
 
Payload is a single varint.
 
  
 
=== <code>MC|TrList</code> ===
 
=== <code>MC|TrList</code> ===
Line 258: Line 366:
 
=== <code>MC|TrSel</code> ===
 
=== <code>MC|TrSel</code> ===
 
''Client to server''
 
''Client to server''
+
 
 
When a player selects a specific trade offered by a villager NPC.
 
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.
 
It contains a single int id corresponding to the selected slot int the players current (trading) inventory.
 
=== <code>MC|PingHost</code> ===
 
''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 [[Protocol#Request|Request]] ([[Protocol#Status|Status]], 0x00, serverbound) packet is instead sent ''before'' the ping.
 
 
=== <code>MC|Brand</code> ===
 
''Two-way''
 
 
Announces the server and client implementation name right after a player has logged in. For the Notchain client and server server, this is "vanilla" (encoded as a [[Data Types|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).
 
 
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.
 
 
=== <code>MC|DebugPath</code> ===
 
''Server to client''
 
 
Never sent, but does something with pathfinding debugging.  The client reads the data and stores it, but does not render anything with it.
 
 
{|class="wikitable"
 
! Name
 
! Type
 
! Notes
 
|-
 
| ?
 
| Int
 
|
 
|-
 
| ?
 
| Float
 
| ?
 
|-
 
| Entity
 
| PathEntity
 
| See below
 
|}
 
 
PathEntity structure:
 
 
{| class="wikitable"
 
! Name
 
! Type
 
! Notes
 
|-
 
| Path index
 
| Int
 
|
 
|-
 
| ?
 
| PathPoint
 
|
 
|-
 
|}
 
 
PathPoint structure:
 
 
{| class="wikitable"
 
! Name
 
! Type
 
! Notes
 
|-
 
| ?
 
| Float
 
|
 
|-
 
| ?
 
| Float
 
|
 
|-
 
| ?
 
| Float
 
|
 
|-
 
| 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
 
  
 
== Notable community plugin channels ==
 
== Notable community plugin channels ==

Revision as of 14:18, 28 March 2016

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. This payload is empty.

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 Notchain client and server server, this is "vanilla" (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).

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.

MC|DebugPath

Server to client

Never sent, but does something with pathfinding debugging. The client reads the data and stores it, but does not render anything with it.

Name Type Notes
? Int
? Float ?
Entity PathEntity See below

PathEntity structure:

Name Type Notes
Path index Int
? PathPoint

PathPoint structure:

Name Type Notes
? Float
? Float
? Float
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|ItemName

Client to server

When a player uses an anvil to name an item. The payload is just a string: the item's new name.

MC|PickItem

Client to server

Swaps out an item at the given inventory index(?) with an item on the hotbar. The server sends back several packets. TODO: Document them.

Payload is a single varint.

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.

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

MC|Struct

Client to server

Does something with the (inaccessible) Structure block.

Field Name Field Type Notes
X Int Tile entity location
Y Int Tile entity location
Z Int Tile entity location
Action Byte See below
Mode String enum One of "SAVE", "LOAD", "CORNER", "DATA".
Name String
Position X Int ?
Position Y Int ?
Position Z Int ?
Size X Int ?
Size Y Int ?
Size Z Int ?x
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

Possible modes:

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

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

Two-way

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

For more information, see Minecraft Forge Handshake.

ML|OpenTE

Server to client

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

WECUI

Two-way

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