Difference between revisions of "Classic Protocol Extension"
Line 234: | Line 234: | ||
! class="col4" | Notes | ! class="col4" | Notes | ||
|- class="row1" | |- class="row1" | ||
− | | class="col0 centeralign | + | | class="col0 centeralign" | 0x24 |
| class="col1 centeralign" | PlayerName | | class="col1 centeralign" | PlayerName | ||
| class="col2 centeralign" | string | | class="col2 centeralign" | string |
Revision as of 07:44, 12 October 2012
Contents
Negotiation
Extended clients should use magic number of 0x42
for the padding byte of the Player Identification packet. All standard/non-extended clients pad this packet with 0x00
, so extended servers should be able to easily notice extended clients. All standard/non-extended servers will ignore the modified padding byte, preserving compatibility.
When the server sees that padding byte is 0x42
, it should immediately reply with an ExtInfo packet, followed by zero or more ExtEntry packets, and await a response (ExtInfo packet) from the client.
After the client has sent its identification packet, it should await a response. If the server responds with an ExtInfo packet, it should parse it and any ExtEntry packets that follow. Client should then compare its locally-supported set of extensions with the list of extensions provided by the server, and find an intersection of these sets. These are the mutually-supported extensions.
At this time, client should send ExtInfo packet of its own, followed by the list of mutually-supported extensions. After receiving the last of ExtEntry packets, server should activate the mutually-supported extensions, and resume normal login procedure.
ExtInfo Packet
Packet ID Field Name Field Type Example Notes 0x10 AppName string MyServer
Client or server software name ExtensionCount short 1 Between 0 and 32767 Total Size: 67 bytes
ExtEntry Packet
Packet ID Field Name Field Type Example Notes 0x11 ExtName string MyExtension
Name of a supported extension Version int 1 Total Size: 69 bytes
Extensions
ClickDistance
- Used to extend or restrict the distance at which client may click blocks, controlled by the server. Click range is given in player-space units (32 units per block). Upon receiving a SetClickDistance packet, client should immediately apply the change.
SetClickDistance packet
- Server to Client
Packet ID Field Name Field Type Example Notes 0x20 Distance short 160 Total Size: 3 bytes
HeldBlock
- Provides a way for the client to notify the server about the blocktype that it is currently holding, and for the server to change the currently-held block type. When this extension is mutually supported, client should use the Player ID field of the Position and Orientation packet (currently unused) to indicate which blocktype the client is currently holding.
- The server can use HoldThis packet to force the client to hold the desired block type.
HoldThis packet
- Server to Client
Packet ID Field Name Field Type Example Notes 0x21 BlockToHold byte Obsidian Total Size: 2 bytes
EmoteFix
- This extension indicates that the client can render emotes in chat properly, without padding or suffixes that are required for vanilla client. When this extension is mutually supported, server should not pad or suffix emotes in chat. This extension does not define any new packets.
TextHotKey
- This extension allows the server to define "hotkeys" for certain commands. The server should send a definition of each hotkey (SetTextHotKey packet) once per connection. Client should not try to persist previously-defined hotkeys between sessions. When a defined hotkey is activated by the user, client should open up a text prompt and type in contents of the "Action" field. A newline character ("\n") in the Action field indicates that whatever is currently typed-in should be sent to the server. If Action does not end with a newline, text prompt should be left open, for the user to complete.
SetTextHotKey packet
- Server to Client
Packet ID Field Name Field Type Example Notes 0x22 Action string /Copy
Text to type in KeyCode int 113
SDL keycode of the key KeyMods byte 0
Key modifier flags, may be combined: - 0 = None
- 1 = Ctrl
- 2 = Shift
- 4 = Alt
Total Size: 70 bytes
ExtAddEntity
- This extension augments the Spawn Player packet to support more players and provide more flexibility in naming of players and loading of skins.
- This extension turns PlayerID byte from a signed to an unsigned byte. It allows up to 250 players/entities to be uniquely numbered on one map (with IDs between 0 and 249). ID 250-254 are reserved for future use. ID 255 ("-1" signed) should still refer to "self."
ExtAddEntity Packet
- Server to Client
Packet ID Field Name Field Type Example Notes 0x23 PlayerID unsigned byte 5
Between 0 and 249 PlayerName string Notch
Raw player name, without any formatting, to be used for autocompletion. ListName string &c[Op]Notch
Player name to be shown in the player list (tab-list). InGameName string &cNotch
Player name to be shown in-game, hovering above player model. SkinName string Notch
Player name whose skin should be used by the client. Total Size: 258 bytes
GroupedPlayerList
- This extension allows the client to be aware - for purposes of autocompletion and player-list (tab-list) display - of players on other worlds. It separates tracking of entities from tracking of names, and allows players in the tab list to be categorized by world/map. When this extension is mutually supported, information from Spawn Player packet and ExtAddEntity packets should not be used for autocompletion or player-list display.
- Client behavior: When ExtAddPlayerName packet is received for an unrecognized PlayerName, they should be added to the autocompletion list and player tab-list. When receiving ExtAddPlayerName packet for an already-listed PlayerName, client should just update ListName and GroupName. Player names should be grouped by GroupName in the player tab-list. Lists should persist when client changes worlds/maps. When ExtRemovePlayerName packet is received for a recognized PlayerName, they should be removed from autocompletion list and player tab-list. When PlayerName is received for an unrecognized PlayerName, no action should be taken.
- Server behavior: When a new player connects, ExtAddPlayerName should be sent. GroupName can be used in any way, for example to group players by map/world or rank. Server should re-send ExtAddPlayerName packet, using the identical PlayerName, when player's ListName or GroupName changes. Server should send an ExtRemovePlayerName reliably when the player disconnects.
ExtAddPlayerName Packet
- Server to Client
Packet ID Field Name Field Type Example Notes 0x24 PlayerName string Notch
Player name used for autocompletion ListName string &c[Op]Notch
GroupName string Staff
Total Size: 193 bytes
ExtRemovePlayerName Packet
- Server to Client
Packet ID Field Name Field Type Example Notes 0x24 PlayerName string Notch
Matches PlayerName of the ExtAddPlayerName packet Total Size: 65 bytes
EnvColors
- This extension allows server to change some of the colors used in world rendering, to give worlds unique feel (time-of-day, climate, etc).
EnvSetColor Packet
- Server to Client
Packet ID Field Name Field Type Example Notes 0x24 VariableToSet byte 1
Enumeration of environmental variables - 0 = reset everything
- 1 = sky color
- 2 = cloud color
- 3 = fog color
- 4 = diffuse light (blocks in shadow) color
- 5 = sunlight (blocks in sun) color
Red unsigned byte 0xF9
Green unsigned byte 0x3C
Blue unsigned byte 0x50
Total Size: 5 bytes
ExtPlayer
- Should be sent by the server after a Spawn Player packet, to identify other players using clients that support the extended protocol.
ExtPlayer packet
- Server to Client
Packet ID Field Name Field Type Example Notes 0x30 PlayerID byte 5 AppName string MyClient
Total Size: 66 bytes