Protocol Overview

This page gives a slightly less technical overview of the minecraft protocol.

Tips

• You need to support the entire protocol. Packets do not have a length field (although some arrays do) and can't be skipped over, so you will need to write generic support for common data types including the slot type and the entity metadata format. While it's okay to do some initial testing in the style of socket.send('\x01'), the reality is you will need to write a decent type packer/unpacker and define packet structures abstractly.
• Some packets have weird rules, for example in 0x17 spawn object/vehicle the last 3 fields only sent if another field is >0
• When arrays are sent, you'll sometimes get the data length, sometimes the record count (these are the same if the record length = 1 byte), and sometimes both. On occasion you'll need to use the same length field to unpack more than one array
• You will need to unpack arrays of dynamic-length datatypes, as in 0x68 set window items
• Sometimes packets send condensed data in arrays that can be unpacked according to a specific format. However, as the array length is given, this is only necessary if you're actually interested in the data. Examples:
  • 0x34 chunk data
  • 0x35 multi block change
  • 0x38 map chunk bulk
  • 0x3C explosion
  • 0xFF kick when responding to a server list ping
• If you want to understand enchantment data sent in slot data, you will need to support NBT
• You will need to support AES, RSA and sha1 as protocol encryption is required

Overview

Authentication

Please see the page on protocol encryption for more details on the authentication process

• 0x01 login request
• 0x02 handshake
• 0xFC encryption key response
• 0xFD encryption key request

Player Movement

Packets 0x0A - 0x0D are sent by the minecraft client when the player moves. 0x0D is also sent server->client to update other player positions.

• 0x0A player
• 0x0B player position
• 0x0C player look
• 0x0D player position & look

Player Interaction

• 0x07 use entity - left-clicking or right-clicking entities
• 0x08 update health - includes HP and food
• 0x09 respawn - unidirectional, sent C->S when the "respawn" button is pressed
• 0x0E player digging - digging/left clicking blocks, drop item out of inventory, shoot arrow, finish eating
• 0x0F player block placement - placement/right clicking blocks, update item state (use bucket, start eating, start to shoot arrow)
• 0x10 held item change - change what quickbar slot you have selected
• 0x11 use bed - sent by the server when a player gets into bed
• 0x12 animation - C->S: left clicking on entities. S->C: damage animation, leave bed, eat food, crouch, uncrouch
• 0x13 entity action - sent by client when it starts/stops crouching or sprinting. also sent to leave a bed
• 0x27 attach entity - sent by server when the player gets in a minecraft, for example
• 0x29 entity effect - potion effects - see here for possibilities
• 0x2A remove entity effect
• 0x2B set experience
• 0x82 update sign - sent when the "done" button is pressed. also sent S->C to give sign contents.

Entity Spawning

• 0x14 spawn named entity - spawns players
• 0x15 spawn dropped item
• 0x16 collect item
• 0x17 spawn object/vehicle - see here for a list of objects/vehicles
• 0x18 spawn mob - see here for a list of mobs
• 0x19 spawn painting
• 0x1A spawn experience orb

Entity Movement

• 0x1C entity velocity
• 0x1E entity
• 0x1F entity relative move
• 0x20 entity look
• 0x21 entity look and relative move
• 0x22 entity teleport
• 0x23 entity head look

Entity Misc

• 0x05 entity equipment - sends armour and held item
• 0x1D destroy entity
• 0x26 entity status - hurt, dead, wolf things, sheep eating grass, eating finished
• 0x28 entity metadata - see entities

Map

• 0x33 chunk data
• 0x34 multi block change
• 0x35 block change
• 0x36 block action - pistons, chest animations, note blocks
• 0x37 block break animation
• 0x38 map chunk bulk
• 0x84 update tile entity - mob spawner mob model

Environment

• 0x04 time update
• 0x06 spawn position
• 0x3C explosion
• 0x3D sound or particle effect
• 0x3E named sound effect
• 0x46 change game state - invalid bed, rain started/stopped, game mode changed, enter credits
• 0x47 global entity - lightning strike

Inventory

See the article on inventory for more details

• 0x64 open window
• 0x65 close window
• 0x66 click window
• 0x67 set slot
• 0x68 set window items
• 0x69 update window property
• 0x6A confirm transaction
• 0x6B creative inventory action
• 0x6C enchant item

Client Integration

• 0xC8 increment statistic
• 0xC9 player list item - used to display players in the tab menu
• 0xCA player abilities - can fly, flying, flying speed, walking speed, god mode, creative inventory
• 0xCB tab complete
• 0xCC client settings - locale, view distance, chat enabled, chat colour enabled, client-side difficulty, "show capes" setting
• 0xCD client statuses - whether or not the player should log in dead.

Misc

• 0x00 keep-alive - sent by the server every minute, must be echoed back
• 0x03 chat message - chat can be coloured and styled.
• 0xFA plugin message - used by minecraft for book editing/signing, texture pack and villager trading
• 0xFE server list ping - used in the multiplayer menu to motd, version, and player counts. See Server List Ping for more details.
• 0xFF kick/disconnect - sent by the server to kick a client, sent by a client when exiting