Map File Format
See these pages for information on Map Editing:
Map Editing (general)
Java Classes to Deserialize Maps
Packet Protocol
Protocol Data Types
| Type | Size [bytes] | Description |
|---|---|---|
| Byte | 1 | Single byte integer |
| Short | 2 | Signed integer, network order |
| String | 64 | Ascii string padded with spaces |
| 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. |
| 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 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. |
| Unused | Byte | |||
| X | Short | |||
| Y | Short | |||
| Z | Short | |||
| Heading | Byte | |||
| Pitch | Byte | |||
| 0x0d | Message | Packet ID | Byte | Contain chat messages sent by player. |
| Unused | Byte | |||
| Message | String |
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 | |||
| Delta X | Byte | |||
| Delta Y | Byte | |||
| Delta Z | Byte | |||
| Delta heading | Byte | |||
| Delta pitch | Byte | |||
| 0x0a | Position Update | Packet ID | Byte | Sent with changes in player position. |
| Player ID | Byte | |||
| Delta X | Byte | |||
| Delta Y | Byte | |||
| Delta Z | Byte | |||
| 0x0b | Orientation Update | Packet ID | Byte | Sent with changes in player rotation. |
| Player ID | Byte | |||
| Delta heading | Byte | |||
| Delta 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 | Op/Deop Player | Packet ID | Byte | Sent when player is opped (0x64) or deopped (0x00). |
| User Type | Byte |
Resources
(Disclaimer: This information is currently biased towards C and Java.)
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 |
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 |
| 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. |