···
1
+
# Packets <img src=".assets/cc-by-sa.png" alt="CC-BY-SA" width="88" height="31">
3
+
_This document is licensed under a [Creative Commons Attribution-ShareAlike 4.0
4
+
license](https://creativecommons.org/licenses/by-sa/4.0/). Derivative works must
5
+
be licensed using the same or a compatible license._
7
+
All packets begin with a single "Packet ID" byte. Listed packet size **does not
8
+
include** this byte. Packets are either Clientbound, Serverbound, or both.
9
+
Packets that travel both Clientbound and Serverbound may reuse fields for
12
+
There is no "length" field; for variable length packets, you must parse to the
13
+
end to determine the length.
17
+
| | Size (bytes) | Range | Notes |
18
+
| ----- | ------------ | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
19
+
| i8 | 1 | -128 to 127 | |
20
+
| u8 | 1 | 0 to 255 | |
21
+
| i16 | 2 | -32768 to 32767 | |
22
+
| i32 | 4 | -2147483648 to 2147483647 | |
23
+
| i64 | 8 | -9223372036854775808 to 9223372036854775807 | |
24
+
| f32 | 4 | See [here][java8spec_floating]. | Single-precision 32-bit IEEE754 floating point. |
25
+
| f64 | 8 | See [here][java8spec_floating]. | Double-precision 64-bit IEEE754 floating point. |
26
+
| str8 | >=2 | N/A | [Modified UTF-8][mutf8] string. Prefixed by an `i16` containing the length of the string **in bytes**. |
27
+
| str16 | >=2 | Minimum length of `0`, maximum character length of `32767` | [UTF-16][utf16] string. Prefixed by an `i16` containing the length of the string **in characters**. |
28
+
| bool | 1 | `0x00` (`false`) or `0x01` (`true`) | |
30
+
There are also additional types being used:
34
+
| ID | Entity | Category | LivingEntity |
35
+
| --- | ------------- | ---------- | ------------ |
36
+
| 1 | Item | Misc | ❌ |
37
+
| 9 | Painting | Misc | ❌ |
38
+
| 10 | Arrow | Projectile | ❌ |
39
+
| 11 | Snowball | Projectile | ❌ |
40
+
| 20 | Primed TNT | Misc | ❌ |
41
+
| 21 | Falling Sand | Misc | ❌ |
42
+
| 40 | Minecart | Vehicle | ❌ |
43
+
| 41 | Boat | Vehicle | ❌ |
44
+
| 50 | Creeper | Hostile | ✅ |
45
+
| 51 | Skeleton | Hostile | ✅ |
46
+
| 52 | Spider | Hostile | ✅ |
47
+
| 53 | Giant | Hostile | ✅ |
48
+
| 54 | Zombie | Hostile | ✅ |
49
+
| 55 | Slime | Hostile | ✅ |
50
+
| 56 | Ghast | Hostile | ✅ |
51
+
| 57 | Zombie Pigman | Neutral | ✅ |
52
+
| 90 | Pig | Passive | ✅ |
53
+
| 91 | Sheep | Passive | ✅ |
54
+
| 92 | Cow | Passive | ✅ |
55
+
| 93 | Chicken | Passive | ✅ |
56
+
| 94 | Squid | Passive | ✅ |
57
+
| 95 | Wolf | Passive | ✅ |
61
+
Entity metadata has a quirky packing format.
63
+
A metadata field is a byte. The top three bits of the byte, when masked off
64
+
(`(byte & 224) >> 5`) and interpreted as a three-bit number from 0 to 7,
65
+
indicate the type of the field.
67
+
The lower five bits are unused. The type of the byte indicates the size and
68
+
type of a payload which follows the initial byte of the field.
70
+
The metadata format consists of at least one field, followed by either another
71
+
field or the magic number `0x7F`. `0x7F` terminates a metadata stream.
73
+
Thus, the example metadata stream `0x00 0x01 0x7f` is decoded as a field of
74
+
type 0, id 0, with a payload of byte 0x00.
76
+
| Field ID | Field Type |
77
+
| -------- | ------------------------------------------- |
82
+
| 4 | str16 (maximum character length of 64) |
83
+
| 5 | ItemStack; `i16` ID, `i8` count, `i16` data |
84
+
| 6 | Vector of `i32`, 3 long (x,y,z) |
86
+
More information is available at [0x18 Spawn Living Entity][spawn_living_entity].
90
+
Sent as an `i32` on the wire, but is actually an `f64`.
95
+
public static int floorDouble(double aDouble) {
96
+
int anInteger = (int)aDouble;
97
+
return aDouble < (double)anInteger ? anInteger - 1 : anInteger;
101
+
### Packed Rotation
103
+
Sent as an `i8` on the wire, but is actually an `f32`.
105
+
Basically, takes a rotation in degrees (`0..360`) and maps it into `0..255`.
110
+
public static byte packRotation(float rotation) {
111
+
return (byte)((int)(rotation * 256.0F / 360.0F))
115
+
### Packed Motion i8
117
+
Sent as an `i8` on the wire, but is actually an `f64`.
119
+
Basically, just multiply the value by `128` and turn it into a (signed) byte.
124
+
public static byte packMotion(double motion) {
125
+
return (byte)((int)(motion * 128.0D))
129
+
### Packed Motion i16
131
+
Sent as an `i16` on the wire, but is actually an `f64`.
133
+
Basically, just multiply the value by `128` and turn it into a (signed) byte.
138
+
public static byte packMotion(double motion) {
139
+
return (byte)((int)(motion * 128.0D))
149
+
This packet must be sent to keep the connection alive.
151
+
- Keep Alive has no payload.
153
+
## 0x01 Login Request
157
+
- Size: 15 + length of strings
161
+
Sent by the server if it accepts the client's login request. If it didn't it
162
+
will send a [Disconnect][disconnect] instead.
164
+
| Field Name | Field Type | Example | Notes |
165
+
| ---------- | ---------- | ------- | --------------------------------------------------------------------------- |
166
+
| Entity ID | i32 | `14` | The protocol version of Beta 1.7 is 14 |
167
+
| Unused | str16 | N/A | Unused by the client. Vanilla server sends an empty string |
168
+
| Map Seed | i64 | `0` | Used by the client to determine its current biome, among a few other things |
169
+
| Dimension | i8 | `0` | `-1` for the Nether, `0` for the Overworld |
173
+
Sent by the client after the handshake to finish logging in.
175
+
| Field Name | Field Type | Example | Notes |
176
+
| ---------------- | ---------- | ------------- | ------------------------------------------------------------------------------- |
177
+
| Protocol version | i32 | `14` | The protocol version of Beta 1.7 is 14 |
178
+
| Username | str16 | `kokiriglade` | The name of the player attempting to login. Max length of 16 |
179
+
| Map Seed | i64 | `0` | Can be safely ignored by the server |
180
+
| Dimension | i8 | `0` | `-1` for the Nether, `0` for the Overworld. Can be safely ignored by the server |
186
+
- Size: 2 + length of strings
190
+
| Field Name | Field Type | Example | Notes |
191
+
| --------------- | ---------- | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
192
+
| Connection Hash | str16 | `2e66f1dc032ab5f0` | A unique, per-connection hash. The vanilla server sends a random `i64` stringified as a hexadecimal number. For offline-mode, the string is always a single `-` |
196
+
| Field Name | Field Type | Example | Notes |
197
+
| ---------- | ---------- | ------------- | ---------------------------------------------------------------------------- |
198
+
| Username | str16 | `kokiriglade` | The name of the player attempting to connect. Maximum character length of 16 |
200
+
## 0x03 Chat Message
204
+
- Size: 2 + length of strings
206
+
| Field Name | Field Type | Example | Notes |
207
+
| ---------- | ---------- | ---------------------- | ----------------------------------------------------------------------------- |
208
+
| Message | str16 | `<kokiriglade> Hello!` | The name of the player attempting to connect. Maximum character length of 119 |
210
+
## 0x04 Update Time
216
+
The time of day is based on `timestamp % 24000`, where:
221
+
- 18000 is midnight
223
+
| Field Name | Field Type | Example | Notes |
224
+
| ---------- | ---------- | ------- | ----------------------- |
225
+
| Time | i64 | | The world time in ticks |
227
+
## 0x05 Set Player Equipment
233
+
After each [player spawn][spawn_player], there will be five of these packets for
234
+
the equipped item and armor. If there are changes in visible equipment, another
235
+
one of these packets is sent.
237
+
| Field Name | Field Type | Example | Notes |
238
+
| ---------- | ---------- | ------- | ------------------------------------ |
239
+
| Entity ID | i32 | | Player's entity ID |
240
+
| Slot | i16 | `4` | Equipment slot. See below |
241
+
| Item ID | i16 | `-1` | Equipped item (`-1` for aempty slot) |
242
+
| Data | i16 | | Item data value |
244
+
### Equipment slots
246
+
(These only apply to this packet)
254
+
## 0x06 Spawn Position
260
+
Sent after login to specify the coordinates of the spawn point (the location at
261
+
which players spawn, and which the compass points to).
263
+
It can be sent at any time to update the point compasses point to.
265
+
| Field Name | Field Type | Example | Notes |
266
+
| ---------- | ---------- | ------- | ---------------------------- |
267
+
| X | i32 | `117` | Spawn X in block coordinates |
268
+
| Y | i32 | `70` | Spawn Y in block coordinates |
269
+
| Z | i32 | `-46` | Spawn Z in block coordinates |
277
+
Sent upon attacking or right clicking an entity.
279
+
| Field Name | Field Type | Example | Notes |
280
+
| ---------------- | ---------- | ------- | ----------------------------------------------------------------------- |
281
+
| Entity ID | i32 | | Player's entity ID. Ignored by the server |
282
+
| Target entity ID | i32 | | Entity ID of the entity being interacted with |
283
+
| Left click | bool | `true` | `true` if the interaction was caused by a left click, `false` otherwise |
285
+
## 0x08 Update Health
291
+
| Field Name | Field Type | Example | Notes |
292
+
| ---------- | ---------- | ------- | ---------------- |
293
+
| Health | i16 | `20` | Half a heart = 1 |
301
+
Sent by the client when the player presses the "Respawn" button after dying.
302
+
The server then teleports the player to the spawn point, and sends a respawn
303
+
packet in response. The client will not leave the respawn screen until it
304
+
receives a respawn packet.
306
+
| Field Name | Field Type | Example | Notes |
307
+
| ---------- | ---------- | ------- | ------------------------------------------------------------------------------- |
308
+
| Dimension | i8 | `0` | `-1` for the Nether, `0` for the Overworld. Can be safely ignored by the server |
316
+
| Field Name | Field Type | Example | Notes |
317
+
| ---------- | ---------- | ------- | -------------------------------------------------------- |
318
+
| On Ground | bool | `true` | `true` if the player is on the ground, `false` otherwise |
320
+
## 0x0B Player Position
326
+
Updates the player position on the server. If `(stance - y) < 0.1 || (stance - y) > 1.65`
327
+
then the stance is illegal.
329
+
If the distance between the last known position of
330
+
the player and the new position set by this packet is greater than 100, then the
331
+
movement is illegal.
333
+
If the absolute number of `x` or `z` are set greater than `3.2E7` then the
334
+
position is illegal.
336
+
| Field Name | Field Type | Example | Notes |
337
+
| ---------- | ---------- | --------- | ----------------------------------------------------------------------------- |
338
+
| X | f64 | `102.809` | |
339
+
| Y | f64 | `70.00` | |
340
+
| Stance | f64 | `71.62` | Used to modify the players bounding box when going up stairs, crouching, etc. |
341
+
| Z | f64 | `68.30` | |
342
+
| On Ground | bool | `true` | `true` if the player is on the ground, `false` otherwise |
344
+
## 0x0C Player Look
350
+
Updates the direction the player is looking in.
352
+
Yaw is measured in degrees, and does not follow classical trigonometry rules.
354
+
The unit circle of yaw on the xz-plane starts at (0, 1) and turns backwards
355
+
towards (-1, 0), or in other words, it turns clockwise instead of
356
+
counter-clockwise. Additionally, yaw is not clamped to between 0 and 360
357
+
degrees; any number is valid, including negative numbers and numbers greater
360
+
| Field Name | Field Type | Example | Notes |
361
+
| ---------- | ---------- | ------- | -------------------------------------------------------- |
362
+
| Yaw | f32 | `0.0` | Rotation on the X Axis, in degrees |
363
+
| Pitch | f32 | `0.0` | Rotation on the Y axis, in degrees |
364
+
| On Ground | bool | `true` | `true` if the player is on the ground, `false` otherwise |
366
+
## 0x0D Player Position and Look
372
+
A combination of [Player Look][player_look] and [Player Position][player_position].
374
+
| Field Name | Field Type | Example | Notes |
375
+
| ---------- | ---------- | --------- | ----------------------------------------------------------------------------- |
376
+
| X | f64 | `102.809` | |
377
+
| Y | f64 | `70.00` | |
378
+
| Stance | f64 | `71.62` | Used to modify the players bounding box when going up stairs, crouching, etc. |
379
+
| Z | f64 | `68.30` | |
380
+
| Yaw | f32 | `0.0` | Rotation on the X Axis, in degrees |
381
+
| Pitch | f32 | `0.0` | Rotation on the Y axis, in degrees |
382
+
| On Ground | bool | `true` | `true` if the player is on the ground, `false` otherwise |
390
+
Sent when the player is digging a block.
392
+
| Field Name | Field Type | Example | Notes |
393
+
| ---------- | ---------- | ------- | ------------------------------------------------------------- |
394
+
| Status | i8 | `1` | The action the player is taking against the block (see below) |
395
+
| X | i32 | `32` | Block position |
396
+
| Y | i8 | `64` | Block position |
397
+
| Z | i32 | `32` | Block position |
398
+
| Face | i8 | `3` | The face being hit (see below) |
404
+
- `0`: Started digging
405
+
- `2`: Finished digging
410
+
For some unthinkable reason, when the player drops an item, it sends this packet
411
+
but the status is `4`, and all other values are `0`.
424
+
## 0x0F Block Interact
430
+
Sent when the player places a block or (probably) an item. The coordinates sent
431
+
in this packet are actually the block being built against, which combined with
432
+
the direction offset tell you where the block should be placed. This is
433
+
required to correctly position furnaces, torches, etc.
435
+
| Field Name | Field Type | Example | Notes |
436
+
| ---------------- | ------------- | ------- | ---------------------------------------------------------- |
437
+
| X | i32 | `32` | Block position |
438
+
| Y | i8 | `64` | Block position |
439
+
| Z | i32 | `32` | Block position |
440
+
| Face | i8 | `3` | The face being placed against (see [Block Dig][block_dig]) |
441
+
| Block or Item ID | i16 | `1` | The block or item to be placed |
442
+
| Count | Optional<i8> | `34` | The count of the itemstack in the players hand |
443
+
| Data | Optional<i16> | `83` | The data value of the itemstack |
445
+
If the Block/ItemID field is greater than or equal to 0, then the last
446
+
2 fields (count and data) are read. Otherwise, they are not read.
448
+
When 'placing' (Or more accurately, using) your empty hand, the client sends -1
449
+
as the Block/Item ID.
453
+
This packet has a special case where X, Y, Z, and Direction are all -1.
454
+
This special packet indicates that the currently held item for the player should
455
+
have its state updated such as eating food, shooting bows, using buckets, etc.
457
+
When using buckets, the client might send two packets: first a normal and then a
458
+
special case. The first normal packet is sent when you're looking at a block
459
+
(e.g. the water you want to scoop up). This normal packet does not appear to do
460
+
anything with a Vanilla server. The second, special case packet appears to
461
+
perform the action - based on current position/orientation and with a distance
462
+
check - it appears that buckets can only be used within a radius of 6 blocks.
464
+
## 0x10 Change Current Slot
470
+
Sent when the player changes their current/active slot.
472
+
| Field Name | Field Type | Example | Notes |
473
+
| ---------- | ---------- | ------- | --------------------------------- |
474
+
| Slot ID | i16 | `1` | Valid values are 0..8 (inclusive) |
482
+
Sent to indicate a player is sleeping in a bed.
484
+
| Field Name | Field Type | Example | Notes |
485
+
| ---------- | ---------- | ------- | ------------------ |
486
+
| Entity ID | i32 | `89` | Player's entity ID |
487
+
| Unknown | i8 | `0` | Always 0, unused |
488
+
| X | i32 | `-247` | Block coordinate |
489
+
| Y | i8 | `78` | Block coordinate |
490
+
| Z | i32 | `128` | Block coordinate |
498
+
| Field Name | Field Type | Example | Notes |
499
+
| ---------- | ---------- | ------- | ------------------ |
500
+
| Entity ID | i32 | `55534` | Player's entity ID |
501
+
| Animate | i8 | `1` | See below |
507
+
- `0`: No animation
509
+
- `2`: Damage animation
512
+
## 0x13 Player Action
518
+
Sent when crouching and leaving a bed.
520
+
| Field Name | Field Type | Example | Notes |
521
+
| ---------- | ---------- | ------- | ------------------ |
522
+
| Entity ID | i32 | `55534` | Player's entity ID |
523
+
| Action | i8 | `1` | See below |
529
+
- `1`: Start crouching
530
+
- `2`: Stop crouching
533
+
## 0x14 Spawn Player
537
+
- Size: 22 + length of strings
539
+
Sent when a player comes into visible range. The vanilla client is not okay
540
+
with receiving player entity packets that refer to its own username or EID; it
541
+
will teleport to the absolute origin of the map and fall through the void any
542
+
time it receives them.
544
+
| Field Name | Field Type | Example | Notes |
545
+
| ---------- | ---------- | ------------- | --------------------------------------------------------------------- |
546
+
| Entity ID | i32 | `94453` | Player's entity ID |
547
+
| Name | str16 | `kokiriglade` | Maximum character length of 16 |
548
+
| X | i32 | `102.809` | [Packed f64][packed_f64] |
549
+
| Y | i32 | `70.00` | [Packed f64][packed_f64] |
550
+
| Z | i32 | `68.30` | [Packed f64][packed_f64] |
551
+
| Yaw | i8 | `0.0` | [Packed rotation][packed_rotation] |
552
+
| Pitch | i8 | `0.0` | [Packed rotation][packed_rotation] |
553
+
| Held Item | i16 | `0` | The item the player is holding. `0` for no item. Must not be negative |
561
+
Sent when a thrown item comes into range of the player.
563
+
| Field Name | Field Type | Example | Notes |
564
+
| ---------- | ---------- | --------- | ------------------------------------ |
565
+
| Entity ID | i32 | `157617` | Item's entity ID |
566
+
| Item ID | i16 | `4` | |
567
+
| Count | i8 | `1` | The count of the itemstack |
568
+
| Data | i16 | Item data | |
569
+
| X | i32 | `102.809` | [Packed f64][packed_f64] |
570
+
| Y | i32 | `70.00` | [Packed f64][packed_f64] |
571
+
| Z | i32 | `68.30` | [Packed f64][packed_f64] |
572
+
| Motion X | i8 | `0.0` | [Packed motion-i8][packed_motion_i8] |
573
+
| Motion Y | i8 | `0.0` | [Packed motion-i8][packed_motion_i8] |
574
+
| Motion Z | i8 | `0.0` | [Packed motion-i8][packed_motion_i8] |
576
+
## 0x16 Pickup Item
582
+
Sent when someone picks up an item lying on the ground - its sole purpose is
583
+
the animation of the item flying towards the player.
585
+
It doesn't destroy the entity in the client memory ([Destroy Entity][destroy_entity]
586
+
does that), and it doesn't add it to the player's inventory ([Set Slot][set_slot]
589
+
The server only checks for items to be picked up after each [Player Position][player_position]
590
+
and [Player Position and Look][player_position_and_look] packet sent by the client.
592
+
| Field Name | Field Type | Example | Notes |
593
+
| ------------------- | ---------- | ------- | -------------------------- |
594
+
| Collected Entity ID | i32 | `28` | Collected item's entity ID |
595
+
| Collector Entity ID | i32 | `30` | Collector's entity ID |
597
+
## 0x17 Spawn Non-Living Entity
603
+
Sent when a Non-Living entity is created.
605
+
| Field Name | Field Type | Example | Notes |
606
+
| ----------- | ---------- | ------- | ---------------------------------------------------------------- |
607
+
| Entity ID | i32 | `62` | |
608
+
| Entity Type | i8 | `11` | [See Entity Types][entity_types] (must be of kind `Living`) |
609
+
| X | i32 | `16080` | [Packed f64][packed_f64] |
610
+
| Y | i32 | `2290` | [Packed f64][packed_f64] |
611
+
| Z | i32 | `592` | [Packed f64][packed_f64] |
612
+
| Has Motion | i32 | `0` | If this flag is bigger than 0 then the following fields are sent |
613
+
| Motion X | i16 | `0` | [Packed motion-i16][packed_motion_i16] |
614
+
| Motion Y | i16 | `0` | [Packed motion-i16][packed_motion_i16] |
615
+
| Motion Z | i16 | `0` | [Packed motion-i16][packed_motion_i16] |
617
+
## 0x18 Spawn Living Entity
621
+
- Size: 19 + [Metadata][entity_metadata] (at least 1)
623
+
Sent when a Living Entity is created.
625
+
| Field Name | Field Type | Example | Notes |
626
+
| ------------------ | ---------------------------------- | ------- | -------------------------------------------------- |
627
+
| Entity ID | i32 | `62` | |
628
+
| Living Entity Type | i8 | `11` | See below |
629
+
| X | i32 | `16080` | [Packed f64][packed_f64] |
630
+
| Y | i32 | `2290` | [Packed f64][packed_f64] |
631
+
| Z | i32 | `592` | [Packed f64][packed_f64] |
632
+
| Yaw | i8 | `-27` | [Packed rotation][packed_rotation] |
633
+
| Pitch | i8 | `0` | [Packed rotation][packed_rotation] |
634
+
| Entity Metadata | [Entity Metadata][entity_metadata] | `127` | Indexed metadata, terminated by `0x7F` - see below |
636
+
### Living Entity types
639
+
- Index 16 is `i8`, for `fuse`
640
+
- `1` for blowing up, `-1` otherwise
641
+
- Index 17 is `bool`, for `is charged`
644
+
- `53`: Giant Zombie
647
+
- Index 16 is `i8`, for `size`
649
+
- Index 16 is `i8`, for `is attacking`
650
+
- `57`: Zombie Pigman
652
+
- Index 16 is `i8`, for `is saddled`
654
+
- Index 16 is `i8` for `coat`
655
+
- You can use a `0x10` bit mask for `shearedness` and `0x0F` for `color` - see below
660
+
- Index 16 is `i8`, and is a bitmask:
661
+
- `0x01` for `is sitting`
662
+
- `0x02` for `is aggressive`
663
+
- `0x04` for `is tamed`
664
+
- Index 17 is `string16`, and is the `name of the player` who tamed the wolf
665
+
- Index 18 is `i32`, and is the `health` of the wolf
667
+
Metadata index 0 is an `i8` representing a set of 8 `bool`s:
670
+
- `0x02`: Is crouched
671
+
- `0x04`: Is riding
683
+
- `8`: Light Gray (Silver)
692
+
## 0x19 Spawn Painting
696
+
- Size: 22 + length of strings
698
+
Sent when a painting is created.
700
+
Calculating the center of an image: given a `(width x height)` grid of cells,
701
+
with `(0, 0)` being the top left corner, the center is `(max(0, width / 2 - 1), height / 2)`.
707
+
| Field Name | Field Type | Example | Notes |
708
+
| ---------- | ---------- | ---------- | ---------------------------------------------------- |
709
+
| Entity ID | i32 | `326` | |
710
+
| Title | str16 | `Creepers` | Name of the painting. Maximum character length of 13 |
711
+
| X | i32 | `50` | Center X coordinate |
712
+
| Y | i32 | `66` | Center Y coordinate |
713
+
| Z | i32 | `-50` | Center Z coordinate |
714
+
| Direction | i32 | `0` | Direction the painting is facing, see below |
723
+
## 0x1C Update Velocity
729
+
Velocity is believed to be in units of 1/32000 of a block per server tick
730
+
(200ms); for example, `-1343` would move `(-1343 / 32000) = -0.04196875` blocks
731
+
per tick (or `-0.20984375 blocks per second`).
733
+
Each axis' velocity is capped between -0.9 and 0.9 blocks per tick (packet
734
+
values -28800 to 28800).
736
+
| Field Name | Field Type | Example | Notes |
737
+
| ---------- | ---------- | ------- | ---------------------- |
738
+
| Entity ID | i32 | `1805` | |
739
+
| X | i16 | `-1343` | Velocity on the X axis |
740
+
| Y | i16 | `0` | Velocity on the Y axis |
741
+
| Z | i16 | `0` | Velocity on the Z axis |
743
+
## 0x1D Destroy Entity
749
+
| Field Name | Field Type | Example | Notes |
750
+
| ---------- | ---------- | ------- | ----- |
751
+
| Entity ID | i32 | `446` | |
759
+
Most entity-related packets are subclasses of this packet. When sent from the
760
+
server to the client, it may initialize the entry.
762
+
For player entities, either this packet or any move/look packet is sent several
763
+
times per second. So the meaning of this packet is basically that the entity
764
+
did not move/look since the last such packet.
766
+
| Field Name | Field Type | Example | Notes |
767
+
| ---------- | ---------- | ------- | ----- |
768
+
| Entity ID | i32 | `446` | |
770
+
## 0x1F Entity Relative Move
776
+
| Field Name | Field Type | Example | Notes |
777
+
| ---------- | ---------- | ------- | ----- |
778
+
| Entity ID | i32 | `446` | |
779
+
| Relative X | i8 | `1` | |
780
+
| Relative Y | i8 | `-7` | |
781
+
| Relative Z | i8 | `5` | |
783
+
Solid documentation on what these relative coordinates actually are is kind of
784
+
lacking - apologies. I'll figure it out eventually though.
786
+
## 0x20 Entity Look
792
+
This packet is sent by the server when an entity rotates.
794
+
Example: `Yaw`=`64` means a 90 degree turn.
796
+
| Field Name | Field Type | Example | Notes |
797
+
| ---------- | ---------- | ------- | ---------------------------------- |
798
+
| Entity ID | i32 | `459` | |
799
+
| Yaw | i8 | `64` | [Packed rotation][packed_rotation] |
800
+
| Pitch | i8 | `0` | [Packed rotation][packed_rotation] |
802
+
## 0x21 Entity Look and Relative Move
808
+
This packet is sent by the server when an entity rotates and moves.
810
+
Since `i8` range is limited from -128 to 127, this packet allows at most four b
811
+
locks movement in any direction. (`-128/32 == -4`)
813
+
| Field Name | Field Type | Example | Notes |
814
+
| ---------- | ---------- | ------- | ------------------------------------ |
815
+
| Entity ID | i32 | `446` | |
816
+
| Relative X | i8 | `1` | |
817
+
| Relative Y | i8 | `-7` | |
818
+
| Relative Z | i8 | `5` | |
819
+
| Yaw | i8 | `64` | X axis rotation as a fraction of 360 |
820
+
| Pitch | i8 | `0` | Y axis rotation as a fraction of 360 |
822
+
## 0x22 Entity Teleport
828
+
This packet is sent by the server when an entity moves more than 4 blocks.
830
+
| Field Name | Field Type | Example | Notes |
831
+
| ---------- | ---------- | ------- | ---------------------------------- |
832
+
| Entity ID | i32 | `446` | |
833
+
| X | i32 | `14162` | [Packed f64][packed_f64] |
834
+
| Y | i32 | `2176` | [Packed f64][packed_f64] |
835
+
| Z | i32 | `1111` | [Packed f64][packed_f64] |
836
+
| Yaw | i8 | `64` | [Packed rotation][packed_rotation] |
837
+
| Pitch | i8 | `0` | [Packed rotation][packed_rotation] |
839
+
## 0x26 Entity Status
845
+
| Field Name | Field Type | Example | Notes |
846
+
| ---------- | ---------- | ------- | --------- |
847
+
| Entity ID | i32 | `446` | |
848
+
| Status | i8 | `2` | See below |
852
+
- `2`: (Living Entities only) Attack animation
853
+
- `3`: (Living Entities only) Death animation
854
+
- `6`: (Wolf only) Make smoke particles
855
+
- `7`: (Wolf only) Make hearts particles
856
+
- `8`: (Wolf only) Shaking
858
+
## 0x27 Ride Entity
864
+
This packet is sent when a player starts riding an entity.
866
+
| Field Name | Field Type | Example | Notes |
867
+
| ----------------- | ---------- | ------- | ------------------- |
868
+
| Player Entity ID | i32 | `446` | Player's entity ID |
869
+
| Vehicle Entity ID | i32 | `1805` | Vehicle's entity ID |
871
+
## 0x28 Update Entity Metadata
875
+
- Size: 4 + [Metadata][entity_metadata] (at least 1)
877
+
| Field Name | Field Type | Example | Notes |
878
+
| --------------- | ---------------------------------- | ------- | ------------------------------------------------- |
879
+
| Entity ID | i32 | `446` | Entity ID |
880
+
| Entity Metadata | [Entity Metadata][entity_metadata] | `127` | Indexed metadata, terminated by `0x7F` - see link |
882
+
## 0x32 Initialize Chunk
888
+
The client is expected to allocate space for a full chunk (16 x 128 x 16 blocks).
890
+
One or more [Chunk Data][chunk_data] packets will follow, specifying actual data
891
+
to fill the chunk with.
893
+
Whenever you send this packet the client will clear any previous chunk at that
894
+
spot if one has previously been sent. Clients don't like being in or next to an
895
+
unloaded chunk, so try not to unload it if players are nearby. If the player
896
+
appears to be twitching and stuck in place after joining the world, there is
897
+
probably an unloaded chunk too close to them.
899
+
| Field Name | Field Type | Example | Notes |
900
+
| ----------- | ---------- | ------- | ------------------------------------------------------------------------------------- |
901
+
| X | i32 | `-9` | Chunk coordinate |
902
+
| Z | i32 | `12` | Chunk coordinate |
903
+
| Load/Unload | bool | `true` | If `false`, the client unloads the chunk. If `true`, the client initializes the chunk |
909
+
- Size: 17 + compressed chunk size
911
+
| Field Name | Field Type | Example | Notes |
912
+
| --------------- | ---------- | ------- | ------------------------------------- |
913
+
| X | i32 | `128` | Block coordinate |
914
+
| Y | i16 | `0` | Block coordinate |
915
+
| Z | i32 | `-192` | Block coordinate |
916
+
| Size X | i8 | `15` | Size X is Actual X Size -1 |
917
+
| Size Y | i8 | `127` | Size Y is Actual Y Size -1 |
918
+
| Size Z | i8 | `15` | Size Z is Actual Z Size -1 |
919
+
| Compressed size | i32 | `3663` | Size of compressed region data |
920
+
| Compressed data | Vec\<u8\> | `...` | Compressed region data (zlib deflate) |
924
+
This is the start position of the region, in world block coordinates.
926
+
To find which chunk is affected, in the same coordinates given by [Initialize Chunk][initialize_chunk]:
934
+
And conversely, which local block in the chunk to start at:
938
+
startY = Y & 127 (not always 0!)
944
+
This is the size of the region, in blocks. The server will subtract one from
945
+
the sizes and then cast them to a byte before sending. This is so that chunks
946
+
as large as 256 are possible.
948
+
### Compressed data
950
+
The data is compressed using the deflate() function in [zlib]. After uncompressing,
951
+
the data consists of four sequential sections, in order:
953
+
- Block ID array (1 byte per block)
954
+
- Block metadata array (half byte/nibble per block)
955
+
- Block Light array (half byte/nibble per block)
956
+
- Sky Light array (half byte/nibble per block)
958
+
The data is exactly `(sizeX+1) * (sizeY+1) * (sizeZ+1) * 2.5` bytes long.
959
+
Nibbles are not rounded either direction, which means that at least one
960
+
dimension of the chunk must be even.
962
+
The arrays are not interlaced.
964
+
In other words, there are `sizeX` number of x planes, each plane made up of
965
+
`sizeZ` number of z rows, each row made up of `sizeY` blocks indexed by y
966
+
coordinate in order.
968
+
The Block ID array is indexed with:
971
+
index = y + (z * (sizeY+1)) + (x * (sizeY+1) * (sizeZ+1))
974
+
The other arrays are similar but you need to divide the index by two after
975
+
calculating the above. Then each byte contains data for two blocks. The low
976
+
four bits contain the first (lower Y) nibble and the high four bits contain the
979
+
If you have a FULL map chunk (`sizeX = 15, sizeY = 127, sizeZ = 15`), you can
980
+
calculate index coordinates:
983
+
x = X + ( index >> 11 )
985
+
z = Z + ( (index & 0x780) >> 7 )
988
+
## 0x34 Multi Block Change
992
+
- Size: 10 + arrays
994
+
This is a multiple-block-change command; if you take the three arrays, and put
995
+
together elements with the same index, and then decompose the `i16` into
996
+
coordinates (top 4 bits is X, next 4 bits is Z, bottom 8 bits is Y), you get
997
+
arrays like [((8, 7, 4), 11, 0), ((7, 13, 6), 11, 0), ((13, 1, 8), 11, 0), ((7, 6, 6), 11, 0)].
999
+
| Field Name | Field Type | Example | Notes |
1000
+
| -------------------- | ---------- | ------- | --------------------------------------- |
1001
+
| X | i32 | `-9` | Chunk coordinate |
1002
+
| Z | i32 | `12` | Chunk coordinate |
1003
+
| Array size | i16 | `2` | The total number of elements per array |
1004
+
| Coordinate array | Vec\<i16\> | `...` | The coordinates of the blocks to change |
1005
+
| Block ID array | Vec\<i8\> | `...` | The ID for each block to change |
1006
+
| Block metadata array | Vec\<i8\> | `...` | The metadata for each block changed |
1008
+
See [blocks] for information on the metadata variable.
1010
+
## 0x35 Block Change
1012
+
- Clientbound: [x]
1013
+
- Serverbound: [ ]
1016
+
| Field Name | Field Type | Example | Notes |
1017
+
| -------------- | ---------- | ------- | -------------------------- |
1018
+
| X | i32 | `128` | Block coordinate |
1019
+
| Y | i8 | `0` | Block coordinate |
1020
+
| Z | i32 | `-192` | Block coordinate |
1021
+
| Block ID | i8 | `78` | The type for the block |
1022
+
| Block metadata | i8 | `0` | The metadata for the block |
1024
+
See [blocks] for information on the metadata variable.
1026
+
## 0x36 Play Note Block
1028
+
- Clientbound: [x]
1029
+
- Serverbound: [ ]
1032
+
Sent when a note block is played.
1034
+
| Field Name | Field Type | Example | Notes |
1035
+
| --------------- | ---------- | ------- | ----------------------------------------------- |
1036
+
| X | i32 | `128` | Block coordinate |
1037
+
| Y | i16 | `0` | Block coordinate |
1038
+
| Z | i32 | `-192` | Block coordinate |
1039
+
| Instrument type | i8 | `3` | See below |
1040
+
| Pitch | i8 | `17` | The pitch of the note (between 0..24 inclusive) |
1042
+
### Instrument types
1045
+
- `1`: Double Bass
1047
+
- `3`: Clicks/Sticks (Hihat)
1052
+
- Clientbound: [x]
1053
+
- Serverbound: [ ]
1054
+
- Size: 32 + `3*(coordinate count)`
1056
+
Sent when an explosion occurs.
1058
+
| Field Name | Field Type | Example | Notes |
1059
+
| ---------------- | --------------------- | -------- | ------------------------------ |
1060
+
| X | f64 | `128.0` | Center coordinate |
1061
+
| Y | f64 | `0.0` | Center coordinate |
1062
+
| Z | f64 | `-192.0` | Center coordinate |
1063
+
| Radius | f32 | `4.0` | |
1064
+
| Coordinate count | i32 | `60` | |
1065
+
| Records | (i8, i8, i8) \* count | `...` | XYZ offsets of affected blocks |
1067
+
## 0x3D Play Effect
1069
+
- Clientbound: [x]
1070
+
- Serverbound: [ ]
1073
+
Sent when a client is to play an effect.
1075
+
| Field Name | Field Type | Example | Notes |
1076
+
| ---------- | ---------- | -------- | ---------------- |
1077
+
| Effect ID | i32 | `1003` | See below |
1078
+
| X | i32 | `128.0` | Block coordinate |
1079
+
| Y | i8 | `0.0` | Block coordinate |
1080
+
| Z | i32 | `-192.0` | Block coordinate |
1081
+
| Data | i32 | `0` | See below |
1085
+
- `1000`: Play sound `random.click` with pitch 1.0
1086
+
- `1001`: Play sound `random.click` with pitch 1.2
1087
+
- `1002`: Play sound `random.bow` with pitch 1.2
1088
+
- `1003`: Play sound randomly between `random.door_open` and `random.door_close` with random uniform pitch between 0.0 and 1.0
1089
+
- `1004`: Play sound `random.fizz` with volume 0.5 and random pitch
1090
+
- `1005`: Play record sound.
1091
+
- The record item ID is given in the effect data.
1092
+
- `2000`: Spawn smoke particles
1093
+
- The radius is given in effect data with two bits for X and Z axis, like this: `0bZZXX`
1094
+
- `2001`: Play and show block break sound and particles.
1095
+
- The block id is given in effect data.
1097
+
## 0x46 Notification
1099
+
- Clientbound: [x]
1100
+
- Serverbound: [ ]
1103
+
Sent to notify the client of some state.
1105
+
| Field Name | Field Type | Example | Notes |
1106
+
| ---------- | ---------- | ------- | --------- |
1107
+
| Reason | i8 | `1` | See below |
1111
+
- `0`: Invalid bed
1112
+
- `1`: Start raining
1113
+
- `2`: Stop raining
1117
+
- Clientbound: [x]
1118
+
- Serverbound: [ ]
1121
+
Notifies the client of thunderbolts striking somewhere. The coordinates specify
1122
+
where exactly the thunderbolt strikes.
1124
+
| Field Name | Field Type | Example | Notes |
1125
+
| ---------- | ---------- | ------- | ------------------------ |
1126
+
| Entity ID | i32 | `4` | Lightning bolt entity ID |
1127
+
| ??? | bool | `true` | Always `true` |
1128
+
| X | i32 | `133` | [Packed f64][packed_f64] |
1129
+
| Y | i32 | `913` | [Packed f64][packed_f64] |
1130
+
| Z | i32 | `63552` | [Packed f64][packed_f64] |
1132
+
## 0x64 Open Inventory
1134
+
- Clientbound: [x]
1135
+
- Serverbound: [ ]
1136
+
- Size: 5 + length of strings
1138
+
| Field Name | Field Type | Example | Notes |
1139
+
| --------------- | ---------- | ------- | -------------------- |
1140
+
| Inventory ID | i8 | `123` | |
1141
+
| Inventory Type | i8 | `0` | See below |
1142
+
| Title | str8 | `Chest` | Only used for chests |
1143
+
| Number of slots | i8 | `3` | |
1145
+
### Inventory Type
1148
+
- `1`: Crafting table
1152
+
## 0x65 Close Inventory
1154
+
- Clientbound: [x]
1155
+
- Serverbound: [x]
1158
+
Clients send this packet with Inventory ID `0` when they close their inventory.
1160
+
| Field Name | Field Type | Example | Notes |
1161
+
| ------------ | ---------- | ------- | ------------------------ |
1162
+
| Inventory ID | i8 | `123` | 0 for player's inventory |
1164
+
## 0x66 Click Inventory
1166
+
- Clientbound: [ ]
1167
+
- Serverbound: [x]
1170
+
Sent when the playuer clicks on a slot in an inventory.
1172
+
| Field Name | Field Type | Example | Notes |
1173
+
| -------------- | ---------- | ------- | ----------------------------------------------------------------------------------------------------- |
1174
+
| Inventory ID | i8 | `123` | 0 for player's inventory |
1175
+
| Cicked Slot | i16 | `36` | |
1176
+
| Right clicking | bool | `true` | `true` if right cicking, `false` otherwise |
1177
+
| Action number | `i16` | `12` | Unique number for the action, used for [transaction handling][transaction] |
1178
+
| Shift | bool | `fase` | `true` if the player was holding shift, `false` otherwise |
1179
+
| Item ID | `i16` | `3` | ID of the item that was in the slot. `-1` for no item. If `-1`, this is the last field in the packet. |
1180
+
| Item Count | `i8` | `64` | |
1181
+
| Item Data | `i16` | `10` | |
1183
+
When right-clicking on a stack of items, half the stack will be picked up and
1184
+
half left in the slot. If the stack is an odd number, the half left in the slot
1185
+
will be smaller of the amounts.
1187
+
The Action number is actually a counter, starting at `1`. This number is used by
1188
+
the server as a transaction ID to send back a [transaction] packet.
1190
+
For help with slot IDs, see the next packet.
1192
+
## 0x67 Set Inventory Slot
1194
+
- Clientbound: [x]
1195
+
- Serverbound: [ ]
1198
+
Sent by the server when an item in a slot is added/removed.
1200
+
| Field Name | Field Type | Example | Notes |
1201
+
| ------------ | ---------- | ------- | ---------------------------------------------------------------- |
1202
+
| Inventory ID | i8 | `123` | 0 for player's inventory |
1203
+
| Slot | i16 | `36` | |
1204
+
| Item ID | `i16` | `3` | `-1` for no item. If `-1`, this is the last field in the packet. |
1205
+
| Item Count | `i8` | `64` | |
1206
+
| Item Data | `i16` | `10` | |
1208
+
Note that if window ID and slot are both `-1`, it means the item currently attached to the cursor.
1212
+
1214
+
## 0x68 Set Inventory Slots
1216
+
- Clientbound: [x]
1217
+
- Serverbound: [ ]
1218
+
- Size: 3 + size of payload
1220
+
Sent by the server when items in slots are added/removed. This includes the
1221
+
player inventory, equipped armor, and crafting slots.
1223
+
| Field Name | Field Type | Example | Notes |
1224
+
| ------------- | ---------- | ------- | ------------------------ |
1225
+
| Inventory ID | i8 | `123` | 0 for player's inventory |
1226
+
| Payload count | i16 | `4` | See below |
1227
+
| Payload | ... | | See below |
1229
+
This packet is a bit trickier to parse than most others because the size of its
1230
+
payload is variable. The payload is an array of shorts (item ID) optionally
1231
+
followed by a byte-short pair (count and data) as long as the item ID does not
1232
+
equal `-1`, which signifies an empty slot.
1237
+
for slot in count:
1238
+
item_id = payload[offset] as short
1240
+
if item_id is not equal to -1:
1241
+
count = payload[offset] as byte
1243
+
uses = payload[offset] as short
1245
+
inventory[slot] = new item(item_id, count, uses)
1247
+
inventory[slot] = None
1250
+
## 0x69 Update Progress Bar
1252
+
- Clientbound: [x]
1253
+
- Serverbound: [ ]
1256
+
| Field Name | Field Type | Example | Notes |
1257
+
| ------------ | ---------- | ------- | ------------------------ |
1258
+
| Inventory ID | i8 | `123` | 0 for player's inventory |
1259
+
| Progress Bar | i16 | `1` | See below |
1260
+
| Value | i16 | 650 | See below |
1268
+
- `2`: Current Item Burn Time
1269
+
- time in ticks that the fuel item takes to burn
1274
+
- Full progress arrow: approx. `180`
1275
+
- Full fire icon: approx. `250`
1277
+
## 0x6A Transaction
1279
+
- Clientbound: [x]
1280
+
- Serverbound: [x]
1283
+
A packet from the server indicating whether a request from the client was
1284
+
accepted, or whether there was a conflict (due to lag). This packet is also
1285
+
sent from the client to the server in response to a server transaction rejection
1288
+
| Field Name | Field Type | Example | Notes |
1289
+
| ------------- | ---------- | ------- | ------------------------ |
1290
+
| Inventory ID | i8 | `123` | 0 for player's inventory |
1291
+
| Action Number | i16 | `12` | |
1292
+
| Accepted | bool | `true` | |
1294
+
## 0x82 Update Sign
1296
+
- Clientbound: [x]
1297
+
- Serverbound: [x]
1298
+
- Size: 10 + length of strings
1300
+
This message is sent from the server to the client whenever a sign comes into
1301
+
view distance or created. This message is sent from the client to the server when the "Done"
1302
+
button is pressed after placing a sign.
1304
+
| Field Name | Field Type | Example | Notes |
1305
+
| ---------- | ---------- | ------------- | ----- |
1306
+
| X | i32 | `123` | |
1307
+
| Y | i16 | `0` | |
1308
+
| Z | i32 | `-128` | |
1309
+
| Text1 | str16 | `First line` | |
1310
+
| Text2 | str16 | `Second line` | |
1311
+
| Text3 | str16 | `Third line` | |
1312
+
| Text4 | str16 | `Fourth line` | |
1316
+
- Clientbound: [x]
1317
+
- Serverbound: [ ]
1318
+
- Size: 5 + length of payload
1320
+
Sends map updates (columns of pixels or decorations).
1322
+
It allows the server to stream partial changes to a map rather than the entire
1325
+
| Field Name | Field Type | Example | Notes |
1326
+
| -------------- | ---------- | ------- | --------- |
1327
+
| Item ID | i16 | `358` | |
1328
+
| Item Data | i16 | `0` | |
1329
+
| Payload length | u8 | `35` | |
1330
+
| Payload | Vec\<i8\> | `...` | See below |
1332
+
### Payload formats
1334
+
The first byte of the payload is a _tag_ indicating the type of update:
1336
+
#### Tag `0` (Column update)
1338
+
- `u8 x_start`: X coordinate (0..127) of the column.
1339
+
- `u8 y_start`: Y coordinate (0..127) of the starting pixel.
1340
+
- `Vec<u8> colors`: Palette indices (one per pixel) written _downwards_ starting at `(x_start, y_start)`.
1342
+
Each color is a raw color (0–255), not a limited palette enum. The raw value is
1343
+
`base_id * 4 + shade`, where:
1345
+
- `base_id` is one of the 14 map palette entries.
1346
+
- `shade` is 0..3 for brightness variation.
1348
+
#### Tag `1` (Decorations)
1350
+
Sequence of entries, each 3 bytes:
1352
+
- `u8 data`: Upper 4 bits = direction (0..15), lower 4 bits = type (always 0).
1353
+
- `u8 x`: X coordinate of the decoration on the map (0..127).
1354
+
- `u8 y`: Y coordinate of the decoration on the map (0..127).
1356
+
Decorations are only used to show the player cursors on the map in Beta 1.7.
1358
+
## 0xC8 Increment Statistic
1360
+
- Clientbound: [x]
1361
+
- Serverbound: [ ]
1364
+
| Field Name | Field Type | Example | Notes |
1365
+
| ------------ | ---------- | ------- | --------------------- |
1366
+
| Statistic ID | i32 | `1003` | See below |
1367
+
| Amount | i8 | `1` | Negative to decrement |
1371
+
- TODO :-( - but you can [try this forum post][statistics]?
1373
+
## 0xFF Disconnect
1375
+
- Clientbound: [x]
1376
+
- Serverbound: [x]
1377
+
- Size: 2 + length of strings
1379
+
Sent by the server before it disconnects a client, or by the client before it
1380
+
disconnects from the server. The receiver of this packet assumes that the
1381
+
sender has already closed the connection by the time the packet arrives.
1383
+
| Field Name | Field Type | Example | Notes |
1384
+
| ---------- | ---------- | --------------------- | ----- |
1385
+
| Reason | str16 | `The server is full!` | |
1387
+
[blocks]: blocks.md
1388
+
[entity_metadata]: #entity-metadata
1389
+
[packed_f64]: #floored-double
1390
+
[packed_rotation]: #packed-rotation
1391
+
[packed_motion_i8]: #packed-motion-i8
1392
+
[packed_motion_i16]: #packed-motion-i16
1393
+
[entity_types]: #entity-types
1394
+
[player_position]: #0x0b-player-position
1395
+
[player_look]: #0x0c-player-look
1396
+
[player_position_and_look]: #0x0d-player-position-and-look
1397
+
[block_dig]: #0x0e-block-dig
1398
+
[spawn_player]: #0x14-spawn-player
1399
+
[spawn_living_entity]: #0x18-spawn-living-entity
1400
+
[destroy_entity]: #0x1d-destroy-entity
1401
+
[initialize_chunk]: #0x32-initialize-chunk
1402
+
[chunk_data]: #0x33-chunk-data
1403
+
[set_slot]: #0x67-set-slot
1404
+
[transaction]: #0x6a-transaction
1405
+
[disconnect]: #0xff-disconnect
1406
+
[statistics]: http://www.minecraftforum.net/viewtopic.php?f=1020&t=295360
1407
+
[zlib]: http://www.zlib.net/
1408
+
[java8spec_floating]: https://docs.oracle.com/javase/specs/jls/se9/html/jls-4.html#jls-4.2.3
1409
+
[utf16]: https://en.wikipedia.org/wiki/UTF-16
1410
+
[mutf8]: https://docs.oracle.com/javase/8/docs/api/java/io/DataInput.html#modified-utf-8
kokirigla.de
