Difference between revisions of "Plugin channels"
(Update MC|ItemName info) |
(→MC|DebugNeighborsUpdate: 1.11.2's new channel) |
||
Line 272: | Line 272: | ||
* 15: DOOR_WOOD_CLOSED | * 15: DOOR_WOOD_CLOSED | ||
* 16: DOOR_IRON_CLOSED | * 16: DOOR_IRON_CLOSED | ||
+ | |||
+ | === <code>MC|DebugNeighborsUpdate</code> === | ||
+ | ''Server to client'' | ||
+ | |||
+ | Never sent, but used to debug block updates. Does not render without modifying the client. | ||
+ | |||
+ | {|class="wikitable" | ||
+ | ! Name | ||
+ | ! Type | ||
+ | ! Notes | ||
+ | |- | ||
+ | | Time | ||
+ | | Long | ||
+ | | 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. | ||
+ | |} | ||
=== <code>MC|ItemName</code> === | === <code>MC|ItemName</code> === |
Revision as of 16:12, 8 February 2017
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" (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
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 | Length of the following array |
Points array | Array of PathPoint | The actual points on the path |
Open set length | Int | Length of the following array |
Open set | Array of PathPoint | Displayed in blue |
Closed set length | Int | Length of 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.
Name | Type | Notes |
---|---|---|
Time | Long | 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). The payload is optional, and if not sent (IE, the length of the packet is 0 bytes) or 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 30 characters long, and if it is longer than that, then the rename is silently ignored.
Field name | Field type | Notes |
---|---|---|
Item name | Optional 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
Used to implement the /stopsound
command. Stops a sound that is currently playing on the client.
Field name | Field type | Notes |
---|---|---|
Sound name | String | A sound effect name. If left empty, all sounds are stopped. |
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. |
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 | 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 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
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.