Classic Protocol Extension

Classic Protocol Extension (CPE) is a project to augment the Minecraft Classic network protocol. Extensions are designed to keep custom clients and servers compatible to standard/vanilla clients and servers. Standard clients and extended clients can play on the same server at the same time. Extensions are also designed to be modular: clients and servers can choose to implement any subset of extensions, and only mutually-supported extensions will be used.

This specification has not yet been finalized, and is subject to change. Last revision: 25 August 2013

Support

These custom servers plan to add support for CPE: fCraft, FemtoCraft, 800Craft, GGS

These custom clients plan to add support for CPE: Charged Miners, OpenClassic

Negotiation

Client behavior: Extended clients must use magic number of 0x42 for the padding byte of the Player Identification packet. After the client has sent its identification packet, it must await a response. If server responds with any packet other than ExtInfo, client must assume that the server does not support CPE. If the server responds with an ExtInfo packet, client must parse it and any ExtEntry packets that follow. Client must 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. Client must now send ExtInfo packet of its own, followed by a list of zero or more client-supported extensions. After sending the last of ExtEntry packets, client should activate all mutually-supported extensions and resume normal login procedure.

Server behavior: All standard/non-extended clients pad this packet with 0x00, so extended servers can 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 must immediately reply with an ExtInfo packet, followed by zero or more ExtEntry packets, and await a response (ExtInfo packet) from the client. Client will respond with one ExtInfo and zero or more ExtEntry packets. Server must then compare its locally-supported set of extensions with the list of extensions provided by the client, and find an intersection of these sets. These are the mutually-supported extensions. After receiving the last of ExtEntry packets, server should activate all mutually-supported extensions and resume normal login procedure.

ExtInfo Packet

Packet ID	Field Name	Field Type	Example	Notes
0x10 (16)	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 (17)	ExtName	string	MyExtension	Name of a supported extension
	Version	int	1	Only extensions with identical version numbers should be considered compatible.
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).

Motivation: This extension allows trusted players to have a wider or virtually-unlimited reach. It may simplify operation of certain bots. Restricting the reach may allow new games/mini-games.

Client Behavior: Upon receiving a SetClickDistance packet, client should immediately apply the change. Distance should persist between worlds/maps.

Server Behavior: Server should send SetClickDistance packet when the server connects, or whenever their permitted click distance changes. Server should allow for some margin-of-error (+/- 1 block) when enforcing click distance restrictions.

SetClickDistance packet

Server to Client

Packet ID	Field Name	Field Type	Example	Notes
0x12 (18)	Distance	short	160
Total Size:	3 bytes

CustomBlocks

Used to add support for custom block types. Custom block IDs start at 50 (0x32). New block types will be added in batches, a few at a time. Both client and server declare which batch they support, and use the lower of the two versions. Claiming to supporting a batch implies fully implementing all the batches that came before it. If either server or client do not support this extension, only the standard 50 block types should be used.

Motivation: Adding new visually distinct blocks, to enhance Classic players' experience.

Client behavior: Client must expect a CustomBlockSupportLevel packet immediately after receiving a handshake from the server. It should then send its own CustomBlockSupportLevel packet, containing its actual support level. Client must then use the lower of the two levels in operation. Client must not send any block types that are not defined by the current support level.

Server behavior: Server must send a CustomBlockSupportLevel packet immediately after sending a handshake to the client. It should then wait to receive a CustomBlockSupportLevel packet from the client before sending anything else. Server must then use the lower of the two levels in operation. If this level is lower than the server's, it has to filter data sent to the client, to make sure that the client never receives any block types that it does not support. Each level will define what substitutions to use.

CustomBlockSupportLevel packet

Server to Client

Packet ID	Field Name	Field Type	Example	Notes
0x13 (19)	SupportLevel	byte	1
Total Size:	2

Blocks in support level 1

Client must be able to receive/render all 16 custom blocks to claim support. Server must be able to receive/store all 16 custom blocks to claim support.

Block name	Block ID	Fallback name	Fallback ID
CobblestoneSlab	0x32 (50)	Slab	0x2C (44)
SpiderWeb	0x33 (51)	TDB	TBD
SmoothSandstone	0x34 (52)	Sand	0x0C (12)
Snow	0x35 (53)	TBD	TBD
Fire	0x36 (54)	Lava	0x0A (10)
LightPinkWool	0x37 (55)	Pink	0x21 (33)
ForestGreenWool	0x38 (56)	Green	0x19 (25)
BrownWool	0x39 (57)	Dirt	0x03 (3)
DeepBlue	0x3A (58)	Blue	0x1d (29)
Turquoise	0x3B (59)	Cyan	0x1c (28)
Ice	0x3C (60)	Glass	0x14 (20)
CeramicTile	0x3D (61)	Iron	0x2a (42)
Magma	0x3E (62)	Obsidian	0x31 (49)
Pillar	0x3F (63)	White	0x24 (36)
Crate	0x40 (64)	WoodenPlanks	0x05 (5)
StoneBrick	0x41 (65)	Stone	0x01 (1)

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.

Motivation: This allows server to know which block player is holding, for example for drawing commands, without needing to wait for the player's click. it also allows for features like /Spectate to show what block a spectated player is holding.

Client behavior: 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. It should be ready to accept HoldThis packets to change the block that the player is holding. If 0 is given for BlockToHold, client should hide the hand/block from the screen, and should not be able to click blocks, until they switch to a different blocktype. If an unrecognized blocktype is given, no action is needed.

Server behavior: The server can use HoldThis packet to force the client to hold the desired block type. It should be done sparingly.

HoldThis packet

Server to Client

Packet ID	Field Name	Field Type	Example	Notes
0x14 (20)	BlockToHold	byte	49	Standard block type
	PreventChange	byte	0	0 = Allow player to change blocktype 1 = Prevent player from changing blocktype
Total Size:	2 bytes

EmoteFix

This extension indicates that the client can render emotes (ASCII control characters) in chat properly, without padding or suffixes that are required for vanilla client. This extension does not define any new packets.

Motivation: To improve appearance of emotes in chat.

Client behavior: Client should not emulate vanilla client's quirks.

Server behavior: Server should not pad or suffix emotes in chat.

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
0x15 (21)	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
0x16 (22)	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
0x17 (23)	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
0x18 (24)	PlayerName	string	Notch	Matches PlayerName of the ExtAddPlayerName packet
Total Size:	65 bytes

EnvColors

This extension allows server to alter some of the colors used by the client in environment rendering.

Motivation: To allow the server to give worlds/maps a unique feel: time-of-day, weather/climate, lighting effect, etc.

Client behavior: Client must check for EnvSetColor packets right before Level Finalize packet, and apply these changes before the map is displayed. Client should be able to read this packet at other times, but it is not required to then apply the changes immediately. If an unrecognized or unsupported Variable field is given, no action is needed.

Server behavior: Server should normally only use EnvSetColor packets right before the Level Finalize packet.

EnvSetColor Packet

Server to Client

Packet ID	Field Name	Field Type	Example	Notes
0x19 (25)	Variable	byte	1	Enumeration of environmental variables 0 = sky color 1 = cloud color 2 = fog color 3 = ambient light (blocks in shadow) color 4 = diffuse light (sunlight) color
	Red	unsigned byte	0xF9
	Green	unsigned byte	0x3C
	Blue	unsigned byte	0x50
Total Size:	5 bytes

SelectionCuboid

Motivation: To allow the server to highlight parts of a world (e.g. for zoning). To allow players to preview draw commands, such as cuboids.

Client behavior:

Server behavior:

MakeSelection packet

Server to Client

Packet ID	Field Name	Field Type	Example	Notes
0x20 (26)	SelectionID	byte	0	Numeric ID of the selection
	Label	string	SomeZone	Text label associated with the selection
	StartX	short	1	X coordinate of the starting point
	StartY	short	2	Y coordinate of the starting point
	StartZ	short	3	Z coordinate of the starting point
	EndX	short	5	X coordinate of the ending point
	EndY	short	6	Y coordinate of the ending point
	EndZ	short	7	Z coordinate of the ending point
	Red	unsigned byte	0xF9
	Green	unsigned byte	0x3C
	Blue	unsigned byte	0x50
	Opacity	unsigned byte	0xFF	0x00 = fully transparent 0xFF = fully opaque
Total Size:	82 bytes

RemoveSelection packet

Server to Client

Packet ID	Field Name	Field Type	Example	Notes
0x21 (27)	SelectionID	byte	0
Total Size:	2 bytes

ExtPlayer

Should be sent by the server after a Spawn Player packet, to identify other players using clients that support the extended protocol.

Motivation: To allow any custom client software to recognize other players using the same client and interact with them accordingly.

Client behavior: Implementation-specific. An example might be displaying an alternate model for players using the same client.

Server behavior: The packet should be sent immediately following the Spawn Player packet (or ExtAddPlayerName packet, if ExtPlayerList is supported) when a new client connects to the server.

ExtPlayer packet

Server to Client

Packet ID	Field Name	Field Type	Example	Notes
0x22 (28)	PlayerID	byte	5
	AppName	string	MyClient
Total Size:	66 bytes

OnScreenMenu

TODO