Packets

Sending packets

connection.sendPacket(id,args...)

// examples
connection.sendPacket("0x04",player.getX(),player.getY(),player.getZ(),player.isOnGround());
connection.sendPacket("0x03",player.isOnGround());
connection.sendPacket("0x07",world.getBlockPos(0,0,0),UP);

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