Classic server protocol

Documentation on the server protocol used by the Minecraft Classic Creative server.
==Minecraft.net Communication==
===Heartbeats===
To be able to connect to a server in Minecraft Classic from the Server List, a server must broadcast to minecraft.net a so-called "heartbeat" every few minutes[to check: some experiments with a python server show that is not more used].
The stock server broadcasts this heartbeat every 45 seconds.
A "heartbeat" takes the form of an HTTP request to https://minecraft.net/heartbeat.jsp.
After sending a heartbeat, the URL for the server is returned.
It is critical to a successful heartbeat that you leave out the "www" in the HTTP request, as you are going to be targeting it as a URI, not a URL.
It can be a GET or POST request. A table of the required parameters is below:
Name 	Details
port 	Port number of the server. This is usually 25565
max 	Maximum number of players on the server
name 	The name of the server
public 	Whether the server is public (i.e. appears in the server list) or not. Can be True or False, in that capitalization.
version	Protocol version number, this should be 7 unless you're using a client version older than 0.28.
salt 	A random, 16-character base-62 salt
users 	Number of users connected to the server
The simplest way to send a heartbeat is to open a TCP socket to port 80 on minecraft.net, and send the following (with the values changed, obviously):
GET /heartbeat.jsp?port=25565&max=32&name=My%20Server&public=True&version=7&salt=wo6kVAHjxoJcInKx&users=0, plus a CRLF(Carriage-return and Line feed).
Make sure any strings, like name, are escaped.
If everything goes well, in the response body you'll receive a URL to the server. Otherwise you'll get a nice HTML error message. There aren't any HTML headers to parse, as the HTTP version is not specified so HTTP/0.9 is used, which does not have headers.
===User Authentication===
The "key" provided when a user joins the server can be compared to the MD5 checksum of the server's "salt" plus the username to verify that the user is logged in to minecraft.net with that username. This is useful for establishing enough trust of the name provided to ban or op the player by name.
 if( player.key == md5( server.salt + player.name ) ) {
 // player is logged in via minecraft.net
 } else {
 // player is forging the username
 }
This is also the way that Notch prevents "cracked," or pirated, clients from accessing online servers. When a cracked client tries to connect to an online server, an error will come up at the connection screen saying, "Failed to Connect: User Not Premium"
Note: This means that you should make sure your "salt" is kept a secret and shared only with heartbeat.jsp. If your server's "salt" is visible anywhere to users, it is trivial for users to produce valid-looking "key"s without being logged in to minecraft.net.
==Packet Protocol==
Every packet starts with a byte representing the Packet ID.
=== Protocol Data Types ===
Type 	Size [bytes]	Description
Byte 	1 	Single byte integer (0 to 255)
SByte 	1 	Single byte signed integer (-128 to 127)
Short 	2 	Signed integer, network order (-32768 to 32767)
String 	64 	US-ASCII/ISO646-US encoded string padded with spaces (0x20)
Byte array	1024 	Binary data padded with null bytes (0x00)
=== Client → Server packets ===
Packet ID	Purpose 	Field Description 	Field Type 	Notes
0x00 	Player Identification 	Packet ID 	Byte 	Sent by a player joining a server with relevant information. Current protocol version is 0x07.
0x00 	Player Identification 	Protocol version 	Byte 	Sent by a player joining a server with relevant information. Current protocol version is 0x07.
0x00 	Player Identification 	Username 	String 	Sent by a player joining a server with relevant information. Current protocol version is 0x07.
0x00 	Player Identification 	Verification key 	String 	Sent by a player joining a server with relevant information. Current protocol version is 0x07.
0x00 	Player Identification 	Unused 	Byte 	Sent by a player joining a server with relevant information. Current protocol version is 0x07.
0x05 	Set Block 	Packet ID 	Byte 	Sent when a user changes a block. The mode field indicates whether a block was created (0x01) or destroyed (0x00).
Block type is always the type player is holding, (even when deleting).
Client assumes that this command packet always succeeds, and so draws the new block immediately. To disallow block creation, server must send back Set Block packet with the old block type.
The XYZ coordinates of the block are just integers representing the coordinate of the block. (As opposed to player coordinates where the lower 5 bits are fractional coordinates)
0x05 	Set Block 	X 	Short 	Sent when a user changes a block. The mode field indicates whether a block was created (0x01) or destroyed (0x00).
Block type is always the type player is holding, (even when deleting).
Client assumes that this command packet always succeeds, and so draws the new block immediately. To disallow block creation, server must send back Set Block packet with the old block type.
The XYZ coordinates of the block are just integers representing the coordinate of the block. (As opposed to player coordinates where the lower 5 bits are fractional coordinates)
0x05 	Set Block 	Y 	Short 	Sent when a user changes a block. The mode field indicates whether a block was created (0x01) or destroyed (0x00).
Block type is always the type player is holding, (even when deleting).
Client assumes that this command packet always succeeds, and so draws the new block immediately. To disallow block creation, server must send back Set Block packet with the old block type.
The XYZ coordinates of the block are just integers representing the coordinate of the block. (As opposed to player coordinates where the lower 5 bits are fractional coordinates)
0x05 	Set Block 	Z 	Short 	Sent when a user changes a block. The mode field indicates whether a block was created (0x01) or destroyed (0x00).
Block type is always the type player is holding, (even when deleting).
Client assumes that this command packet always succeeds, and so draws the new block immediately. To disallow block creation, server must send back Set Block packet with the old block type.
The XYZ coordinates of the block are just integers representing the coordinate of the block. (As opposed to player coordinates where the lower 5 bits are fractional coordinates)
0x05 	Set Block 	Mode 	Byte 	Sent when a user changes a block. The mode field indicates whether a block was created (0x01) or destroyed (0x00).
Block type is always the type player is holding, (even when deleting).
Client assumes that this command packet always succeeds, and so draws the new block immediately. To disallow block creation, server must send back Set Block packet with the old block type.
The XYZ coordinates of the block are just integers representing the coordinate of the block. (As opposed to player coordinates where the lower 5 bits are fractional coordinates)
0x05 	Set Block 	Block type 	Byte 	Sent when a user changes a block. The mode field indicates whether a block was created (0x01) or destroyed (0x00).
Block type is always the type player is holding, (even when deleting).
Client assumes that this command packet always succeeds, and so draws the new block immediately. To disallow block creation, server must send back Set Block packet with the old block type.
The XYZ coordinates of the block are just integers representing the coordinate of the block. (As opposed to player coordinates where the lower 5 bits are fractional coordinates)
0x08 	Position and Orientation	Packet ID 	Byte 	Sent frequently (even while not moving) by the player with the player's current location and orientation. Player ID is always 255, referring to itself. Player coordinates are fixed-point values with the lowest 5 bits representing the fractional position (i.e. divide by 32 to get actual position in terms of block coordinates). The angle parameters are scaled such that a value of 255 would correspond to 360 degrees.
0x08 	Position and Orientation	Player ID 	Byte 	Sent frequently (even while not moving) by the player with the player's current location and orientation. Player ID is always 255, referring to itself. Player coordinates are fixed-point values with the lowest 5 bits representing the fractional position (i.e. divide by 32 to get actual position in terms of block coordinates). The angle parameters are scaled such that a value of 255 would correspond to 360 degrees.
0x08 	Position and Orientation	X 	Short 	Sent frequently (even while not moving) by the player with the player's current location and orientation. Player ID is always 255, referring to itself. Player coordinates are fixed-point values with the lowest 5 bits representing the fractional position (i.e. divide by 32 to get actual position in terms of block coordinates). The angle parameters are scaled such that a value of 255 would correspond to 360 degrees.
0x08 	Position and Orientation	Y 	Short 	Sent frequently (even while not moving) by the player with the player's current location and orientation. Player ID is always 255, referring to itself. Player coordinates are fixed-point values with the lowest 5 bits representing the fractional position (i.e. divide by 32 to get actual position in terms of block coordinates). The angle parameters are scaled such that a value of 255 would correspond to 360 degrees.
0x08 	Position and Orientation	Z 	Short 	Sent frequently (even while not moving) by the player with the player's current location and orientation. Player ID is always 255, referring to itself. Player coordinates are fixed-point values with the lowest 5 bits representing the fractional position (i.e. divide by 32 to get actual position in terms of block coordinates). The angle parameters are scaled such that a value of 255 would correspond to 360 degrees.
0x08 	Position and Orientation	Yaw (Heading) 	Byte 	Sent frequently (even while not moving) by the player with the player's current location and orientation. Player ID is always 255, referring to itself. Player coordinates are fixed-point values with the lowest 5 bits representing the fractional position (i.e. divide by 32 to get actual position in terms of block coordinates). The angle parameters are scaled such that a value of 255 would correspond to 360 degrees.
0x08 	Position and Orientation	Pitch 	Byte 	Sent frequently (even while not moving) by the player with the player's current location and orientation. Player ID is always 255, referring to itself. Player coordinates are fixed-point values with the lowest 5 bits representing the fractional position (i.e. divide by 32 to get actual position in terms of block coordinates). The angle parameters are scaled such that a value of 255 would correspond to 360 degrees.
0x0d 	Message 	Packet ID 	Byte 	Contain chat messages sent by player.
0x0d 	Message 	Unused, maybe message color	Byte (0xFF)	Contain chat messages sent by player.
0x0d 	Message 	Message 	String 	Contain chat messages sent by player.
=== Server → Client packets ===
Packet ID	Purpose 	Field Description	Field Type	Notes
0x00 	Server Identification 	Packet ID 	Byte 	Response to a joining player. The user type indicates whether a player is an op (0x64) or not (0x00) Current protocol version is 0x07.
0x00 	Server Identification 	Protocol version 	Byte 	Response to a joining player. The user type indicates whether a player is an op (0x64) or not (0x00) Current protocol version is 0x07.
0x00 	Server Identification 	Server name 	String 	Response to a joining player. The user type indicates whether a player is an op (0x64) or not (0x00) Current protocol version is 0x07.
0x00 	Server Identification 	Server MOTD 	String 	Response to a joining player. The user type indicates whether a player is an op (0x64) or not (0x00) Current protocol version is 0x07.
0x00 	Server Identification 	User type 	Byte 	Response to a joining player. The user type indicates whether a player is an op (0x64) or not (0x00) Current protocol version is 0x07.
0x01 	Ping 	Packet ID 	Byte 	Sent to clients periodically. The only way a client can disconnect at the moment is to force it closed, which does not let the server know. The ping packet is used to determine if the connection is still open.
0x02 	Level Initialize 	Packet ID 	Byte 	Notifies player of incoming level data.
0x03 	Level Data Chunk 	Packet ID 	Byte 	Contains a chunk of gzipped map (not level.dat file). After decompression the map consists of an int(4 bytes) containing number of blocks + raw map array. (chunk is up to 1024 bytes, padded with 0x00s if less).
0x03 	Level Data Chunk 	Chunk Length 	Short 	Contains a chunk of gzipped map (not level.dat file). After decompression the map consists of an int(4 bytes) containing number of blocks + raw map array. (chunk is up to 1024 bytes, padded with 0x00s if less).
0x03 	Level Data Chunk 	Chunk Data 	Byte Array	Contains a chunk of gzipped map (not level.dat file). After decompression the map consists of an int(4 bytes) containing number of blocks + raw map array. (chunk is up to 1024 bytes, padded with 0x00s if less).
0x03 	Level Data Chunk 	Percent Complete 	Byte 	Contains a chunk of gzipped map (not level.dat file). After decompression the map consists of an int(4 bytes) containing number of blocks + raw map array. (chunk is up to 1024 bytes, padded with 0x00s if less).
0x04 	Level Finalize 	Packet ID 	Byte 	Sent after level data is complete and gives map dimensions. The y coordinate is how tall the map is.
0x04 	Level Finalize 	X Size 	Short 	Sent after level data is complete and gives map dimensions. The y coordinate is how tall the map is.
0x04 	Level Finalize 	Y Size 	Short 	Sent after level data is complete and gives map dimensions. The y coordinate is how tall the map is.
0x04 	Level Finalize 	Z Size 	Short 	Sent after level data is complete and gives map dimensions. The y coordinate is how tall the map is.
0x06 	Set Block 	Packet ID 	Byte 	Sent to indicate a block change by physics or by players. In the case of a player change, the server will also echo the block change back to the player who initiated it.
0x06 	Set Block 	X 	Short 	Sent to indicate a block change by physics or by players. In the case of a player change, the server will also echo the block change back to the player who initiated it.
0x06 	Set Block 	Y 	Short 	Sent to indicate a block change by physics or by players. In the case of a player change, the server will also echo the block change back to the player who initiated it.
0x06 	Set Block 	Z 	Short 	Sent to indicate a block change by physics or by players. In the case of a player change, the server will also echo the block change back to the player who initiated it.
0x06 	Set Block 	Block Type 	Byte 	Sent to indicate a block change by physics or by players. In the case of a player change, the server will also echo the block change back to the player who initiated it.
0x07 	Spawn Player 	Packet ID 	Byte 	Sent to indicate where a new player is spawning in the world. Position and orientation are encoded the same as for packet 0x08 below.
0x07 	Spawn Player 	Player ID 	SByte 	Sent to indicate where a new player is spawning in the world. Position and orientation are encoded the same as for packet 0x08 below.
0x07 	Spawn Player 	Player Name 	String 	Sent to indicate where a new player is spawning in the world. Position and orientation are encoded the same as for packet 0x08 below.
0x07 	Spawn Player 	X 	Short 	Sent to indicate where a new player is spawning in the world. Position and orientation are encoded the same as for packet 0x08 below.
0x07 	Spawn Player 	Y 	Short 	Sent to indicate where a new player is spawning in the world. Position and orientation are encoded the same as for packet 0x08 below.
0x07 	Spawn Player 	Z 	Short 	Sent to indicate where a new player is spawning in the world. Position and orientation are encoded the same as for packet 0x08 below.
0x07 	Spawn Player 	Yaw (Heading) 	Byte 	Sent to indicate where a new player is spawning in the world. Position and orientation are encoded the same as for packet 0x08 below.
0x07 	Spawn Player 	Pitch 	Byte 	Sent to indicate where a new player is spawning in the world. Position and orientation are encoded the same as for packet 0x08 below.
0x08 	Position and Orientation (Player Teleport)	Packet ID 	Byte 	Sent with changes in player position and rotation. Teleports player it's sent to if player ID < 0 (For sending initial position in map, and /tp)
0x08 	Position and Orientation (Player Teleport)	Player ID 	SByte 	Sent with changes in player position and rotation. Teleports player it's sent to if player ID < 0 (For sending initial position in map, and /tp)
0x08 	Position and Orientation (Player Teleport)	X 	Short 	Sent with changes in player position and rotation. Teleports player it's sent to if player ID < 0 (For sending initial position in map, and /tp)
0x08 	Position and Orientation (Player Teleport)	Y 	Short 	Sent with changes in player position and rotation. Teleports player it's sent to if player ID < 0 (For sending initial position in map, and /tp)
0x08 	Position and Orientation (Player Teleport)	Z 	Short 	Sent with changes in player position and rotation. Teleports player it's sent to if player ID < 0 (For sending initial position in map, and /tp)
0x08 	Position and Orientation (Player Teleport)	Yaw (Heading) 	Byte 	Sent with changes in player position and rotation. Teleports player it's sent to if player ID < 0 (For sending initial position in map, and /tp)
0x08 	Position and Orientation (Player Teleport)	Pitch 	Byte 	Sent with changes in player position and rotation. Teleports player it's sent to if player ID < 0 (For sending initial position in map, and /tp)
0x09 	Position and Orientation Update 	Packet ID 	Byte 	Sent with changes in player position and rotation. Sent when both position and orientation is changed at the same time.
Not required for server operation.
0x09 	Position and Orientation Update 	Player ID 	SByte 	Sent with changes in player position and rotation. Sent when both position and orientation is changed at the same time.
Not required for server operation.
0x09 	Position and Orientation Update 	Change in X 	SByte 	Sent with changes in player position and rotation. Sent when both position and orientation is changed at the same time.
Not required for server operation.
0x09 	Position and Orientation Update 	Change in Y 	SByte 	Sent with changes in player position and rotation. Sent when both position and orientation is changed at the same time.
Not required for server operation.
0x09 	Position and Orientation Update 	Change in Z 	SByte 	Sent with changes in player position and rotation. Sent when both position and orientation is changed at the same time.
Not required for server operation.
0x09 	Position and Orientation Update 	Yaw (Heading) 	Byte 	Sent with changes in player position and rotation. Sent when both position and orientation is changed at the same time.
Not required for server operation.
0x09 	Position and Orientation Update 	Pitch 	Byte 	Sent with changes in player position and rotation. Sent when both position and orientation is changed at the same time.
Not required for server operation.
0x0a 	Position Update 	Packet ID 	Byte 	Sent with changes in player position.
Not required for server operation.
0x0a 	Position Update 	Player ID 	SByte 	Sent with changes in player position.
Not required for server operation.
0x0a 	Position Update 	Change in X 	SByte 	Sent with changes in player position.
Not required for server operation.
0x0a 	Position Update 	Change in Y 	SByte 	Sent with changes in player position.
Not required for server operation.
0x0a 	Position Update 	Change in Z 	SByte 	Sent with changes in player position.
Not required for server operation.
0x0b 	Orientation Update 	Packet ID 	Byte 	Sent with changes in player rotation.
Not required for server operation.
0x0b 	Orientation Update 	Player ID 	SByte 	Sent with changes in player rotation.
Not required for server operation.
0x0b 	Orientation Update 	Yaw (Heading) 	Byte 	Sent with changes in player rotation.
Not required for server operation.
0x0b 	Orientation Update 	Pitch 	Byte 	Sent with changes in player rotation.
Not required for server operation.
0x0c 	Despawn Player 	Packet ID 	Byte 	Sent when player disconnects.
0x0c 	Despawn Player 	Player ID 	SByte 	Sent when player disconnects.
0x0d 	Message 	Packet ID 	Byte 	Messages sent by chat or from the console.
0x0d 	Message 	Player ID 	SByte 	Messages sent by chat or from the console.
0x0d 	Message 	Message 	String 	Messages sent by chat or from the console.
0x0e 	Disconnect player 	Packet ID 	Byte 	Sent to a player when they're disconnected from the server.
#"Cheat detected: Distance" - happens not only when setting tile too far away from the player (how far is maximum distance and how it is measured?), but also when player moves and then immediately builds.
#"Cheat detected: Tile type"
0x0e 	Disconnect player 	Disconnect reason	String 	Sent to a player when they're disconnected from the server.
#"Cheat detected: Distance" - happens not only when setting tile too far away from the player (how far is maximum distance and how it is measured?), but also when player moves and then immediately builds.
#"Cheat detected: Tile type"
0x0f 	Update user type 	Packet ID 	Byte 	Sent when a player is opped/deopped
Will give or remove the client's ability of breaking Bedrock blocks
#User type can be either 100, which will allow the player, or 0, which will disallow the player to break Bedrock blocks
0x0f 	Update user type 	User type 	Byte 	Sent when a player is opped/deopped
Will give or remove the client's ability of breaking Bedrock blocks
#User type can be either 100, which will allow the player, or 0, which will disallow the player to break Bedrock blocks
==Player Position==
===Fixed Point===
Player position is represented via X, Y, and Z fixed-point coordinates. The fractional portion is 5 bits, so dividing the short integers received in position update packets by 32, you will have floating point coordinates for the player. This position corresponds to the center of the client viewport.
===Standing On Things===
The bottom of the player's feet is located 1.59375 (fixed-point: 51) units below the center of the viewport, so to position the player on top of a particular block you could send a teleport (0x08) packet specifying a Y value based on the block position as: (Y x 32 + 51)
===Orientation===
A yaw value of 0 means the player is facing in the Z- (negative Z) direction. This value increases in a clockwise direction as seen from above. If we call the negative Z direction "North", then a yaw of 64 means "East", 128 means "South", and 192 means "West".
A pitch value of 0 means level and this value increases in a downward direction. 64 is down, and 192 is up. Values of 65 to 191 should never occur because the player cannot look further up or down than the 64 → 0, 255 → 192 range. However, the Minecraft Classic client does not ignore invalid values, so it is possible to make players' heads "upside-down".
==Color codes==
Messages sent from the server to the client can contain color codes, which allow coloring of text for various purposes.
An ampersand symbol (&) followed by a hex digit in the message tells the client to switch colors while displaying text. The current version of the game uses a section (§) symbol, but the 0.30 version uses ampersands. For the formatting codes for the current version of the game, see Formatting codes.
Color coding at the start of the message will only work if the player ID byte is less than 127. If it's 127 or higher, the game automatically adds &e before the message, making it yellow. However, color codes after the first character still work. If you use an ID below 127, it doesn't add a color code, so the ones you use will work.
Sample	Code	Common Name 	Alternate Name	Foreground Color	Foreground Color	Foreground Color	Foreground Color	Background Color	Background Color	Background Color	Background Color
 	 	 	 	R 	G 	B 	HEX 	R 	G 	B 	HEX
 	&0 	Black 	Black 	0 	0 	0 	#000 	0 	0 	0 	#000000
 	&1 	Dark Blue 	Navy 	0 	0 	170 	#00A 	0 	0 	42 	#00002A
 	&2 	Dark Green 	Green 	0 	170 	0 	#0A0 	0 	42 	0 	#002A00
 	&3 	Teal 	Teal 	0 	170 	170 	#0AA 	0 	42 	42 	#002A2A
 	&4 	Dark Red 	Maroon 	170 	0 	0 	#A00 	42 	0 	0 	#2A0000
 	&5 	Purple 	Purple 	170 	0 	170 	#A0A 	42 	0 	42 	#2A002A
 	&6 	Dark Yellow 	Gold 	170 	170 	0 	#AA0 	42 	42 	0 	#2A2A00
 	&7 	Gray 	Silver 	170 	170 	170 	#AAA 	42 	42 	42 	#2A2A2A
 	&8 	Dark Gray 	Gray 	85 	85 	85 	#555 	21 	21 	21 	#151515
 	&9 	Indigo 	Blue 	85 	85 	255 	#55F 	21 	21 	63 	#15153F
 	&a 	Bright Green	Lime 	85 	255 	85 	#5F5 	21 	63 	21 	#153F15
 	&b 	Cyan 	Aqua 	85 	255 	255 	#5FF 	21 	63 	63 	#153F3F
 	&c 	Red 	Red 	255 	85 	85 	#F55 	63 	21 	21 	#3F1515
 	&d 	Pink 	Pink 	255 	85 	255 	#F5F 	63 	21 	63 	#3F153F
 	&e 	Yellow 	Yellow 	255 	255 	85 	#FF5 	63 	63 	21 	#3F3F15
 	&f 	White 	White 	255 	255 	255 	#FFF 	63 	63 	63 	#3F3F3F
Category:Development
de:Classic-Server Protokoll
fr:Protocole de serveur Classique
nl:Classic server protocol
pt:Protocolo de servidor Classic
ru:Протокол сервера Classic
zh:Classic服务器协议