Development Resources

From Minepedia - The Minecraft Wiki!

Contents 1 Map File Format 2 Packet Protocol 2.1 Protocol Data Types 2.2 Client → Server packets 2.3 Server → Client packets 3 Resources 3.1 Programs 3.2 References and Tutorials

[edit] Map File Format

See these pages for information on Map Editing:

Map Editing (general)

Map Editing (hex)

Java Classes to Deserialize Maps

.dat Map Format

Map Format (NBT) 1 2

Java Class to read and write NBT structures

[edit] Packet Protocol

Every packet starts with a byte representing the Packet ID.

[edit] Protocol Data Types

Type	Size [bytes]	Description
Byte	1	Single byte integer (0 to 255)
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)

[edit] 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.
		Protocol version	Byte
		Username	String
		Verification key	String
		Unused	Byte
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). If a block is destroyed, the block type is the kind of block destroyed.
		X	Short
		Y	Short
		Z	Short
		Mode	Byte
		Block type	Byte
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 256 would correspond to 360 degrees.
		Player ID	Byte
		X	Short
		Y	Short
		Z	Short
		Heading	Byte
		Pitch	Byte
0x0d	Message	Packet ID	Byte	Contain chat messages sent by player.
		Unused	Byte (0xFF)
		Message	String

[edit] 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.
		Protocol version	Byte
		Server name	String
		Server MOTD	String
		User type	Byte
0x01	Ping	Packet ID	Byte	Sent to clients periodically. Presumably acts as a keep-alive packet, but this isn't known for certain.
0x02	Level Initialize	Packet ID	Byte	Notifies player of incoming level data.
0x03	Level Data Chunk	Packet ID	Byte	Contains a chunk of the level.dat file (up to 1024 bytes, padded with 0x00s if less).
		Chunk Length	Short
		Chunk Data	Byte Array
		Percent Complete	Byte
0x04	Level Finalize	Packet ID	Byte	Sent after level data is complete and gives map dimensions.
		X Size	Short
		Y Size	Short
		Z Size	Short
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.
		X	Short
		Y	Short
		Z	Short
		Block Type	Byte
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 and 0x09 below.
		Player ID	Byte
		Player Name	String
		X	Short
		Y	Short
		Z	Short
		Heading	Byte
		Pitch	Byte
0x08	Player Teleport	Packet ID	Byte	Mostly identical to player position updates but only sent for player teleports (/tp command).
		Player ID	Byte
		X	Short
		Y	Short
		Z	Short
		Heading	Byte
		Pitch	Byte
0x09	Position and Orientation Update	Packet ID	Byte	Sent with changes in player position and rotation.
		Player ID	Byte
		X	Short
		Y	Short
		Z	Short
		Heading	Byte
		Pitch	Byte
0x0a	Position Update	Packet ID	Byte	Sent with changes in player position.
		Player ID	Byte
		X	Short
		Y	Short
		Z	Short
0x0b	Orientation Update	Packet ID	Byte	Sent with changes in player rotation.
		Player ID	Byte
		Heading	Byte
		Pitch	Byte
0x0c	Despawn Player	Packet ID	Byte	Sent when player disconnects.
		Player ID	Byte
0x0d	Message	Packet ID	Byte	Messages sent by chat or from the console.
		Player ID	Byte
		Message	String
0x0e	Disconnect player	Packet ID	Byte	Sent to a player when they're disconnected from the server.
		Disconnect reason	String

[edit] Resources

(Disclaimer: This information is currently biased towards C and Java.)

[edit] Programs

URL	Program	OS	Notes
http://www.delorie.com/djgpp/	Djgpp, GCC for windows	Windows
http://www.cygwin.com/	Cygwin the Linux-on-Windows (Unix Environment)	Windows	Good for Windows users.
http://www.wireshark.org/]	Wireshark Packet Sniffer	Windows	Use this to figure out the exact contents of the packets. Notch would be unhappy if I just told you...
http://java.sun.com/javase/downloads/index.jsp	Java Development Kit download	Cross-platform	Essential if you want to compile Java code

[edit] References and Tutorials

URL	Resource	Notes
http://cppprogramming.com	C++ Programming Site	Good place to start learning C/C++.
http://beej.us/guide/bgnet/	Beej's Guide to Network Programming	Absolutely essential if you want to write any kind of server/client software. NOTE: Uses C in UNIX
http://java.sun.com/docs/books/tutorial/	Java tutorials	Learn to program in Java
http://java.sun.com/docs/books/tutorial/networking/sockets/index.html	Java socket tutorial	Network programming for Java.
http://www.java2s.com/	Java examples (example source code) Organized by topic	Also has information on C/C++ and other languages