Pre-release protocol

From wiki.vg
Revision as of 11:19, 12 October 2013 by Thinkofdeath (talk | contribs) (→‎Maps)
Jump to navigation Jump to search

This page documents the changes from the last stable Minecraft release (currently 1.6.2, protocol 74) to the current pre-release. Note that this page contains bleeding-edge information that may not be completely or correctly documented. He who wishes to commandeer the merging of this into Protocol when an update is made must be sure to respect any changes that may have occured to the respective packets there.

Contents

Protocol History

13w36a

  • Added sound category byte to 0x3E
  • Changed 0xC8 to a string:int map

13w37b

1.6.3

  • Terrain fixes to help moving to 1.7, no packet changes from 1.6.2

1.6.4

13w38a/b/c

13w39a/b

  • UUIDs added to spawn named entity
  • Game state 'gamemode' byte -> float

13w41a

  • Large protocol rework

13w41b

  • Removed Player (Clientbound), Player Position (Clientbound), Player Look (Clientbound)
  • Removed Player Position and Look (Clientbound)'s 'Stance'
  • Removed Join Game's 'N/A' and 'Level Type'
  • Changed Join Game's 'Gamemode' 'Difficulty' 'Max Players' types to Unsigned Byte
  • Changed Handshake's 'Server Port' type to Unsigned Short
  • Removed Respawn's 'World Height' 'Level Type'
  • Changed Respawn's 'Difficulty' and 'Gamemode' types to Unsigned Byte
  • Changed Held Item Change's 'Slot' type to Byte
  • Removed Use Bed's 'unknown byte'
  • Changed Animation's 'Animation' type to Unsigned Byte
  • Changed Spawn Player's 'Entity ID' type to VarInt
  • Changed Spawn Object's 'Entity ID' type to VarInt
  • Changed Spawn Mob's 'Entity ID' type to VarInt
  • Changed Spawn Painting's 'Entity ID' type to VarInt
  • Changed Spawn Experience Orb's 'Entity ID' type to VarInt
  • Changed Multi Block Change's 'Chunk X' and 'Chunk Z' types to VarInt
  • Changed Block Change's 'Block Type' type to VarInt
  • Changed Block Action's 'Block Type' type to VarInt
  • Changed Block Break Animation's 'Entity ID' type to VarInt
  • Changed Explosion's 'X' 'Y' and 'Z' types to Float
  • Changed Change Game State's 'Reason' type to Unsigned Byte
  • Changed Spawn Global Entity's 'Entity ID' type to VarInt
  • Changed Close Window's 'Window ID' type to Unsigned Byte
  • Changed Set Slot's 'Window ID' type to Unsigned Byte
  • Changed Window Items's 'Window ID' type to Unsigned Byte
  • Changed Window Property's 'Window ID' type to Unsigned Byte
  • Changed Comfirm Transaction's 'Window ID' type to Unsigned Byte
  • Changed Maps' 'Item Damage' type to VarInt
  • Removed Maps' 'Item Type'

Protocol Version

13w41a/b - 0

13w39a/b - 80

13w38a/b/c - 79

1.6.4 - 78

1.6.3 - 77

13w37b - 76

13w36a - 75

Packet format

Field Name Field Type Notes
Length VarInt
Type VarInt
Data

Data Types

VarInt - Protocol Buffer 32-bit Varint

String - UTF-8 String prefixed with a VarInt

Handshaking

Serverbound

Handshake

This causes the server to switch into the target state.

Packet ID Field Name Field Type Notes
0x00 Protocol Version VarInt
Server Address (hostname or IP) String localhost
Server Port Unsigned Short 25565
Current state VarInt 1 for status, 2 for login

Play

Clientbound

Keep Alive

Packet ID Field Name Field Type Notes
0x00 Keep Alive ID Int


Join Game

Packet ID Field Name Field Type Notes
0x01 Entity ID Int The player's Entity ID
Gamemode Unsigned Byte 0: survival, 1: creative, 2: adventure. Bit 3 (0x8) is the hardcore flag
Dimension Byte -1: nether, 0: overworld, 1: end
Difficulty Unsigned Byte 0 thru 3 for Peaceful, Easy, Normal, Hard
Max Players Unsigned Byte Used by the client to draw the player list

Chat Message

Packet ID Field Name Field Type Notes
0x02 JSON Data String https://gist.github.com/thinkofdeath/e882ce057ed83bac0a1c

Time Update

Packet ID Field Name Field Type Notes
0x03 Age of the world Long In ticks; not changed by server commands
Time of day Long The world (or region) time, in ticks. If negative the sun will stop moving at the Math.abs of the time

Entity Equipment

Packet ID Field Name Field Type Notes
0x04 EntityID Int Entity's ID
Slot Short Equipment slot: 0=held, 1-4=armor slot (1 - boots, 2 - leggings, 3 - chestplate, 4 - helmet)
Item Slot Item in slot format

Spawn Position

Packet ID Field Name Field Type Notes
0x05 X Int Spawn X in block coordinates
Y Int Spawn Y in block coordinates
Z Int in block coordinates

Update Health

Packet ID Field Name Field Type Notes
0x06 Health Float 0 or less = dead, 20 = full HP
Food Short 0 - 20
Food Saturation Float Seems to vary from 0.0 to 5.0 in integer increments

Respawn

Packet ID Field Name Field Type Notes
0x07 Dimension Int -1: The Nether, 0: The Overworld, 1: The End
Difficulty Unsigned Byte 0 thru 3 for Peaceful, Easy, Normal, Hard.
Gamemode Unsigned Byte 0: survival, 1: creative, 2: adventure. The hardcore flag is not included

Player Position And Look

Packet ID Field Name Field Type Notes
0x08 X Double Absolute position
Y Double Absolute position
Z Double Absolute position
Yaw Float Absolute rotation on the X Axis, in degrees
Pitch Float Absolute rotation on the Y Axis, in degrees
On Ground Bool True if the client is on the ground, False otherwise

Held Item Change

Packet ID Field Name Field Type Notes
0x09 Slot Byte The slot which the player has selected (0-8)

Use Bed

Packet ID Field Name Field Type Notes
0x0A Entity ID Int Player ID
X Int Bed headboard X as block coordinate
Y Unsigned Byte Bed headboard Y as block coordinate
Z Int Bed headboard Z as block coordinate

Animation

Packet ID Field Name Field Type Notes
0x0B Entity ID Int Player ID
Animation Unsigned Byte Animation ID

Animation can be one of the following values:

ID Animation
0 No animation
1 Swing arm
2 Damage animation
3 Leave bed
5 Eat food
6 Critical effect
7 Magic critical effect
102 (unknown)
104 Crouch
105 Uncrouch

Spawn Player

Packet ID Field Name Field Type Notes
0x0C Entity ID VarInt Player's Entity ID
Player UUID String Player's UUID
Player Name String Player's Name
X Int Player X as a Fixed-Point number
Y Int Player X as a Fixed-Point number
Z Int Player X as a Fixed-Point number
Yaw Byte Player rotation as a packed byte
Pitch Byte Player rotation as a packet byte
Current Item Short The item the player is currently holding. Note that this should be 0 for "no item", unlike -1 used in other packets. A negative value crashes clients.
Metadata Metadata The client will crash if no metadata is sent

Collect Item

Packet ID Field Name Field Type Notes
0x0D Collected Entity ID Int
Collector Entity ID Int

Spawn Object

Packet ID Field Name Field Type Notes
0x0E Entity ID VarInt Entity ID of the object
Type Byte The of object (See Objects
X Int X position as a Fixed-Point number
Y Int Y position as a Fixed-Point number
Z Int Z position as a Fixed-Point number
Pitch Byte The pitch in steps of 2p/256
Yaw Byte The yaw in steps of 2p/256
Data Object Data

Spawn Mob

Packet ID Field Name Field Type Notes
0x0F Entity ID VarInt Entity's ID
Type Unsigned Byte The type of mob. See Mobs
X Int X position as a Fixed-Point number
Y Int Y position as a Fixed-Point number
Z Int Z position as a Fixed-Point number
Pitch Byte The pitch in steps of 2p/256
Head Pitch Byte The pitch in steps of 2p/256
Yaw Byte The yaw in steps of 2p/256
Velocity X Short
Velocity Y Short
Velocity Z Short
Metadata Metadata

Spawn Painting

Packet ID Field Name Field Type Notes
0x10 Entity ID VarInt Entity's ID
Title String Name of the painting. Max length 13
X Int Center X coordinate
Y Int Center Y coordinate
Z Int Center Z coordinate
Direction Int Direction the painting faces (0 -z, 1 -x, 2 +z, 3 +x)

Spawn Experience Orb

Packet ID Field Name Field Type Notes
0x11 Entity ID VarInt Entity's ID
X Int X position as a Fixed-Point number
Y Int Y position as a Fixed-Point number
Z Int Z position as a Fixed-Point number
Count Short The amount of experience this orb will reward once collected

Entity Velocity

Packet ID Field Name Field Type Notes
0x12 Entity ID Int Entity's ID
Velocity X Short Velocity on the X axis
Velocity Y Short Velocity on the Y axis
Velocity Z Short Velocity on the Z axis

Destroy Entities

Packet ID Field Name Field Type Notes
0x13 Count Byte Length of following array
Entity IDs Array of Int The list of entities of destroy

Entity

Packet ID Field Name Field Type Notes
0x14 Entity ID Int Entity's ID

Entity Relative Move

Packet ID Field Name Field Type Notes
0x15 Entity ID Int Entity's ID
DX Byte Change in X position as a Fixed-Point number
DY Byte Change in Y position as a Fixed-Point number
DZ Byte Change in Z position as a Fixed-Point number

Entity Look

Packet ID Field Name Field Type Notes
0x16 Entity ID Int Entity's ID
Yaw Byte The X Axis rotation as a fraction of 360
Pitch Byte The Y Axis rotation as a fraction of 360

Entity Look and Relative Move

Packet ID Field Name Field Type Notes
0x17 Entity ID Int Entity's ID
DX Byte Change in X position as a Fixed-Point number
DY Byte Change in Y position as a Fixed-Point number
DZ Byte Change in Z position as a Fixed-Point number
Yaw Byte The X Axis rotation as a fraction of 360
Pitch Byte The Y Axis rotation as a fraction of 360

Entity Teleport

Packet ID Field Name Field Type Notes
0x18 Entity ID Int Entity's ID
X Int X position as a Fixed-Point number
Y Int Y position as a Fixed-Point number
Z Int Z position as a Fixed-Point number
Yaw Byte The X Axis rotation as a fraction of 360
Pitch Byte The Y Axis rotation as a fraction of 360

Entity Head Look

Packet ID Field Name Field Type Notes
0x19 Entity ID Int Entity's ID
Head Yaw Byte Head yaw in steps of 2p/256

Entity Status

Packet ID Field Name Field Type Notes
0x1A Entity ID Int Entity's ID
Entity Status Byte See below
Entity Status Meaning
2 Entity hurt
3 Entity dead
6 Wolf taming
7 Wolf tamed
8 Wolf shaking water off itself
9 (of self) Eating accepted by server
10 Sheep eating grass
11 Iron Golem handing over a rose
12 Spawn "heart" particles near a villager
13 Spawn particles indicating that a villager is angry and seeking revenge
14 Spawn happy particles near a villager
15 Spawn a "magic" particle near the Witch
16 Zombie converting into a villager by shaking violently (unused in recent update)
17 A firework exploding

Attach Entity

Packet ID Field Name Field Type Notes
0x1B Entity ID Int Entity's ID
Vehicle ID Int Vechicle's Entity ID
Leash Bool If true leashes the entity to the vehicle

Entity Metadata

Packet ID Field Name Field Type Notes
0x1C Entity ID Int Entity's ID
Metadata Metadata

Entity Effect

Packet ID Field Name Field Type Notes
0x1D Entity ID Int Entity's ID
Effect ID Byte See [[1]]
Amplifier Byte
Duration Short

Remove Entity Effect

Packet ID Field Name Field Type Notes
0x1E Entity ID Int Entity's ID
Effect ID Byte

Set Experience

Packet ID Field Name Field Type Notes
0x1F Experience bar Float Between 0 and 1
Level Short
Total Experience Short

Entity Properties

Packet ID Field Name Field Type Notes
0x20 Entity ID Entity's ID
Count Int Length of following array
Properties Array of Property Data

Property Data structure:

Field Name Field Type Notes
Key String
Value Double
List Length Short Number of list elements that follow.
Modifiers Array of Modifier Data http://www.minecraftwiki.net/wiki/Attribute#Modifiers

Known key values:

Key Default Min Max Label
generic.maxHealth 20.0 0.0 Double.MaxValue Max Health
generic.followRange 32.0 0.0 2048.0 Follow Range
generic.knockbackResistance 0.0 0.0 1.0 Knockback Resistance
generic.movementSpeed 0.699999988079071 0.0 Double.MaxValue Movement Speed
generic.attackDamage 2.0 0.0 Double.MaxValue
horse.jumpStrength 0.7 0.0 2.0 Jump Strength
zombie.spawnReinforcements 0.0 0.0 1.0 Spawn Reinforcements Chance

Modifier Data structure:

Field Name Field Type Notes
UUID 128-bit integer
Amount Double
Operation Byte

Chunk Data

Packet ID Field Name Field Type Notes
0x21 Chunk X Int Chunk X coordinate
Chunk Z Int Chunk Z coordinate
Ground-Up continuous Boolean This is True if the packet represents all sections in this vertical column, where the primary bit map specifies exactly which sections are included, and which are air
Primary bit map Unsigned Short Bitmask with 1 for every 16x16x16 section which data follows in the compressed data.
Add bit map Unsigned Short Same as above, but this is used exclusively for the 'add' portion of the payload
Compressed size Int Size of compressed chunk data
Compressed data Byte array The chunk data is compressed using Zlib Deflate

Multi Block Change

Packet ID Field Name Field Type Notes
0x22 Chunk X VarInt Chunk X coordinate
Chunk Z VarInt Chunk Z Coordinate
Record count Short The number of blocks affected
Data size Int The total size of the data, in bytes. Should always be 4*record count
Records Array of Records

Record

Bit mask Width Meaning
00 00 00 0F 4 bits Block metadata
00 00 FF F0 12 bits Block ID
00 FF 00 00 8 bits Y co-ordinate
0F 00 00 00 4 bits Z co-ordinate, relative to chunk
F0 00 00 00 4 bits X co-ordinate, relative to chunk

Block Change

Packet ID Field Name Field Type Notes
0x23 X Int Block X Coordinate
Y Unsigned Byte Block Y Coordinate
Z Int Block Z Coordinate
Block Type VarInt The new block type for the block
Block Data Unsigned Byte The new data for the block

Block Action

Packet ID Field Name Field Type Notes
0x24 X Int Block X Coordinate
Y Short Block Y Coordinate
Z Int Block Z Coordinate
Byte 1 Unsigned Byte Varies depending on block - see Block_Actions
Byte 2 Unsigned Byte Varies depending on block - see Block_Actions
Block Type VarInt The block type for the block

Block Break Animation

Packet ID Field Name Field Type Notes
0x25 Entity ID VarInt Entity's ID
X Int Block Position
Y Int
Z Int
Destroy Stage Byte 0 - 9

Map Chunk Bulk

Packet ID Field Name Field Type Notes
0x26 Chunk column count Short The number of chunk in this packet
Data length Int The size of the data field
Sky light sent Bool Whether or not the chunk data contains a light nibble array. This is true in the main world, false in the end + nether
Data Byte Array Compressed chunk data
Meta information Meta See below

Meta

Field Name Field Type Notes
Chunk X Int The X Coordinate of the chunk
Chunk Z Int The Z Coordinate of the chunk
Primary bitmap Unsigned Short A bitmap which specifies which sections are not empty in this chunk
Add bitmap Unsigned Short A bitmap which specifies which sections need add information because of very high block ids. not yet used

Explosion

Packet ID Field Name Field Type Notes
0x27 X Float
Y Float
Z Float
Radius Float Currently unused in the client
Record count Int This is the count, not the size. The size is 3 times this value.
Records (Byte, Byte, Byte) × count Each record is 3 signed bytes long, each bytes are the XYZ (respectively) offsets of affected blocks.
Player Motion X Float X velocity of the player being pushed by the explosion
Player Motion Y Float Y velocity of the player being pushed by the explosion
Player Motion Z Float Z velocity of the player being pushed by the explosion

Effect

Packet ID Field Name Field Type Notes
0x28 Effect ID Int The ID of the effect, see below.
X Int The X location of the effect multiplied by 8
Y Byte The Y location of the effect multiplied by 8
Z Int The Z location of the effect multiplied by 8
Data Int Extra data for certain effects, see below.
Disable relative volume Bool See above

Sound:

  • 1000: random.click
  • 1001: random.click
  • 1002: random.bow
  • 1003: random.door_open or random.door_close (50/50 chance)
  • 1004: random.fizz
  • 1005: Play a music disc. Data: Record ID
  • (1006 not assigned)
  • 1007: mob.ghast.charge
  • 1008: mob.ghast.fireball
  • 1009: mob.ghast.fireball, but with a lower volume.
  • 1010: mob.zombie.wood
  • 1011: mob.zombie.metal
  • 1012: mob.zombie.woodbreak
  • 1013: mob.wither.spawn
  • 1014: mob.wither.shoot
  • 1015: mob.bat.takeoff
  • 1016: mob.zombie.infect
  • 1017: mob.zombie.unfect
  • 1018: mob.enderdragon.end
  • 1020: random.anvil_break
  • 1021: random.anvil_use
  • 1022: random.anvil_land

Particle:

  • 2000: Spawns 10 smoke particles, e.g. from a fire. Data: direction, see below
  • 2001: Block break. Data: Block ID
  • 2002: Splash potion. Particle effect + glass break sound. Data: Potion ID
  • 2003: Eye of ender entity break animation - particles and sound
  • 2004: Mob spawn particle effect: smoke + flames
  • 2005: Spawn "happy villager" effect (hearts).

Smoke directions:

ID Direction
0 South - East
1 South
2 South - West
3 East
4 (Up or middle ?)
5 West
6 North - East
7 North
8 North - West

Sound Effect

Packet ID Field Name Field Type Notes
0x29 Sound name String
Effect position X Int Effect X multiplied by 8
Effect position Y Int Effect Y multiplied by 8
Effect position Z Int Effect Z multiplied by 8
Volume Float 1 is 100%, can be more
Pitch Unsigned Byte 63 is 100%, can be more
Sound Category Unsigned Byte Possible values:

MASTER: 0

MUSIC: 1

RECORDS: 2

WEATHER: 3

BLOCKS: 4

MOBS: 5

ANIMALS: 6

PLAYERS: 7

Particle

Packet ID Field Name Field Type Notes
0x2A Particle name String The name of the particle to create. A list can be found here
X Float X position of the particle
Y Float Y position of the particle
Z Float Z position of the particle
Offset X Float This is added to the X position after being multiplied by random.nextGaussian()
Offset Y Float This is added to the Y position after being multiplied by random.nextGaussian()
Offset Z Float This is added to the Z position after being multiplied by random.nextGaussian()
Particle speed Float The speed of each particle
Number of particles Int The number of particles to create

Change Game State

Packet ID Field Name Field Type Notes
0x2B Reason Unsigned Byte
Value Float Depends on reason

Reason codes

Code Effect Notes
0 Invalid Bed "tile.bed.notValid"
1 Begin raining
2 End raining
3 Change game mode "gameMode.changed" 0 - Survival, 1 - Creative, 2 - Adventure
4 Enter credits
5 Demo messages 0 - Show welcome to demo screen, 101 - Tell movement controls, 102 - Tell jump control, 103 - Tell inventory control
Bow hit sound
7 Fade value The current darkness value. 1 = Dark, 0 = Bright, Setting the value higher causes the game to change color and freeze
8 Fade time Time in ticks for the sky to fade

Spawn Global Entity

Packet ID Field Name Field Type Notes
0x2C Entity ID VarInt The entity ID of the thunderbolt
Type Byte The global entity type, currently always 1 for thunderbolt.
X Int Thunderbolt X a fixed-point number
Y Int Thunderbolt Y a fixed-point number
Z Int Thunderbolt Z a fixed-point number

Open Window

Packet ID Field Name Field Type Notes
0x2D Window id Unsigned Byte A unique id number for the window to be displayed. Notchian server implementation is a counter, starting at 1.
Inventory Type Unsigned Byte The window type to use for display. Check below
Window title String The title of the window.
Number of Slots Unsigned Byte Number of slots in the window (excluding the number of slots in the player inventory).
Use provided window title Bool If false, the client will look up a string like "window.minecart". If true, the client uses what the server provides.
Entity ID Int EntityHorse's entityId. Only sent when window type is equal to 11 (AnimalChest).

See inventory windows for further information.

Close Window

Packet ID Field Name Field Type Notes
0x2E Window ID Unsigned Byte This is the id of the window that was closed. 0 for inventory.

Set Slot

Packet ID Field Name Field Type Notes
0x2F Window ID Unsigned Byte The window which is being updated. 0 for player inventory. Note that all known window types include the player inventory. This packet will only be sent for the currently opened window while the player is performing actions, even if it affects the player inventory. After the window is closed, a number of these packets are sent to update the player's inventory window (0).
Slot Short The slot that should be updated
Slot data Slot

Window Items

Packet ID Field Name Field Type Notes
0x30 Window ID Unsigned Byte The id of window which items are being sent for. 0 for player inventory.
Count Short The number of slots (see below)
Slot data Array of Slots

See inventory windows for further information about how slots are indexed.

Window Property

Packet ID Field Name Field Type Notes
0x31 Window ID Unsigned Byte The id of the window.
Property Short Which property should be updated.
Value Short The new value for the property.

Furnace

Properties:

  • 0: Progress arrow
  • 1: Fire icon (fuel)

Values:

  • 0-200 for progress arrow
  • 0-200 for fuel indicator

Ranges are presumably in in-game ticks

Enchantment Table

Properties: 0, 1 or 2 depending on the "enchantment slot" being given.

Values: The enchantment's level.

Confirm Transaction

Packet ID Field Name Field Type Notes
0x32 Window ID Unsigned Byte The id of the window that the action occurred in.
Action number Short Every action that is to be accepted has a unique number. This field corresponds to that number.
Accepted Bool Whether the action was accepted.

Update Sign

Packet ID Field Name Field Type Notes
0x33 X Int Block X Coordinate
Y Short Block Y Coordinate
Z Int Block Z Coordinate
Line 1 String First line of text in the sign
Line 2 String Second line of text in the sign
Line 3 String Third line of text in the sign
Line 4 String Fourth line of text in the sign

Maps

Packet ID Field Name Field Type Notes
0x34 Item Damage VarInt The damage value of the map being modified
Length Short Length of following byte array
Data Byte Array Array data

If the first byte of the array is 0, the next two bytes are X start and Y start and the rest of the bytes are the colors in that column.

If the first byte of the array is 1, the rest of the bytes are in groups of three: (data, x, y). The lower half of the data is the type (always 0 under vanilla) and the upper half is the direction.

If the first byte of the array is 2, the second byte is the map scale.

Update Block Entity

Packet ID Field Name Field Type Notes
0x35 X Int
Y Short
Z Int
Action Byte The type of update to perform
Data length Short Varies
NBT Data Byte Array Present if data length > 0. Compressed with gzip. Varies

Actions

  • 1: Set mob displayed inside a mob spawner. Custom 1 contains the mob type

Block Editor Open

Packet ID Field Name Field Type Notes
0x36 Tile Entity Id Byte Always seems to be 0 (TileEntitySign)
X Int X in block coordinates
Y Int Y in block coordinates
Z Int Z in block coordinates

Statistics

Packet ID Field Name Field Type Notes
0x37 Count Int Number of entrys
Entry Statistic's name String
Amount Int The amount to increase by

Player List Item

Packet ID Field Name Field Type Notes
0x38 Player name String Supports chat colouring, limited to 16 characters.
Online byte 1 for true, 0 for false. The client will remove the user from the list if false.
Ping Short Ping, presumably in ms.

Player Abilities

Packet ID Field Name Field Type Notes
0x39 Flags Byte
Flying speed Float previous integer value divided by 250
Walking speed Float previous integer value divided by 250

Tab-Complete

Packet ID Field Name Field Type Notes
0x3A Text String

Scoreboard Objective

Packet ID Field Name Field Type Notes
0x3B Objective name String An unique name for the objective
Objective value String The text to be displayed for the score.
Create/Remove Byte 0 to create the scoreboard. 1 to remove the scoreboard. 2 to update the display text.

Update Score

Packet ID Field Name Field Type Notes
0x3C Item Name String An unique name to be displayed in the list.
Update/Remove Byte 0 to create/update an item. 1 to remove an item.
Score Name String The unique name for the scoreboard to be updated. Only sent when Update/Remove does not equal 1.
Value Int The score to be displayed next to the entry. Only sent when Update/Remove does not equal 1.

Display Scoreboard

Packet ID Field Name Field Type Notes
0x3D Position Byte The position of the scoreboard. 0 = list, 1 = sidebar, 2 = belowName.
Score Name String The unique name for the scoreboard to be displayed.

Teams

Packet ID Field Name Field Type Notes
0x3E Team Name String A unique name for the team. (Shared with scoreboard).
Mode Byte If 0 then the team is created.

If 1 then the team is removed.

If 2 the team team information is updated.

If 3 then new players are added to the team.

If 4 then players are removed from the team.

Team Display Name String Only if Mode = 0 or 2.
Team Prefix String Only if Mode = 0 or 2. Displayed before the players' name that are part of this team.
Team Suffix String Only if Mode = 0 or 2. Displayed after the players' name that are part of this team.
Friendly fire Byte Only if Mode = 0 or 2; 0 for off, 1 for on, 3 for seeing friendly invisibles
Player count Short Only if Mode = 0 or 3 or 4. Number of players in the array
Players Array of strings Only if Mode = 0 or 3 or 4. Players to be added/remove from the team.

Plugin Message

Packet ID Field Name Field Type Notes
0x3F Channel String Name of the "channel" used to send the data.
Length Short Length of the following byte array
Data Byte Array Any data.

More documentation on this: http://dinnerbone.com/blog/2012/01/13/minecraft-plugin-channels-messaging/

Disconnect

Packet ID Field Name Field Type Notes
0x40 Reason String Displayed to the client when the connection terminates

Serverbound

Keep Alive

Packet ID Field Name Field Type Notes
0x00 Keep Alive ID Int

Chat Message

Packet ID Field Name Field Type Notes
0x01 JSON Data String https://gist.github.com/thinkofdeath/e882ce057ed83bac0a1c

?

Packet ID Field Name Field Type Notes
0x02 Int
Byte

Player

Packet ID Field Name Field Type Notes
0x03 On Ground True if the client is on the ground, False otherwise

Player Position

Packet ID Field Name Field Type Notes
0x04 X Double Absolute position
Y Double Absolute position
Stance Double Used to modify the players bounding box when going up stairs, crouching, etc…
Z Double Absolute position
On Ground Bool True if the client is on the ground, False otherwise

Player Look

Packet ID Field Name Field Type Notes
0x05 Yaw Float Absolute rotation on the X Axis, in degrees
Pitch Float Absolute rotation on the Y Axis, in degrees
On Ground Bool True if the client is on the ground, False otherwise

Player Position And Look

Packet ID Field Name Field Type Notes
0x06 X Double Absolute position
Y Double Absolute position
Stance Double Used to modify the players bounding box when going up stairs, crouching, etc…
Z Double Absolute position
Yaw Float Absolute rotation on the X Axis, in degrees
Pitch Float Absolute rotation on the Y Axis, in degrees
On Ground Bool True if the client is on the ground, False otherwise

Player Digging

Packet ID Field Name Field Type Notes
0x07 Status Byte The action the player is taking against the block (see below)
X Int Block position
Y Byte Block position
Z Int Block position
Face Byte The face being hit (see below)

Status can (currently) be one of six values:

Meaning Value
Started digging 0
Cancelled digging 1
Finished digging 2
Drop item stack 3
Drop item 4
Shoot arrow / finish eating 5

Notchian clients send a 0 (started digging) when they start digging and a 2 (finished digging) once they think they are finished. If digging is aborted, the client simply send a 1 (Cancel digging).

Status code 4 (drop item) is a special case. In-game, when you use the Drop Item command (keypress 'q'), a dig packet with a status of 4, and all other values set to 0, is sent from client to server. Status code 3 is similar, but drops the entire stack.

Status code 5 (shoot arrow / finish eating) is also a special case. The x, y and z fields are all set to 0 like above, with the exception of the face field, which is set to 255.

The face can be one of six values, representing the face being hit:

Value 0 1 2 3 4 5
Offset -Y +Y -Z +Z -X +X

In 1.7.3, when a player opens a door with left click the server receives Packet 0xE+start digging and opens the door.

Player Block Placement

Packet ID Field Name Field Type Notes
0x08 X Int Block position
Y Unsigned Byte Block position
Z Int Block position
Direction Byte The offset to use for block/item placement (see below)
Held item Slot
Cursor position X Byte The position of the crosshair on the block
Cursor position Y Byte
Cursor position Z Byte

In normal operation (ie placing a block), this packet is sent once, with the values set normally.

This packet has a special case where X, Y, Z, and Direction are all -1. (Note that Y is unsigned so set to 255.) This special packet indicates that the currently held item for the player should have its state updated such as eating food, shooting bows, using buckets, etc.

In a Notchian Beta client, the block or item ID corresponds to whatever the client is currently holding, and the client sends one of these packets any time a right-click is issued on a surface, so no assumptions can be made about the safety of the ID. However, with the implementation of server-side inventory, a Notchian server seems to ignore the item ID, instead operating on server-side inventory information and holding selection. The client has been observed (1.2.5 and 1.3.2) to send both real item IDs and -1 in a single session.

Special note on using buckets: When using buckets, the Notchian client might send two packets: first a normal and then a special case. The first normal packet is sent when you're looking at a block (e.g. the water you want to scoop up). This normal packet does not appear to do anything with a Notchian server. The second, special case packet appears to perform the action - based on current position/orientation and with a distance check - it appears that buckets can only be used within a radius of 6 units.

Held Item Change

Packet ID Field Name Field Type Notes
0x09 Slot Short The slot which the player has selected (0-8)

Animation

Packet ID Field Name Field Type Notes
0x0A Entity ID Int Player ID
Animation Byte Animation ID


Animation can be one of the following values:

ID Animation
0 No animation
1 Swing arm
2 Damage animation
3 Leave bed
5 Eat food
6 Critical effect
7 Magic critical effect
102 (unknown)
104 Crouch
105 Uncrouch

Entity Action

Packet ID Field Name Field Type Notes
0x0B Entity ID Int Player ID
Action ID Byte The ID of the action, see below.
Jump Boost Int Horse jump boost. Ranged from 0 -> 100.

Action ID can be one of the following values:

ID Action
1 Crouch
2 Uncrouch
3 Leave bed
4 Start sprinting
5 Stop sprinting

Steer Vehicle

Packet ID Field Name Field Type Notes
0x0C Sideways Float Positive to the left of the player
Forward Float Positive forward
Jump Bool
Unmount Bool True when leaving the vehicle

Close Window

Packet ID Field Name Field Type Notes
0x0D Window id byte This is the id of the window that was closed. 0 for inventory.


Click Window

Packet ID Field Name Field Type Notes
0x0E Window ID Byte The id of the window which was clicked. 0 for player inventory.
Slot Short The clicked slot. See below.
Button Byte The button used in the click. See below.
Action number Short A unique number for the action, used for transaction handling (See the Transaction packet).
Mode Byte Inventory operation mode. See below.
Clicked item Slot

See inventory windows for further information about how slots are indexed.

When right-clicking on a stack of items, half the stack will be picked up and half left in the slot. If the stack is an odd number, the half left in the slot will be smaller of the amounts.

The Action number is actually a counter, starting at 1. This number is used by the server as a transaction ID to send back a Transaction packet.

The distinct type of click performed by the client is determined by the combination of the "Mode" and "Button" fields.

Mode Button Slot Trigger
0 0 Normal Left mouse click
1 Normal Right mouse click
1 0 Normal Shift + left mouse click
1 Normal Shift + right mouse click (Identical behavior)
2 0 Normal Number key 1
1 Normal Number key 2
2 Normal Number key 3
... ... ...
8 Normal Number key 9
3 2 Normal Middle click
4 0 Normal Drop key (Q)
1 Normal Ctrl + Drop key (Ctrl-Q)
0 -999 Left click outside inventory holding nothing (No-op)
1 -999 Right click outside inventory holding nothing (No-op)
5 0 -999 Starting left mouse drag (Or middle mouse)
4 -999 Starting right mouse drag
1 Normal Add slot for left-mouse drag
5 Normal Add slot for right-mouse drag
2 -999 Ending left mouse drag
6 -999 Ending right mouse drag
6 0 Normal Double click

Starting from version 1.5, "painting mode" is available for use in inventory windows. It is done by picking up stack of something (more than 1 items), then holding mouse button (left, right or middle) and dragging holded stack over empty (or same type in case of right button ) slots. In that case client sends the following to server after mouse button release (omitting first pickup packet which is sent as usual):

  1. packet with mode 5, slot -999 , button (0 for left | 4 for right);
  2. packet for every slot painted on, mode is still 5, button (1 | 5);
  3. packet with mode 5, slot -999, button (2 | 6);

If any of the painting packets other than the "progress" ones are sent out of order (for example, a start, some slots, then another start; or a left-click in the middle) the painting status will be reset.

Confirm Transaction

Packet ID Field Name Field Type Notes
0x0F Window ID Byte The id of the window that the action occurred in.
Action number Short Every action that is to be accepted has a unique number. This field corresponds to that number.
Accepted Bool Whether the action was accepted.

Creative Inventory Action

Packet ID Field Name Field Type Notes
0x10 Slot Short Inventory slot
Clicked item Slot

Enchant Item

Packet ID Field Name Field Type Notes
0x11 Window ID Byte The ID sent by Open Window
Enchantment Byte The position of the enchantment on the enchantment table window, starting with 0 as the topmost one.

Update Sign

Packet ID Field Name Field Type Notes
0x12 X Int Block X Coordinate
Y Short Block Y Coordinate
Z Int Block Z Coordinate
Line 1 String First line of text in the sign
Line 2 String Second line of text in the sign
Line 3 String Third line of text in the sign
Line 4 String Fourth line of text in the sign

Player Abilities

Packet ID Field Name Field Type Notes
0x13 Flags Byte
Flying speed Float previous integer value divided by 250
Walking speed Float previous integer value divided by 250

Tab-Complete

Packet ID Field Name Field Type Notes
0x14 Text String


Client Settings

Packet ID Field Name Field Type Notes
0x15 Locale String en_GB
View distance Byte 0-3 for 'far', 'normal', 'short', 'tiny'.
Chat flags Byte Chat settings. See notes below.
??? Bool ???
Difficulty Byte Client-side difficulty from options.txt
Show Cape Bool Client-side "show cape" option

Chat flags has several values packed into one byte.

Chat Enabled: Bits 0-1. 00: Enabled. 01: Commands only. 10: Hidden.

Colors Enabled: Bit 3. 0: Disabled. 1: Enabled.

Client Status

Packet ID Field Name Field Type Notes
0x16 Action ID Byte See below

Action ID values:

Action ID Name
1 Perform respawn
2 Request stats
3 Open inventory achievement

Plugin Message

Packet ID Field Name Field Type Notes
0x17 Channel String Name of the "channel" used to send the data.
Length Short Length of the following byte array
Data Byte Array Any data.

More documentation on this: http://dinnerbone.com/blog/2012/01/13/minecraft-plugin-channels-messaging/

Status

The status ping works as follows.

   C->S : Handshake State=1
   C->S : Request
   S->C : Response
   C->S : Ping
   S->C : Ping

Clientbound

Response

Packet ID Field Name Field Type Notes
0x00 JSON Response String https://gist.github.com/thinkofdeath/6927216


Ping

Packet ID Field Name Field Type Notes
0x01 Time Long Should be the same as sent by the client

Serverbound

Request

Packet ID Field Name Field Type Notes
0x00


Ping

Packet ID Field Name Field Type Notes
0x01 Time Long

Login

The login process is as follows:

   C->S : Handshake State=2
   C->S : Login Start
   S->C : Encryption Key Request
   C->S : Encryption Key Response
   (Auth & enable encryption)
   S->S : Login Success

Clientbound

Disconnect

Packet ID Field Name Field Type Notes
0x00 JSON Data String

Encryption Response

Packet ID Field Name Field Type Notes
0x01 Server ID String
Length Short length of public key
Byte array public key
Length Short length of verify token
Byte array verify token

Login Success

Packet ID Field Name Field Type Notes
0x02 UUID String Username String

Serverbound

Login Start

Packet ID Field Name Field Type Notes
0x00 Name String unknown

Encryption Request

Packet ID Field Name Field Type Notes
0x01 Length Short length of public key
Byte array public key
Length Short length of verify token
Byte array verify token

Plugin Channels

MC|RPack

Field Name Field Type Example Notes
Resource pack URL UTF8 string http://example.com/pack.zip