Packets
Sending packets
Packet IDs may be found below. The packets listed down below are the only supported packets for now. If you wish more packets to get added, make a suggestion in discord.
Keep Alive (0x00)
The server will frequently send out a keep-alive, each containing a random ID. The client must respond with the same packet.
Parameter
Type
id
integer
Chat Message (0x01)
The default server will check the message to see if it begins with a '/'. If it doesn't, the username of the sender is prepended and sent to all other clients (including the original sender). If it does, the server assumes it to be a command and attempts to process it. A message longer than 100 characters will cause the server to kick the client. This change was initially done by allowing the client to not slice the message up to 119 (the previous limit), without changes to the server. For this reason, the vanilla server kept the code to cut messages at 119, but this isn't a protocol limitation and can be ignored.
Parameter
Type
message
String
Use Entity (0x02)
This packet is sent from the client to the server when the client attacks or right-clicks another entity (a player, minecart, etc).
A Notchian server only accepts this packet if the entity being attacked/used is visible without obstruction and within a 4-unit radius of the player's position.
Parameter
Type
entity
Entity
action
Action
Parameter
Type
entity
Entity
hitVec
Vec3
Action can be one of 3 actions:
Value
ATTACK
INTERACT
INTERACT_AT
Player (0x03)
This packet as well as Player Position (Play, 0x04, serverbound), Player Look (Play, 0x05, serverbound), and Player Position And Look (Play, 0x06, serverbound) are called the “serverbound movement packets”. At least one of them must be sent on each tick to ensure that servers will update things like player health correctly. Vanilla clients will send Player Position once every 20 ticks even for a stationary player, and Player on every other tick.
This packet is used to indicate whether the player is on ground (walking/swimming), or airborne (jumping/falling).
When dropping from sufficient height, fall damage is applied when this state goes from false to true. The amount of damage applied is based on the point where it last changed from true to false. Note that there are several movement related packets containing this state.
Parameter
Type
ground
boolean
Player Position (0x04)
Updates the player's XYZ position on the server.
If the distance between the last known position of the player on the server and the new position set by this packet is greater than 100 units, this will result in the client being kicked for “You moved too quickly :( (Hacking?)”
If the distance is greater than 10 units, the server will log the warning message "<name> moved too quickly!", followed by two coordinate triples (maybe movement delta?), but will not kick the client.
Also if the fixed-point number of X or Z is set greater than 3.2×107 the client will be kicked for “Illegal position”.
Parameters
Type
x
double
y
double
z
double
ground
boolean
Player Look (0x05)
Updates the direction the player is looking in.
Yaw is measured in degrees and does not follow classical trigonometry rules. The unit circle of yaw on the XZ-plane starts at (0, 1) and turns counterclockwise, with 90 at (-1, 0), 180 at (0,-1) and 270 at (1, 0). Additionally, yaw is not clamped to between 0 and 360 degrees; any number is valid, including negative numbers and numbers greater than 360.
Pitch is measured in degrees, where 0 is looking straight ahead, -90 is looking straight up, and 90 is looking straight down.
Parameters
Type
yaw
float
pitch
float
ground
boolean
Player Position and Look (0x06)
A combination of Player Look and Player Position.
Parameters
Type
x
double
y
double
z
double
yaw
float
pitch
float
ground
boolean
Player Digging (0x07)
Sent when the player mines a block. A Notchian server only accepts digging packets with coordinates within a 6-unit radius of the player's position.
Parameters
Type
status
Action
location
BlockPos
face
EnumFacing
Status can (currently) be one of six values:
Meaning
Value
Started Digging
START_DESTROY_BLOCK
Cancelled Digging
ABORT_DESTROY_BLCOK
Finished Digging
STOP_DESTROY_BLOCK
Drop item stack
DROP_ALL_ITEMS
Drop item
DROP_ITEM
Shoot arrow / finish eating
RELEASE_USE_ITEM
Face can be one of six values:
Values
UP
DOWN
NORTH
SOUTH
WEST
EAST
Player Block Placement (0x08)
In normal operation (i.e. placing a block), this packet is sent once, with the values set normally.
This packet has a special case where X, Y, Z, and Face 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, pulling back 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.
Parameters
Type
location
BlockPos
face
int
held_item
ItemStack
facingx
float
facingy
float
facingz
float
Held Item Change (0x09)
Sent when the player changes the slot selection
Parameters
Type
slot
integer
Animation (0x0A)
Sent when the player's arm swings
Entity Action (0x0B)
Sent by the client to indicate that it has performed certain actions: sneaking (crouching), sprinting, exiting a bed, jumping with a horse, and opening a horse's inventory while riding it.
Parameters
Type
entity
Entity
action
Action
The action may be one of 7 values
Meaning
Value
Start sneaking
START_SNEAKING
Stop sneaking
STOP_SNEAKING
Leave bed
STOP_SLEEPING
Start sprinting
START_SPRINTING
Stop sprinting
STOP_SPRINTING
Jump with horse
RIDING_JUMP
Open ridden horse inventory
OPEN_INVENTORY
Close Window (0x0D)
This packet is sent by the client when closing a window.
Notchian clients send a Close Window packet with Window ID 0 to close their inventory even though there is never an Open Window packet for the inventory.
Parameters
Type
windowID
integer
Click Window (0x0E)
This packet is sent by the player when it clicks on a slot in a window.
Parameters
Type
windowId
int
slotId
int
usedButton
int
mode
int
clickedItem
ItemStack
actionNumber
short
See about modes at https://wiki.vg/index.php?title=Protocol&oldid=7368#Serverbound_2
Confirm Transaction (0x0F)
If a transaction sent by the client was not accepted, the server will reply with a Confirm Transaction (Play, 0x32, clientbound) packet with the Accepted field set to false. When this happens, the client must reflect the packet to apologize (as with movement), otherwise the server ignores any successive transactions.
Parameters
Type
windowId
int
transactionID
short
accepted
boolean
Player Abilities (0x13)
DA HYPIXEL PACKET
The latter 2 bytes are used to indicate the walking and flying speeds respectively, while the first byte is used to determine the value of 4 booleans.
The vanilla client sends this packet when the player starts/stops flying with the Flags parameter changed accordingly. All other parameters are ignored by the vanilla server.
Parameters
Type
flySpeed
float
walkSpeed
float
flying
boolean
allowFlying
boolean
creativeMode
boolean
invulnerable
boolean
Spectate (0x18)
Teleports the player to the given entity. The player must be in spectator mode.
The Notchian client only uses this to teleport to players, but it appears to accept any type of entity. The entity does not need to be in the same dimension as the player; if necessary, the player will be respawned in the right world. If the given entity cannot be found (or isn't loaded), this packet will be ignored. It will also be ignored if the player attempts to teleport to themselves.
Parameters
Type
uuid
UUID
Last updated