Classic server protocol

Documentation on the server protocol used by the Minecraft Classic Creative server.

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.

The stock server broadcasts this heartbeat every 45 seconds.

A "heartbeat" takes the form of an HTTP request to http://www.minecraft.net/heartbeat.jsp. After sending a heartbeat, the URL for the server is returned.

It can be a GET or POST request. A table of the required parameters is below: The simplest way to send a heartbeat is to open a TCP socket to port 80 on www.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.

In the response body you'll receive a URL to the server. Else you'll get a nice HTML error message.

(No headers are returned if you use the HTTP/0.9 request format as shown above, making this simple method even simpler.)

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 }

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.

Skins
Skins for a player are downloaded by the client from http://minecraft.net/skin/skinname.png, where skinname is the name of the player. This means that the name for a player can be faked to give a desired skin.

Packet Protocol
Every packet starts with a byte representing the Packet ID.

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=0 (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 followed by a hex digit in the message tells the client to switch colors while displaying text.

Colour 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, colour codes after the first character still work. If you use an ID below 127, it doesn't add a colour code, so the ones you use will work.

It is important to note that an ampersand at the end of a message that is not followed by a hex digit will crash all clients that receive it, so it is a must to sanitize chat messages received from clients.



Multiworld
This allows the addition of adding multiple levels to the server due to how simple the client handles networking. It usually requires several minor architectural changes, and can take a few hours to implement. It requires several different maps to be stored in memory in some way, which, in C, can be done by shifting the map-related values including the map data into a struct. It also requires some way to track what map a player is in, and ways of only sending packets to players on a map. Finally, there needs to be mechanisms to add, remove, and switch maps.

With respect to packets, all that is required is that the map init packets (02, 03 several times, 04) and the player spawn/creation packets (07 several times) are sent to trigger the loading of a new map. Optionally, a new server init packet (00) can be sent before these packets to change the server name and/or message. The server appears to not need to send the player destroy packets (0C several times) to the client changing maps; however, the player destroy packet for the player (0C) should be sent to the other clients on the map