Difference between revisions of "Classic Protocol Extension"

From wiki.vg
Jump to navigation Jump to search
Line 158: Line 158:
 
:This extension augments the [[Classic_Protocol#Server_.E2.86.92_Client_packets|Spawn Player]] packet to support more players and provide more flexibility in naming of players and loading of skins, autocompletion, and player tab-list display. It also turns PlayerID byte from a signed to an unsigned, allowing up to 250 players/entities to be uniquely numbered on one map). IDs 0-254 should be used to identify other players. ID 255 ("-1" signed) should still refer to "self."
 
:This extension augments the [[Classic_Protocol#Server_.E2.86.92_Client_packets|Spawn Player]] packet to support more players and provide more flexibility in naming of players and loading of skins, autocompletion, and player tab-list display. It also turns PlayerID byte from a signed to an unsigned, allowing up to 250 players/entities to be uniquely numbered on one map). IDs 0-254 should be used to identify other players. ID 255 ("-1" signed) should still refer to "self."
  
:This extension separates tracking of entities from tracking of names, to allow listing and autocompleting names of players on worlds/maps other than client's own. It also allows organizing player names into groups, making the player tab-list easier to read.
+
:'''Motivation''': Allows listing and autocompleting names of players on worlds/maps other than client's own, organizing player names into groups, and making the player tab-list easier to read.
  
 
:<h4>Client Behavior</h4>
 
:<h4>Client Behavior</h4>

Revision as of 08:41, 12 October 2012

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.
Motivation: To speed up and simplify access to commonly-used commands and command macros by providing server-defined client-side hotkeys.
Client behavior: 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. Client may provide a way for the user to see a list of currently-defined hotkeys, and a way to notify the user when a hotkey was activated.
Server behavior: The server should send a definition of each hotkey (SetTextHotKey packet) once per connection.

SetTextHotKey packet

Server to Client
Packet ID Field Name Field Type Example Notes
0x22 Label string Copy Readable name of the hotkey
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: 134 bytes

ExtPlayerList

This extension augments the Spawn Player packet to support more players and provide more flexibility in naming of players and loading of skins, autocompletion, and player tab-list display. It also turns PlayerID byte from a signed to an unsigned, allowing up to 250 players/entities to be uniquely numbered on one map). IDs 0-254 should be used to identify other players. ID 255 ("-1" signed) should still refer to "self."
Motivation: Allows listing and autocompleting names of players on worlds/maps other than client's own, organizing player names into groups, and making the player tab-list easier to read.

Client Behavior

When ExtAddPlayerName packet is received for an unrecognized PlayerID, a new entry should be added to the autocompletion list and player tab-list. When receiving ExtAddPlayerName packet for an already-listed PlayerID, client should just update ListName, GroupName, and GroupRank.
Player names should be grouped by GroupName in the player tab-list. Players within a GroupName should be sorted by GroupRank (in ascending order). Players within the same GroupName and GroupRank should be sorted alphabetically by ListName. Color codes should be either drawn or stripped in ListName, GroupName, and InGameName. Lists should persist when client changes worlds/maps.
When an ExtAddEntity packet is received, it should be treated as the Spawn Player packet. InGameName should be shown above the player's heads in-game. Skin should be loaded from minecraft.net using the given SkinName for a player name. Client should still be ready to treat Spawn Player packets normally. When client receives ExtAddEntity packet for an already-spawned player, their InGameName and SkinName should be updated.
When a standard Despawn Player packet is received, player model should be removed from a world, but player name should stay on the autocompletion list and tab-list until ExtRemovePlayerName packet is received for the PlayerID.
When ExtRemovePlayerName packet is received for a recognized PlayerID, they should be removed from autocompletion list and player tab-list. If ExtAddEntity packet was used to spawn a player with the same ID, it should be despawned (treated as Despawn Player packet). When ExtRemovePlayerName is received for an unrecognized PlayerID, no action should be taken.

Server Behavior

When a new player connects, ExtAddPlayerName should be sent. GroupName and GroupRank can be used in any way, for example to group players by map/world or rank/class/faction. Server should re-send ExtAddPlayerName packet, using the identical PlayerName, when player's ListName, GroupName, or GroupRank change. Server may opt to use ExtAddEntity or standard SpawnPlayer packet. Server should reliably send an ExtRemovePlayerName when the player disconnects. Color codes are permitted in ListName, GroupName, and InGameName.

ExtAddPlayerName Packet

Server to Client
Packet ID Field Name Field Type Example Notes
0x23 PlayerID unsigned byte 5 Between 0 and 254
PlayerName string Notch Player name used for autocompletion
ListName string &c[Op]Notch
GroupName string Staff
GroupRank byte 0 Rank of a player within the group.
Total Size: 193 bytes

ExtAddEntity Packet

Server to Client
Packet ID Field Name Field Type Example Notes
0x24 PlayerID unsigned byte 5 Between 0 and 249
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

ExtRemovePlayerName Packet

Server to Client
Packet ID Field Name Field Type Example Notes
0x25 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
0x26 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